Skip to main content

Dual balances, Note selection and remainder

Two balances require different evidence​

An ordinary balance comes from native-asset or token queries for an on-chain account. A private balance comes from authenticated decryption, asset and membership verification, and spending-state checks on Note inventory. A public address balance query cannot reveal its private balance.

Pin the network, token contract and decimals. Private inventory also needs a Core deployment and account scope. Tokens named USDT on different chains cannot be combined to fund one on-chain payment.

DisplaySuggested meaning
Ordinary balancePublic funds for the selected account and network
Private totalVerified private assets, with reservations shown separately
Private availableVerified inventory available for a new operation
Reserved / processingInputs assigned to an unresolved operation and unavailable for reuse
Unknown / syncingIncomplete scanning or unavailable evidence; not a confirmed zero

A portfolio total may combine valuations, with a visible breakdown. Avoid counting the same transitioning funds in both public balances and private inventory.

Automatic and manual selection​

Automatic selection chooses available inputs for the operation; the SDK and application determine the optimization policy. Manual selection should expose only usable Notes within the same account, asset and deployment. Recheck spending and reservations after selection. List amounts are snapshots, not a guarantee of spendability at signing.

Confirmation should show the required amount, selected total, count and shortfall. For a payment of 120 with inputs of 130, the remainder is 10 in a fee-free example. If fees are deducted from the same inputs, include them in the requirement rather than still promising a remainder of 10.

  • Insufficient inputs: block confirmation, show the shortfall and provide reselection.
  • Increased payment: recalculate immediately; prior selection does not bypass validation.
  • Exact coverage of outputs and fees: no remainder; do not promise an additional positive-value change Note.
  • Positive remainder: show its asset and receiving account; actual output construction follows the selected operation.

Distinguish two uses of “change”​

A remainder output from spending Note inventory differs from legacy product flows that add public funds to obscure a payment amount. Do not apply a public-deposit percentage formula to manual Note selection. Likewise, do not automatically apply a legacy single-token-instance assumption to a newer SDK/Core deployment.

Lifecycle​

Persist the operation and reserve inputs before proving or broadcasting. Keep reservations while the result is unknown; reconcile before confirming consumption, rollback or release. Historical membership, HTTP success or a transaction missing from one node cannot establish that an input is reusable.

Use WalletSession for inventory and recovery. See Note fund flows for permissions.