@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/crypto-babyjub.js

@@ -0,0 +1,312 @@
+/**
+ * Baby Jubjub curve operations for UTXOpia
+ *
+ * Twisted Edwards curve matching circomlib's BabyJubjub:
+ *   a*x^2 + y^2 = 1 + d*x^2*y^2
+ *   a = 168700, d = 168696
+ *
+ * Over BN254 scalar field.
+ * Used for spending keys and in-circuit key derivation via BabyPbk().
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-2494
+ * @see circomlib/circuits/babyjub.circom
+ */
+import { sha256 } from "@noble/hashes/sha2.js";
+// =============================================================================
+// Field Constants
+// =============================================================================
+/** BN254 scalar field prime (Baby Jubjub base field) */
+export const BABYJUB_FIELD_PRIME = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/** Baby Jubjub curve parameter a */
+export const BABYJUB_A = 168700n;
+/** Baby Jubjub curve parameter d */
+export const BABYJUB_D = 168696n;
+/**
+ * Baby Jubjub subgroup order (order of BASE8 generator)
+ * = field_prime / 8 (cofactor 8)
+ */
+export const BABYJUB_ORDER = 2736030358979909402780800718157159386076813972158567259200215660948447373041n;
+/**
+ * Baby Jubjub cofactor
+ */
+export const BABYJUB_COFACTOR = 8n;
+/**
+ * Generator point (BASE8) - matches circomlib's BabyPbk() generator
+ * This is the base point of the prime-order subgroup (cofactor-cleared).
+ */
+export const BABYJUB_BASE8 = {
+    x: 5299619240641551281634865583518297030282874472190772894086521144482721001553n,
+    y: 16950150798460657717958625567821834550301663161624707787222815936182638968203n,
+};
+/** Identity element (point at infinity for twisted Edwards) */
+export const BABYJUB_IDENTITY = { x: 0n, y: 1n };
+// =============================================================================
+// Modular Arithmetic
+// =============================================================================
+const P = BABYJUB_FIELD_PRIME;
+function mod(n, p = P) {
+    const result = n % p;
+    return result >= 0n ? result : result + p;
+}
+function modInverse(a, p = P) {
+    let [old_r, r] = [a, p];
+    let [old_s, s] = [1n, 0n];
+    while (r !== 0n) {
+        const q = old_r / r;
+        [old_r, r] = [r, old_r - q * r];
+        [old_s, s] = [s, old_s - q * s];
+    }
+    return mod(old_s, p);
+}
+// =============================================================================
+// Curve Operations
+// =============================================================================
+/**
+ * Check if a point is the identity element
+ */
+export function isIdentity(point) {
+    return point.x === 0n && point.y === 1n;
+}
+/**
+ * Verify a point is on the Baby Jubjub curve
+ *
+ * a*x^2 + y^2 = 1 + d*x^2*y^2
+ */
+export function isOnBabyJubCurve(point) {
+    if (isIdentity(point))
+        return true;
+    const { x, y } = point;
+    const x2 = mod(x * x);
+    const y2 = mod(y * y);
+    const lhs = mod(BABYJUB_A * x2 + y2);
+    const rhs = mod(1n + BABYJUB_D * x2 * y2);
+    return lhs === rhs;
+}
+/**
+ * Point addition on Baby Jubjub (twisted Edwards addition law)
+ *
+ * For twisted Edwards: a*x^2 + y^2 = 1 + d*x^2*y^2
+ * x3 = (x1*y2 + y1*x2) / (1 + d*x1*x2*y1*y2)
+ * y3 = (y1*y2 - a*x1*x2) / (1 - d*x1*x2*y1*y2)
+ */
+export function babyJubAdd(p1, p2) {
+    const { x: x1, y: y1 } = p1;
+    const { x: x2, y: y2 } = p2;
+    const x1x2 = mod(x1 * x2);
+    const y1y2 = mod(y1 * y2);
+    const dx1x2y1y2 = mod(BABYJUB_D * x1x2 * y1y2);
+    const x3Num = mod(x1 * y2 + y1 * x2);
+    const x3Den = mod(1n + dx1x2y1y2);
+    const y3Num = mod(y1y2 - BABYJUB_A * x1x2);
+    const y3Den = mod(1n - dx1x2y1y2);
+    const x3 = mod(x3Num * modInverse(x3Den));
+    const y3 = mod(y3Num * modInverse(y3Den));
+    return { x: x3, y: y3 };
+}
+/**
+ * Point doubling on Baby Jubjub
+ */
+export function babyJubDouble(point) {
+    return babyJubAdd(point, point);
+}
+/**
+ * Scalar multiplication using double-and-add (constant-time Montgomery ladder)
+ *
+ * SECURITY: Uses Montgomery ladder for constant-time execution.
+ */
+export function babyJubMul(scalar, point) {
+    scalar = mod(scalar, BABYJUB_ORDER);
+    if (scalar === 0n)
+        return BABYJUB_IDENTITY;
+    if (isIdentity(point))
+        return BABYJUB_IDENTITY;
+    // Montgomery ladder
+    let r0 = BABYJUB_IDENTITY;
+    let r1 = point;
+    // Process all bits of the scalar
+    const bits = scalar.toString(2).length;
+    for (let i = bits - 1; i >= 0; i--) {
+        const bit = (scalar >> BigInt(i)) & 1n;
+        if (bit === 1n) {
+            r0 = babyJubAdd(r0, r1);
+            r1 = babyJubDouble(r1);
+        }
+        else {
+            r1 = babyJubAdd(r0, r1);
+            r0 = babyJubDouble(r0);
+        }
+    }
+    return r0;
+}
+/**
+ * Negate a point (flip x coordinate for twisted Edwards)
+ */
+export function babyJubNegate(point) {
+    if (isIdentity(point))
+        return point;
+    return {
+        x: mod(-point.x),
+        y: point.y,
+    };
+}
+// =============================================================================
+// Compression / Serialization
+// =============================================================================
+/**
+ * Compress a Baby Jubjub point to 32 bytes
+ *
+ * Format: y-coordinate with sign of x stored in MSB of last byte
+ * This matches circomlib's pointbits.circom compression.
+ */
+export function babyJubCompress(point) {
+    const bytes = new Uint8Array(32);
+    let y = point.y;
+    // Store y in little-endian (matching circomlib convention)
+    let temp = y;
+    for (let i = 0; i < 32; i++) {
+        bytes[i] = Number(temp & 0xffn);
+        temp = temp >> 8n;
+    }
+    // Set MSB of last byte to sign of x (1 if x is odd)
+    if ((point.x & 1n) === 1n) {
+        bytes[31] |= 0x80;
+    }
+    return bytes;
+}
+/**
+ * Decompress a 32-byte representation to a Baby Jubjub point
+ */
+export function babyJubDecompress(bytes) {
+    if (bytes.length !== 32) {
+        throw new Error("Expected 32 bytes for compressed Baby Jubjub point");
+    }
+    // Extract sign of x from MSB
+    const xSign = (bytes[31] & 0x80) !== 0;
+    // Read y (little-endian), clearing the sign bit
+    const cleanBytes = new Uint8Array(bytes);
+    cleanBytes[31] &= 0x7f;
+    let y = 0n;
+    for (let i = 31; i >= 0; i--) {
+        y = (y << 8n) | BigInt(cleanBytes[i]);
+    }
+    // Recover x from curve equation: a*x^2 + y^2 = 1 + d*x^2*y^2
+    // x^2 = (1 - y^2) / (a - d*y^2)
+    const y2 = mod(y * y);
+    const num = mod(1n - y2);
+    const den = mod(BABYJUB_A - BABYJUB_D * y2);
+    const x2 = mod(num * modInverse(den));
+    // Compute x via Tonelli-Shanks square root
+    let x = modSqrt(x2);
+    // Adjust sign of x
+    const xIsOdd = (x & 1n) === 1n;
+    if (xIsOdd !== xSign) {
+        x = mod(-x);
+    }
+    const point = { x, y };
+    if (!isOnBabyJubCurve(point)) {
+        throw new Error("Decompressed point is not on the Baby Jubjub curve");
+    }
+    return point;
+}
+/**
+ * Tonelli-Shanks modular square root
+ */
+function modSqrt(n) {
+    if (n === 0n)
+        return 0n;
+    // For p ≡ 3 (mod 4), sqrt = n^((p+1)/4)
+    // BN254 scalar field: p ≡ 1 (mod 4), so we need full Tonelli-Shanks
+    const p = P;
+    // Check if n is a quadratic residue
+    const euler = modPow(n, (p - 1n) / 2n);
+    if (euler !== 1n) {
+        throw new Error("No square root exists (not a quadratic residue)");
+    }
+    // Factor out powers of 2 from p-1
+    let Q = p - 1n;
+    let S = 0n;
+    while ((Q & 1n) === 0n) {
+        Q >>= 1n;
+        S++;
+    }
+    // Find a non-residue z
+    let z = 2n;
+    while (modPow(z, (p - 1n) / 2n) !== p - 1n) {
+        z++;
+    }
+    let M = S;
+    let c = modPow(z, Q);
+    let t = modPow(n, Q);
+    let R = modPow(n, (Q + 1n) / 2n);
+    while (true) {
+        if (t === 1n)
+            return R;
+        let i = 1n;
+        let temp = mod(t * t);
+        while (temp !== 1n) {
+            temp = mod(temp * temp);
+            i++;
+        }
+        const b = modPow(c, 1n << (M - i - 1n));
+        M = i;
+        c = mod(b * b);
+        t = mod(t * c);
+        R = mod(R * b);
+    }
+}
+function modPow(base, exp) {
+    let result = 1n;
+    base = mod(base);
+    while (exp > 0n) {
+        if (exp & 1n) {
+            result = mod(result * base);
+        }
+        exp >>= 1n;
+        base = mod(base * base);
+    }
+    return result;
+}
+// =============================================================================
+// Key Generation
+// =============================================================================
+/**
+ * Generate a random Baby Jubjub keypair
+ */
+export function generateBabyJubKeyPair() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    const privKey = babyJubScalarFromBytes(bytes);
+    const pubKey = babyJubMul(privKey, BABYJUB_BASE8);
+    return { privKey, pubKey };
+}
+/**
+ * Derive a Baby Jubjub keypair from a seed (deterministic)
+ */
+export function deriveBabyJubKeyFromSeed(seed) {
+    const hash = sha256(seed);
+    const privKey = babyJubScalarFromBytes(hash);
+    const pubKey = babyJubMul(privKey, BABYJUB_BASE8);
+    return { privKey, pubKey };
+}
+/**
+ * Derive a scalar from bytes (reduces modulo Baby Jubjub order)
+ */
+export function babyJubScalarFromBytes(bytes) {
+    let result = 0n;
+    for (let i = 0; i < bytes.length; i++) {
+        result = (result << 8n) | BigInt(bytes[i]);
+    }
+    return mod(result, BABYJUB_ORDER);
+}
+/**
+ * Convert a Baby Jubjub scalar to 32 bytes (big-endian)
+ */
+export function babyJubScalarToBytes(scalar) {
+    const bytes = new Uint8Array(32);
+    let temp = mod(scalar, BABYJUB_ORDER);
+    for (let i = 31; i >= 0; i--) {
+        bytes[i] = Number(temp & 0xffn);
+        temp >>= 8n;
+    }
+    return bytes;
+}

package/packages/sdk/dist/crypto-ed25519.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Ed25519/X25519 utilities for UTXOpia viewing keys
+ *
+ * Uses @noble/curves for Ed25519 key generation and X25519 ECDH.
+ * Ed25519 is used for viewing keys (off-chain only, fast and standard).
+ *
+ * Viewing key operations:
+ * - Key generation: Ed25519 keypair
+ * - ECDH: X25519 (Montgomery form of Curve25519)
+ * - Shared secret: 32 bytes from X25519
+ *
+ * @see https://github.com/paulmillr/noble-curves
+ */
+/**
+ * Generate an Ed25519 keypair for viewing key use
+ *
+ * @returns 32-byte private key and 32-byte public key
+ */
+export declare function ed25519GenerateKeyPair(): {
+    privKey: Uint8Array;
+    pubKey: Uint8Array;
+};
+/**
+ * Derive an Ed25519 public key from a private key
+ *
+ * @param privKey - 32-byte Ed25519 private key
+ * @returns 32-byte Ed25519 public key
+ */
+export declare function ed25519GetPublicKey(privKey: Uint8Array): Uint8Array;
+/**
+ * Derive an Ed25519 keypair from a seed (deterministic)
+ *
+ * @param seed - Arbitrary bytes to derive from (will be SHA256'd to 32 bytes)
+ * @returns Ed25519 keypair
+ */
+export declare function ed25519DeriveKeyFromSeed(seed: Uint8Array): {
+    privKey: Uint8Array;
+    pubKey: Uint8Array;
+};
+/**
+ * Convert Ed25519 public key to X25519 (Montgomery form) for ECDH
+ *
+ * Uses the birational map from twisted Edwards to Montgomery form.
+ */
+export declare function ed25519PubToX25519(edPub: Uint8Array): Uint8Array;
+/**
+ * Perform X25519 ECDH key exchange
+ *
+ * @param privKey - 32-byte Ed25519 private key (will be converted internally)
+ * @param pubKey - 32-byte Ed25519 public key (will be converted to X25519)
+ * @returns 32-byte shared secret
+ */
+export declare function x25519Ecdh(privKey: Uint8Array, pubKey: Uint8Array): Uint8Array;
+/**
+ * Convert an Ed25519 private key to its X25519 (Montgomery) scalar.
+ *
+ * Uses the same clamped-scalar derivation as `x25519Ecdh` internally.
+ * The returned 32 bytes are a valid X25519 private key suitable for
+ * `x25519.getSharedSecret` or `x25519.getPublicKey`.
+ */
+export declare function ed25519PrivToX25519(edPriv: Uint8Array): Uint8Array;
+/**
+ * Derive an X25519 public key from a raw X25519 private scalar.
+ */
+export declare function x25519PubFromPriv(x25519Priv: Uint8Array): Uint8Array;
+/**
+ * Perform X25519 ECDH with raw X25519 keys (no Ed25519 conversion).
+ *
+ * @param x25519Priv - 32-byte X25519 private scalar (from `ed25519PrivToX25519` or `x25519PubFromPriv`)
+ * @param x25519Pub  - 32-byte X25519 public key (u-coordinate)
+ * @returns 32-byte shared secret
+ */
+export declare function x25519EcdhRaw(x25519Priv: Uint8Array, x25519Pub: Uint8Array): Uint8Array;
+/**
+ * Derive an 8-byte encryption key from X25519 shared secret
+ *
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns 8-byte encryption key
+ */
+export declare function deriveAmountKey(sharedSecret: Uint8Array): Uint8Array;
+/**
+ * Encrypt amount with XOR using shared secret
+ *
+ * @param amount - Amount in satoshis
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns 8-byte encrypted amount
+ */
+export declare function encryptAmountEd25519(amount: bigint, sharedSecret: Uint8Array): Uint8Array;
+/**
+ * Decrypt amount with XOR using shared secret
+ *
+ * @param encryptedAmount - 8-byte encrypted amount
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns Decrypted amount in satoshis
+ */
+export declare function decryptAmountEd25519(encryptedAmount: Uint8Array, sharedSecret: Uint8Array): bigint;
+/**
+ * Encrypt note data: token_id(32 bytes, big-endian) || amount(8 bytes, LE)
+ *
+ * @param tokenId - Token identifier as bigint
+ * @param amount - Amount in token's native units
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns 40-byte encrypted blob
+ */
+export declare function encryptNoteData(tokenId: bigint, amount: bigint, sharedSecret: Uint8Array): Uint8Array;
+/**
+ * Decrypt note data: extracts token_id and amount from 40-byte encrypted blob.
+ *
+ * @param encryptedData - 40-byte encrypted blob
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns { tokenId, amount }
+ */
+export declare function decryptNoteData(encryptedData: Uint8Array, sharedSecret: Uint8Array): {
+    tokenId: bigint;
+    amount: bigint;
+};

package/packages/sdk/dist/crypto-ed25519.js

@@ -0,0 +1,235 @@
+/**
+ * Ed25519/X25519 utilities for UTXOpia viewing keys
+ *
+ * Uses @noble/curves for Ed25519 key generation and X25519 ECDH.
+ * Ed25519 is used for viewing keys (off-chain only, fast and standard).
+ *
+ * Viewing key operations:
+ * - Key generation: Ed25519 keypair
+ * - ECDH: X25519 (Montgomery form of Curve25519)
+ * - Shared secret: 32 bytes from X25519
+ *
+ * @see https://github.com/paulmillr/noble-curves
+ */
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { x25519 } from "@noble/curves/ed25519.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+// =============================================================================
+// Key Generation
+// =============================================================================
+/**
+ * Generate an Ed25519 keypair for viewing key use
+ *
+ * @returns 32-byte private key and 32-byte public key
+ */
+export function ed25519GenerateKeyPair() {
+    const privKey = ed25519.utils.randomSecretKey();
+    const pubKey = ed25519.getPublicKey(privKey);
+    return { privKey, pubKey };
+}
+/**
+ * Derive an Ed25519 public key from a private key
+ *
+ * @param privKey - 32-byte Ed25519 private key
+ * @returns 32-byte Ed25519 public key
+ */
+export function ed25519GetPublicKey(privKey) {
+    return ed25519.getPublicKey(privKey);
+}
+/**
+ * Derive an Ed25519 keypair from a seed (deterministic)
+ *
+ * @param seed - Arbitrary bytes to derive from (will be SHA256'd to 32 bytes)
+ * @returns Ed25519 keypair
+ */
+export function ed25519DeriveKeyFromSeed(seed) {
+    const privKey = sha256(seed);
+    const pubKey = ed25519.getPublicKey(privKey);
+    return { privKey, pubKey };
+}
+// =============================================================================
+// ECDH (X25519)
+// =============================================================================
+/**
+ * Convert Ed25519 public key to X25519 (Montgomery form) for ECDH
+ *
+ * Uses the birational map from twisted Edwards to Montgomery form.
+ */
+export function ed25519PubToX25519(edPub) {
+    return ed25519.utils.toMontgomery(edPub);
+}
+/**
+ * Perform X25519 ECDH key exchange
+ *
+ * @param privKey - 32-byte Ed25519 private key (will be converted internally)
+ * @param pubKey - 32-byte Ed25519 public key (will be converted to X25519)
+ * @returns 32-byte shared secret
+ */
+export function x25519Ecdh(privKey, pubKey) {
+    // Convert Ed25519 pub to X25519 u-coordinate
+    const x25519Pub = ed25519.utils.toMontgomery(pubKey);
+    // Convert Ed25519 private key to X25519 scalar
+    const x25519Priv = ed25519.utils.toMontgomerySecret(privKey);
+    return x25519.getSharedSecret(x25519Priv, x25519Pub);
+}
+/**
+ * Convert an Ed25519 private key to its X25519 (Montgomery) scalar.
+ *
+ * Uses the same clamped-scalar derivation as `x25519Ecdh` internally.
+ * The returned 32 bytes are a valid X25519 private key suitable for
+ * `x25519.getSharedSecret` or `x25519.getPublicKey`.
+ */
+export function ed25519PrivToX25519(edPriv) {
+    return ed25519.utils.toMontgomerySecret(edPriv);
+}
+/**
+ * Derive an X25519 public key from a raw X25519 private scalar.
+ */
+export function x25519PubFromPriv(x25519Priv) {
+    return x25519.getPublicKey(x25519Priv);
+}
+/**
+ * Perform X25519 ECDH with raw X25519 keys (no Ed25519 conversion).
+ *
+ * @param x25519Priv - 32-byte X25519 private scalar (from `ed25519PrivToX25519` or `x25519PubFromPriv`)
+ * @param x25519Pub  - 32-byte X25519 public key (u-coordinate)
+ * @returns 32-byte shared secret
+ */
+export function x25519EcdhRaw(x25519Priv, x25519Pub) {
+    return x25519.getSharedSecret(x25519Priv, x25519Pub);
+}
+// =============================================================================
+// Amount Encryption/Decryption
+// =============================================================================
+/**
+ * Derive an 8-byte encryption key from X25519 shared secret
+ *
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns 8-byte encryption key
+ */
+export function deriveAmountKey(sharedSecret) {
+    const hash = sha256(sharedSecret);
+    return hash.slice(0, 8);
+}
+/**
+ * Encrypt amount with XOR using shared secret
+ *
+ * @param amount - Amount in satoshis
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns 8-byte encrypted amount
+ */
+export function encryptAmountEd25519(amount, sharedSecret) {
+    const key = deriveAmountKey(sharedSecret);
+    const amountBytes = new Uint8Array(8);
+    let temp = amount;
+    for (let i = 0; i < 8; i++) {
+        amountBytes[i] = Number(temp & 0xffn);
+        temp >>= 8n;
+    }
+    const encrypted = new Uint8Array(8);
+    for (let i = 0; i < 8; i++) {
+        encrypted[i] = amountBytes[i] ^ key[i];
+    }
+    return encrypted;
+}
+/**
+ * Decrypt amount with XOR using shared secret
+ *
+ * @param encryptedAmount - 8-byte encrypted amount
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns Decrypted amount in satoshis
+ */
+export function decryptAmountEd25519(encryptedAmount, sharedSecret) {
+    const key = deriveAmountKey(sharedSecret);
+    const decrypted = new Uint8Array(8);
+    for (let i = 0; i < 8; i++) {
+        decrypted[i] = encryptedAmount[i] ^ key[i];
+    }
+    let amount = 0n;
+    for (let i = 7; i >= 0; i--) {
+        amount = (amount << 8n) | BigInt(decrypted[i]);
+    }
+    return amount;
+}
+// ============================================================================
+// Combined Note Data Encryption (token_id + amount)
+// ============================================================================
+/**
+ * Derive a 40-byte keystream for encrypting token_id(32) + amount(8).
+ * Uses two SHA-256 hashes with domain separation to get enough key material.
+ *
+ * keystream[0..32]  = sha256(sharedSecret || 0x00)  — for token_id
+ * keystream[32..40] = sha256(sharedSecret || 0x01)[0..8] — for amount
+ */
+function deriveNoteDataKeystream(sharedSecret) {
+    const buf0 = new Uint8Array(sharedSecret.length + 1);
+    buf0.set(sharedSecret);
+    buf0[sharedSecret.length] = 0x00;
+    const buf1 = new Uint8Array(sharedSecret.length + 1);
+    buf1.set(sharedSecret);
+    buf1[sharedSecret.length] = 0x01;
+    const key0 = sha256(buf0); // 32 bytes for token_id
+    const key1 = sha256(buf1); // 32 bytes, take first 8 for amount
+    const keystream = new Uint8Array(40);
+    keystream.set(key0, 0);
+    keystream.set(key1.slice(0, 8), 32);
+    return keystream;
+}
+/**
+ * Encrypt note data: token_id(32 bytes, big-endian) || amount(8 bytes, LE)
+ *
+ * @param tokenId - Token identifier as bigint
+ * @param amount - Amount in token's native units
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns 40-byte encrypted blob
+ */
+export function encryptNoteData(tokenId, amount, sharedSecret) {
+    const keystream = deriveNoteDataKeystream(sharedSecret);
+    const plaintext = new Uint8Array(40);
+    // token_id: 32 bytes big-endian
+    let t = tokenId;
+    for (let i = 31; i >= 0; i--) {
+        plaintext[i] = Number(t & 0xffn);
+        t >>= 8n;
+    }
+    // amount: 8 bytes little-endian
+    let a = amount;
+    for (let i = 0; i < 8; i++) {
+        plaintext[32 + i] = Number(a & 0xffn);
+        a >>= 8n;
+    }
+    // XOR
+    const encrypted = new Uint8Array(40);
+    for (let i = 0; i < 40; i++) {
+        encrypted[i] = plaintext[i] ^ keystream[i];
+    }
+    return encrypted;
+}
+/**
+ * Decrypt note data: extracts token_id and amount from 40-byte encrypted blob.
+ *
+ * @param encryptedData - 40-byte encrypted blob
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns { tokenId, amount }
+ */
+export function decryptNoteData(encryptedData, sharedSecret) {
+    if (encryptedData.length < 40) {
+        throw new Error(`Expected 40-byte encrypted note data, got ${encryptedData.length}`);
+    }
+    const keystream = deriveNoteDataKeystream(sharedSecret);
+    const plaintext = new Uint8Array(40);
+    for (let i = 0; i < 40; i++) {
+        plaintext[i] = encryptedData[i] ^ keystream[i];
+    }
+    // token_id: 32 bytes big-endian → bigint
+    let tokenId = 0n;
+    for (let i = 0; i < 32; i++) {
+        tokenId = (tokenId << 8n) | BigInt(plaintext[i]);
+    }
+    // amount: 8 bytes little-endian → bigint
+    let amount = 0n;
+    for (let i = 7; i >= 0; i--) {
+        amount = (amount << 8n) | BigInt(plaintext[32 + i]);
+    }
+    return { tokenId, amount };
+}