@orbinum/sdk 0.14.0 → 0.15.0

package/dist/index.d.mts

@@ -1925,6 +1925,11 @@ declare class NoteBuilder {
  * Layout (180 bytes, ECDH):
  *   nonce(12) || ciphertext+MAC(136) || ephPk_packed(32) = 180
  *
+ * View tag (memos built by SDK ≥ 0.15): nonce[0] = deriveViewTag(sharedSecret)
+ * — see memo.ts. Layout and size are unchanged; legacy memos carry a random
+ * byte there instead, so the filter is only sound at/after the wallet's
+ * tagActivationLeaf.
+ *
  * Plaintext layout (120 bytes):
  *   value_lo(8 LE) || value_hi(8 LE) || owner_pk(32) || blinding(32) || asset_id(4 LE) || counterparty_pk(32) || circuit_version(4 LE)
  *
@@ -2007,10 +2012,42 @@ declare const EncryptedMemo: {
      * @param viewingSecretKey 32-byte HKDF viewing secret key from deriveViewingSecretKey().
      */
     extractSharedSecret(memoBytes: Uint8Array, viewingSecretKey: Uint8Array): Uint8Array | null;
+    /**
+     * Cheap view-tag check: does memo nonce[0] match the tag derived from
+     * `sharedSecret`? One SHA256 + one byte compare — no AEAD work.
+     *
+     * Only meaningful for memos built with view tags (commitments at/after
+     * the wallet's tagActivationLeaf): a legacy memo carries a random byte
+     * there and would false-negative 255/256 of the time.
+     */
+    checkViewTag(memoBytes: Uint8Array, sharedSecret: Uint8Array): boolean;
+    /**
+     * Decrypt with an already-computed shared secret (from
+     * extractSharedSecret), skipping the ECDH. Pair with checkViewTag for the
+     * fast scan path: ECDH once → tag check → decrypt only on match.
+     */
+    decryptWithSharedSecret(memoBytes: Uint8Array, commitment: Uint8Array, sharedSecret: Uint8Array): DecryptedMemo | null;
     /** @internal */
     _decrypt(memoBytes: Uint8Array, commitment: Uint8Array, viewingSecretKey: Uint8Array): DecryptedMemo | null;
 };
 
+/**
+ * Derive the 1-byte view tag (Monero-style fast-scan filter) from the ECDH
+ * shared secret:
+ *   view_tag = SHA256("orbinum-view-tag-v1" || sharedSecret)[0]
+ *
+ * The sender embeds it as the memo's first nonce byte (nonce[0]); a scanner
+ * that has computed the shared secret compares one byte and skips the AEAD
+ * decrypt on mismatch — 255/256 of foreign notes. Safe to publish: without
+ * the viewing key the shared secret is unknowable, so the byte reads as
+ * uniform noise to any observer.
+ *
+ * Nonce safety: the encryption key is unique per note (see
+ * deriveEncryptionKey), so each key encrypts exactly one message and the
+ * remaining 11 random nonce bytes are more than enough.
+ */
+declare function deriveViewTag(sharedSecret: Uint8Array): number;
+
 /**
  * NoteDecryptor
  *
@@ -2034,6 +2071,17 @@ declare const EncryptedMemo: {
  * deriveSpendingKeyFromSignature.
  */
 declare function computeNullifier(commitment: bigint, spendingKey: bigint): bigint;
+interface TryDecryptOptions {
+    /**
+     * View-tag fast path: compute the ECDH shared secret once, compare the
+     * 1-byte tag in memo nonce[0], and skip the AEAD decrypt on mismatch
+     * (255/256 of foreign notes; `reason: 'view_tag_mismatch'`).
+     *
+     * Only enable for commitments at/after the wallet's tagActivationLeaf —
+     * legacy memos carry a random byte there and would be silently dropped.
+     */
+    viewTag?: boolean;
+}
 /**
  * Attempt to decrypt an on-chain commitment using the recipient's viewing secret key.
  *
@@ -2047,13 +2095,14 @@ declare function computeNullifier(commitment: bigint, spendingKey: bigint): bigi
  * @param spendingKey      Spending key bigint (for nullifier computation).
  * @param ownOwnerPk       The viewer's global BabyJubJub Ax (ownerPk). Required for stealth detection.
  *                         Pass 0n to disable stealth detection (legacy/own-note-only scanning).
+ * @param opts             See TryDecryptOptions (view-tag fast path).
  */
-declare function tryDecryptNote(commitment: ScanCommitment, viewingSecretKey: Uint8Array, spendingKey: bigint, ownOwnerPk?: bigint): ZkNote | null;
+declare function tryDecryptNote(commitment: ScanCommitment, viewingSecretKey: Uint8Array, spendingKey: bigint, ownOwnerPk?: bigint, opts?: TryDecryptOptions): ZkNote | null;
 /**
  * Like tryDecryptNote but also returns a human-readable reason for failure.
  * Useful for debugging scan issues (wrong key, corrupted memo, commitment mismatch).
  */
-declare function tryDecryptNoteVerbose(commitment: ScanCommitment, viewingSecretKey: Uint8Array, spendingKey: bigint, ownOwnerPk?: bigint): {
+declare function tryDecryptNoteVerbose(commitment: ScanCommitment, viewingSecretKey: Uint8Array, spendingKey: bigint, ownOwnerPk?: bigint, opts?: TryDecryptOptions): {
     note: ZkNote | null;
     reason?: string;
 };
@@ -4172,4 +4221,4 @@ interface ExtrinsicFailedData {
     dispatch_info: DispatchInfo;
 }
 
-export { type AccountListing, type AccountMappedData, type AccountMappedEvent, type AccountMappingCall, type AccountMappingEvent, AccountMappingModule, AccountMappingPrecompile, type AccountMetadata, type AccountUnmappedEvent, type ActiveVersionSetEvent, type AddChainLinkArgs, type AddChainLinkParams, type AddSupportedChainArgs, type AliasFullIdentity, type AliasInfo, type AliasListedForSaleEvent, type AliasOnSaleData, type AliasRegisteredData, type AliasRegisteredEvent, type AliasReleasedEvent, type AliasSaleCancelledEvent, type AliasSoldData, type AliasSoldEvent, type AliasTransferredData, type AliasTransferredEvent, type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BatchRegisterVerificationKeysArgs, type BatchVerificationKeysRegisteredEvent, type BlockInfo, type BuyAliasArgs, type Bytes32, CURRENT_CIRCUIT_VERSION, type ChainInfo, type ChainLink, type ChainLinkAddedEvent, type ChainLinkRemovedEvent, CircuitId, CircuitId as CircuitIdType, CircuitVersionResolver, type ClaimShieldedFeesParams, type ClientProviderConfig, type CommitmentsInsertedEvent, type CommitmentsInsertedEventData, type ConnectionStatus, CryptoPrecompiles, type DecodedAddChainLinkArgs, type DecodedBatchArgs, type DecodedDispatchAsPrivateLinkArgs, type DecodedEthereumTransactArgs, type DecodedEvmCallArgs, type DecodedPrecompile, type DecodedPrivateTransferArgs, type DecodedPutAliasForSaleArgs, type DecodedRegisterAliasArgs, type DecodedRemarkArgs, type DecodedRevealPrivateLinkArgs, type DecodedSetAccountMetadataArgs, type DecodedShieldArgs, type DecodedShieldBatchArgs, type DecodedShieldBatchOperation, type DecodedSudoArgs, type DecodedTransferAllArgs, type DecodedTransferArgs, type DecodedTransferKeepAliveArgs, type DecodedUnshieldArgs, type DecryptedMemo, type DispatchAsLinkedAccountArgs, type DispatchAsLinkedParams, type DispatchAsPrivateLinkArgs, type DispatchError, type DispatchInfo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, type EncryptedNoteRecord, type EndowedEventData, type EthereumExecutedData, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, type EvmExecutedData, type EvmExitReason, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFailedData, type ExtrinsicSuccessData, type FeeClaimProofInputs, type FormatOptions, KNOWN_PRECOMPILES, type KnownPrecompileInfo, type ListingInfo, type MerkleRootUpdatedData, type MerkleRootUpdatedEvent, type MerkleTreeInfo, type MetadataUpdatedEvent, NoteBuilder, type NoteDisclosure, type NoteInput, type NoteStatusUpdate, type NullifiersSpentEvent, type NullifiersSpentEventData, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, PRECOMPILE_ADDR, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateChainLinkAddedEvent, type PrivateChainLinkRemovedEvent, type PrivateChainLinkRevealedEvent, type PrivateLink, type PrivateLinkDispatchExecutedEvent, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type ProofVerificationFailedEvent, type ProofVerifiedEvent, type ProxyCallExecutedEvent, type PutAliasOnSaleArgs, type PutOnSaleParams, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type RegisterAliasArgs, type RegisterAssetArgs, type RegisterPrivateLinkArgs, type RegisterVerificationKeyArgs, type RelayerInfo, RelayerStatusModule, type RemoveChainLinkArgs, type RemovePrivateLinkArgs, type RemoveSupportedChainArgs, type RemoveVerificationKeyArgs, type ReservedEventData, type ResolvedAlias, type ResolvedSpendVersion, type RevealPrivateLinkArgs, type RpcV2MerkleProof, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, SLIP0044_NAMESPACE, type ScanCommitment, type SetAccountMetadataArgs, type SetActiveVersionArgs, type SetMetadataParams, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedEvent, type ShieldedEventData, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SignatureScheme, type StatusChangeEvent, type StatusListener, SubstrateClient, type SupportedChain, type SupportedChainAddedEvent, type SupportedChainRemovedEvent, type SystemHealth, type TokenInfo, type TokenTransfer, type TransferAliasArgs, type TransferEventData, type TransferInputNote, type TransferOutputNote, type TxResult, type UnsafeTxOptions, type UnshieldArgs, type UnshieldParams, type UnshieldProofInputs, type UnshieldedEvent, type UnshieldedEventData, type UnverifyAssetArgs, VaultLockedError, type VerificationKeyRegisteredEvent, type VerificationKeyRemovedEvent, type VerifyAssetArgs, type VerifyProofArgs, type VkEntry, type ZkNote, type ZkVerifierCall, type ZkVerifierCircuitVersionInfo, type ZkVerifierEvent, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, applyNoteStatus, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildDummyTransferInput, bytesToBigintLE, computeNullifier, computePathIndices, createNoteDisclosureKey, decodeNoteDisclosureKey, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, deriveSpendingKeyFromSignature, deriveSpendingKeyMessage, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewingPublicKey, deriveViewingSecretKey, encryptJson, encryptNote, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, formatBalance, formatORB, fromBase64, fromHex, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getPrecompileLabel, hexToBigint, hexToNumber, implicitSubstrateToEvm, isEvmAddress, isImplicitEvmAccount, isSs58, isSubstrateAddress, isUnifiedAddress, leHexToBigint, mapExtrinsicArgs, mapZkEventData, normalizeEvmAddress, noteBlindTag, randomBlinding, recoverOwnerPkPoint, selectNotes, shortHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, vaultReplacer, vaultReviver };
+export { type AccountListing, type AccountMappedData, type AccountMappedEvent, type AccountMappingCall, type AccountMappingEvent, AccountMappingModule, AccountMappingPrecompile, type AccountMetadata, type AccountUnmappedEvent, type ActiveVersionSetEvent, type AddChainLinkArgs, type AddChainLinkParams, type AddSupportedChainArgs, type AliasFullIdentity, type AliasInfo, type AliasListedForSaleEvent, type AliasOnSaleData, type AliasRegisteredData, type AliasRegisteredEvent, type AliasReleasedEvent, type AliasSaleCancelledEvent, type AliasSoldData, type AliasSoldEvent, type AliasTransferredData, type AliasTransferredEvent, type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BatchRegisterVerificationKeysArgs, type BatchVerificationKeysRegisteredEvent, type BlockInfo, type BuyAliasArgs, type Bytes32, CURRENT_CIRCUIT_VERSION, type ChainInfo, type ChainLink, type ChainLinkAddedEvent, type ChainLinkRemovedEvent, CircuitId, CircuitId as CircuitIdType, CircuitVersionResolver, type ClaimShieldedFeesParams, type ClientProviderConfig, type CommitmentsInsertedEvent, type CommitmentsInsertedEventData, type ConnectionStatus, CryptoPrecompiles, type DecodedAddChainLinkArgs, type DecodedBatchArgs, type DecodedDispatchAsPrivateLinkArgs, type DecodedEthereumTransactArgs, type DecodedEvmCallArgs, type DecodedPrecompile, type DecodedPrivateTransferArgs, type DecodedPutAliasForSaleArgs, type DecodedRegisterAliasArgs, type DecodedRemarkArgs, type DecodedRevealPrivateLinkArgs, type DecodedSetAccountMetadataArgs, type DecodedShieldArgs, type DecodedShieldBatchArgs, type DecodedShieldBatchOperation, type DecodedSudoArgs, type DecodedTransferAllArgs, type DecodedTransferArgs, type DecodedTransferKeepAliveArgs, type DecodedUnshieldArgs, type DecryptedMemo, type DispatchAsLinkedAccountArgs, type DispatchAsLinkedParams, type DispatchAsPrivateLinkArgs, type DispatchError, type DispatchInfo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, type EncryptedNoteRecord, type EndowedEventData, type EthereumExecutedData, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, type EvmExecutedData, type EvmExitReason, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFailedData, type ExtrinsicSuccessData, type FeeClaimProofInputs, type FormatOptions, KNOWN_PRECOMPILES, type KnownPrecompileInfo, type ListingInfo, type MerkleRootUpdatedData, type MerkleRootUpdatedEvent, type MerkleTreeInfo, type MetadataUpdatedEvent, NoteBuilder, type NoteDisclosure, type NoteInput, type NoteStatusUpdate, type NullifiersSpentEvent, type NullifiersSpentEventData, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, PRECOMPILE_ADDR, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateChainLinkAddedEvent, type PrivateChainLinkRemovedEvent, type PrivateChainLinkRevealedEvent, type PrivateLink, type PrivateLinkDispatchExecutedEvent, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type ProofVerificationFailedEvent, type ProofVerifiedEvent, type ProxyCallExecutedEvent, type PutAliasOnSaleArgs, type PutOnSaleParams, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type RegisterAliasArgs, type RegisterAssetArgs, type RegisterPrivateLinkArgs, type RegisterVerificationKeyArgs, type RelayerInfo, RelayerStatusModule, type RemoveChainLinkArgs, type RemovePrivateLinkArgs, type RemoveSupportedChainArgs, type RemoveVerificationKeyArgs, type ReservedEventData, type ResolvedAlias, type ResolvedSpendVersion, type RevealPrivateLinkArgs, type RpcV2MerkleProof, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, SLIP0044_NAMESPACE, type ScanCommitment, type SetAccountMetadataArgs, type SetActiveVersionArgs, type SetMetadataParams, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedEvent, type ShieldedEventData, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SignatureScheme, type StatusChangeEvent, type StatusListener, SubstrateClient, type SupportedChain, type SupportedChainAddedEvent, type SupportedChainRemovedEvent, type SystemHealth, type TokenInfo, type TokenTransfer, type TransferAliasArgs, type TransferEventData, type TransferInputNote, type TransferOutputNote, type TryDecryptOptions, type TxResult, type UnsafeTxOptions, type UnshieldArgs, type UnshieldParams, type UnshieldProofInputs, type UnshieldedEvent, type UnshieldedEventData, type UnverifyAssetArgs, VaultLockedError, type VerificationKeyRegisteredEvent, type VerificationKeyRemovedEvent, type VerifyAssetArgs, type VerifyProofArgs, type VkEntry, type ZkNote, type ZkVerifierCall, type ZkVerifierCircuitVersionInfo, type ZkVerifierEvent, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, applyNoteStatus, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildDummyTransferInput, bytesToBigintLE, computeNullifier, computePathIndices, createNoteDisclosureKey, decodeNoteDisclosureKey, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, deriveSpendingKeyFromSignature, deriveSpendingKeyMessage, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewTag, deriveViewingPublicKey, deriveViewingSecretKey, encryptJson, encryptNote, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, formatBalance, formatORB, fromBase64, fromHex, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getPrecompileLabel, hexToBigint, hexToNumber, implicitSubstrateToEvm, isEvmAddress, isImplicitEvmAccount, isSs58, isSubstrateAddress, isUnifiedAddress, leHexToBigint, mapExtrinsicArgs, mapZkEventData, normalizeEvmAddress, noteBlindTag, randomBlinding, recoverOwnerPkPoint, selectNotes, shortHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, vaultReplacer, vaultReviver };

package/dist/index.d.ts

@@ -1925,6 +1925,11 @@ declare class NoteBuilder {
  * Layout (180 bytes, ECDH):
  *   nonce(12) || ciphertext+MAC(136) || ephPk_packed(32) = 180
  *
+ * View tag (memos built by SDK ≥ 0.15): nonce[0] = deriveViewTag(sharedSecret)
+ * — see memo.ts. Layout and size are unchanged; legacy memos carry a random
+ * byte there instead, so the filter is only sound at/after the wallet's
+ * tagActivationLeaf.
+ *
  * Plaintext layout (120 bytes):
  *   value_lo(8 LE) || value_hi(8 LE) || owner_pk(32) || blinding(32) || asset_id(4 LE) || counterparty_pk(32) || circuit_version(4 LE)
  *
@@ -2007,10 +2012,42 @@ declare const EncryptedMemo: {
      * @param viewingSecretKey 32-byte HKDF viewing secret key from deriveViewingSecretKey().
      */
     extractSharedSecret(memoBytes: Uint8Array, viewingSecretKey: Uint8Array): Uint8Array | null;
+    /**
+     * Cheap view-tag check: does memo nonce[0] match the tag derived from
+     * `sharedSecret`? One SHA256 + one byte compare — no AEAD work.
+     *
+     * Only meaningful for memos built with view tags (commitments at/after
+     * the wallet's tagActivationLeaf): a legacy memo carries a random byte
+     * there and would false-negative 255/256 of the time.
+     */
+    checkViewTag(memoBytes: Uint8Array, sharedSecret: Uint8Array): boolean;
+    /**
+     * Decrypt with an already-computed shared secret (from
+     * extractSharedSecret), skipping the ECDH. Pair with checkViewTag for the
+     * fast scan path: ECDH once → tag check → decrypt only on match.
+     */
+    decryptWithSharedSecret(memoBytes: Uint8Array, commitment: Uint8Array, sharedSecret: Uint8Array): DecryptedMemo | null;
     /** @internal */
     _decrypt(memoBytes: Uint8Array, commitment: Uint8Array, viewingSecretKey: Uint8Array): DecryptedMemo | null;
 };
 
+/**
+ * Derive the 1-byte view tag (Monero-style fast-scan filter) from the ECDH
+ * shared secret:
+ *   view_tag = SHA256("orbinum-view-tag-v1" || sharedSecret)[0]
+ *
+ * The sender embeds it as the memo's first nonce byte (nonce[0]); a scanner
+ * that has computed the shared secret compares one byte and skips the AEAD
+ * decrypt on mismatch — 255/256 of foreign notes. Safe to publish: without
+ * the viewing key the shared secret is unknowable, so the byte reads as
+ * uniform noise to any observer.
+ *
+ * Nonce safety: the encryption key is unique per note (see
+ * deriveEncryptionKey), so each key encrypts exactly one message and the
+ * remaining 11 random nonce bytes are more than enough.
+ */
+declare function deriveViewTag(sharedSecret: Uint8Array): number;
+
 /**
  * NoteDecryptor
  *
@@ -2034,6 +2071,17 @@ declare const EncryptedMemo: {
  * deriveSpendingKeyFromSignature.
  */
 declare function computeNullifier(commitment: bigint, spendingKey: bigint): bigint;
+interface TryDecryptOptions {
+    /**
+     * View-tag fast path: compute the ECDH shared secret once, compare the
+     * 1-byte tag in memo nonce[0], and skip the AEAD decrypt on mismatch
+     * (255/256 of foreign notes; `reason: 'view_tag_mismatch'`).
+     *
+     * Only enable for commitments at/after the wallet's tagActivationLeaf —
+     * legacy memos carry a random byte there and would be silently dropped.
+     */
+    viewTag?: boolean;
+}
 /**
  * Attempt to decrypt an on-chain commitment using the recipient's viewing secret key.
  *
@@ -2047,13 +2095,14 @@ declare function computeNullifier(commitment: bigint, spendingKey: bigint): bigi
  * @param spendingKey      Spending key bigint (for nullifier computation).
  * @param ownOwnerPk       The viewer's global BabyJubJub Ax (ownerPk). Required for stealth detection.
  *                         Pass 0n to disable stealth detection (legacy/own-note-only scanning).
+ * @param opts             See TryDecryptOptions (view-tag fast path).
  */
-declare function tryDecryptNote(commitment: ScanCommitment, viewingSecretKey: Uint8Array, spendingKey: bigint, ownOwnerPk?: bigint): ZkNote | null;
+declare function tryDecryptNote(commitment: ScanCommitment, viewingSecretKey: Uint8Array, spendingKey: bigint, ownOwnerPk?: bigint, opts?: TryDecryptOptions): ZkNote | null;
 /**
  * Like tryDecryptNote but also returns a human-readable reason for failure.
  * Useful for debugging scan issues (wrong key, corrupted memo, commitment mismatch).
  */
-declare function tryDecryptNoteVerbose(commitment: ScanCommitment, viewingSecretKey: Uint8Array, spendingKey: bigint, ownOwnerPk?: bigint): {
+declare function tryDecryptNoteVerbose(commitment: ScanCommitment, viewingSecretKey: Uint8Array, spendingKey: bigint, ownOwnerPk?: bigint, opts?: TryDecryptOptions): {
     note: ZkNote | null;
     reason?: string;
 };
@@ -4172,4 +4221,4 @@ interface ExtrinsicFailedData {
     dispatch_info: DispatchInfo;
 }
 
-export { type AccountListing, type AccountMappedData, type AccountMappedEvent, type AccountMappingCall, type AccountMappingEvent, AccountMappingModule, AccountMappingPrecompile, type AccountMetadata, type AccountUnmappedEvent, type ActiveVersionSetEvent, type AddChainLinkArgs, type AddChainLinkParams, type AddSupportedChainArgs, type AliasFullIdentity, type AliasInfo, type AliasListedForSaleEvent, type AliasOnSaleData, type AliasRegisteredData, type AliasRegisteredEvent, type AliasReleasedEvent, type AliasSaleCancelledEvent, type AliasSoldData, type AliasSoldEvent, type AliasTransferredData, type AliasTransferredEvent, type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BatchRegisterVerificationKeysArgs, type BatchVerificationKeysRegisteredEvent, type BlockInfo, type BuyAliasArgs, type Bytes32, CURRENT_CIRCUIT_VERSION, type ChainInfo, type ChainLink, type ChainLinkAddedEvent, type ChainLinkRemovedEvent, CircuitId, CircuitId as CircuitIdType, CircuitVersionResolver, type ClaimShieldedFeesParams, type ClientProviderConfig, type CommitmentsInsertedEvent, type CommitmentsInsertedEventData, type ConnectionStatus, CryptoPrecompiles, type DecodedAddChainLinkArgs, type DecodedBatchArgs, type DecodedDispatchAsPrivateLinkArgs, type DecodedEthereumTransactArgs, type DecodedEvmCallArgs, type DecodedPrecompile, type DecodedPrivateTransferArgs, type DecodedPutAliasForSaleArgs, type DecodedRegisterAliasArgs, type DecodedRemarkArgs, type DecodedRevealPrivateLinkArgs, type DecodedSetAccountMetadataArgs, type DecodedShieldArgs, type DecodedShieldBatchArgs, type DecodedShieldBatchOperation, type DecodedSudoArgs, type DecodedTransferAllArgs, type DecodedTransferArgs, type DecodedTransferKeepAliveArgs, type DecodedUnshieldArgs, type DecryptedMemo, type DispatchAsLinkedAccountArgs, type DispatchAsLinkedParams, type DispatchAsPrivateLinkArgs, type DispatchError, type DispatchInfo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, type EncryptedNoteRecord, type EndowedEventData, type EthereumExecutedData, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, type EvmExecutedData, type EvmExitReason, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFailedData, type ExtrinsicSuccessData, type FeeClaimProofInputs, type FormatOptions, KNOWN_PRECOMPILES, type KnownPrecompileInfo, type ListingInfo, type MerkleRootUpdatedData, type MerkleRootUpdatedEvent, type MerkleTreeInfo, type MetadataUpdatedEvent, NoteBuilder, type NoteDisclosure, type NoteInput, type NoteStatusUpdate, type NullifiersSpentEvent, type NullifiersSpentEventData, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, PRECOMPILE_ADDR, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateChainLinkAddedEvent, type PrivateChainLinkRemovedEvent, type PrivateChainLinkRevealedEvent, type PrivateLink, type PrivateLinkDispatchExecutedEvent, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type ProofVerificationFailedEvent, type ProofVerifiedEvent, type ProxyCallExecutedEvent, type PutAliasOnSaleArgs, type PutOnSaleParams, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type RegisterAliasArgs, type RegisterAssetArgs, type RegisterPrivateLinkArgs, type RegisterVerificationKeyArgs, type RelayerInfo, RelayerStatusModule, type RemoveChainLinkArgs, type RemovePrivateLinkArgs, type RemoveSupportedChainArgs, type RemoveVerificationKeyArgs, type ReservedEventData, type ResolvedAlias, type ResolvedSpendVersion, type RevealPrivateLinkArgs, type RpcV2MerkleProof, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, SLIP0044_NAMESPACE, type ScanCommitment, type SetAccountMetadataArgs, type SetActiveVersionArgs, type SetMetadataParams, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedEvent, type ShieldedEventData, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SignatureScheme, type StatusChangeEvent, type StatusListener, SubstrateClient, type SupportedChain, type SupportedChainAddedEvent, type SupportedChainRemovedEvent, type SystemHealth, type TokenInfo, type TokenTransfer, type TransferAliasArgs, type TransferEventData, type TransferInputNote, type TransferOutputNote, type TxResult, type UnsafeTxOptions, type UnshieldArgs, type UnshieldParams, type UnshieldProofInputs, type UnshieldedEvent, type UnshieldedEventData, type UnverifyAssetArgs, VaultLockedError, type VerificationKeyRegisteredEvent, type VerificationKeyRemovedEvent, type VerifyAssetArgs, type VerifyProofArgs, type VkEntry, type ZkNote, type ZkVerifierCall, type ZkVerifierCircuitVersionInfo, type ZkVerifierEvent, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, applyNoteStatus, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildDummyTransferInput, bytesToBigintLE, computeNullifier, computePathIndices, createNoteDisclosureKey, decodeNoteDisclosureKey, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, deriveSpendingKeyFromSignature, deriveSpendingKeyMessage, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewingPublicKey, deriveViewingSecretKey, encryptJson, encryptNote, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, formatBalance, formatORB, fromBase64, fromHex, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getPrecompileLabel, hexToBigint, hexToNumber, implicitSubstrateToEvm, isEvmAddress, isImplicitEvmAccount, isSs58, isSubstrateAddress, isUnifiedAddress, leHexToBigint, mapExtrinsicArgs, mapZkEventData, normalizeEvmAddress, noteBlindTag, randomBlinding, recoverOwnerPkPoint, selectNotes, shortHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, vaultReplacer, vaultReviver };
+export { type AccountListing, type AccountMappedData, type AccountMappedEvent, type AccountMappingCall, type AccountMappingEvent, AccountMappingModule, AccountMappingPrecompile, type AccountMetadata, type AccountUnmappedEvent, type ActiveVersionSetEvent, type AddChainLinkArgs, type AddChainLinkParams, type AddSupportedChainArgs, type AliasFullIdentity, type AliasInfo, type AliasListedForSaleEvent, type AliasOnSaleData, type AliasRegisteredData, type AliasRegisteredEvent, type AliasReleasedEvent, type AliasSaleCancelledEvent, type AliasSoldData, type AliasSoldEvent, type AliasTransferredData, type AliasTransferredEvent, type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BatchRegisterVerificationKeysArgs, type BatchVerificationKeysRegisteredEvent, type BlockInfo, type BuyAliasArgs, type Bytes32, CURRENT_CIRCUIT_VERSION, type ChainInfo, type ChainLink, type ChainLinkAddedEvent, type ChainLinkRemovedEvent, CircuitId, CircuitId as CircuitIdType, CircuitVersionResolver, type ClaimShieldedFeesParams, type ClientProviderConfig, type CommitmentsInsertedEvent, type CommitmentsInsertedEventData, type ConnectionStatus, CryptoPrecompiles, type DecodedAddChainLinkArgs, type DecodedBatchArgs, type DecodedDispatchAsPrivateLinkArgs, type DecodedEthereumTransactArgs, type DecodedEvmCallArgs, type DecodedPrecompile, type DecodedPrivateTransferArgs, type DecodedPutAliasForSaleArgs, type DecodedRegisterAliasArgs, type DecodedRemarkArgs, type DecodedRevealPrivateLinkArgs, type DecodedSetAccountMetadataArgs, type DecodedShieldArgs, type DecodedShieldBatchArgs, type DecodedShieldBatchOperation, type DecodedSudoArgs, type DecodedTransferAllArgs, type DecodedTransferArgs, type DecodedTransferKeepAliveArgs, type DecodedUnshieldArgs, type DecryptedMemo, type DispatchAsLinkedAccountArgs, type DispatchAsLinkedParams, type DispatchAsPrivateLinkArgs, type DispatchError, type DispatchInfo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, type EncryptedNoteRecord, type EndowedEventData, type EthereumExecutedData, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, type EvmExecutedData, type EvmExitReason, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFailedData, type ExtrinsicSuccessData, type FeeClaimProofInputs, type FormatOptions, KNOWN_PRECOMPILES, type KnownPrecompileInfo, type ListingInfo, type MerkleRootUpdatedData, type MerkleRootUpdatedEvent, type MerkleTreeInfo, type MetadataUpdatedEvent, NoteBuilder, type NoteDisclosure, type NoteInput, type NoteStatusUpdate, type NullifiersSpentEvent, type NullifiersSpentEventData, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, PRECOMPILE_ADDR, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateChainLinkAddedEvent, type PrivateChainLinkRemovedEvent, type PrivateChainLinkRevealedEvent, type PrivateLink, type PrivateLinkDispatchExecutedEvent, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type ProofVerificationFailedEvent, type ProofVerifiedEvent, type ProxyCallExecutedEvent, type PutAliasOnSaleArgs, type PutOnSaleParams, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type RegisterAliasArgs, type RegisterAssetArgs, type RegisterPrivateLinkArgs, type RegisterVerificationKeyArgs, type RelayerInfo, RelayerStatusModule, type RemoveChainLinkArgs, type RemovePrivateLinkArgs, type RemoveSupportedChainArgs, type RemoveVerificationKeyArgs, type ReservedEventData, type ResolvedAlias, type ResolvedSpendVersion, type RevealPrivateLinkArgs, type RpcV2MerkleProof, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, SLIP0044_NAMESPACE, type ScanCommitment, type SetAccountMetadataArgs, type SetActiveVersionArgs, type SetMetadataParams, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedEvent, type ShieldedEventData, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SignatureScheme, type StatusChangeEvent, type StatusListener, SubstrateClient, type SupportedChain, type SupportedChainAddedEvent, type SupportedChainRemovedEvent, type SystemHealth, type TokenInfo, type TokenTransfer, type TransferAliasArgs, type TransferEventData, type TransferInputNote, type TransferOutputNote, type TryDecryptOptions, type TxResult, type UnsafeTxOptions, type UnshieldArgs, type UnshieldParams, type UnshieldProofInputs, type UnshieldedEvent, type UnshieldedEventData, type UnverifyAssetArgs, VaultLockedError, type VerificationKeyRegisteredEvent, type VerificationKeyRemovedEvent, type VerifyAssetArgs, type VerifyProofArgs, type VkEntry, type ZkNote, type ZkVerifierCall, type ZkVerifierCircuitVersionInfo, type ZkVerifierEvent, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, applyNoteStatus, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildDummyTransferInput, bytesToBigintLE, computeNullifier, computePathIndices, createNoteDisclosureKey, decodeNoteDisclosureKey, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, deriveSpendingKeyFromSignature, deriveSpendingKeyMessage, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewTag, deriveViewingPublicKey, deriveViewingSecretKey, encryptJson, encryptNote, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, formatBalance, formatORB, fromBase64, fromHex, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getPrecompileLabel, hexToBigint, hexToNumber, implicitSubstrateToEvm, isEvmAddress, isImplicitEvmAccount, isSs58, isSubstrateAddress, isUnifiedAddress, leHexToBigint, mapExtrinsicArgs, mapZkEventData, normalizeEvmAddress, noteBlindTag, randomBlinding, recoverOwnerPkPoint, selectNotes, shortHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, vaultReplacer, vaultReviver };

package/dist/index.js

@@ -79,6 +79,7 @@ __export(index_exports, {
   deriveStealthSk: () => deriveStealthSk,
   deriveVaultBlindKey: () => deriveVaultBlindKey,
   deriveVaultKey: () => deriveVaultKey,
+  deriveViewTag: () => deriveViewTag,
   deriveViewingPublicKey: () => deriveViewingPublicKey,
   deriveViewingSecretKey: () => deriveViewingSecretKey,
   encryptJson: () => encryptJson,
@@ -226,7 +227,7 @@ var SubstrateClient = class _SubstrateClient {
    * Throws if the node does not respond within `timeoutMs`.
    */
   static async connect(wsUrl, timeoutMs = 15e3) {
-    const provider = (0, import_ws.getWsProvider)(wsUrl);
+    const provider = (0, import_ws.getWsProvider)(wsUrl, { heartbeatTimeout: 3e4 });
     const papi = (0, import_polkadot_api.createClient)(provider);
     let timer;
     try {
@@ -1262,6 +1263,7 @@ var BABYJUB_SUBORDER = 273603035897990940278080071815715938607681397215856725920
 // src/shielded-pool/protocol/memo.ts
 var import_sha2 = require("@noble/hashes/sha2.js");
 var KEY_DOMAIN = new TextEncoder().encode("orbinum-note-encryption-v1");
+var VIEW_TAG_DOMAIN = new TextEncoder().encode("orbinum-view-tag-v1");
 var MEMO_PLAINTEXT_SIZE = 120;
 function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk, circuitVersion) {
   const buf = new Uint8Array(MEMO_PLAINTEXT_SIZE);
@@ -1282,6 +1284,12 @@ function deriveEncryptionKey(sharedSecret, commitment) {
   h.update(KEY_DOMAIN);
   return h.digest();
 }
+function deriveViewTag(sharedSecret) {
+  const h = import_sha2.sha256.create();
+  h.update(VIEW_TAG_DOMAIN);
+  h.update(sharedSecret);
+  return h.digest()[0];
+}
 
 // src/shielded-pool/protocol/EncryptedMemo.ts
 var NONCE_SIZE = 12;
@@ -1358,6 +1366,7 @@ var EncryptedMemo = {
       const sharedPoint = (0, import_baby_jubjub.mulPointEscalar)(ivkPoint, ephSkScalar);
       sharedSecret = bigintTo32Le(sharedPoint[0]);
     }
+    nonce[0] = deriveViewTag(sharedSecret);
     const encKey = deriveEncryptionKey(sharedSecret, commitment);
     const cipher = (0, import_chacha.chacha20poly1305)(encKey, nonce);
     const ciphertext = cipher.encrypt(plaintext);
@@ -1447,24 +1456,35 @@ var EncryptedMemo = {
     const sharedPoint = (0, import_baby_jubjub.mulPointEscalar)(ephPkPoint, ivskScalar);
     return bigintTo32Le(sharedPoint[0]);
   },
-  /** @internal */
-  _decrypt(memoBytes, commitment, viewingSecretKey) {
+  /**
+   * Cheap view-tag check: does memo nonce[0] match the tag derived from
+   * `sharedSecret`? One SHA256 + one byte compare — no AEAD work.
+   *
+   * Only meaningful for memos built with view tags (commitments at/after
+   * the wallet's tagActivationLeaf): a legacy memo carries a random byte
+   * there and would false-negative 255/256 of the time.
+   */
+  checkViewTag(memoBytes, sharedSecret) {
+    if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) return false;
+    return memoBytes[0] === deriveViewTag(sharedSecret);
+  },
+  /**
+   * Decrypt with an already-computed shared secret (from
+   * extractSharedSecret), skipping the ECDH. Pair with checkViewTag for the
+   * fast scan path: ECDH once → tag check → decrypt only on match.
+   */
+  decryptWithSharedSecret(memoBytes, commitment, sharedSecret) {
+    if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) return null;
     const nonce = memoBytes.slice(0, NONCE_SIZE);
     const ciphertextWithMac = memoBytes.slice(NONCE_SIZE, NONCE_SIZE + CIPHERTEXT_SIZE);
-    const ephPkPackedBytes = memoBytes.slice(NONCE_SIZE + CIPHERTEXT_SIZE);
-    const ephPkPackedBigint = bytesToBigintLE(ephPkPackedBytes);
-    let sharedSecret;
-    if (ephPkPackedBigint === 0n) {
-      sharedSecret = new Uint8Array(32);
-    } else {
-      const ephPkPoint = (0, import_baby_jubjub.unpackPoint)(ephPkPackedBigint);
-      if (!ephPkPoint) return null;
-      const ivskScalar = bytesToBjjScalar(viewingSecretKey);
-      const sharedPoint = (0, import_baby_jubjub.mulPointEscalar)(ephPkPoint, ivskScalar);
-      sharedSecret = bigintTo32Le(sharedPoint[0]);
-    }
     const encKey = deriveEncryptionKey(sharedSecret, commitment);
     return parsePlaintext(nonce, ciphertextWithMac, encKey);
+  },
+  /** @internal */
+  _decrypt(memoBytes, commitment, viewingSecretKey) {
+    const sharedSecret = EncryptedMemo.extractSharedSecret(memoBytes, viewingSecretKey);
+    if (!sharedSecret) return null;
+    return EncryptedMemo.decryptWithSharedSecret(memoBytes, commitment, sharedSecret);
   }
 };
 
@@ -3869,10 +3889,10 @@ var import_poseidon_lite2 = require("poseidon-lite");
 function computeNullifier(commitment, spendingKey) {
   return (0, import_poseidon_lite2.poseidon2)([commitment, spendingKey]);
 }
-function tryDecryptNote(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n) {
-  return tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk).note;
+function tryDecryptNote(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n, opts) {
+  return tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk, opts).note;
 }
-function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n) {
+function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n, opts) {
   if (!commitment.encryptedMemo) return { note: null, reason: "no_memo" };
   let commitmentBytes;
   let memoBytes;
@@ -3888,21 +3908,29 @@ function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwn
       reason: `memo_size_mismatch:got_${memoBytes.length}_expected_${ENCRYPTED_MEMO_SIZE}`
     };
   }
-  const plaintext = EncryptedMemo.decrypt(memoBytes, commitmentBytes, viewingSecretKey);
+  let sharedSecret = null;
+  if (opts?.viewTag) {
+    sharedSecret = EncryptedMemo.extractSharedSecret(memoBytes, viewingSecretKey);
+    if (!sharedSecret) return { note: null, reason: "stealth_shared_secret_failed" };
+    if (!EncryptedMemo.checkViewTag(memoBytes, sharedSecret)) {
+      return { note: null, reason: "view_tag_mismatch" };
+    }
+  }
+  const plaintext = sharedSecret ? EncryptedMemo.decryptWithSharedSecret(memoBytes, commitmentBytes, sharedSecret) : EncryptedMemo.decrypt(memoBytes, commitmentBytes, viewingSecretKey);
   if (!plaintext) return { note: null, reason: "decrypt_failed:wrong_key_or_corrupt_mac" };
   let effectiveOwnerPk = plaintext.ownerPk;
   let effectiveSpendingKey = spendingKey;
   if (ownOwnerPk !== 0n && plaintext.ownerPk !== ownOwnerPk) {
-    const sharedSecret = EncryptedMemo.extractSharedSecret(memoBytes, viewingSecretKey);
-    if (!sharedSecret) return { note: null, reason: "stealth_shared_secret_failed" };
+    const ss = sharedSecret ?? EncryptedMemo.extractSharedSecret(memoBytes, viewingSecretKey);
+    if (!ss) return { note: null, reason: "stealth_shared_secret_failed" };
     const ownPkPoint = recoverOwnerPkPoint(ownOwnerPk);
     if (!ownPkPoint) return { note: null, reason: "stealth_invalid_own_owner_pk" };
-    const stealthOwnerPk = deriveStealthOwnerPk(sharedSecret, ownOwnerPk, ownPkPoint);
+    const stealthOwnerPk = deriveStealthOwnerPk(ss, ownOwnerPk, ownPkPoint);
     if (stealthOwnerPk !== plaintext.ownerPk) {
       return { note: null, reason: "commitment_mismatch" };
     }
     effectiveOwnerPk = stealthOwnerPk;
-    effectiveSpendingKey = deriveStealthSk(sharedSecret, ownOwnerPk, spendingKey);
+    effectiveSpendingKey = deriveStealthSk(ss, ownOwnerPk, spendingKey);
   }
   const recomputed = (0, import_poseidon_lite2.poseidon4)([
     plaintext.value,
@@ -5303,6 +5331,7 @@ var import_polkadot_api4 = require("polkadot-api");
   deriveStealthSk,
   deriveVaultBlindKey,
   deriveVaultKey,
+  deriveViewTag,
   deriveViewingPublicKey,
   deriveViewingSecretKey,
   encryptJson,

package/dist/index.mjs

@@ -95,7 +95,7 @@ var SubstrateClient = class _SubstrateClient {
    * Throws if the node does not respond within `timeoutMs`.
    */
   static async connect(wsUrl, timeoutMs = 15e3) {
-    const provider = getWsProvider(wsUrl);
+    const provider = getWsProvider(wsUrl, { heartbeatTimeout: 3e4 });
     const papi = createClient(provider);
     let timer;
     try {
@@ -1131,6 +1131,7 @@ var BABYJUB_SUBORDER = 273603035897990940278080071815715938607681397215856725920
 // src/shielded-pool/protocol/memo.ts
 import { sha256 } from "@noble/hashes/sha2.js";
 var KEY_DOMAIN = new TextEncoder().encode("orbinum-note-encryption-v1");
+var VIEW_TAG_DOMAIN = new TextEncoder().encode("orbinum-view-tag-v1");
 var MEMO_PLAINTEXT_SIZE = 120;
 function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk, circuitVersion) {
   const buf = new Uint8Array(MEMO_PLAINTEXT_SIZE);
@@ -1151,6 +1152,12 @@ function deriveEncryptionKey(sharedSecret, commitment) {
   h.update(KEY_DOMAIN);
   return h.digest();
 }
+function deriveViewTag(sharedSecret) {
+  const h = sha256.create();
+  h.update(VIEW_TAG_DOMAIN);
+  h.update(sharedSecret);
+  return h.digest()[0];
+}
 
 // src/shielded-pool/protocol/EncryptedMemo.ts
 var NONCE_SIZE = 12;
@@ -1227,6 +1234,7 @@ var EncryptedMemo = {
       const sharedPoint = mulPointEscalar(ivkPoint, ephSkScalar);
       sharedSecret = bigintTo32Le(sharedPoint[0]);
     }
+    nonce[0] = deriveViewTag(sharedSecret);
     const encKey = deriveEncryptionKey(sharedSecret, commitment);
     const cipher = chacha20poly1305(encKey, nonce);
     const ciphertext = cipher.encrypt(plaintext);
@@ -1316,24 +1324,35 @@ var EncryptedMemo = {
     const sharedPoint = mulPointEscalar(ephPkPoint, ivskScalar);
     return bigintTo32Le(sharedPoint[0]);
   },
-  /** @internal */
-  _decrypt(memoBytes, commitment, viewingSecretKey) {
+  /**
+   * Cheap view-tag check: does memo nonce[0] match the tag derived from
+   * `sharedSecret`? One SHA256 + one byte compare — no AEAD work.
+   *
+   * Only meaningful for memos built with view tags (commitments at/after
+   * the wallet's tagActivationLeaf): a legacy memo carries a random byte
+   * there and would false-negative 255/256 of the time.
+   */
+  checkViewTag(memoBytes, sharedSecret) {
+    if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) return false;
+    return memoBytes[0] === deriveViewTag(sharedSecret);
+  },
+  /**
+   * Decrypt with an already-computed shared secret (from
+   * extractSharedSecret), skipping the ECDH. Pair with checkViewTag for the
+   * fast scan path: ECDH once → tag check → decrypt only on match.
+   */
+  decryptWithSharedSecret(memoBytes, commitment, sharedSecret) {
+    if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) return null;
     const nonce = memoBytes.slice(0, NONCE_SIZE);
     const ciphertextWithMac = memoBytes.slice(NONCE_SIZE, NONCE_SIZE + CIPHERTEXT_SIZE);
-    const ephPkPackedBytes = memoBytes.slice(NONCE_SIZE + CIPHERTEXT_SIZE);
-    const ephPkPackedBigint = bytesToBigintLE(ephPkPackedBytes);
-    let sharedSecret;
-    if (ephPkPackedBigint === 0n) {
-      sharedSecret = new Uint8Array(32);
-    } else {
-      const ephPkPoint = unpackPoint(ephPkPackedBigint);
-      if (!ephPkPoint) return null;
-      const ivskScalar = bytesToBjjScalar(viewingSecretKey);
-      const sharedPoint = mulPointEscalar(ephPkPoint, ivskScalar);
-      sharedSecret = bigintTo32Le(sharedPoint[0]);
-    }
     const encKey = deriveEncryptionKey(sharedSecret, commitment);
     return parsePlaintext(nonce, ciphertextWithMac, encKey);
+  },
+  /** @internal */
+  _decrypt(memoBytes, commitment, viewingSecretKey) {
+    const sharedSecret = EncryptedMemo.extractSharedSecret(memoBytes, viewingSecretKey);
+    if (!sharedSecret) return null;
+    return EncryptedMemo.decryptWithSharedSecret(memoBytes, commitment, sharedSecret);
   }
 };
 
@@ -3741,10 +3760,10 @@ import { poseidon2 as poseidon22, poseidon4 as poseidon42 } from "poseidon-lite"
 function computeNullifier(commitment, spendingKey) {
   return poseidon22([commitment, spendingKey]);
 }
-function tryDecryptNote(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n) {
-  return tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk).note;
+function tryDecryptNote(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n, opts) {
+  return tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk, opts).note;
 }
-function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n) {
+function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n, opts) {
   if (!commitment.encryptedMemo) return { note: null, reason: "no_memo" };
   let commitmentBytes;
   let memoBytes;
@@ -3760,21 +3779,29 @@ function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwn
       reason: `memo_size_mismatch:got_${memoBytes.length}_expected_${ENCRYPTED_MEMO_SIZE}`
     };
   }
-  const plaintext = EncryptedMemo.decrypt(memoBytes, commitmentBytes, viewingSecretKey);
+  let sharedSecret = null;
+  if (opts?.viewTag) {
+    sharedSecret = EncryptedMemo.extractSharedSecret(memoBytes, viewingSecretKey);
+    if (!sharedSecret) return { note: null, reason: "stealth_shared_secret_failed" };
+    if (!EncryptedMemo.checkViewTag(memoBytes, sharedSecret)) {
+      return { note: null, reason: "view_tag_mismatch" };
+    }
+  }
+  const plaintext = sharedSecret ? EncryptedMemo.decryptWithSharedSecret(memoBytes, commitmentBytes, sharedSecret) : EncryptedMemo.decrypt(memoBytes, commitmentBytes, viewingSecretKey);
   if (!plaintext) return { note: null, reason: "decrypt_failed:wrong_key_or_corrupt_mac" };
   let effectiveOwnerPk = plaintext.ownerPk;
   let effectiveSpendingKey = spendingKey;
   if (ownOwnerPk !== 0n && plaintext.ownerPk !== ownOwnerPk) {
-    const sharedSecret = EncryptedMemo.extractSharedSecret(memoBytes, viewingSecretKey);
-    if (!sharedSecret) return { note: null, reason: "stealth_shared_secret_failed" };
+    const ss = sharedSecret ?? EncryptedMemo.extractSharedSecret(memoBytes, viewingSecretKey);
+    if (!ss) return { note: null, reason: "stealth_shared_secret_failed" };
     const ownPkPoint = recoverOwnerPkPoint(ownOwnerPk);
     if (!ownPkPoint) return { note: null, reason: "stealth_invalid_own_owner_pk" };
-    const stealthOwnerPk = deriveStealthOwnerPk(sharedSecret, ownOwnerPk, ownPkPoint);
+    const stealthOwnerPk = deriveStealthOwnerPk(ss, ownOwnerPk, ownPkPoint);
     if (stealthOwnerPk !== plaintext.ownerPk) {
       return { note: null, reason: "commitment_mismatch" };
     }
     effectiveOwnerPk = stealthOwnerPk;
-    effectiveSpendingKey = deriveStealthSk(sharedSecret, ownOwnerPk, spendingKey);
+    effectiveSpendingKey = deriveStealthSk(ss, ownOwnerPk, spendingKey);
   }
   const recomputed = poseidon42([
     plaintext.value,
@@ -5197,6 +5224,7 @@ export {
   deriveStealthSk,
   deriveVaultBlindKey,
   deriveVaultKey,
+  deriveViewTag,
   deriveViewingPublicKey,
   deriveViewingSecretKey,
   encryptJson,

package/package.json

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