Docs1Concepts

Section 1

Concepts

Nine terms carry the whole system.

1.1Private balance

Privacy Rings, built by Helius, gives an SPL token a shielded balance. A deposit moves tokens from a public token account into it. A transfer moves value from one private balance to another. A withdrawal moves tokens back out to a public address.

In the default ring, the amount of a transfer is hidden, and so is the balance it leaves behind. The sender address and the recipient address are visible. The amounts of deposits and withdrawals are visible. The privacy model has the full table.

1.2Agent wallet

An AgentWallet is one Solana address, one asset and one policy. It is the only object your agent code touches. It prices a payment, asks the policy, sends the transfer through the rail and stores a receipt. It runs in your process, next to the agent, and the model never sees the key.

1.3Policy

A policy is a small JSON file the owner writes: a cap per payment, a budget per rolling 24 hours, an allow-list of payees and an expiry. The wallet checks it before anything is signed. A refused payment throws an error that names the rule, and nothing is sent. See Policies.

The policy is enforced by the wallet process. It is not an on-chain program, so it constrains whatever spends through the wallet and nothing else that might hold the same key.

1.4Rail

A rail is the interface between the wallet and a private balance: balance, transfer, deposit, withdraw, isRegistered and signMessage. RingsRail implements it over @heliuslabs/spr. MemoryRail implements it in memory, with the same visibility rules, so tests and dry runs exercise the real wallet code without a network.

1.5Payee registration

An address can receive a private transfer only after it has registered with Privacy Rings, a one-time transaction that publishes its shielded address. The wallet checks this before paying and fails with PAYEE_NOT_REGISTERED if the payee has not done it.

1.6The 402 exchange

HTTP has had a status code for this since 1997: 402 Payment Required. A provider answers an unpaid request with 402 and a price. The wallet pays that price as a private transfer, repeats the request with a signed proof, and gets the response. One call to wallet.fetch does all of it. The wire format is in HTTP 402.

1.7Protocol fee

The SDK can add a protocol fee to each payment as a second output of the same transfer. The rate is 1% of the amount, rounded up to one base unit. The fee counts toward the policy limits, so a cap of 0.05 means 0.05 leaves the balance at most. Collected fees are meant to fund buybacks of DOEI. See Token.

1.8Receipt

Each payment produces a receipt: payee, amount, fee, total, transaction signature, and the memo and URL if there were any. Receipts stay with the wallet. The memo is never written on-chain.

1.9Viewing key

A viewing key is a read-only export of a wallet's shielded keys. Whoever holds it can read every amount that wallet sent and received. It cannot sign and cannot move funds. It is how an owner, a finance team or an auditor reads the books of an agent without being able to spend from it.