Skip to main content

List notes by status, asset, or label

What this lets you do​

List your notes by filtering the array that session.exportAccount() returns. There is no dedicated query method, so you read your notes and filter the array by status, asset, label, value, or whatever else you need.

Common filter dimensions​

The dimensions you'll most often filter on:

  • Status: one of INACTIVE (not yet tracked), PENDING (awaiting attestation), ACTIVE (spendable), SPENT (already nullified), REJECTED (the ASP refused), or EXITED (exited via ragequit).
  • Asset: by tokenId, which is either the ETH placeholder or an ERC20 contract address.
  • Label: deposit lineage. All notes that trace back to a single deposit share a label.
  • Value: the note's value, in the asset's smallest unit. Filter or sort by it to find notes that cover an amount you want to spend.
  • Age: createdAtBlock, recorded when the note was created, to sort or filter by recency.

Filtering is plain array logic, so you can combine these freely, or match any other field such as a specific commitment or txHash.

Constraints & limits​

  • Local-only: the list reflects what your NoteManager knows. If you haven't discovered recently, the list may be stale.
  • No cross-account view: you only see notes addressed to you. If you are managing multiple addresses, you must aggregate per-address.
  • Label privacy: deposit labels are not exposed in deposit events: the Deposited and Note events carry no label field, and the deposit circuit computes the label in-circuit rather than as a public signal. A label only becomes public if you ragequit, because the Ragequit event publishes it. Grouping by label is fine for your own internal UI, but treat labels as locally held data rather than as public on-chain data.

What it unlocks next​

  • Private transfer, where you pick inputs by value, asset, and status.
  • Treasury dashboards that show the balance per asset and the count of pending versus active notes.
  • Label-aware spend planning to stay under the five-by-five circuit cap.

How to use it​

const NATIVE_ETH = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
const USDC = "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238";

const { notes } = await session.exportAccount();

// Spendable ETH notes, biggest first.
const spendableEth = notes
    .filter((n) => n.status === "ACTIVE" && n.tokenId === NATIVE_ETH)
    .sort((a, b) => (BigInt(b.value) > BigInt(a.value) ? 1 : -1));

// Group by label (for picking inputs that stay under the 5x5 circuit cap).
const byLabel = new Map();
for (const n of notes.filter((n) => n.status === "ACTIVE")) {
    if (!byLabel.has(n.label)) byLabel.set(n.label, []);
    byLabel.get(n.label).push(n);
}

// Pending balance for a UI badge.
const pendingUsdc = notes
    .filter((n) => n.status === "PENDING" && n.tokenId === USDC)
    .reduce((sum, n) => sum + BigInt(n.value), 0n);

Behind the scenes​

SDK call session.exportAccount(), followed by JavaScript array methods
Truth source NoteManager state from the configured persistent-storage adapter
Freshness The snapshot from the last discoverNotes() call. Refresh first if you need current state