Reference
The program
The remit program's addresses, accounts, instructions, circuits and errors.
The remit program stores no remits and no holds in accounts of its own. They are private balances in the Solana Privacy Rings state tree, owned by the program's addresses, with Remit's data encrypted inside them. The program owns two kinds of account: one config, and one record per registered payee.
Addresses
remit on mainnet | 7pG4N8LwyWoHAbKBUqqjC5Z8S8xyUfAUZHv2DAD3M13o |
remit on devnet | 7pG4N8LwyWoHAbKBUqqjC5Z8S8xyUfAUZHv2DAD3M13o |
remit on a local network | 7pG4N8LwyWoHAbKBUqqjC5Z8S8xyUfAUZHv2DAD3M13o |
| Solana Privacy Program | ring1GaLCuJnkUMVkX2JeZLTTX17wKsV4fZmPVzXANW |
| User Registry | regy3WAeRXMYuMYxr5iK3Bf9Arr3PcxGxyzAddbiqDQ |
GET /v1/config returns the program id of the cluster an API serves.
Program addresses
| Address | Seeds | What it is |
|---|---|---|
| remit authority | "remit_authority", owner | Owns every remit that owner opens. |
| hold authority | "hold_authority", payee | Owns every hold paid to that payee. |
| config | "config" | The fee, the fee recipient and the admin. |
| payee record | "payee", payee | A payee's directory record and standing. |
owner and payee are 32-byte wallet addresses. The two authorities hold no data. They exist so that only the program can sign for the balances they own.
Accounts
Config
165 bytes at the config address.
| Offset | Size | Field |
|---|---|---|
0 | 1 | Kind, always 1. |
1 | 1 | Bump. |
2 | 32 | admin: the key that can change the config. |
34 | 2 | fee_bps: the protocol fee in basis points, u16 little-endian, at most 10,000. |
36 | 32 | The fee recipient's owner hash. |
68 | 33 | The fee recipient's viewing public key. |
101 | 32 | The fee recipient's signing public key. |
133 | 32 | The fee recipient's nullifier public key. |
The last four fields are the fee recipient's private address. settle hashes the owner hash and the viewing key into the address its proof must pay the fee to.
Payee record
646 bytes at the payee's record address.
| Offset | Size | Field |
|---|---|---|
0 | 1 | Kind, always 2. |
1 | 1 | Bump. |
2 | 32 | payee: the wallet that registered. |
34 | 32 | mint: the mint the payee prices in. |
66 | 8 | price_hint: u64 little-endian, base units of mint. |
74 | 8 | settled: u64 little-endian. |
82 | 8 | refunded: u64 little-endian. |
90 | 8 | first_settled_at: i64 little-endian unix seconds, 0 until the first settlement. |
98 | 1 + 64 | name: one length byte, then up to 64 bytes. |
163 | 1 + 200 | url: one length byte, then up to 200 bytes. |
364 | 2 + 280 | description: a u16 little-endian length, then up to 280 bytes. |
Unused bytes of the three strings are zero.
Private state
Remit terms
The data of a remit, hashed into its commitment and encrypted.
| Field | Type | Meaning |
|---|---|---|
owner | UTXO owner | The owner: paid by refunds and by revoke, and the only signer of revoke. |
agent | 32 bytes | The owner identity of the agent key, the only signer pay accepts. |
view_address | 32 bytes | The hash of the address every later state of the remit is encrypted to: the remit authority with the owner's viewing key. Fixed at open. |
per_payment_cap | u64 | |
daily_cap | u64 | |
day | u64 | The UTC day (unix ÷ 86,400) that spent_today counts. |
spent_today | u64 | |
payee_root | 32 bytes | The Poseidon Merkle root of up to 32 payee identities in a tree of depth 5. Zero for any payee. |
expires_at | u64 | Unix seconds. |
last_request | 32 bytes | The request hash of the latest payment. |
last_deadline | u64 | The deadline of the latest payment's hold. |
The amount and the mint are the balance's own fields.
Hold terms
| Field | Type | Meaning |
|---|---|---|
payee | 32 bytes | The owner identity of the payee, the only signer settle accepts. |
owner | UTXO owner | The remit's owner, whom a refund pays. |
request_hash | 32 bytes | The hash of the request the payment is for. |
deadline | u64 | Unix seconds. |
Instructions
The first byte of the instruction data is the tag. Instructions 4 to 8 carry their own arguments, then the Solana Privacy Program's transact data, which the program forwards unchanged. Their accounts are the ones listed here, then the transact accounts, with the authorities the program signs for among them.
0 init_config
Creates the config. Runs once.
| Accounts | admin (signer, writable), config (writable), the program's program-data account, system program |
| Data | fee_bps (u16), then the fee recipient: owner hash (32), viewing key (33), signing key (32), nullifier key (32) |
| Checks | The signer is the program's upgrade authority. fee_bps is at most 10,000. The config does not exist yet. |
1 set_config
Changes the fee, the fee recipient and the admin.
| Accounts | admin (signer), config (writable) |
| Data | As init_config, then the admin from here on (32) |
| Checks | The signer is the config's admin. fee_bps is at most 10,000. |
2 register_payee
Creates the signer's payee record with both counts at zero.
| Accounts | payee (signer, writable), payee record (writable), system program |
| Data | mint (32), price_hint (u64), name (u8 length, bytes), URL (u8 length, bytes), description (u16 length, bytes) |
| Checks | The name is 1 to 64 bytes, the URL at most 200, the description at most 280. The record does not exist yet. |
The payee pays the record's rent.
3 update_payee
Rewrites the directory fields. The standing is not touched.
| Accounts | payee (signer), payee record (writable) |
| Data | As register_payee |
| Checks | The signer is the record's payee. |
4 open
Moves an amount from the owner's private balance into a new remit.
| Accounts | owner (signer) |
| Arguments | proof (128), the agent's viewing key (33), the owner's viewing key (33), remit authority bump |
| Checks | The open proof, against the owner and the remit's two addresses. |
| Signs | The owner's remit authority. |
| Outputs | The owner's change, and the remit, encrypted to the agent. |
5 pay
Pays from a remit into a hold.
| Accounts | agent (signer), owner, payee |
| Arguments | proof, now (u64), day (u64), the owner's viewing key, the payee's viewing key, remit authority bump, hold authority bump |
| Checks | now is not ahead of the cluster clock and at most 300 seconds behind it, and day = now ÷ 86,400. The transaction's one message is the payee's address. The pay proof. |
| Signs | The owner's remit authority and the payee's hold authority. |
| Outputs | The next remit, encrypted to the owner, and the hold, encrypted to the payee. |
6 settle
Pays a hold to its payee, less the fee.
| Accounts | payee (signer), config, payee record (writable) |
| Arguments | proof, deadline (u64), response_hash (32), hold authority bump |
| Checks | The clock is at or before deadline. The transaction's one message is the response hash. The settle proof, with the fee and the fee recipient from the config. |
| Effects | settled goes up by one. first_settled_at is set if it was zero. |
| Signs | The payee's hold authority. |
| Outputs | The amount less the fee to the payee, and the fee to the fee recipient. |
7 refund
Returns a hold to its owner after the deadline.
| Accounts | caller (signer), payee, payee record (writable) |
| Arguments | proof, deadline (u64), hold authority bump |
| Checks | The clock is after deadline. The refund proof. |
| Effects | refunded goes up by one. |
| Signs | The payee's hold authority. |
| Outputs | The whole amount to the owner. |
The caller is any account that pays the fee. In settle and refund the payee record is the address derived for the payee. When that payee never registered, the address holds no record and nothing is counted.
8 revoke
Closes a remit.
| Accounts | owner (signer) |
| Arguments | proof, remit authority bump |
| Checks | The revoke proof. |
| Signs | The owner's remit authority. |
| Outputs | Everything the remit holds, to the owner. |
Circuits
One per instruction that moves a private balance, written in Rust with Xark 0.3.1 and proven with Groth16 over BN254. A proof is 128 bytes. Its one public input is the hash of the values below together with the hash of the pool transaction it belongs to.
| Circuit | Public values | What it proves |
|---|---|---|
open | owner identity, remit address, view address | The signer's balance funds the remit. The amount and the cap per payment are greater than zero. The terms are set, with the view address fixed in them. |
pay | agent identity, payee identity, now, day, remit address, hold address | The signer is the remit's agent. now is before the expiry. The amount is greater than zero and within the cap per payment. The day's spend plus the amount is within the cap per day. The payee is in the payee tree, or the root is zero. The deadline is after now and at most 86,400 seconds later. The next remit keeps every term and is encrypted to the fixed view address. The hold carries the payee, the owner, the request hash and the deadline. |
settle | payee identity, deadline, fee rate, fee address | The signer is the hold's payee. The fee is amount × rate ÷ 10,000 rounded down and goes to the fee address. The rest goes to the payee's own address. |
refund | deadline | The whole hold goes to the owner named in it. |
revoke | owner identity | The signer is the remit's owner and everything goes to them. |
Errors
The program's errors are custom codes 9000 to 9014.
| Code | Name | Raised when |
|---|---|---|
| 9000 | ProofVerificationFailed | The proof of open, pay, settle, refund or revoke does not verify against the instruction's accounts and arguments. |
| 9001 | InvalidInstructionData | The data does not parse, or a payee's name, URL or description is outside its length. |
| 9002 | InvalidShieldedPoolProgram | The account passed as the Solana Privacy Program is another program. |
| 9003 | MissingAuthority | The authority the program signs for is not among the transact accounts. |
| 9004 | HashingFailed | A hash over the public values could not be computed. |
| 9005 | InvalidAuthorityBump | The bump in the arguments does not derive the authority. |
| 9006 | StaleClock | pay: now is ahead of the clock, more than 300 seconds behind it, or day is not now ÷ 86,400. |
| 9007 | HoldExpired | settle after the hold's deadline. |
| 9008 | HoldNotExpired | refund at or before the hold's deadline. |
| 9009 | InvalidConfig | The config account is not the program's config. |
| 9010 | NotAdmin | init_config by a key that is not the upgrade authority, or set_config by a key that is not the admin. |
| 9011 | InvalidPayeeRecord | The payee record is not the address derived for the payee, or update_payee by a key that is not its payee. |
| 9012 | InvalidFee | A fee above 10,000 basis points. |
| 9013 | AlreadyInitialized | init_config or register_payee on an account that exists. |
| 9014 | InvalidMessage | pay whose message is not the payee's address, or settle whose message is not the response hash. |
A payment that breaks a remit's terms has no valid proof. The SDK and the engine refuse it before a transaction exists, with the error that names the term. Sent anyway with a forged proof, it fails with 9000.