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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  1. 1AskPayee

    GET api.lumen.example/search402 · 0.02 USDC

    The payee answers the unpaid call with its price, its address and a deadline.

    no transaction
  2. 2PayAgent

    held

    The agent proves the payment fits the remit’s terms. The price leaves the remit and waits in a hold for the payee.

    pay
  3. 3ServePayee

    200 · the response

    The payee decrypts the hold, checks the amount and the request it pays for, and serves.

    no transaction
  4. 4SettlePayee

    settled

    The 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.

WhatOwnerAgentPayeeAnyone
That the agent paid the payeereads itreads itreads itreads it
The amount of a paymentreads itreads itreads it
The request it paid foras a hash; the owner’s statement also holds the URLreads itreads itreads it
The remit’s balancereads itreads it
The caps, the payee list and the expiryreads itreads it
The remit’s other paymentsreads itreads 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.