Skip to main content

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 proof (orbproof1:)Payment slip (orbslip1:)
Made byThe payer's wallet, beside the slip of every payment to someone elseThe payer's wallet
The server holdsThe recipient's public orbpriv3: addressThe recipient's viewing key (orbview1:), which reads every payment to that address
ProvesThis payer made a payment of exactly this amount and asset to this address, and it is in the treeA 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 addressRefused (invalid-proof): only the viewing key proves that claimProven
Use it forSettling orders from the publicYour own wallet's reconciliation, or payers you already trust
FunctionverifyPaymentProofverifyPayment

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'
}
OptionMeaning
addressThe recipient's orbpriv3: privacy address
treeWhere 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​

  1. The proof decodes: scheme, field lengths and checksum.
  2. Its ephemeral secret is the memo's: [ephSk]·B equals 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.
  3. 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.
  4. Its asset and value equal expected, exactly.
  5. 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​

ResultMeaningWhat to do
{ ok: true, payment }Paid and final. payment has commitmentHex, value, assetId, sender and leafIndexMark the order paid, keyed on commitmentHex
invalid-proofMalformed, not this address's note, inconsistent, or the sender is named by addressRefuse
wrong-asset, wrong-amountA real payment to you, not the one this order expects. payment is includedRefuse for this order
not-on-chainThe note is not in the tree: never paid, or not landed yetRetry briefly, then refuse
not-finalIn a block, not finalized yetRetry in a few seconds
Throws TypeErroraddress is not a valid orbpriv3: address, expected is malformed, or tree cannot read the finalized chainA configuration bug: fix it
Throws another errorThe node could not answer, or answered nonsenseRetry; 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​

finalityAcceptsRisk
'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 fieldType
proofThe orbproof1: string
addressYour orbpriv3: address
valueThe expected amount, a decimal string in the asset's smallest unit
assetIdThe expected asset id, a decimal string. Required: there is no default asset
AnswerMeaning
{"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>
PartContents
viewingSecretKeyThe 32-byte incoming viewing secret key, hex
ownerPkThe 32-byte owner key from the recipient's privacy address, hex
checksum8 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);
RefusalMeaning
not-for-youNot sealed to this key, not this owner's note, or inconsistent
wrong-asset, wrong-amountA real slip, for another payment
not-on-chain, not-finalAs 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​

RuleWhy
One payment, one order. Key orders on the verified commitmentHex, under a unique constraint written in the same transaction that marks the order paidA 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 agreeThe 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 logsWhoever 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 chainA 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 answerRefusing an order on a node error can refuse a paid order