README

Track value like physical cash in your PHP apps. Every unit has an origin, can only be spent once, and leaves a complete audit trail.

$ledger = Ledger::inMemory();
$ledger->credit('alice', 100)->transfer('alice', 'bob', 25);
echo $ledger->totalUnspentByOwner('bob'); // 25

Zero-dependency PHP 8.4+ library implementing the UTXO model, inspired by Bitcoin and decoupled as a standalone library.

Table of Contents

• Why?
• When to use it
• Install
• Quick Start
• Output types
• Examples
• Documentation
• Learning Path
• FAQ
• Contributing

Why?

Traditional balance tracking (balance: 500) is just a number you mutate. There's no history, no proof of where it came from, and race conditions can corrupt it.

Unspent tracks value like physical cash. You can't photocopy a $20 bill - you spend it and get change back. This gives you:

• Double-spend prevention — a unit can only be spent once, ever
• Complete audit trail — trace any value back to its origin
• Immutable history — state changes are additive, never mutated
• Advanced locks — timelocks, multisig, hash-locked outputs (HTLCs)
• Zero external dependencies — pure PHP 8.4+

When to use it

Use Unspent when value moves between parties, you need to prove who authorized what, or audit trail is a requirement.

Skip it when you only need a simple counter, single-user balance, or no audit requirements.

Limitations

Install

composer require chemaclass/unspent

Quick Start

In-Memory (prototyping)

use Chemaclass\Unspent\Ledger;

$ledger = Ledger::inMemory();
$ledger->credit('alice', 1000)
    ->credit('bob', 500)
    ->transfer('alice', 'bob', 200)
    ->transfer('alice', 'bob', 100, fee: 5)
    ->debit('bob', 50);

$ledger->totalUnspentByOwner('alice');  // 695
$ledger->totalUnspentByOwner('bob');    // 750

SQLite persistence (production)

use Chemaclass\Unspent\Persistence\Sqlite\SqliteRepositoryFactory;
use Chemaclass\Unspent\Output;

$repo = SqliteRepositoryFactory::createFromFile('ledger.db');

$ledger = $repo->find('my-ledger')
    ?? Ledger::withGenesis(Output::ownedBy('alice', 1000));

$ledger->transfer('alice', 'bob', 200);
$repo->save('my-ledger', $ledger);

Coin Control (full input/output control)

use Chemaclass\Unspent\Tx;

$ledger = Ledger::withGenesis(
    Output::ownedBy('alice', 500, 'alice-savings'),
    Output::ownedBy('alice', 300, 'alice-checking'),
);

$ledger->apply(Tx::create(
    spendIds: ['alice-checking'],
    outputs: [
        Output::ownedBy('bob', 200),
        Output::ownedBy('alice', 100, 'alice-change'),
    ],
    signedBy: 'alice',
));

Use Coin Control for: specific output selection, custom IDs, multiple recipients, complex fees.

Batch operations

$ledger->consolidate('alice', fee: 10);

$ledger->batchTransfer('alice', [
    'bob' => 100,
    'charlie' => 200,
    'dave' => 300,
], fee: 5);

Transaction Mempool

Stage transactions for validation before commit:

use Chemaclass\Unspent\Mempool;

$mempool = new Mempool($ledger);
$mempool->add($tx1);
$mempool->add($tx2);
// $mempool->add($conflictingTx); // Throws OutputAlreadySpentException
$mempool->commit();

Output types

Examples

Runnable demos under example/:

php example/run               # List all
php example/run game          # Run a demo (also: loyalty, accounting, events, btc, wallet, locks, sqlite)
php example/run game --reset  # Reset state

See example/README.md for full output samples and the web API demo.

Documentation

Start at docs/README.md for the full index.

Learning Path

FAQ

$ledger->apply(Tx::create(
    spendIds: ['input-100'],       // Spending 100
    outputs: [Output::open(95)],   // Creating 95
));
// Fee = 100 - 95 = 5 (implicit)

Contributing

See CONTRIBUTING.md for setup, TDD workflow, quality gates, and commit format.

composer install     # Installs dependencies + pre-commit hook
composer check:quick # Fast feedback: cs-fixer + phpunit
composer test        # Full: cs-fixer + rector + phpstan + phpunit

Docker workflow available via make help.

License

MIT — see LICENSE.