# Peal Private Links

Read this when the user wants to get paid privately, send money privately,
add a "pay me" link, or mentions Peal Links, Peal Private Links, Bonsai, a
private balance, or a payment whose amount should not be on a chain. It is a
different engine from sealed submissions: nothing here opens at a deadline.

## What exists, stated plainly

**A private payment ledger with a product on top.** A receiver creates a
request (an amount in one asset, a title, an optional reference and expiry) and
shares a link. The payer opens it, connects a wallet, and pays. Deposits and
withdrawals are public transactions through a gateway contract on the chain;
every payment in between is a zero-knowledge proof on a ledger built for
payments. The ledger learns which account acted. It does not learn the amount,
the other party, or whether it was a send or a receive.

**Today, hosted: Ethereum Sepolia only.** Circle's testnet USDC and a faucet
token, behind one hosted node at `https://peal.network/links/v1`. Tempo
Moderato is also deployed but is not hosted and not public. Test funds. Do
not tell a user it takes real money: the node refuses to run its settlement signers
or the dev-mint fixture beside a mainnet namespace, so no mainnet withdrawal is
possible today.

**What the user needs:** an EVM wallet. That is the whole identity. At setup
the wallet signs a sign-in message, a recovery message (twice, if it signs
deterministically) and the profile authorization; then a sign-in every twelve
hours and one approval per payment. Deposits and withdrawals are ordinary
transactions. Nothing that can spend leaves the client.

Live pages: `https://peal.network/developers/links` (the picture),
`https://peal.network/developers/links-api` (every route, and which ones are
public reads). The product is at
`https://peal.network/#/bonsai/app`, a checkout is `https://peal.network/pay/<id>`.

## What you can build on today

There is no published client library. The TypeScript client that proves and
signs lives inside the hosted app, and the repository it comes from is not
public. Do not tell the user to install `peal-links`, clone a repository, or
run their own node: none of those is available to them.

1. **The hosted app and checkout.** `https://peal.network/#/bonsai/app` sets
   up an account from one wallet, creates requests, funds, claims and
   withdraws. `https://peal.network/pay/<id>` is a complete checkout: it
   verifies the request, connects the wallet, funds, asks for the approval,
   proves in the browser and delivers the receipt. For "add a pay-me link",
   the receiver creates the request in the app and the integration links to
   the checkout.
2. **Public reads, `/links/v1`.** JSON over plain HTTP from any language, no
   key, no session: the node's configuration, the proving key digests, the
   public ledger, a request by id, deposit and withdrawal status. Use them to
   show a request's state, confirm a payment landed, or audit the ledger.
3. **Writes: not yet.** Registering, paying, claiming, depositing and
   withdrawing each carry a zero-knowledge proof or an account signature. A
   published client for them is coming. Until then, say so plainly rather
   than hand-roll proofs or signatures.

## The public reads

| call | what it returns |
| --- | --- |
| `GET /links/v1/status` | the namespaces (an asset on a chain: `id`, `label`, `chain_id`, `token_address`, `decimals`, `gateway`, `confirmations`, `available`), the `circuit_id`, the settlement signers and threshold, and a summary per ledger |
| `GET /links/v1/params` | the proving and verifying key files with their SHA-256 `digest` and `size`, and the `setup` they came from |
| `GET /links/v1/ledger/{ns}` | `seq`, `receipt_count`, `state_root`, `receipt_root`, `recent_roots[]`, `minted_total` |
| `GET /links/v1/ledger/{ns}/history?from=&limit=` | the public record: `ops[]` of `seq`, `kind` (`register`, `op`, ...) and the envelope. No amounts, no counterparties |
| `GET /links/v1/ledger/{ns}/accounting` | `minted_total`, `withdrawn_total`, `outstanding_liability`, as integer strings |
| `GET /links/v1/requests/{id}` | what a payer sees: the signed manifest (amount, title, reference, expiry), `status` (`active`, `expired`, `fulfilled`, `archived`), `reserved`, `fulfilled_at`. 404 `unknown_request` |
| `GET /links/v1/deposits/intents/{ns}/{receipt}` | `pending` or `minted` |
| `GET /links/v1/withdrawals/{ns}/{position}` | `status`, the certificate, and `tx_hash` once it is on the chain |

A request read is the node's word. The manifest is signed by the receiver's
private account; the checkout checks that signature and the receiver's
directory profile before paying. Until a published client can do the same
check in the user's code, show a request's state from this read but send
payment through the checkout.

## The procedure

Same discipline as a sealed-submission integration. Say what you found before
you build.

1. **Survey.** Who receives and who pays? What does the app need: a link to
   pay, a status to show, a record to audit? Is it on Sepolia? That is the
   only hosted chain.
2. **Say what is possible today.** Pay-me links through the hosted app and
   checkout, and reads from their own code. Accounts held by their own server
   or their own checkout page are not possible yet. If that is what they
   need, say so and stop there.
3. **Implement** the link and the reads. Amounts from `status` decimals, never
   floats.
4. **Verify** with the script below before reporting success.

## Verify before you say it is done

Checks the hosted node's public surface the way an integration reads it. Needs
Node 20 or newer, no key, no funds, a few seconds.

```js
// verify-links.mjs: node verify-links.mjs
const BASE = (process.env.PEAL_URL ?? 'https://peal.network') + '/links/v1';
let failures = 0;
const ok = (label, cond) => { if (!cond) failures++; console.log(`${cond ? 'ok  ' : 'FAIL'}  ${label}`); };
const get = async (path) => { const r = await fetch(BASE + path); return { status: r.status, body: await r.json() }; };
const hex32 = (v) => typeof v === 'string' && /^[0-9a-f]{64}$/.test(v);
const units = (v) => typeof v === 'string' && /^[0-9]+$/.test(v);

const { body: status } = await get('/status');
const ns = status.namespaces?.find((n) => n.label === 'sepolia/USDC');
ok('node answers with a circuit id', hex32(status.circuit_id));
ok('sepolia/USDC is served and available', !!ns?.available);
ok('decimals come from the namespace', ns?.decimals === 6);

const { body: params } = await get('/params');
ok('proving keys are for the same circuit', params.circuit_id === status.circuit_id);
ok('every key file carries a digest', Object.values(params.files ?? {}).every((f) => hex32(f.digest)));

const { body: ledger } = await get(`/ledger/${ns.id}`);
ok('ledger has a sequence and roots', Number.isInteger(ledger.seq) && hex32(ledger.state_root) && hex32(ledger.receipt_root));

const { body: history } = await get(`/ledger/${ns.id}/history?limit=5`);
ok('history is ordered and carries no amounts',
   Array.isArray(history.ops) && history.ops.every((o, i, a) => (i === 0 || o.seq > a[i - 1].seq) && !('amount' in o)));

const { body: acct } = await get(`/ledger/${ns.id}/accounting`);
ok('accounting is integer strings',
   units(acct.minted_total) && units(acct.withdrawn_total) && units(acct.outstanding_liability));
ok('liability is minted minus withdrawn',
   BigInt(acct.minted_total) - BigInt(acct.withdrawn_total) === BigInt(acct.outstanding_liability));

const missing = await get('/requests/AAAAAAAAAAAAAAAAAAAAAAAA');
ok('an unknown request is a 404 with a code', missing.status === 404 && missing.body.code === 'unknown_request');

console.log(failures === 0 ? '\nPASS' : `\nFAIL: ${failures} check(s) failed`);
process.exit(failures === 0 ? 0 : 1);
```

What a pass looks like: ten `ok` lines ending in `PASS`. What each failure
means:

- `sepolia/USDC is served and available` fails: the node's chain watcher
  cannot reach the RPC; nothing you did. Try later.
- `proving keys are for the same circuit` fails: the node is mid-upgrade.
  Try later; do not mix reads from before and after.
- `liability is minted minus withdrawn` fails: stop and report it. That is a
  ledger accounting fault, not an integration bug.

To see a payment end to end, make one in the hosted app with test funds and
read its position back from `history`.

## Money and encodings

- Amounts are decimal strings of integer base units on every boundary:
  `'12500000'` is 12.50 USDC. Decimals come from the namespace. Compare with
  `BigInt`. Never a float, never a number with a decimal point.
- Namespace ids, account ids, keys and tags are 32 bytes as 64 lowercase hex
  characters without `0x`. Addresses are lowercase `0x`. Timestamps are Unix
  seconds. Proofs are 128 bytes.

## What the server checks, and what it cannot

The node verifies sign-ins, profile signatures, request manifests, key
bindings, inbox read headers, withdrawal claims, and every zero-knowledge proof.
It cannot forge an account signature or a wallet signature, and cannot forge a
proof under the proof system's soundness assumption, so it cannot spend or forge
a receipt, and cannot release a withdrawal without the signer threshold. That
soundness assumption is itself unaudited today: per-process key setup, no
external review of the circuits.

The **client** must verify two things itself and never take the node's word:
the request manifest's signature against the receiver's account, and the
receiver's directory profile against the wallet address in it, including the
version chain. The hosted checkout does both before it asks the wallet for
anything.

## Errors

Every error body is `{ type, title, status, code, detail }`. Match on `code`.
On the public reads, the ones you will see:

| code | status | what happened |
|---|---|---|
| `unknown_request` | 404 | no request under that id |
| `unknown_namespace` | 404 | the namespace id is not served by this node |
| `unknown_account` | 404 | no account under that id in the namespace |
| `malformed` | 400 | an id that is not 64 lowercase hex characters, or a field element out of range |
| `not_enough_signers` / `chain_unreachable` | 503 | settlement cannot certify right now; retry |

The full table, writes included, is `reference/errors.md`.

## The trust model, stated plainly

Say these to the user; do not soften them.

- **Testnet only.** Sepolia, test tokens, one hosted node run by the operator.
- **Private, not unlinkable.** The node's directory knows which wallet owns
  which private account. The ledger shows which account acted and when.
  Deposits and withdrawals are public on the chain, and an observer can
  correlate them by amount and timing. Between them, the amount and the
  parties of a payment are on no chain.
- **Withdrawals are committee-attested, not trustless.** Two of three settlement
  signers certify a burn; today their keys live in one process. A compromised
  threshold can release reserves. If the operator disappears, funds not yet
  withdrawn are stuck. Never call the bridge trustless, ZK-settled or
  rollup-secured.
- **No ceremony, no audit.** The proving keys come from a per-process setup;
  the circuits are a pinned prototype revision with no external review.
- **Recovery is the user's.** The recovery signature or code never reaches the
  node. Losing the device and the recovery material loses the account.
- **The node can delay or refuse.** It cannot spend, read a balance, or read a
  receipt.
