How a remit works
A remit is an amount set aside for one agent key, with terms. It is a private balance in the Default Ring of Solana Privacy Rings, owned by the Remit program, and every payment from it is a proof over those terms.
What a remit holds
The terms are part of the commitment the pool stores, beside the balance. They travel with the money.
- Owner
- The wallet that opened it. Only the owner revokes it, and what is left returns to the owner.
- Agent key
- The one key that can spend it. The key spends this remit and nothing else of the owner’s.
- Mint and balance
- What is left of the amount the owner set aside, in the mint it was opened in.
- Cap per payment
- The most a single payment may be.
- Cap per day
- The most all payments of one UTC day may add up to, with the day’s spend so far.
- Payees
- The list of payees it may pay, kept as one root, or any payee.
- Expiry
- The moment after which no payment can be made from it.
research-agenthEXa…ZJ4uremaining, read with the owner’s key
USDCof 20.00
waiting for the next call
What the chain showsAmounts, terms and requests are encrypted
- hEXa…ZJ4uMgFG…DsbEpay, settle
- hEXa…ZJ4uPfGJ…8wJJpay, settle
Five things can happen to it
open
The owner signs.
The amount moves from the owner’s private balance into a new remit. A note encrypted to the agent lets it find the remit.
That this owner opened a remit, and the SOL sent to the agent key for fees.
pay
The agent signs, with a proof that the payment fits the terms.
The price leaves the remit and waits in a hold for the payee. The remit’s balance and day’s spend change; its terms do not.
That this agent paid this payee.
settle
The payee signs, after serving the request.
The hold, less the protocol fee, lands in the payee’s private balance. The settlement binds the payment to a request hash and a response hash: it is the receipt.
That this payee settled a hold.
refund
Anyone may send it once the deadline has passed. A keeper does.
A hold the payee never settled returns whole to the owner’s private balance.
That a hold for this payee was refunded.
revoke
The owner signs.
The remit closes and its remaining balance returns to the owner’s private balance. Later payments from it fail.
That this owner revoked a remit.
One payment, from 402 to receipt
Over HTTP a paid call is one round trip more than an unpaid one. The payee is paid when it delivers.
1AskPayee
GET api.lumen.example/search402 · 0.02 USDCThe payee answers the unpaid call with its price, its address and a deadline.
no transaction2PayAgent
heldThe agent proves the payment fits the remit’s terms. The price leaves the remit and waits in a hold for the payee.
pay3ServePayee
200 · the responseThe payee decrypts the hold, checks the amount and the request it pays for, and serves.
no transaction4SettlePayee
settledThe payee claims the hold with the hash of what it returned. That settlement is the receipt.
settle
Who sees what
In the Default Ring the two sides of a payment are public and amounts are encrypted. Remit encrypts the terms, the price and the request as well. One payment can be shown to one more person by handing over its receipt.
| What | Owner | Agent | Payee | Anyone |
|---|---|---|---|---|
| That the agent paid the payee | reads it | reads it | reads it | reads it |
| The amount of a payment | reads it | reads it | reads it | |
| The request it paid foras a hash; the owner’s statement also holds the URL | reads it | reads it | reads it | |
| The remit’s balance | reads it | reads it | ||
| The caps, the payee list and the expiry | reads it | reads it | ||
| The remit’s other payments | reads it | reads it |
The rule that keeps a remit inside its terms
A remit can be spent only by a proof over its own terms, and the terms are part of what the pool stores. The check runs in the Remit program and the Rings pool, on validators. It does not run in the agent, in the SDK or at the payee, so it holds when any of those is compromised.
- All holds ever made from a remit add up to no more than its opening balance.
- No hold is larger than the cap per payment.
- The holds of one day add up to no more than the cap per day.
- No hold names a payee off the list.
A hold leaves in one of two ways: to its payee before the deadline, or to its owner after. Money in flight is never stuck and never paid twice.