Notes & NoteStore
SDK note fields, lifecycle states, encrypted journal behavior, backups and production storage requirements.
The SDK Note contains a pool, asset, bigint amount, owner commitment, randomness, commitment and optional encrypted payload, leaf index, generation, state and transaction metadata. The commitment is verified against the note preimage when the encrypted file store loads it.
Note lifecycle
| State | Meaning |
|---|---|
available | Can be selected for a private operation. |
reserved | Locked to an operation while proving/preparing. |
submitted | A signature has been submitted; the result still needs reconciliation. |
spent | The canonical on-chain nullifier confirms consumption. |
The SDK's NoteStore interface supports getNotes, saveNote, reserveNote, markSubmitted, markSpent and releaseReservation. EncryptedFileNoteStore also journals operations, prepared transactions, output preimages and status transitions.
Encrypted file store
Create a durable store from the wallet seed and owner commitment:
const keys = keyHierarchy(seed);
const owner = ownerCommitment(keys.spendSecret);
const store = EncryptedFileNoteStore.fromSeed(noteStorePath, seed, owner);The journal is encrypted/authenticated with XChaCha20-Poly1305 and written as an append-only operation log. It contains note randomness and pending operation preimages; protect it like the seed. The production shieldedWallet path requires an explicit persistent NoteStore or storage path. InMemoryNoteStore is exported for tests, demos or ephemeral work, not production recovery.
Backups
exportBackup() returns the encrypted journal bytes; importBackup(bytes) validates and restores an encrypted backup. Keep the seed and journal/backup under a suitable custody policy. Losing both the seed and backups can prevent note recovery.
Private Swap output randomness is not included in the public event. If its local preimage and encrypted backup are lost, that output cannot be reconstructed from chain data alone. See Recovery & witnesses and Note security.