Concepts
Keys: owner, agent, payee
Which key the owner, the agent and the payee each hold, what each key can do, and what each can read.
Three people take part in a payment and each holds one key. The owner's key funds and closes remits. The agent's key pays from one remit, inside its terms. The payee's key takes the holds made out to it.
What each key can do
| Owner's wallet | Agent key | Payee's wallet | |
|---|---|---|---|
| Deposit and withdraw a private balance | its own | its own | |
| Open a remit | yes | ||
| Pay from a remit | from its own remit, inside the terms | ||
| Revoke a remit | its own remits | ||
| Settle a hold | holds made out to it | ||
| Register and edit a directory record | its own |
refund needs none of the three. Any account can send it once a hold's deadline has passed, and the money goes to the owner named in the hold.
The owner's wallet
The owner is an ordinary Solana wallet. Its Ed25519 key signs every transaction the owner sends: deposits, withdrawals, open and revoke.
A private balance needs two more keys, a viewing key that decrypts and a nullifier key used when spending. Both are derived from one signature: the wallet signs a fixed message once, and the keys come from that signature. Signing the same message again gives the same keys, so nothing has to be backed up beyond the wallet itself.
Registering publishes the public halves of the two keys in the User Registry under the wallet's address. From then on others can pay the wallet privately knowing only its Solana address.
The agent key
The agent key is a Solana keypair made for one agent. A remit is opened to the key's private address, so the remit is encrypted to it. The app generates one when a remit is opened and shows it once, with the line that sets it for the SDK:
REMIT_AGENT_KEY=<the agent's secret key, base58>An owner who already has a key for the agent pastes its public key in place of generating one.
What the agent key can do is fixed by the remit, not by the software that holds it:
- It signs
pay, and only for the remit whose terms name it. The proof inside each payment checks the signer against the terms. - It reads its own remit: the terms, what is left, and what it has spent today.
- It pays its transaction fees from the SOL the owner sends it when the remit is opened.
It cannot revoke the remit, change a term, move anything else of the owner's, or read the owner's other remits. A payment outside the terms has no valid proof, whoever holds the key.
Revoking a remit ends what its agent key can do. The key itself holds no money beyond the SOL for fees.
The payee's wallet
The payee is a Solana wallet too, registered for a private balance the same way as an owner. Holds are encrypted to its viewing key and owned by a program address derived from its wallet address, and settle accepts only its signature.
A gate settles every payment it serves, so the server that runs the gate holds the payee's key, as a secret key in REMIT_PAYEE_KEY. The money it earns lands in the payee's private balance and is withdrawn from there to any public account.
Who reads what
| Reads | |
|---|---|
| Owner | Their private balance. Every remit they opened: balance, terms, and each payment with payee, amount, request hash, deadline and status. |
| Agent | The remit it was given. |
| Payee | Its private balance. Each hold made out to it: owner, amount, mint, request hash, deadline. Its settlements with the fee on each. |
| Anyone given a receipt | That one payment. |
| Anyone else | What the chain shows. |
Where keys are used
Remit's engine builds each transaction with its proof and decrypts private state. It keeps nothing between requests: the keys a call needs arrive in that call and are not stored or logged.
- The app asks the wallet for the derivation signature and sends it with each request that reads or builds. Transactions come back unsigned and the wallet signs them, so the wallet's signing key never leaves it.
- An agent gives its secret key to the SDK, which sends it to the engine at
REMIT_ENGINE_URLwith each call that reads the agent's remit or builds and signs apay. - A gate gives the payee's key to the SDK, which sends it to the engine the same way to decrypt incoming holds and to sign
settle.
The derivation signature reads a wallet's whole private history, so treat it like a key. The API lists the engine's routes and what each takes.