Verifying Payments
A shop, an exchange or any service paid privately on Orbinum has to confirm that a payment arrived
before it delivers. The chain shows only commitments, so the backend checks what the payer hands it
against the recipient's address and the note tree. @orbinum/protocol does it two ways: from the
payer's payment proof, with the recipient's public address alone, or from a payment slip,
with the recipient's viewing key. This page shows both, end to end.
Table of Contents
- Which check to use
- Payment proofs
- Finality
- Backends not on Node
- Slip and viewing key
- Before you ship
Which check to use
Payment proof (orbproof1:) | Payment slip (orbslip1:) | |
|---|---|---|
| Made by | The payer's wallet, beside the slip of every payment to someone else | The payer's wallet |
| The server holds | The recipient's public orbpriv3: address | The recipient's viewing key (orbview1:), which reads every payment to that address |
| Proves | This payer made a payment of exactly this amount and asset to this address, and it is in the tree | A note to this address exists in the tree. Not who made it: a slip's fields are public on chain, so anyone can seal them to you |
| Sender named by address | Refused (invalid-proof): only the viewing key proves that claim | Proven |
| Use it for | Settling orders from the public | Your own wallet's reconciliation, or payers you already trust |
| Function | verifyPaymentProof | verifyPayment |
Settle orders from the public on proofs. A proof needs no secret on the server, so a breach of the server leaks no ability to read your income.
Payment proofs
import { OrbinumClient, verifyPaymentProof } from '@orbinum/protocol';
const client = await OrbinumClient.connect({ substrateWs: 'wss://rpc-1.testnet.orbinum.io' });
const result = await verifyPaymentProof(order.paymentProof, {
address: 'orbpriv3:…', // yours, public
tree: client.privacy,
expected: { value: order.amount, assetId: 0n }, // planck, bigint
});
if (result.ok) {
// One payment, one order: commitmentHex under a unique constraint, in the same write.
await markPaid(order.id, result.payment.commitmentHex);
} else if (result.reason === 'not-final') {
// Landed, not finalized yet: retry in a few seconds.
} else {
// 'invalid-proof' | 'wrong-asset' | 'wrong-amount' | 'not-on-chain'
}
| Option | Meaning |
|---|---|
address | The recipient's orbpriv3: privacy address |
tree | Where the commitment is looked up: client.privacy, or any NoteTreeLookup (getMerkleProofByCommitment, and getFinalizedLeafIndex unless finality is 'best') |
expected | { value, assetId } as bigints: the exact amount in the asset's smallest unit (more than zero) and the asset id (0n for ORB) |
finality | 'finalized' (default) or 'best'. See Finality |
What it checks
- The proof decodes: scheme, field lengths and checksum.
- Its ephemeral secret is the memo's:
[ephSk]·Bequals the ephemeral key in the memo, and the memo's view tag matches, so the recipient's wallet finds the same note when it scans. - With that ephemeral and the address's viewing key, the memo opens; the note is owned by the address (directly or through its stealth key) and recomputes to the proof's commitment, so the recipient's wallet can spend exactly this note.
- Its asset and value equal
expected, exactly. - Its commitment is in the note tree, in a finalized block by default.
The node is asked last, and only about a proof that passed every offline check, so an attacker cannot make your backend query the node about arbitrary commitments.
Results
| Result | Meaning | What to do |
|---|---|---|
{ ok: true, payment } | Paid and final. payment has commitmentHex, value, assetId, sender and leafIndex | Mark the order paid, keyed on commitmentHex |
invalid-proof | Malformed, not this address's note, inconsistent, or the sender is named by address | Refuse |
wrong-asset, wrong-amount | A real payment to you, not the one this order expects. payment is included | Refuse for this order |
not-on-chain | The note is not in the tree: never paid, or not landed yet | Retry briefly, then refuse |
not-final | In a block, not finalized yet | Retry in a few seconds |
Throws TypeError | address is not a valid orbpriv3: address, expected is malformed, or tree cannot read the finalized chain | A configuration bug: fix it |
| Throws another error | The node could not answer, or answered nonsense | Retry; never refuse an order that may be paid |
sender is what the payer chose to show: { kind: 'anonymous' } or { kind: 'pseudonym', name }.
A pseudonym is unverified text.
Checking offline
checkPaymentProof(proof, { address, expected }) runs steps 1–4 and stops before the chain, for a
backend that queries its node itself. It never throws on a bad proof, returns the same refusals
without not-on-chain and not-final, and on ok: true gives the payment without a leaf index.
Then look the commitment up at the finalized head:
import { checkPaymentProof, commitmentLeafIndexKey } from '@orbinum/protocol';
const check = checkPaymentProof(proof, { address, expected });
if (check.ok) {
const key = commitmentLeafIndexKey(check.payment.commitmentHex);
// state_getStorage(key, chain_getFinalizedHead()) on your node:
// non-null → paid and final; null → not paid or not final yet; an RPC error → retry.
}
commitmentLeafIndexKey is the storage key of the commitment in ShieldedPool.CommitmentToLeafIndex;
the value stored there is the leaf index as a SCALE u32.
Finality
finality | Accepts | Risk |
|---|---|---|
'finalized' (default) | A commitment in a finalized block, read from ShieldedPool.CommitmentToLeafIndex at the finalized head (client.privacy.getFinalizedLeafIndex) | None from reorganisation |
'best' | A commitment in the node's best block (privacy_getMerkleProofByCommitment) | A reorganisation can drop the block, and the payer can then spend the same notes again. Only for amounts you can afford to lose |
With the default, a payment that has landed but is not finalized yet is reported as not-final:
retry in a few seconds rather than refusing. Finality on Orbinum usually trails the best block by a
few blocks.
Backends not on Node
Every GitHub release of @orbinum/protocol attaches orbinum-verify.wasm, a WASI command that runs
checkPaymentProof: one JSON request on stdin, one JSON answer on stdout. Python (wasmtime), Go
(wazero), Rust, PHP and Ruby all embed WASI modules.
echo '{"proof":"orbproof1:…","address":"orbpriv3:…","value":"1500","assetId":"0"}' \
| wasmtime orbinum-verify.wasm
| Request field | Type |
|---|---|
proof | The orbproof1: string |
address | Your orbpriv3: address |
value | The expected amount, a decimal string in the asset's smallest unit |
assetId | The expected asset id, a decimal string. Required: there is no default asset |
| Answer | Meaning |
|---|---|
{"ok":true,"payment":{"commitmentHex","value","assetId","sender"},"storageKey":"0x…"} | The proof checks out offline. Amounts are decimal strings |
{"ok":false,"reason":"invalid-proof" | "wrong-asset" | "wrong-amount"} | Refuse, as above |
{"error":"…"} | The request is wrong (a missing field, a bad address): a bug to fix, not a payer to refuse |
On ok: true, read storageKey at your node's finalized head:
state_getStorage(storageKey, chain_getFinalizedHead()). Non-null means paid and final; null means
not paid, or not final yet (retry in a few seconds); an RPC error means retry. The released module
is the build CI tested, with a build-provenance attestation:
gh attestation verify orbinum-verify.wasm -R orbinum/ts-protocol
Slip and viewing key
A backend that holds the recipient's viewing key can verify a payment slip instead. The recipient
exports the key from their vault as an orbview1: string:
orbview1:<viewingSecretKey>:<ownerPk>:<checksum>
| Part | Contents |
|---|---|
viewingSecretKey | The 32-byte incoming viewing secret key, hex |
ownerPk | The 32-byte owner key from the recipient's privacy address, hex |
checksum | 8 hex characters of SHA-256 over the rest: a typo guard, not authentication |
import { OrbinumClient, decodeViewingKey, verifyPayment } from '@orbinum/protocol';
const key = decodeViewingKey(process.env.ORBINUM_VIEWING_KEY!); // null if malformed
if (!key) throw new Error('bad viewing key');
const result = await verifyPayment(slip, {
key,
tree: client.privacy,
expected: { value: order.amount, assetId: 0n },
});
if (result.ok) await markPaid(order.id, result.payment.commitmentHex);
| Refusal | Meaning |
|---|---|
not-for-you | Not sealed to this key, not this owner's note, or inconsistent |
wrong-asset, wrong-amount | A real slip, for another payment |
not-on-chain, not-final | As for proofs |
verifyPayment returns commitmentHex, value, assetId, sender and the leaf index the node
reports. It does not return the slip's own txHash or leaf index: whoever seals a slip states them,
and a payer could reseal one slip with another txHash to be paid twice by a backend keyed on it. A
refusal carries no payment, so the endpoint cannot be used to decrypt your incoming notes. Unlike a
proof, a slip proves a sender named by address.
A viewing key reads every payment sent to its address — amount, asset and declared sender — and
cannot be revoked. It cannot spend, or tell a spent note from an unspent one. Keep it like an API
secret, or prefer proofs. Its multiplications run on a constant-time path, but JavaScript BigInt
is not constant-time itself, so do not expose slip verification to unauthenticated traffic at
volume.
Before you ship
| Rule | Why |
|---|---|
One payment, one order. Key orders on the verified commitmentHex, under a unique constraint written in the same transaction that marks the order paid | A payer can repeat a txHash, a leaf index or your reference; never key on those. Check-then-insert races |
| Trust your node. Run one, or use one you trust; for large amounts, ask two independent nodes and require both to agree | The chain check believes the node that answers it, and names the commitment to it |
| Wait for finality. Keep the default | 'best' trades safety for seconds |
| A proof is a bearer token. Accept it only in the session that created the order it pays, over TLS. Store it with the order, never in logs | Whoever holds it can present it, and it shows that payment's amount and declared sender |
| Keep the proof. Your wallet finds payments by the memo on chain | A payer who lands the note with a different memo leaves the proof as the only key to it; the recipient's wallet can import it |
| Retry on errors. A thrown error means the node could not answer | Refusing an order on a node error can refuse a paid order |
Related
- @orbinum/protocol — the proof format and the verification exports
- Payment Slips — where users find the slip and the proof in the app
- Keys & Identity — what a viewing key can and cannot do
- Note Discovery — memos, view tags and stealth owner keys
- Verifying Disclosure Keys — proving one note to a third party