@orbinum/sdk 1.0.1 → 1.1.1

package/dist/index.d.mts

@@ -4779,6 +4779,97 @@ declare function decodeNoteTransferPage(uri: string): NoteTransferPayload;
  */
 declare function assembleNoteTransfer(pages: NoteTransferPayload[]): NoteTransferEntry[];
 
+/**
+ * CLOSED JSON backup of notes — the same notes moved between a user's devices as
+ * a plain file, WITHOUT exposing any spending key.
+ *
+ * ## The idea
+ *
+ * A backup entry carries only what is already PUBLIC on chain: the commitment and
+ * the encrypted memo. It contains no spending key, so the file is safe to hold
+ * and even share — it grants nothing on its own.
+ *
+ * On import, the recipient DECRYPTS each memo with their own viewing key
+ * (`importNotesFromBackup`). Decryption is the proof of ownership:
+ *   - the memo decrypts → the note is theirs → a full spendable `ZkNote` is
+ *     reconstructed, spending key and stealth key derived from their identity;
+ *   - the memo does not decrypt → the note is someone else's → it is dropped.
+ *
+ * This is NOT a chain scan: only the N memos in the backup are tried, not the
+ * whole pool. It moves notes between devices without re-scanning, and a note that
+ * is not yours simply fails to import.
+ *
+ * ## What travels vs what does not
+ *
+ * Travels: `commitmentHex`, `encryptedMemo`, and `leafIndex` (informational).
+ * Does NOT travel: value, ownerPk, blinding, spendingKey — all recovered by
+ * decrypting the memo. The Merkle proof is re-fetched at spend time.
+ */
+
+/** Current backup format version. Bumped only if the entry shape changes. */
+declare const NOTE_BACKUP_VERSION: 1;
+/**
+ * One note in a closed backup — public data only. Field names are short but not
+ * cryptic; readability matters more than density in a file (unlike the QR path).
+ */
+interface NoteBackupEntry {
+    /** 0x-prefixed 32-byte LE commitment hex. */
+    commitmentHex: string;
+    /** 0x-prefixed encrypted memo hex (180 bytes). Decrypted on import. */
+    encryptedMemo: string;
+    /** Merkle leaf index, when known. Informational — spends re-fetch the proof. */
+    leafIndex?: number;
+    /**
+     * Whether the note was already spent when exported. A local status flag (not
+     * a key or secret), carried so a restored vault separates available from spent
+     * without a chain round-trip. A host may still reconcile against the chain
+     * afterward — this is a fast, possibly-stale hint, not the source of truth.
+     */
+    spent?: boolean;
+    /** Local timestamp the note was marked spent, when known. */
+    spentAt?: number | null;
+}
+interface NoteBackup {
+    v: typeof NOTE_BACKUP_VERSION;
+    /** Export time (ms). Informational. */
+    ts: number;
+    notes: NoteBackupEntry[];
+}
+/** Keys the importer needs to prove ownership by decrypting each memo. */
+interface BackupImportKeys {
+    /** 32-byte viewing secret key (ivsk). */
+    viewingSecretKey: Uint8Array;
+    /** Spending key scalar — folded into the derived stealth key / nullifier. */
+    spendingKey: bigint;
+    /** The importer's global owner pk (Ax), for stealth detection. */
+    ownerPk: bigint;
+}
+/**
+ * Encode notes into a closed JSON backup. Carries the memo, not the keys.
+ * `now` is injectable for a deterministic export (tests).
+ */
+declare function encodeNoteBackup(notes: ZkNote[], options?: {
+    now?: () => number;
+}): NoteBackup;
+/**
+ * Decode a JSON backup (string or object) into entries. Strict: a malformed
+ * payload is rejected rather than partially imported.
+ */
+declare function decodeNoteBackup(json: string | object): NoteBackupEntry[];
+/**
+ * Import a closed backup: decrypt each entry's memo with the importer's keys and
+ * return the notes that belong to them as full, spendable `ZkNote`s.
+ *
+ * Ownership is proven by decryption — an entry whose memo does not open under
+ * these keys is silently skipped (it is not this user's note). No chain access:
+ * only the backup's own memos are tried.
+ *
+ * The decrypted note is reconstructed as unspent; the entry's `spent`/`spentAt`
+ * flags are then applied so a restored vault separates available from spent. A
+ * host may reconcile against the chain afterward if the backup could be stale.
+ */
+declare function importNotesFromBackup(entries: NoteBackupEntry[], keys: BackupImportKeys): ZkNote[];
+
 /**
  * The steps every spend shares, in the order a spend performs them.
  *
@@ -5386,4 +5477,4 @@ declare class OrbinumWallet {
     private requireKey;
 }
 
-export { type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BlockInfo, type BuildNoteDeps, type BuildNoteParams, type Bytes32, CachedNullifier, type ChainInfo, ChainModule, type ChunkInfo, CircuitId, CircuitVersionResolver, type ClaimShieldedFeesParams, type ClientProviderConfig, type CoinSelection, type CollectScanEntriesParams, type CommitmentsInsertedEvent, type ConnectionStatus, type CryptoKey$1 as CryptoKey, CryptoPrecompiles, type DecodedPrecompile, DecryptPool, DecryptedMemo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, EncryptedNoteRecord, EncryptedTxRecord, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFacts, type ExtrinsicRecord, type FeeClaimDeps, type FeeClaimParams, type FeeClaimProofInputs, type FeeClaimProofOutput, type FeeClaimStep, type FormatOptions, KNOWN_PALLET_ERRORS, KNOWN_PRECOMPILES, type KnownPrecompileInfo, LEAVES_PER_TREE, MIN_GASLESS_FEE, MIN_SIGNATURE_BYTES, MemoryVaultStorage, type MerkleRootUpdatedEvent, type MutableWalletSession, NATIVE_ASSET_ID, NOTE_BIGINT_FIELDS, NOTE_TRANSFER_URI_SCHEME, type NoteBuildKeys, NoteBuilder, type NoteDisclosure, NoteInput, NoteStatusUpdate, NoteStorage, type NoteTransferEntry, type NoteTransferPayload, type NoteWithMeta, type NotesCache, NullifierCache, type NullifierChunkBody, type NullifierManifest, type NullifierSource, NullifierSyncMeta, type NullifierTail, type NullifiersSpentEvent, type ObservableNotesCache, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, OrbinumWallet, type OrbinumWalletConfig, PAGE_SIZE, PRECOMPILE_ADDR, type PairwiseEphWindowEntry, type PalletErrorKind, type PersistParams, type PrecompileMethod, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type ProofOptions, type ProviderFactory, QR_PAGE_MAX_CHARS, RECOVERED_TX_RESULT, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type ReconstructDeps, type ReconstructedTxRecord, type RegisterAssetArgs, type RelayerInfo, RelayerStatusModule, type ResolveSpentSetParams, type ResolvedProverVersion, type ResolvedSpendVersion, type RpcV2MerkleProof, RpcV2Module, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, type RunScanParams, SPENDING_KEY_CANONICAL_ORIGIN, SPENDING_KEY_VERIFYING_CONTRACT, SPENDING_KEY_WARNING, type ScanChunkManifest, ScanCommitment, type ScanHint, type ScanHintPage, type ScanHintSource, ScanKeys, type ScanOptions, type ScanOutcome, type ScanProgress, type ScanResult, SecretStore, type SelfEphWindowEntry, type SelfStealthKeys, type SessionCacheDeps, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedEvent, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SpendDetails, type SpendPlanProblem, type SpendPrivacyReads, type SpendVault, type SpendableInputsCheck, type SpendingKeyTypedData, type StatusChangeEvent, type StatusListener, SubstrateClient, type SystemHealth, TRANSFER_INPUTS, TRANSFER_OUTPUTS, type TokenInfo, type TokenTransfer, type TransferDeps, type TransferFactsRow, type TransferFactsSource, type TransferInputNote, type TransferOutputNote, type TransferParams, type TransferPlan, type TransferStep, type TransferSubmitRequest, type TxFactsSource, TxHistoryStore, type TxKind, type TxLandingPollOptions, type TxResult, type UnsafeTxOptions, type UnshieldArgs, type UnshieldDeps, type UnshieldNoteParams, type UnshieldParams, type UnshieldPlan, type UnshieldProofInputs, type UnshieldProofResult, type UnshieldStep, type UnshieldSubmitRequest, type UnshieldedEvent, type UnverifyAssetArgs, VAULT_SCHEMA_VERSION, VaultConfigRecord, VaultLockedError, VaultStorage, VaultStore, type VaultStoreDeps, type VaultUnlockOptions, type VerifyAssetArgs, type VersionedArtifactProvider, type WalletScanKeys, type WalletSession, ZkNote, type ZkVerifierCircuitVersionInfo, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, addressToFieldElement, applyBatch, applyNoteStatus, assembleNoteTransfer, base64UrlDecode, base64UrlEncode, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildConfig, buildDummyTransferInput, buildShieldBatchOperations, buildShieldParams, buildZkNote, bytesToBigintLE, bytesToBjjScalar, cacheSession, canPairWith, canonicalAccountId, chainActiveCircuitVersion, checkSpendableInputs, claimFees, classifyChainError, clearSession, collectNullifiersToQuery, collectScanEntries, commitmentHexOf, computeNoteCommitment, computeNullifier, computePathIndices, connectInjectedExtension, createNoteDisclosureKey, createNotesCache, createWalletSession, decodeNoteDisclosureKey, decodeNoteTransferPage, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, derivePairwiseEphSk, derivePairwiseSharedSecret, deriveSelfEphSk, deriveSpendingKeyFromMaster, deriveSpendingKeyFromSignature, deriveSpendingKeyMessageV2, deriveSpendingKeyTypedData, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewTag, deriveViewingPublicKey, deriveViewingSecretKey, detectCommitmentMismatch, encodeNoteTransferPages, encryptJson, encryptNote, ensureCreatedAt, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, extractPalletError, failed, fastMulBase, fastMulPoint, fetchExtrinsicFacts, formatAmountPlain, formatBalance, formatORB, fromBase64, fromHex, gapMargin, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getInjectedExtensions, getPrecompileLabel, hasCachedSession, hasInjectedExtensions, hexToBigint, hexToNumber, implicitSubstrateToEvm, isAbortError, isAlreadySpentError, isConnectionLossError, isEvmAddress, isGhostNoteError, isImplicitEvmAccount, isNativeAsset, isNoteSelfConsistent, isSpendable, isSs58, isSubstrateAddress, isUnifiedAddress, isValidLeafIndex, leHexToBigint, mapExtrinsicArgs, mapZkEventData, markInputsSpent, normalizeChainFingerprint, normalizeEvmAddress, normalizeNote, normalizeNotes, noteBlindTag, noteCreatedAt, noteCreatedTxHash, noteMatchesCommitment, noteOrigin, noteSpentTxHash, noteToTransferEntry, noteTxKind, pairwiseEphWindow, palletErrorKind, parseAmount, parseEvmAddress, persistCursor, persistScanResults, planTransfer, planUnshield, randomBlinding, reconstructOutgoingTxRecords, recoverOwnerPkPoint, recoverSelfStealthNote, refuseIfAlreadySpent, removeByCommitment, requireSessionKeys, reservePairwiseIndex, reserveSelfEphIndex, resolveSelfEphCeiling, resolveSpentSet, resolveSpentStatus, restoreSession, runScan, scalarToHex, scanAbortError, selectGhosts, selectNotes, selfEphWindow, serializeMemo, sessionCacheKey, shortHash, signAndSubmitTx, spendableBalance, stampCreatedAt, stampCreatedTxHash, stampSpentTxHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, transferNotes, treeIdOf, treeOf, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, txLandedAfterError, unshieldNote, upsertNote, vaultReplacer, vaultReviver, vaultStorageName, windowSizeForCounter };
+export { type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BackupImportKeys, type BlockInfo, type BuildNoteDeps, type BuildNoteParams, type Bytes32, CachedNullifier, type ChainInfo, ChainModule, type ChunkInfo, CircuitId, CircuitVersionResolver, type ClaimShieldedFeesParams, type ClientProviderConfig, type CoinSelection, type CollectScanEntriesParams, type CommitmentsInsertedEvent, type ConnectionStatus, type CryptoKey$1 as CryptoKey, CryptoPrecompiles, type DecodedPrecompile, DecryptPool, DecryptedMemo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, EncryptedNoteRecord, EncryptedTxRecord, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFacts, type ExtrinsicRecord, type FeeClaimDeps, type FeeClaimParams, type FeeClaimProofInputs, type FeeClaimProofOutput, type FeeClaimStep, type FormatOptions, KNOWN_PALLET_ERRORS, KNOWN_PRECOMPILES, type KnownPrecompileInfo, LEAVES_PER_TREE, MIN_GASLESS_FEE, MIN_SIGNATURE_BYTES, MemoryVaultStorage, type MerkleRootUpdatedEvent, type MutableWalletSession, NATIVE_ASSET_ID, NOTE_BACKUP_VERSION, NOTE_BIGINT_FIELDS, NOTE_TRANSFER_URI_SCHEME, type NoteBackup, type NoteBackupEntry, type NoteBuildKeys, NoteBuilder, type NoteDisclosure, NoteInput, NoteStatusUpdate, NoteStorage, type NoteTransferEntry, type NoteTransferPayload, type NoteWithMeta, type NotesCache, NullifierCache, type NullifierChunkBody, type NullifierManifest, type NullifierSource, NullifierSyncMeta, type NullifierTail, type NullifiersSpentEvent, type ObservableNotesCache, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, OrbinumWallet, type OrbinumWalletConfig, PAGE_SIZE, PRECOMPILE_ADDR, type PairwiseEphWindowEntry, type PalletErrorKind, type PersistParams, type PrecompileMethod, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type ProofOptions, type ProviderFactory, QR_PAGE_MAX_CHARS, RECOVERED_TX_RESULT, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type ReconstructDeps, type ReconstructedTxRecord, type RegisterAssetArgs, type RelayerInfo, RelayerStatusModule, type ResolveSpentSetParams, type ResolvedProverVersion, type ResolvedSpendVersion, type RpcV2MerkleProof, RpcV2Module, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, type RunScanParams, SPENDING_KEY_CANONICAL_ORIGIN, SPENDING_KEY_VERIFYING_CONTRACT, SPENDING_KEY_WARNING, type ScanChunkManifest, ScanCommitment, type ScanHint, type ScanHintPage, type ScanHintSource, ScanKeys, type ScanOptions, type ScanOutcome, type ScanProgress, type ScanResult, SecretStore, type SelfEphWindowEntry, type SelfStealthKeys, type SessionCacheDeps, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedEvent, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SpendDetails, type SpendPlanProblem, type SpendPrivacyReads, type SpendVault, type SpendableInputsCheck, type SpendingKeyTypedData, type StatusChangeEvent, type StatusListener, SubstrateClient, type SystemHealth, TRANSFER_INPUTS, TRANSFER_OUTPUTS, type TokenInfo, type TokenTransfer, type TransferDeps, type TransferFactsRow, type TransferFactsSource, type TransferInputNote, type TransferOutputNote, type TransferParams, type TransferPlan, type TransferStep, type TransferSubmitRequest, type TxFactsSource, TxHistoryStore, type TxKind, type TxLandingPollOptions, type TxResult, type UnsafeTxOptions, type UnshieldArgs, type UnshieldDeps, type UnshieldNoteParams, type UnshieldParams, type UnshieldPlan, type UnshieldProofInputs, type UnshieldProofResult, type UnshieldStep, type UnshieldSubmitRequest, type UnshieldedEvent, type UnverifyAssetArgs, VAULT_SCHEMA_VERSION, VaultConfigRecord, VaultLockedError, VaultStorage, VaultStore, type VaultStoreDeps, type VaultUnlockOptions, type VerifyAssetArgs, type VersionedArtifactProvider, type WalletScanKeys, type WalletSession, ZkNote, type ZkVerifierCircuitVersionInfo, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, addressToFieldElement, applyBatch, applyNoteStatus, assembleNoteTransfer, base64UrlDecode, base64UrlEncode, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildConfig, buildDummyTransferInput, buildShieldBatchOperations, buildShieldParams, buildZkNote, bytesToBigintLE, bytesToBjjScalar, cacheSession, canPairWith, canonicalAccountId, chainActiveCircuitVersion, checkSpendableInputs, claimFees, classifyChainError, clearSession, collectNullifiersToQuery, collectScanEntries, commitmentHexOf, computeNoteCommitment, computeNullifier, computePathIndices, connectInjectedExtension, createNoteDisclosureKey, createNotesCache, createWalletSession, decodeNoteBackup, decodeNoteDisclosureKey, decodeNoteTransferPage, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, derivePairwiseEphSk, derivePairwiseSharedSecret, deriveSelfEphSk, deriveSpendingKeyFromMaster, deriveSpendingKeyFromSignature, deriveSpendingKeyMessageV2, deriveSpendingKeyTypedData, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewTag, deriveViewingPublicKey, deriveViewingSecretKey, detectCommitmentMismatch, encodeNoteBackup, encodeNoteTransferPages, encryptJson, encryptNote, ensureCreatedAt, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, extractPalletError, failed, fastMulBase, fastMulPoint, fetchExtrinsicFacts, formatAmountPlain, formatBalance, formatORB, fromBase64, fromHex, gapMargin, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getInjectedExtensions, getPrecompileLabel, hasCachedSession, hasInjectedExtensions, hexToBigint, hexToNumber, implicitSubstrateToEvm, importNotesFromBackup, isAbortError, isAlreadySpentError, isConnectionLossError, isEvmAddress, isGhostNoteError, isImplicitEvmAccount, isNativeAsset, isNoteSelfConsistent, isSpendable, isSs58, isSubstrateAddress, isUnifiedAddress, isValidLeafIndex, leHexToBigint, mapExtrinsicArgs, mapZkEventData, markInputsSpent, normalizeChainFingerprint, normalizeEvmAddress, normalizeNote, normalizeNotes, noteBlindTag, noteCreatedAt, noteCreatedTxHash, noteMatchesCommitment, noteOrigin, noteSpentTxHash, noteToTransferEntry, noteTxKind, pairwiseEphWindow, palletErrorKind, parseAmount, parseEvmAddress, persistCursor, persistScanResults, planTransfer, planUnshield, randomBlinding, reconstructOutgoingTxRecords, recoverOwnerPkPoint, recoverSelfStealthNote, refuseIfAlreadySpent, removeByCommitment, requireSessionKeys, reservePairwiseIndex, reserveSelfEphIndex, resolveSelfEphCeiling, resolveSpentSet, resolveSpentStatus, restoreSession, runScan, scalarToHex, scanAbortError, selectGhosts, selectNotes, selfEphWindow, serializeMemo, sessionCacheKey, shortHash, signAndSubmitTx, spendableBalance, stampCreatedAt, stampCreatedTxHash, stampSpentTxHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, transferNotes, treeIdOf, treeOf, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, txLandedAfterError, unshieldNote, upsertNote, vaultReplacer, vaultReviver, vaultStorageName, windowSizeForCounter };

package/dist/index.d.ts

@@ -4779,6 +4779,97 @@ declare function decodeNoteTransferPage(uri: string): NoteTransferPayload;
  */
 declare function assembleNoteTransfer(pages: NoteTransferPayload[]): NoteTransferEntry[];
 
+/**
+ * CLOSED JSON backup of notes — the same notes moved between a user's devices as
+ * a plain file, WITHOUT exposing any spending key.
+ *
+ * ## The idea
+ *
+ * A backup entry carries only what is already PUBLIC on chain: the commitment and
+ * the encrypted memo. It contains no spending key, so the file is safe to hold
+ * and even share — it grants nothing on its own.
+ *
+ * On import, the recipient DECRYPTS each memo with their own viewing key
+ * (`importNotesFromBackup`). Decryption is the proof of ownership:
+ *   - the memo decrypts → the note is theirs → a full spendable `ZkNote` is
+ *     reconstructed, spending key and stealth key derived from their identity;
+ *   - the memo does not decrypt → the note is someone else's → it is dropped.
+ *
+ * This is NOT a chain scan: only the N memos in the backup are tried, not the
+ * whole pool. It moves notes between devices without re-scanning, and a note that
+ * is not yours simply fails to import.
+ *
+ * ## What travels vs what does not
+ *
+ * Travels: `commitmentHex`, `encryptedMemo`, and `leafIndex` (informational).
+ * Does NOT travel: value, ownerPk, blinding, spendingKey — all recovered by
+ * decrypting the memo. The Merkle proof is re-fetched at spend time.
+ */
+
+/** Current backup format version. Bumped only if the entry shape changes. */
+declare const NOTE_BACKUP_VERSION: 1;
+/**
+ * One note in a closed backup — public data only. Field names are short but not
+ * cryptic; readability matters more than density in a file (unlike the QR path).
+ */
+interface NoteBackupEntry {
+    /** 0x-prefixed 32-byte LE commitment hex. */
+    commitmentHex: string;
+    /** 0x-prefixed encrypted memo hex (180 bytes). Decrypted on import. */
+    encryptedMemo: string;
+    /** Merkle leaf index, when known. Informational — spends re-fetch the proof. */
+    leafIndex?: number;
+    /**
+     * Whether the note was already spent when exported. A local status flag (not
+     * a key or secret), carried so a restored vault separates available from spent
+     * without a chain round-trip. A host may still reconcile against the chain
+     * afterward — this is a fast, possibly-stale hint, not the source of truth.
+     */
+    spent?: boolean;
+    /** Local timestamp the note was marked spent, when known. */
+    spentAt?: number | null;
+}
+interface NoteBackup {
+    v: typeof NOTE_BACKUP_VERSION;
+    /** Export time (ms). Informational. */
+    ts: number;
+    notes: NoteBackupEntry[];
+}
+/** Keys the importer needs to prove ownership by decrypting each memo. */
+interface BackupImportKeys {
+    /** 32-byte viewing secret key (ivsk). */
+    viewingSecretKey: Uint8Array;
+    /** Spending key scalar — folded into the derived stealth key / nullifier. */
+    spendingKey: bigint;
+    /** The importer's global owner pk (Ax), for stealth detection. */
+    ownerPk: bigint;
+}
+/**
+ * Encode notes into a closed JSON backup. Carries the memo, not the keys.
+ * `now` is injectable for a deterministic export (tests).
+ */
+declare function encodeNoteBackup(notes: ZkNote[], options?: {
+    now?: () => number;
+}): NoteBackup;
+/**
+ * Decode a JSON backup (string or object) into entries. Strict: a malformed
+ * payload is rejected rather than partially imported.
+ */
+declare function decodeNoteBackup(json: string | object): NoteBackupEntry[];
+/**
+ * Import a closed backup: decrypt each entry's memo with the importer's keys and
+ * return the notes that belong to them as full, spendable `ZkNote`s.
+ *
+ * Ownership is proven by decryption — an entry whose memo does not open under
+ * these keys is silently skipped (it is not this user's note). No chain access:
+ * only the backup's own memos are tried.
+ *
+ * The decrypted note is reconstructed as unspent; the entry's `spent`/`spentAt`
+ * flags are then applied so a restored vault separates available from spent. A
+ * host may reconcile against the chain afterward if the backup could be stale.
+ */
+declare function importNotesFromBackup(entries: NoteBackupEntry[], keys: BackupImportKeys): ZkNote[];
+
 /**
  * The steps every spend shares, in the order a spend performs them.
  *
@@ -5386,4 +5477,4 @@ declare class OrbinumWallet {
     private requireKey;
 }
 
-export { type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BlockInfo, type BuildNoteDeps, type BuildNoteParams, type Bytes32, CachedNullifier, type ChainInfo, ChainModule, type ChunkInfo, CircuitId, CircuitVersionResolver, type ClaimShieldedFeesParams, type ClientProviderConfig, type CoinSelection, type CollectScanEntriesParams, type CommitmentsInsertedEvent, type ConnectionStatus, type CryptoKey$1 as CryptoKey, CryptoPrecompiles, type DecodedPrecompile, DecryptPool, DecryptedMemo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, EncryptedNoteRecord, EncryptedTxRecord, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFacts, type ExtrinsicRecord, type FeeClaimDeps, type FeeClaimParams, type FeeClaimProofInputs, type FeeClaimProofOutput, type FeeClaimStep, type FormatOptions, KNOWN_PALLET_ERRORS, KNOWN_PRECOMPILES, type KnownPrecompileInfo, LEAVES_PER_TREE, MIN_GASLESS_FEE, MIN_SIGNATURE_BYTES, MemoryVaultStorage, type MerkleRootUpdatedEvent, type MutableWalletSession, NATIVE_ASSET_ID, NOTE_BIGINT_FIELDS, NOTE_TRANSFER_URI_SCHEME, type NoteBuildKeys, NoteBuilder, type NoteDisclosure, NoteInput, NoteStatusUpdate, NoteStorage, type NoteTransferEntry, type NoteTransferPayload, type NoteWithMeta, type NotesCache, NullifierCache, type NullifierChunkBody, type NullifierManifest, type NullifierSource, NullifierSyncMeta, type NullifierTail, type NullifiersSpentEvent, type ObservableNotesCache, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, OrbinumWallet, type OrbinumWalletConfig, PAGE_SIZE, PRECOMPILE_ADDR, type PairwiseEphWindowEntry, type PalletErrorKind, type PersistParams, type PrecompileMethod, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type ProofOptions, type ProviderFactory, QR_PAGE_MAX_CHARS, RECOVERED_TX_RESULT, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type ReconstructDeps, type ReconstructedTxRecord, type RegisterAssetArgs, type RelayerInfo, RelayerStatusModule, type ResolveSpentSetParams, type ResolvedProverVersion, type ResolvedSpendVersion, type RpcV2MerkleProof, RpcV2Module, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, type RunScanParams, SPENDING_KEY_CANONICAL_ORIGIN, SPENDING_KEY_VERIFYING_CONTRACT, SPENDING_KEY_WARNING, type ScanChunkManifest, ScanCommitment, type ScanHint, type ScanHintPage, type ScanHintSource, ScanKeys, type ScanOptions, type ScanOutcome, type ScanProgress, type ScanResult, SecretStore, type SelfEphWindowEntry, type SelfStealthKeys, type SessionCacheDeps, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedEvent, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SpendDetails, type SpendPlanProblem, type SpendPrivacyReads, type SpendVault, type SpendableInputsCheck, type SpendingKeyTypedData, type StatusChangeEvent, type StatusListener, SubstrateClient, type SystemHealth, TRANSFER_INPUTS, TRANSFER_OUTPUTS, type TokenInfo, type TokenTransfer, type TransferDeps, type TransferFactsRow, type TransferFactsSource, type TransferInputNote, type TransferOutputNote, type TransferParams, type TransferPlan, type TransferStep, type TransferSubmitRequest, type TxFactsSource, TxHistoryStore, type TxKind, type TxLandingPollOptions, type TxResult, type UnsafeTxOptions, type UnshieldArgs, type UnshieldDeps, type UnshieldNoteParams, type UnshieldParams, type UnshieldPlan, type UnshieldProofInputs, type UnshieldProofResult, type UnshieldStep, type UnshieldSubmitRequest, type UnshieldedEvent, type UnverifyAssetArgs, VAULT_SCHEMA_VERSION, VaultConfigRecord, VaultLockedError, VaultStorage, VaultStore, type VaultStoreDeps, type VaultUnlockOptions, type VerifyAssetArgs, type VersionedArtifactProvider, type WalletScanKeys, type WalletSession, ZkNote, type ZkVerifierCircuitVersionInfo, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, addressToFieldElement, applyBatch, applyNoteStatus, assembleNoteTransfer, base64UrlDecode, base64UrlEncode, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildConfig, buildDummyTransferInput, buildShieldBatchOperations, buildShieldParams, buildZkNote, bytesToBigintLE, bytesToBjjScalar, cacheSession, canPairWith, canonicalAccountId, chainActiveCircuitVersion, checkSpendableInputs, claimFees, classifyChainError, clearSession, collectNullifiersToQuery, collectScanEntries, commitmentHexOf, computeNoteCommitment, computeNullifier, computePathIndices, connectInjectedExtension, createNoteDisclosureKey, createNotesCache, createWalletSession, decodeNoteDisclosureKey, decodeNoteTransferPage, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, derivePairwiseEphSk, derivePairwiseSharedSecret, deriveSelfEphSk, deriveSpendingKeyFromMaster, deriveSpendingKeyFromSignature, deriveSpendingKeyMessageV2, deriveSpendingKeyTypedData, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewTag, deriveViewingPublicKey, deriveViewingSecretKey, detectCommitmentMismatch, encodeNoteTransferPages, encryptJson, encryptNote, ensureCreatedAt, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, extractPalletError, failed, fastMulBase, fastMulPoint, fetchExtrinsicFacts, formatAmountPlain, formatBalance, formatORB, fromBase64, fromHex, gapMargin, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getInjectedExtensions, getPrecompileLabel, hasCachedSession, hasInjectedExtensions, hexToBigint, hexToNumber, implicitSubstrateToEvm, isAbortError, isAlreadySpentError, isConnectionLossError, isEvmAddress, isGhostNoteError, isImplicitEvmAccount, isNativeAsset, isNoteSelfConsistent, isSpendable, isSs58, isSubstrateAddress, isUnifiedAddress, isValidLeafIndex, leHexToBigint, mapExtrinsicArgs, mapZkEventData, markInputsSpent, normalizeChainFingerprint, normalizeEvmAddress, normalizeNote, normalizeNotes, noteBlindTag, noteCreatedAt, noteCreatedTxHash, noteMatchesCommitment, noteOrigin, noteSpentTxHash, noteToTransferEntry, noteTxKind, pairwiseEphWindow, palletErrorKind, parseAmount, parseEvmAddress, persistCursor, persistScanResults, planTransfer, planUnshield, randomBlinding, reconstructOutgoingTxRecords, recoverOwnerPkPoint, recoverSelfStealthNote, refuseIfAlreadySpent, removeByCommitment, requireSessionKeys, reservePairwiseIndex, reserveSelfEphIndex, resolveSelfEphCeiling, resolveSpentSet, resolveSpentStatus, restoreSession, runScan, scalarToHex, scanAbortError, selectGhosts, selectNotes, selfEphWindow, serializeMemo, sessionCacheKey, shortHash, signAndSubmitTx, spendableBalance, stampCreatedAt, stampCreatedTxHash, stampSpentTxHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, transferNotes, treeIdOf, treeOf, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, txLandedAfterError, unshieldNote, upsertNote, vaultReplacer, vaultReviver, vaultStorageName, windowSizeForCounter };
+export { type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BackupImportKeys, type BlockInfo, type BuildNoteDeps, type BuildNoteParams, type Bytes32, CachedNullifier, type ChainInfo, ChainModule, type ChunkInfo, CircuitId, CircuitVersionResolver, type ClaimShieldedFeesParams, type ClientProviderConfig, type CoinSelection, type CollectScanEntriesParams, type CommitmentsInsertedEvent, type ConnectionStatus, type CryptoKey$1 as CryptoKey, CryptoPrecompiles, type DecodedPrecompile, DecryptPool, DecryptedMemo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, EncryptedNoteRecord, EncryptedTxRecord, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFacts, type ExtrinsicRecord, type FeeClaimDeps, type FeeClaimParams, type FeeClaimProofInputs, type FeeClaimProofOutput, type FeeClaimStep, type FormatOptions, KNOWN_PALLET_ERRORS, KNOWN_PRECOMPILES, type KnownPrecompileInfo, LEAVES_PER_TREE, MIN_GASLESS_FEE, MIN_SIGNATURE_BYTES, MemoryVaultStorage, type MerkleRootUpdatedEvent, type MutableWalletSession, NATIVE_ASSET_ID, NOTE_BACKUP_VERSION, NOTE_BIGINT_FIELDS, NOTE_TRANSFER_URI_SCHEME, type NoteBackup, type NoteBackupEntry, type NoteBuildKeys, NoteBuilder, type NoteDisclosure, NoteInput, NoteStatusUpdate, NoteStorage, type NoteTransferEntry, type NoteTransferPayload, type NoteWithMeta, type NotesCache, NullifierCache, type NullifierChunkBody, type NullifierManifest, type NullifierSource, NullifierSyncMeta, type NullifierTail, type NullifiersSpentEvent, type ObservableNotesCache, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, OrbinumWallet, type OrbinumWalletConfig, PAGE_SIZE, PRECOMPILE_ADDR, type PairwiseEphWindowEntry, type PalletErrorKind, type PersistParams, type PrecompileMethod, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type ProofOptions, type ProviderFactory, QR_PAGE_MAX_CHARS, RECOVERED_TX_RESULT, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type ReconstructDeps, type ReconstructedTxRecord, type RegisterAssetArgs, type RelayerInfo, RelayerStatusModule, type ResolveSpentSetParams, type ResolvedProverVersion, type ResolvedSpendVersion, type RpcV2MerkleProof, RpcV2Module, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, type RunScanParams, SPENDING_KEY_CANONICAL_ORIGIN, SPENDING_KEY_VERIFYING_CONTRACT, SPENDING_KEY_WARNING, type ScanChunkManifest, ScanCommitment, type ScanHint, type ScanHintPage, type ScanHintSource, ScanKeys, type ScanOptions, type ScanOutcome, type ScanProgress, type ScanResult, SecretStore, type SelfEphWindowEntry, type SelfStealthKeys, type SessionCacheDeps, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedEvent, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SpendDetails, type SpendPlanProblem, type SpendPrivacyReads, type SpendVault, type SpendableInputsCheck, type SpendingKeyTypedData, type StatusChangeEvent, type StatusListener, SubstrateClient, type SystemHealth, TRANSFER_INPUTS, TRANSFER_OUTPUTS, type TokenInfo, type TokenTransfer, type TransferDeps, type TransferFactsRow, type TransferFactsSource, type TransferInputNote, type TransferOutputNote, type TransferParams, type TransferPlan, type TransferStep, type TransferSubmitRequest, type TxFactsSource, TxHistoryStore, type TxKind, type TxLandingPollOptions, type TxResult, type UnsafeTxOptions, type UnshieldArgs, type UnshieldDeps, type UnshieldNoteParams, type UnshieldParams, type UnshieldPlan, type UnshieldProofInputs, type UnshieldProofResult, type UnshieldStep, type UnshieldSubmitRequest, type UnshieldedEvent, type UnverifyAssetArgs, VAULT_SCHEMA_VERSION, VaultConfigRecord, VaultLockedError, VaultStorage, VaultStore, type VaultStoreDeps, type VaultUnlockOptions, type VerifyAssetArgs, type VersionedArtifactProvider, type WalletScanKeys, type WalletSession, ZkNote, type ZkVerifierCircuitVersionInfo, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, addressToFieldElement, applyBatch, applyNoteStatus, assembleNoteTransfer, base64UrlDecode, base64UrlEncode, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildConfig, buildDummyTransferInput, buildShieldBatchOperations, buildShieldParams, buildZkNote, bytesToBigintLE, bytesToBjjScalar, cacheSession, canPairWith, canonicalAccountId, chainActiveCircuitVersion, checkSpendableInputs, claimFees, classifyChainError, clearSession, collectNullifiersToQuery, collectScanEntries, commitmentHexOf, computeNoteCommitment, computeNullifier, computePathIndices, connectInjectedExtension, createNoteDisclosureKey, createNotesCache, createWalletSession, decodeNoteBackup, decodeNoteDisclosureKey, decodeNoteTransferPage, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, derivePairwiseEphSk, derivePairwiseSharedSecret, deriveSelfEphSk, deriveSpendingKeyFromMaster, deriveSpendingKeyFromSignature, deriveSpendingKeyMessageV2, deriveSpendingKeyTypedData, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewTag, deriveViewingPublicKey, deriveViewingSecretKey, detectCommitmentMismatch, encodeNoteBackup, encodeNoteTransferPages, encryptJson, encryptNote, ensureCreatedAt, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, extractPalletError, failed, fastMulBase, fastMulPoint, fetchExtrinsicFacts, formatAmountPlain, formatBalance, formatORB, fromBase64, fromHex, gapMargin, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getInjectedExtensions, getPrecompileLabel, hasCachedSession, hasInjectedExtensions, hexToBigint, hexToNumber, implicitSubstrateToEvm, importNotesFromBackup, isAbortError, isAlreadySpentError, isConnectionLossError, isEvmAddress, isGhostNoteError, isImplicitEvmAccount, isNativeAsset, isNoteSelfConsistent, isSpendable, isSs58, isSubstrateAddress, isUnifiedAddress, isValidLeafIndex, leHexToBigint, mapExtrinsicArgs, mapZkEventData, markInputsSpent, normalizeChainFingerprint, normalizeEvmAddress, normalizeNote, normalizeNotes, noteBlindTag, noteCreatedAt, noteCreatedTxHash, noteMatchesCommitment, noteOrigin, noteSpentTxHash, noteToTransferEntry, noteTxKind, pairwiseEphWindow, palletErrorKind, parseAmount, parseEvmAddress, persistCursor, persistScanResults, planTransfer, planUnshield, randomBlinding, reconstructOutgoingTxRecords, recoverOwnerPkPoint, recoverSelfStealthNote, refuseIfAlreadySpent, removeByCommitment, requireSessionKeys, reservePairwiseIndex, reserveSelfEphIndex, resolveSelfEphCeiling, resolveSpentSet, resolveSpentStatus, restoreSession, runScan, scalarToHex, scanAbortError, selectGhosts, selectNotes, selfEphWindow, serializeMemo, sessionCacheKey, shortHash, signAndSubmitTx, spendableBalance, stampCreatedAt, stampCreatedTxHash, stampSpentTxHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, transferNotes, treeIdOf, treeOf, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, txLandedAfterError, unshieldNote, upsertNote, vaultReplacer, vaultReviver, vaultStorageName, windowSizeForCounter };

package/dist/index.js

@@ -45,6 +45,7 @@ __export(index_exports, {
   MIN_SIGNATURE_BYTES: () => MIN_SIGNATURE_BYTES,
   MemoryVaultStorage: () => MemoryVaultStorage,
   NATIVE_ASSET_ID: () => NATIVE_ASSET_ID,
+  NOTE_BACKUP_VERSION: () => NOTE_BACKUP_VERSION,
   NOTE_BIGINT_FIELDS: () => NOTE_BIGINT_FIELDS,
   NOTE_TRANSFER_URI_SCHEME: () => NOTE_TRANSFER_URI_SCHEME,
   NoteBuilder: () => NoteBuilder,
@@ -120,6 +121,7 @@ __export(index_exports, {
   createNotesCache: () => createNotesCache,
   createWalletSession: () => createWalletSession,
   createWorkerPool: () => createWorkerPool,
+  decodeNoteBackup: () => decodeNoteBackup,
   decodeNoteDisclosureKey: () => decodeNoteDisclosureKey,
   decodeNoteTransferPage: () => decodeNoteTransferPage,
   decodePrecompileCalldata: () => decodePrecompileCalldata,
@@ -143,6 +145,7 @@ __export(index_exports, {
   deriveViewingPublicKey: () => deriveViewingPublicKey,
   deriveViewingSecretKey: () => deriveViewingSecretKey,
   detectCommitmentMismatch: () => detectCommitmentMismatch,
+  encodeNoteBackup: () => encodeNoteBackup,
   encodeNoteTransferPages: () => encodeNoteTransferPages,
   encryptJson: () => encryptJson,
   encryptNote: () => encryptNote,
@@ -179,6 +182,7 @@ __export(index_exports, {
   hexToNumber: () => hexToNumber,
   implicitSubstrateToEvm: () => implicitSubstrateToEvm,
   importDeviceKey: () => importDeviceKey,
+  importNotesFromBackup: () => importNotesFromBackup,
   isAbortError: () => isAbortError,
   isAlreadySpentError: () => isAlreadySpentError,
   isConnectionLossError: () => isConnectionLossError,
@@ -6326,6 +6330,80 @@ function assembleNoteTransfer(pages) {
   return [...pages].sort((a, b) => a.p - b.p).flatMap((p) => p.notes);
 }
 
+// src/wallet/ops/notes/noteBackup.ts
+var NOTE_BACKUP_VERSION = 1;
+function noteToBackupEntry(note) {
+  return {
+    commitmentHex: note.commitmentHex,
+    encryptedMemo: toHex(Uint8Array.from(note.memo)),
+    ...note.leafIndex !== void 0 ? { leafIndex: note.leafIndex } : {},
+    spent: note.spent,
+    spentAt: note.spentAt
+  };
+}
+function encodeNoteBackup(notes, options = {}) {
+  const now = options.now ?? Date.now;
+  return {
+    v: NOTE_BACKUP_VERSION,
+    ts: now(),
+    notes: notes.map(noteToBackupEntry)
+  };
+}
+function decodeNoteBackup(json) {
+  let payload;
+  if (typeof json === "string") {
+    try {
+      payload = JSON.parse(json);
+    } catch {
+      throw new Error("Note backup is not valid JSON.");
+    }
+  } else {
+    payload = json;
+  }
+  const p = payload;
+  if (p.v !== NOTE_BACKUP_VERSION) {
+    throw new Error(`Unsupported note-backup version: ${String(p.v)}.`);
+  }
+  if (!Array.isArray(p.notes) || p.notes.some((n) => !isEntry2(n))) {
+    throw new Error("Note backup is missing required fields.");
+  }
+  return p.notes;
+}
+function importNotesFromBackup(entries, keys) {
+  const out = [];
+  for (const entry of entries) {
+    const commitment = {
+      commitmentHex: entry.commitmentHex,
+      leafIndex: entry.leafIndex ?? -1,
+      encryptedMemo: entry.encryptedMemo
+    };
+    const note = tryDecryptNote(
+      commitment,
+      keys.viewingSecretKey,
+      keys.spendingKey,
+      keys.ownerPk
+    );
+    if (note) {
+      out.push({
+        ...note,
+        spent: entry.spent ?? false,
+        spentAt: entry.spentAt ?? null
+      });
+    }
+  }
+  return out;
+}
+function isEntry2(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const e = value;
+  if (typeof e["commitmentHex"] !== "string" || e["commitmentHex"].length === 0) return false;
+  if (typeof e["encryptedMemo"] !== "string" || e["encryptedMemo"].length === 0) return false;
+  if ("leafIndex" in e && e["leafIndex"] !== void 0 && typeof e["leafIndex"] !== "number") {
+    return false;
+  }
+  return true;
+}
+
 // src/wallet/ops/spend/transfer.ts
 var import_proof_generator6 = require("@orbinum/proof-generator");
 
@@ -7414,6 +7492,7 @@ var OrbinumWallet = class {
   MIN_SIGNATURE_BYTES,
   MemoryVaultStorage,
   NATIVE_ASSET_ID,
+  NOTE_BACKUP_VERSION,
   NOTE_BIGINT_FIELDS,
   NOTE_TRANSFER_URI_SCHEME,
   NoteBuilder,
@@ -7489,6 +7568,7 @@ var OrbinumWallet = class {
   createNotesCache,
   createWalletSession,
   createWorkerPool,
+  decodeNoteBackup,
   decodeNoteDisclosureKey,
   decodeNoteTransferPage,
   decodePrecompileCalldata,
@@ -7512,6 +7592,7 @@ var OrbinumWallet = class {
   deriveViewingPublicKey,
   deriveViewingSecretKey,
   detectCommitmentMismatch,
+  encodeNoteBackup,
   encodeNoteTransferPages,
   encryptJson,
   encryptNote,
@@ -7548,6 +7629,7 @@ var OrbinumWallet = class {
   hexToNumber,
   implicitSubstrateToEvm,
   importDeviceKey,
+  importNotesFromBackup,
   isAbortError,
   isAlreadySpentError,
   isConnectionLossError,

package/dist/index.mjs

@@ -5226,6 +5226,80 @@ function assembleNoteTransfer(pages) {
   return [...pages].sort((a, b) => a.p - b.p).flatMap((p) => p.notes);
 }
 
+// src/wallet/ops/notes/noteBackup.ts
+var NOTE_BACKUP_VERSION = 1;
+function noteToBackupEntry(note) {
+  return {
+    commitmentHex: note.commitmentHex,
+    encryptedMemo: toHex(Uint8Array.from(note.memo)),
+    ...note.leafIndex !== void 0 ? { leafIndex: note.leafIndex } : {},
+    spent: note.spent,
+    spentAt: note.spentAt
+  };
+}
+function encodeNoteBackup(notes, options = {}) {
+  const now = options.now ?? Date.now;
+  return {
+    v: NOTE_BACKUP_VERSION,
+    ts: now(),
+    notes: notes.map(noteToBackupEntry)
+  };
+}
+function decodeNoteBackup(json) {
+  let payload;
+  if (typeof json === "string") {
+    try {
+      payload = JSON.parse(json);
+    } catch {
+      throw new Error("Note backup is not valid JSON.");
+    }
+  } else {
+    payload = json;
+  }
+  const p = payload;
+  if (p.v !== NOTE_BACKUP_VERSION) {
+    throw new Error(`Unsupported note-backup version: ${String(p.v)}.`);
+  }
+  if (!Array.isArray(p.notes) || p.notes.some((n) => !isEntry2(n))) {
+    throw new Error("Note backup is missing required fields.");
+  }
+  return p.notes;
+}
+function importNotesFromBackup(entries, keys) {
+  const out = [];
+  for (const entry of entries) {
+    const commitment = {
+      commitmentHex: entry.commitmentHex,
+      leafIndex: entry.leafIndex ?? -1,
+      encryptedMemo: entry.encryptedMemo
+    };
+    const note = tryDecryptNote(
+      commitment,
+      keys.viewingSecretKey,
+      keys.spendingKey,
+      keys.ownerPk
+    );
+    if (note) {
+      out.push({
+        ...note,
+        spent: entry.spent ?? false,
+        spentAt: entry.spentAt ?? null
+      });
+    }
+  }
+  return out;
+}
+function isEntry2(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const e = value;
+  if (typeof e["commitmentHex"] !== "string" || e["commitmentHex"].length === 0) return false;
+  if (typeof e["encryptedMemo"] !== "string" || e["encryptedMemo"].length === 0) return false;
+  if ("leafIndex" in e && e["leafIndex"] !== void 0 && typeof e["leafIndex"] !== "number") {
+    return false;
+  }
+  return true;
+}
+
 // src/wallet/ops/spend/transfer.ts
 import { CircuitType as CircuitType5 } from "@orbinum/proof-generator";
 
@@ -6036,6 +6110,7 @@ export {
   MIN_SIGNATURE_BYTES,
   MemoryVaultStorage,
   NATIVE_ASSET_ID,
+  NOTE_BACKUP_VERSION,
   NOTE_BIGINT_FIELDS,
   NOTE_TRANSFER_URI_SCHEME,
   NoteBuilder,
@@ -6111,6 +6186,7 @@ export {
   createNotesCache,
   createWalletSession,
   createWorkerPool,
+  decodeNoteBackup,
   decodeNoteDisclosureKey,
   decodeNoteTransferPage,
   decodePrecompileCalldata,
@@ -6134,6 +6210,7 @@ export {
   deriveViewingPublicKey,
   deriveViewingSecretKey,
   detectCommitmentMismatch,
+  encodeNoteBackup,
   encodeNoteTransferPages,
   encryptJson,
   encryptNote,
@@ -6170,6 +6247,7 @@ export {
   hexToNumber,
   implicitSubstrateToEvm,
   importDeviceKey,
+  importNotesFromBackup,
   isAbortError,
   isAlreadySpentError,
   isConnectionLossError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbinum/sdk",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Official TypeScript SDK for Orbinum.",
   "author": "Orbinum",
   "license": "MIT",