Concepts

The remit and its terms

What a remit holds, what each term means, and how validators keep every payment inside the terms.

A remit is a private balance set aside for one agent key, with the owner's terms stored inside it. The balance and the terms are one object: validators check every payment against the terms before any money moves, and the terms stay encrypted the whole time.

What a remit holds

A remit is a private balance in the Default Ring of Solana Privacy Rings. It is owned by a program address derived from the owner's wallet, so only the Remit program can move it, and only with a proof that the move is one the terms allow.

FieldTypeMeaning
amountu64What the remit still holds, in base units of its mint.
mintAddressThe mint the remit was opened in. Every payment from it is in this mint.
ownerAddressThe wallet that opened it. Refunds and whatever is left at revoke go back to the owner's private balance. Only the owner can revoke.
agentAddressThe agent key. It is the only key that can pay from the remit.
perPaymentCapu64The most one payment can be.
dailyCapu64The most the remit can pay in one UTC day.
payeesAddress[] or "any"The payees the remit can pay. Up to 32 addresses, or any payee.
expiresAtunix secondsThe moment after which the remit pays nothing.
day, spentTodayu64The UTC day the remit last paid on and what it has paid that day. The program keeps these.

The remit's id is the signature of the transaction that opened it.

The terms

The owner sets the terms once, when the remit is opened. No instruction changes them afterwards. To change what an agent may do, the owner revokes the remit and opens another.

Cap per payment

A payment's amount is greater than zero and no greater than perPaymentCap. The cap itself is greater than zero.

Cap per day

A day is a UTC day: day number = unix time ÷ 86,400, rounded down, so the count starts again at 00:00 UTC. A payment passes when the day's spend so far plus the payment's amount is no greater than dailyCap. On the first payment of a new day the spend so far is zero.

The day's spend counts every payment made that day at the moment it is made. A payment that is later refunded still counts toward the day it was made on.

Payees

The list holds up to 32 payee addresses. The remit stores the list as one hash, the root of a Merkle tree of the addresses, and each payment proves that its payee is a leaf of that tree. A remit opened with "any" stores zero in place of the root and pays any address.

Expiry

A payment passes while the cluster's clock is before expiresAt. From that second on the remit pays nothing. What it still holds stays in it until the owner revokes it.

Balance

A payment cannot be larger than what the remit holds. Refunded payments return to the owner's private balance, not to the remit, so a remit's balance only goes down.

What can happen to a remit

InstructionWho signsWhat it does to the remit
openthe ownerMoves an amount from the owner's private balance into a new remit with its terms.
paythe agentReplaces the remit with a smaller one carrying the same terms, and puts the payment's amount in a hold for the payee.
revokethe ownerCloses the remit and returns everything it holds to the owner's private balance.

settle and refund act on a hold, after the money has left the remit. Paying: holds, settlement, refunds follows a payment from there.

A remit is in one of four states:

StatusMeaning
openIt holds money and its expiry has not passed.
emptyIt has paid out everything it held.
expiredIts expiry has passed. The owner can still revoke it and take back what is left.
revokedThe owner closed it. Any later pay fails.

Revoking does not touch holds that already exist. Each one still goes to its payee at settlement or back to the owner at its deadline.

How a payment stays inside the terms

The pool stores a commitment to each remit: a hash over its amount, its mint, its owner and its terms. To pay, the agent builds a zero-knowledge proof of these statements about the remit behind that commitment:

  • the signer of the transaction is the remit's agent key
  • the clock is before expiresAt
  • the amount is greater than zero and within perPaymentCap
  • the day's spend plus the amount is within dailyCap
  • the payee is on the list, or the list is "any"
  • the hold's deadline is after now and no more than 24 hours away
  • the outputs are a hold of exactly the amount for that payee, and a new remit holding the rest with every term unchanged and the day's spend updated

The Remit program verifies the proof, checks the time the proof states against the cluster's clock (it may trail the clock by up to 300 seconds and never run ahead of it), and only then asks the pool to spend the old remit and create the two outputs. A payment that breaks a term has no valid proof, so there is no transaction to send, and a forged proof is rejected by the program with ProofVerificationFailed.

Because every pay carries the terms forward unchanged, the same checks apply to the next payment and the one after it. Over a remit's life the holds created from it never add up to more than it was opened with, no hold is above the cap per payment, no UTC day's holds are above the cap per day, and no hold names a payee off the list. The check runs in the program and the pool, so it holds whatever the agent's code, its prompt or its SDK do.

Who reads a remit

The amount and the terms are encrypted. The owner and the agent read them. The chain records that the owner opened a remit and that the agent paid a payee, and nothing of the amounts or the terms: What the chain shows lists it instruction by instruction.

Loading the index