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 mainnet7pG4N8LwyWoHAbKBUqqjC5Z8S8xyUfAUZHv2DAD3M13o
remit on devnet7pG4N8LwyWoHAbKBUqqjC5Z8S8xyUfAUZHv2DAD3M13o
remit on a local network7pG4N8LwyWoHAbKBUqqjC5Z8S8xyUfAUZHv2DAD3M13o
Solana Privacy Programring1GaLCuJnkUMVkX2JeZLTTX17wKsV4fZmPVzXANW
User Registryregy3WAeRXMYuMYxr5iK3Bf9Arr3PcxGxyzAddbiqDQ

GET /v1/config returns the program id of the cluster an API serves.

Program addresses

AddressSeedsWhat it is
remit authority"remit_authority", ownerOwns every remit that owner opens.
hold authority"hold_authority", payeeOwns every hold paid to that payee.
config"config"The fee, the fee recipient and the admin.
payee record"payee", payeeA 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.

OffsetSizeField
01Kind, always 1.
11Bump.
232admin: the key that can change the config.
342fee_bps: the protocol fee in basis points, u16 little-endian, at most 10,000.
3632The fee recipient's owner hash.
6833The fee recipient's viewing public key.
10132The fee recipient's signing public key.
13332The 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.

OffsetSizeField
01Kind, always 2.
11Bump.
232payee: the wallet that registered.
3432mint: the mint the payee prices in.
668price_hint: u64 little-endian, base units of mint.
748settled: u64 little-endian.
828refunded: u64 little-endian.
908first_settled_at: i64 little-endian unix seconds, 0 until the first settlement.
981 + 64name: one length byte, then up to 64 bytes.
1631 + 200url: one length byte, then up to 200 bytes.
3642 + 280description: 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.

FieldTypeMeaning
ownerUTXO ownerThe owner: paid by refunds and by revoke, and the only signer of revoke.
agent32 bytesThe owner identity of the agent key, the only signer pay accepts.
view_address32 bytesThe 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_capu64
daily_capu64
dayu64The UTC day (unix ÷ 86,400) that spent_today counts.
spent_todayu64
payee_root32 bytesThe Poseidon Merkle root of up to 32 payee identities in a tree of depth 5. Zero for any payee.
expires_atu64Unix seconds.
last_request32 bytesThe request hash of the latest payment.
last_deadlineu64The deadline of the latest payment's hold.

The amount and the mint are the balance's own fields.

Hold terms

FieldTypeMeaning
payee32 bytesThe owner identity of the payee, the only signer settle accepts.
ownerUTXO ownerThe remit's owner, whom a refund pays.
request_hash32 bytesThe hash of the request the payment is for.
deadlineu64Unix 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.

Accountsadmin (signer, writable), config (writable), the program's program-data account, system program
Datafee_bps (u16), then the fee recipient: owner hash (32), viewing key (33), signing key (32), nullifier key (32)
ChecksThe 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.

Accountsadmin (signer), config (writable)
DataAs init_config, then the admin from here on (32)
ChecksThe 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.

Accountspayee (signer, writable), payee record (writable), system program
Datamint (32), price_hint (u64), name (u8 length, bytes), URL (u8 length, bytes), description (u16 length, bytes)
ChecksThe 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.

Accountspayee (signer), payee record (writable)
DataAs register_payee
ChecksThe signer is the record's payee.

4 open

Moves an amount from the owner's private balance into a new remit.

Accountsowner (signer)
Argumentsproof (128), the agent's viewing key (33), the owner's viewing key (33), remit authority bump
ChecksThe open proof, against the owner and the remit's two addresses.
SignsThe owner's remit authority.
OutputsThe owner's change, and the remit, encrypted to the agent.

5 pay

Pays from a remit into a hold.

Accountsagent (signer), owner, payee
Argumentsproof, now (u64), day (u64), the owner's viewing key, the payee's viewing key, remit authority bump, hold authority bump
Checksnow 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.
SignsThe owner's remit authority and the payee's hold authority.
OutputsThe next remit, encrypted to the owner, and the hold, encrypted to the payee.

6 settle

Pays a hold to its payee, less the fee.

Accountspayee (signer), config, payee record (writable)
Argumentsproof, deadline (u64), response_hash (32), hold authority bump
ChecksThe 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.
Effectssettled goes up by one. first_settled_at is set if it was zero.
SignsThe payee's hold authority.
OutputsThe 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.

Accountscaller (signer), payee, payee record (writable)
Argumentsproof, deadline (u64), hold authority bump
ChecksThe clock is after deadline. The refund proof.
Effectsrefunded goes up by one.
SignsThe payee's hold authority.
OutputsThe 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.

Accountsowner (signer)
Argumentsproof, remit authority bump
ChecksThe revoke proof.
SignsThe owner's remit authority.
OutputsEverything 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.

CircuitPublic valuesWhat it proves
openowner identity, remit address, view addressThe 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.
payagent identity, payee identity, now, day, remit address, hold addressThe 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.
settlepayee identity, deadline, fee rate, fee addressThe 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.
refunddeadlineThe whole hold goes to the owner named in it.
revokeowner identityThe signer is the remit's owner and everything goes to them.

Errors

The program's errors are custom codes 9000 to 9014.

CodeNameRaised when
9000ProofVerificationFailedThe proof of open, pay, settle, refund or revoke does not verify against the instruction's accounts and arguments.
9001InvalidInstructionDataThe data does not parse, or a payee's name, URL or description is outside its length.
9002InvalidShieldedPoolProgramThe account passed as the Solana Privacy Program is another program.
9003MissingAuthorityThe authority the program signs for is not among the transact accounts.
9004HashingFailedA hash over the public values could not be computed.
9005InvalidAuthorityBumpThe bump in the arguments does not derive the authority.
9006StaleClockpay: now is ahead of the clock, more than 300 seconds behind it, or day is not now ÷ 86,400.
9007HoldExpiredsettle after the hold's deadline.
9008HoldNotExpiredrefund at or before the hold's deadline.
9009InvalidConfigThe config account is not the program's config.
9010NotAdmininit_config by a key that is not the upgrade authority, or set_config by a key that is not the admin.
9011InvalidPayeeRecordThe payee record is not the address derived for the payee, or update_payee by a key that is not its payee.
9012InvalidFeeA fee above 10,000 basis points.
9013AlreadyInitializedinit_config or register_payee on an account that exists.
9014InvalidMessagepay 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.

Loading the index