We propose an institution-managed user payment ledger for recording account debits and credits, enforcing spending capacity, and sealing account periods independently of funds settlement.
Problem and scope
A payment institution needs to distinguish a customer’s business entries from changes to the spending capacity it grants. It also needs to connect individual entries, current-period totals, and sealed periods when reconciling customer funds. An institution-level aggregate does not provide those per-account records.
This proposal defines a common contract interface for those records and controls. It can serve an institution’s own business independently or compose with an on-chain payment protocol. It does not issue or transfer assets, establish customer identity, or prove that funds have been frozen or settled.
Account model and interface
Each account is scoped by (account, institution). An institution can serve payer accounts, merchant accounts, or both; the same address at two institutions does not share records or capacity. Holding the account’s private key does not grant permission to write entries.
Current state contains a limit baseline, cumulative outflows and inflows, and a user-period identifier:
available = limit + credit - debit
The three amounts and the resulting available capacity must fit in uint96; arithmetic uses wider intermediates and rejects negative capacity or out-of-range results.
Five write operations separate the relevant responsibilities:
addLimitandsubLimitadjust the baseline without changing business-entry totals.debitandcreditrecord outflows and inflows. A debit requires sufficient available capacity.rollupseals both period totals, sets the baseline to current available capacity, clears the totals, and advances the period identifier without changing available capacity.
Only the account’s institution adjusts limits and rolls up periods. Debit and credit callers follow the deployment’s declared authorization policy. Standard events expose individual entries and sealed totals; queries return current state.
For example, a baseline of 100, outflows of 30, and inflows of 5 leave capacity of 75. Rollup records those totals and starts the next period with a baseline of 75 and zero totals. This changes the accounting period, not the available capacity or the status of funds processing.
Replay, refunds, and task authorization
The four incremental operations use stable identifiers unique across an institution within one deployment, including across functions, accounts, and periods. A successful identifier cannot be reused; a reverted operation does not consume it. Rollup instead checks and advances the account’s period identifier.
Direct recording enforces duplicate prevention locally. Controlled composition may reuse upstream duplicate prevention only when it covers every recording path and preserves identifier uniqueness. The ledger then trusts that controlled entry point to emit each entry once; it does not provide a second independent defense against duplicate calls made by the entry point itself.
A limit reduction floors the baseline at zero but reverts if the resulting capacity would be negative. Its event records the actual reduction, which may be zero; a successful zero reduction still consumes the identifier. Capacity contributed by net inflow can be removed by rolling it into the baseline before reducing the baseline.
Historical refunds enter the current account period. They may restore numerical capacity after a task has ended, so institutions must continue to reject new business under expired or revoked task authorization. Zero capacity is not a permanent account-closure mechanism.
Relationship to ERC-8439
The related ERC-8439 proposal records inter-institution accounting. This proposal records accounts served by those institutions. Independent use does not require deploying ERC-8439 or introducing a Payment Network.
The specification declares requires: 8439 because it defines concrete composition rules for that proposal. ERC-8439 is still pending in its own PR. This proposal has been assigned ERC-8494 and remains an unmerged draft proposal.
When the ledgers are composed, all integrated on-chain payment or refund state and the corresponding user entries must commit or revert together. Implementations identify whether the payer side, recipient side, or both are integrated. Where both are integrated, the outflow is checked before the inflow, and batch entries preserve input order. Upstream authorization and refund checks remain in force.
User periods and institution periods remain independent. Reconciliation combines sealed records and current totals for the same business scope; it does not require the two layers’ current-period totals to match. On-chain atomicity does not extend to off-chain funds execution.
Implementation and feedback
The PR includes two diagrams and a minimal reference implementation. The attached sources compile independently and pass 39 account tests, including two fuzz tests with 512 runs each. The test sources and reproduction instructions are included in the PR. The tests exercise the independent reference implementation; its example writer policy, custom errors, and storage layout do not add requirements to the standard, and the suite does not validate ERC-8439 composition. These checks do not establish production readiness, an independent security audit, or successful fiat settlement.
Feedback is particularly useful on whether the interface and events let independent implementations agree on account history; whether the controlled-entry-point trust boundary is sufficiently precise; and whether the composition rules cover realistic payer-side and merchant-side integrations without making either mandatory for independent use. Concrete counterexamples involving duplicate entries, concurrent rollup, or late refunds would help test the specification’s guarantees.