SDK

balance

How geode.balance rebuilds the holder's unspent notes, what the result means for payments, and the errors it raises.

TypeScript
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

  1. 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.

  2. Read the tree

    GET /tree returns every leaf (its index, commitment and encrypted memo) and every spent nullifier. The client checks that the leaves hash to the returned root. Every balance call reads the tree again.

  3. 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.

  4. Sum

    The amounts are summed as bigint and returned as a decimal string.

Return value

Balance
lamports
string
The sum of the unspent notes, in lamports, as a decimal string.
notes
number
How many unspent notes hold that sum.

A 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.

TypeScript
const { lamports, notes } = await geode.balance()
const sol = Number(BigInt(lamports)) / 1e9

What it costs

Nothing. No transaction is sent.

Errors

CodeRaised when
VALIDATION_ERRORA memo that decrypts under the view key has invalid fields or a commitment other than its leaf's
WALLET_REJECTEDThe client has no wallet, or the wallet declines the key message
UNKNOWN_ROOTThe tree leaves the relayer returned do not hash to its root
RELAYER_FAILEDA relayer reply does not match the contract
WRONG_KEY, NOT_FOUND, IRYS_UNAVAILABLE, PAYLOAD_TOO_LARGE, CONFIGURATION_REQUIREDThe manifest cannot be read on first unlock
UPSTREAM_UNAVAILABLEA network failure or any other unrecognised error

Codes from /tree and /manifest pass through as listed at /docs/api#errors.