Skip to content

Use Pay-to-Play ​

Pay-to-Play lets customers deposit money and pay for services from that balance.

For example, a customer deposits $100 worth of the chain's native currency to use an AI service. The deposit is held on-chain in a smart contract that tracks the customer's balance.

Each time the customer makes a purchase, they authorize a payment by signing a digital voucher off-chain, without submitting a blockchain transaction. The service collects the payment by submitting that voucher to the smart contract, which verifies it and transfers the authorized amount on-chain.

Invoices, purchases and service delivery are managed off-chain. Each voucher includes an invoice reference, while the smart contract tracks the cumulative amount collected.

Customers can add funds, withdraw unused money after a waiting period, or recover their remaining balance when the payment arrangement ends. Each balance belongs to one owner within one payment channel.

This guide describes source 2c8f962c, including invoice-bound v2 vouchers, collector-gated payments and positive-credit withdrawal restarts. An older non-upgradeable deployment retains its original behavior; verify the deployed contract before relying on these instructions.

Choose a task

Choose the owner and channel, then Open balance. The selection stays fixed when you switch wallets. The active task is a label, not a button that resets its form.

DestinationUse it to
BalanceRead current state. No transaction editors.
DepositAdd native coins to your selected position.
Withdraw or moveRequest an exit, replace a request, or consume a mature request.
VouchersRegister a permanent key, inspect signing details, or collect a payment.
RecoveryInspect deadlines, choose a refund recipient, close a cycle, refund or retire a channel.
Channel settingsManage the channel's shared payee and collector as admin.

Choose an action, inspect the prepared contract, arguments and value, then authorize it with the connected wallet. Success means a successful receipt and the resulting state, not merely a simulation or transaction hash. Refresh rereads state and removes a prepared call; Back rereads a prior view and restores compatible drafts. Switching accounts clears account-bound drafts.

Keep the roles separate

The owner supplies funds and controls withdrawals. The permanent voucher key signs payment authority. The payee receives payment. The configured collector submits vouchers. The admin creates channels and changes payee/collector settings. These roles can be different addresses. Viewing another owner's balance grants none of their authority.

Channel 0 is a reserve: it can hold and move funds, but cannot register a voucher key or collect payments. A channel's claim period is shared; its customers' balances are separate.

A payment, with numbers

Alice deposits 100 wei into channel 7 and registers key K. K signs a voucher for a lifetime cumulative total of 30, including the agreed invoice hash. The configured collector submits it with a 30-wei cap. The current payee receives 30, Alice's balance becomes 70, and her lifetime paid amount becomes 30. A later voucher for cumulative total 50 can authorize another 20, not another 50. Gas fees are separate.

What a voucher authorizes

payment = min(maxAmount,
              max(cumulativeTotal - voucherPaid, 0),
              currentBalance)

The caller must be the current nonzero collector, the signature must match the registered key, and collection must precede the recovery cutoff. These checks still apply to zero payment. Only a successful transfer increases voucherPaid.

A deposit authorizes no charge by itself. A voucher authorizes settlement, not proof of work or invoice allocation. The invoice hash is signed, but the contract does not enforce invoice uniqueness, allocation, delivery or refunds for a failed service.

Register the permanent key carefully

In Vouchers, connect the balance-owner wallet and enter the key's address, never its private key. Registration is once per operating, nonzero-channel position. Check that you can sign with the key before approving.

The key cannot be replaced, revoked or reset, including after a refund. Changing the owner's wallet or its ERC-1271 policy does not revoke the key's ECDSA signatures. Old unpaid vouchers can become collectible again after an open position is refunded and funded again. Use a different position for a different key.

Withdraw or move funds

While operating, the owner requests a positive amount no greater than the balance. requestWithdrawal leaves an existing request unchanged. setWithdrawal explicitly creates or replaces it and restarts the full wait, even for the same or a smaller amount. There is no cancellation operation.

At or after readyAt, anyone may execute a withdrawal to the balance owner. Only the owner may instead move the requested funds to another operating position of their own. Either operation transfers the smaller of request and balance and clears the whole request. A failed native transfer reverts.

A request does not reserve funds. Collection can reduce the balance before withdrawal. In this source revision, a positive deposit or incoming move into a position with a pending request restarts the full wait using the receiving channel’s claim period, preserving the amount requested. Zero-value credits do not restart it. For example, after a mature request for 100 survives collection of the original balance, depositing another 100 restarts readiness at the new credit timestamp plus the claim period. The reset is not a reservation for a payee or a promise of payment for later work. Older deployed contracts can still apply a mature request immediately to new funds. Ordinary withdrawals pay the owner, not the separately configured full-refund recipient.

Recover the full balance

Use Recovery to inspect the effective deadline and destination before acting. Positive funding and incoming moves normally schedule recovery after 365 days plus the claim period. Time passing changes the phase, but sends no transaction automatically.

PhaseMeaning
OperatingFunding and owner renewal are allowed.
SettlingNo new funding or renewal; previously authorized vouchers remain collectible before the final cutoff.
Refund-onlyCollection has ended; anyone may execute a full refund to the stored destination.

End a funding cycle early

The owner, admin or current payee may start wind-down. It can shorten, but never postpone, an existing effective exit. Settlement cannot be cancelled. Already-created ordinary withdrawal entitlements are preserved.

Retire a channel

The admin or current payee can retire a channel permanently. This stops new funding immediately, preserves earlier exits, and allows each position to be refunded independently after its cutoff. It neither loops over customers nor transfers all funds at once. Only the admin can retire channel 0.

Choose the full-refund destination

Only the balance owner may change this destination; the default is the owner. A refund caller cannot choose it. A full refund clears the balance, ordinary request and funding-cycle deadline, but retains the key, paid total and configured recipient. A rejecting recipient affects only that position; its owner can correct the destination and retry.

Refund many positions

Use the bounded refund worker for event discovery and independent batches. Complete historical funding and incoming-move coverage matters. A channel's escrowTotal == 0 means no credited customer balance remains, not that forced uncredited native transfers are absent.

Integrate with a service

Follow the payment-integration guide from deployment identity through durable invoice authorization, collection and reconciliation. The contract does not provide a purchase database or prove service delivery.

Resolve and verify the payment address, not the CAM host.

Sign the four-field PayToPlay/2 voucher with the confirmed permanent key. The helper reference owns exact invoice encodings and interoperability vectors.

Use the deployed ABI and authored route mapping; continuation inputs are not necessarily Solidity arguments.

Plan replacement explicitly. A new manifest cannot migrate balances, keys or issued vouchers to another contract.

Try locally

Start with a local wallet and 100-wei deposit, then sign and collect a test voucher. The shared wallet guide owns browser setup and cleanup; use public fixture keys only on disposable local state.

Verification for contributors

Choose the payment or recovery campaign, or hand an isolated deployment to another repository's test runner. Live signing checks require disposable state. A passing fixture does not establish production readiness or delivered work.