Concepts

Paying: holds, settlement, refunds

A payment is held for the payee until it delivers. It settles to the payee before the deadline or returns to the owner after it.

A payment from a remit does not go straight to the payee. It goes into a hold: a private balance set aside for that payee, with a deadline. The payee takes it by settling before the deadline. If the deadline passes first, the hold returns to the remit's owner.

  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

The hold

pay creates one hold per payment. A hold is a private balance owned by a program address derived from the payee's wallet, and it is encrypted to the payee.

FieldTypeMeaning
amountu64The price paid, in base units of the remit's mint.
payeeAddressThe only key that can settle the hold.
ownerAddressThe remit's owner, who is paid if the hold is refunded.
requestHash32 bytesThe hash of the request this payment pays for.
deadlineunix secondsThe last second at which the payee can settle.

The agent sets the deadline when it pays, as a number of seconds from now. It is after the moment of payment and at most 86,400 seconds (24 hours) later. The API's GET /v1/config returns the default the SDK uses as defaultHoldSeconds.

A hold leaves in exactly two ways, and the deadline decides which is open:

Clocksettlerefund
at or before deadlinepassesfails with HoldNotExpired
after deadlinefails with HoldExpiredpasses

So a hold is never paid twice and never stays stuck: at every moment one of the two instructions can spend it, and each spends all of it.

Settlement

The payee settles after it has served the request. settle is signed by the payee's key and carries the hash of the response it returned.

  1. The program reads the fee rate and the fee recipient from its config.
  2. It checks that the clock is at or before the hold's deadline.
  3. It verifies the payee's proof: the signer is the hold's payee, the fee is the configured share of the hold's amount, the fee goes to the fee recipient and everything else goes to the payee's own private balance.
  4. It adds one to the payee's settled count and, on the payee's first settlement, records the time.
  5. The pool spends the hold and creates the two outputs.

The settlement is the payment's receipt. The hold carries the request hash and the settlement carries the response hash, so the two transactions together say what was asked for, what was returned, to whom and for how much. Receipts and disclosure covers how one receipt is shown to someone else.

Refund

A hold that is not settled by its deadline goes back to the owner. refund needs no signature from the owner or the payee: any account can pay for and send the transaction, as long as the sender holds the hold's opening (the values behind its commitment). Remit's keeper sends it for holds it has been handed.

  1. The program checks that the clock is after the hold's deadline.
  2. It verifies the proof: the whole amount goes to the private balance of the owner named in the hold.
  3. It adds one to the payee's refunded count.
  4. The pool spends the hold and creates the output.

A refund carries no fee. The money returns to the owner's private balance, not to the remit, and the payment still counts toward the remit's cap for the day it was made on.

A payment's status

StatusMeaning
heldThe hold exists. The payee has not settled and the deadline has not been acted on.
settledThe payee took the hold. The payment has a settlement signature, a response hash and a fee.
refundedThe hold returned to the owner after its deadline.

The owner sees each payment with its status in the remit's statement. The payee sees its holds and settlements on the Earn screen.

What each side can rely on

The owner's money leaves the remit only into a hold that names the payee, the request and a deadline no more than 24 hours out. If the payee does not settle, the whole amount comes back.

The payee can read the hold before it serves anything: the amount, the mint, the request hash and the deadline are all in it, and the hold can only go to the payee or back to the owner. Until the deadline nobody but the payee can spend it.

Loading the index