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.
| Display | Suggested meaning |
|---|---|
| Ordinary balance | Public funds for the selected account and network |
| Private total | Verified private assets, with reservations shown separately |
| Private available | Verified inventory available for a new operation |
| Reserved / processing | Inputs assigned to an unresolved operation and unavailable for reuse |
| Unknown / syncing | Incomplete 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.