SDK
balance
How geode.balance rebuilds the holder's unspent notes, what the result means for payments, and the errors it raises.
balance(): Promise<Balance>balance rebuilds the holder's unspent notes from the pool's tree and returns their sum in lamports and their count.
What it does
Unlock the vault
On the client's first vault call, the wallet signs the key message and the manifest and notes are read, as in
recover.Read the tree
GET /treereturns every leaf (its index, commitment and encrypted memo) and every spent nullifier. The client checks that the leaves hash to the returned root. Everybalancecall reads the tree again.Find the holder's notes
The client tries to decrypt each memo with the view key; memos of other holders fail authentication and are skipped. A memo holds the amount and blinding only: the client recomputes the owner from the spending key and checks the commitment against the leaf. Notes whose nullifier is spent, and notes of zero lamports, are left out.
Sum
The amounts are summed as
bigintand returned as a decimal string.
Return value
lamportsstringnotesnumberA payment proof spends at most two notes, the two largest. A store payment succeeds when those two cover the storage price, Geode's fee and the network refund (networkLamports); an unshield succeeds when they cover the amount and the network refund. lamports counts every note. Each shield adds one note, and each payment that leaves change adds one change note. See Notes and the pool.
const { lamports, notes } = await geode.balance()
const sol = Number(BigInt(lamports)) / 1e9What it costs
Nothing. No transaction is sent.
Errors
| Code | Raised when |
|---|---|
VALIDATION_ERROR | A memo that decrypts under the view key has invalid fields or a commitment other than its leaf's |
WALLET_REJECTED | The client has no wallet, or the wallet declines the key message |
UNKNOWN_ROOT | The tree leaves the relayer returned do not hash to its root |
RELAYER_FAILED | A relayer reply does not match the contract |
WRONG_KEY, NOT_FOUND, IRYS_UNAVAILABLE, PAYLOAD_TOO_LARGE, CONFIGURATION_REQUIRED | The manifest cannot be read on first unlock |
UPSTREAM_UNAVAILABLE | A network failure or any other unrecognised error |
Codes from /tree and /manifest pass through as listed at /docs/api#errors.