# Proof of balances

> An hourly Merkle sum tree over every balance, signed by the sequencer. Its total equals the supply, and every account can check it is counted.

Accounts on USD Network are [confidential](/wallet/confidential), so nobody can add up the balances themselves. Instead, every hour the sequencer takes every balance at one block height, builds a Merkle sum tree and signs its root and total. Anyone can check the total against the supply, and every account can check that its own balance is inside.

Live at [usd.net/explorer/balances](https://usd.net/explorer/balances) and `GET /balances`.

## The tree

:::steps
1. **One leaf per account with a balance.** `leaf = SHA-256(0x00 ‖ "usdnet-balance-v1" ‖ address (20 bytes) ‖ balance (u64, big-endian, in units of 10⁻⁶ USD₮) ‖ salt (32 bytes))`. The salt is `HMAC-SHA256(key, "<snapshot id>:<address>")` with a key only the sequencer holds, so a leaf can't be matched to a guessed address and balance. Each account gets its own salt with its proof.
2. **Sorted by leaf hash.** Neighbours in the tree are unrelated accounts.
3. **Nodes carry sums.** `node = SHA-256(0x01 ‖ left hash ‖ left sum (u64) ‖ right hash ‖ right sum (u64))`, and its sum is `left sum + right sum`. A node left over at the end of a level moves up unchanged.
4. **The root carries the total.** The sequencer signs `SHA-256` of the canonical JSON of `{ chain, count, height, id, kind: "usdnet-balances-v1", root, time, total }` with its Ed25519 key, the same key that signs [checkpoints](/open-data/checkpoints).
:::

## What it proves

- **Nothing is missing.** The signed total equals the supply at the same height: every USD₮ that exists is in somebody's leaf.
- **You are counted.** Your path rebuilds to the signed root with your exact balance. A sum can't be negative (each is an unsigned 64-bit number), so other balances can't cancel yours out.
- **It was this snapshot.** The signature ties root, total and height to the sequencer's key.

A path shows the sums of sibling subtrees on the way up. The sibling of your leaf is one other account's balance, never its address.

## Check it yourself

In the wallet: **Settings** → **Verify my balance**. Or by hand, with a [read pass](/build/api#confidential-reads):

```ts title="check-balance.ts"
import { sha256 } from '@noble/hashes/sha256';
import { ed25519 } from '@noble/curves/ed25519';
import { bytesToHex, concatBytes, hexToBytes, utf8ToBytes } from '@noble/hashes/utils';

const u64 = (v: bigint) => { const b = new Uint8Array(8); for (let i = 7; i >= 0; i--) { b[i] = Number(v & 0xffn); v >>= 8n; } return b; };
const hex = (b: Uint8Array) => bytesToHex(sha256(b));

const p = await (await fetch(`https://usd.net/api/v1/balances/proof/${address}`, { headers: { 'x-usd-read': pass } })).json();
let h = hex(concatBytes(new Uint8Array([0]), utf8ToBytes('usdnet-balance-v1'), hexToBytes(p.leaf.address.slice(2)), u64(BigInt(p.leaf.balance)), hexToBytes(p.leaf.salt)));
let s = BigInt(p.leaf.balance);
for (const step of p.path) {
  const ss = BigInt(step.s);
  h = step.left
    ? hex(concatBytes(new Uint8Array([1]), hexToBytes(step.h), u64(ss), hexToBytes(h), u64(s)))
    : hex(concatBytes(new Uint8Array([1]), hexToBytes(h), u64(s), hexToBytes(step.h), u64(ss)));
  s += ss;
}
const x = p.head;
const msg = JSON.stringify({ chain: x.chain, count: x.count, height: x.height, id: x.id, kind: 'usdnet-balances-v1', root: x.root, time: x.time, total: x.total });
console.log({
  included: h === x.root && s.toString() === x.total,
  signed: ed25519.verify(hexToBytes(p.sig), sha256(utf8ToBytes(msg)), hexToBytes(p.key)),
  equalsSupply: x.total === p.supply,
});
```

The keys of that JSON are already in sorted order, which is what canonical JSON needs.
