Allowance contract

Status: tested offline, not deployed, not audited. The contract, its tests and the TypeScript transaction builders exist in the repository. No allowance has been created on any network, and the app’s signing path does not use it. Every Cardano payment ZyroPay makes today still needs your passkey. See Autonomous mode for why Cardano needs a different mechanism.

The idea

Your passkey stays the master key. With one tap you lock a budget at a script address that belongs to you. An agent key can then pay from it without asking, but the Cardano ledger refuses any payment that breaks the limits written in the budget’s datum. Your owner key alone can take everything back at any time. If the agent key leaks, the loss is bounded by those limits until you revoke.

Limit	Enforced by the script
Per payment	At most per_payment_max lovelace per transaction
Per period	At most period_cap per aligned window of period_ms
Recipients	Only listed payment credentials (keys or scripts such as an escrow)
Expiry	No agent payment whose validity reaches past expires_at
Owner withdrawal	The owner key can always spend the whole UTxO, whatever its datum

How a payment is checked

The validator (contracts/allowance, Aiken, parameterized by the owner’s payment key hash) accepts an agent payment only if all of these hold. Here paid is the lovelace taken out of the allowance.

1. The agent key signed.
2. The allowance is the only script-locked input. This stops double satisfaction: one payee output cannot settle two allowances.
3. Exactly one output returns to the same script address, with the same tokens and no reference script.
4. 0 < paid <= per_payment_max.
5. The validity range is finite, starts at or after the period start, and ends by the expiry.
6. The period rolls over once the validity lower bound reaches the next window. Within the window, spent + paid <= period_cap.
7. The new datum is exactly the old one with the updated period start and counter.
8. When a payee list is set, outputs to listed payees hold at least paid.

The agent pays the network fee and posts collateral from its own small ADA balance. A fee taken from the allowance would count as a payment and would need a payee.

What is tested

• Aiken: 49 unit tests and 8 property tests (aiken check). They cover the happy paths, both limits, period roll-over, expiry and infinite bounds, wrong signers, wrong or underpaid payees, value theft through the continuing output (missing, split, moved stake key, reference script, tokens), every datum field tampered with, and double satisfaction. Each payment rule was disabled in turn once, and a test failed for every mutant.
• TypeScript: packages/blockchain/src/cardano/allowance.ts encodes the datum and redeemers, applies the owner parameter, derives the address, and plans create, agent-pay, revoke and top-up transactions offline. With aiken installed, its tests run the built transactions through aiken tx simulate against the validator. Honest payments, a roll-over, a payment into a Masumi escrow and a revoke are accepted. Transactions built from forged datums are rejected by the script. An agent payment measured about 0.27 M memory units and 0.11 G CPU steps.

aiken tx simulate runs the scripts only. Ledger rules such as fees and min-UTxO were not checked against a node, because no transaction was submitted.

Limits

• Creation is not checked on chain. Anyone can send a UTxO with any datum to your allowance address, using their own funds. Off-chain code must trust only allowances you funded and whose datum it decoded and checked.
• An empty payee list means anyone, the agent included.
• Each allowance UTxO is a separate budget, and only one can be spent per transaction.
• One payment per block per allowance, because the UTxO is spent and recreated each time.
• Not wired in. Using it needs a Cardano agent key for each agent, a create flow behind the passkey, and an executor that builds and signs agent payments. None of these exist yet.
• Not audited. An audit is on the roadmap before any mainnet use.