Most engineers coming from traditional web development approach blockchain ledger state by looking for account balances. They expect a database table where a wallet address maps directly to a static number. In a private, zero-knowledge ecosystem, account balances do not exist. Everything is structured as a Note.
Most product teams discover this architectural reality when they try to build custom accounting or reporting features on top of a private pool. They quickly realize they cannot simply query the chain for a user's total balance.
Instead, the ledger is a sea of separate, un-linkable cryptographic commitments. When a user holds $5,000 in a shielded pool, they don't have a single $5,000 balance. They own a collection of individual, distinct notes—perhaps one worth $3,000, one worth $1,500, and one worth $500. Each note is defined by its explicit value, the owner’s public key, and a unique blinding factor, all bound tightly inside an encrypted envelope.
Simple View vs. Operating Reality
- The Simple View: A wallet holds a single, updatable balance.
- The Operating Reality: A wallet holds a collection of discrete, immutable cryptographic notes.
- The Simple View: Spending money modifies an existing integer.
- The Operating Reality: Spending money destroys old notes and creates completely new ones.
What is a Shielded Note?
A Note is the fundamental unit of value within a shielded UTXO ledger model. It represents a specific asset amount and is strictly defined by three components:
- Its explicit value
- The owner's cryptographic public key
- A unique blinding factor
All of these elements are completely hidden from public view inside a cryptographic commitment.
Architecting Private Asset Ledgers
Do not let your product development get bogged down by complex UTXO state tracking. NetiRails seamlessly indexes and manages shielded note lifecycles behind standardized, easy-to-use API endpoints.
Deploy production-grade ZK state management with NetiRails. By handling the underlying note orchestration, NetiRails allows you to build intuitive, balance-focused user experiences without fighting the complexities of zero-knowledge architecture.
FAQ
How do you calculate a total wallet balance if there are only notes? Your client-side software uses its private viewing key to scan the ledger, locate every valid note belonging to you, decrypt their values, and sum them up locally.
What happens to a note when it is spent? The note is cryptographically invalidated on the ledger by publishing its corresponding nullifier. It can never be spent again, and any remaining change is returned to the user as a brand-new note.
Can a single note be split into smaller values? Yes. During a transaction, a large note can be consumed to create multiple new notes of smaller denominations—similar to breaking a large cash bill into smaller coins and change.
