@veilo/sdk-core 0.3.3 → 0.4.0

package/dist/esm/client.d.ts

@@ -0,0 +1,407 @@
+import * as anchor from "@coral-xyz/anchor";
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { PublicKey, Transaction, Keypair } from "@solana/web3.js";
+import { TransactionProofStruct, TransactionProofBuilder, ExtData } from "./proof.js";
+import { SerializedUTXO, InputUTXO } from "./utxo.js";
+import { MerkleTree } from "./merkle.js";
+import { PrivacyConfigAccount } from "./config.js";
+/**
+ * Get pool PDAs for a given mint address.
+ * Note: All seeds use "v3" suffix.
+ */
+export declare function getPoolPdas(programId: PublicKey, mintAddress: PublicKey): {
+    config: anchor.web3.PublicKey;
+    vault: anchor.web3.PublicKey;
+    nullifiers: anchor.web3.PublicKey;
+};
+/**
+ * Get the note tree PDA for a specific tree ID.
+ */
+export declare function getNoteTreePda(programId: PublicKey, mintAddress: PublicKey, treeId: number): PublicKey;
+/**
+ * Get the global config PDA.
+ */
+export declare function getGlobalConfigPda(programId: PublicKey): PublicKey;
+/**
+ * Get the nullifier marker PDA for a specific nullifier.
+ * NOTE: Nullifier markers are global (no tree_id) to prevent cross-tree double-spend.
+ */
+export declare function getNullifierMarkerPda(programId: PublicKey, mintAddress: PublicKey, nullifier: Uint8Array): PublicKey;
+/**
+ * Fetch and decode the on-chain PrivacyConfig account for a pool.
+ */
+export declare function fetchPoolConfig<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<PrivacyConfigAccount>;
+/**
+ * Check whether a nullifier has been spent on-chain.
+ * Returns true if the nullifier marker PDA exists (funds already spent).
+ */
+export declare function checkNullifierSpent<T extends Idl>(program: Program<T>, mintAddress: PublicKey, nullifier: Uint8Array): Promise<boolean>;
+/** On-chain tree utilization info */
+export type TreeInfo = {
+    treeId: number;
+    leafCount: number;
+    capacity: number;
+    utilizationPercent: number;
+    remainingCapacity: number;
+    isFull: boolean;
+    treePDA: PublicKey;
+};
+/**
+ * Fetch utilization info for a specific tree.
+ * Returns null if the tree does not exist yet.
+ */
+export declare function getTreeInfo<T extends Idl>(program: Program<T>, mintAddress: PublicKey, treeId: number): Promise<TreeInfo | null>;
+/**
+ * Fetch utilization info for all trees in a pool.
+ */
+export declare function getAllTreeInfo<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<TreeInfo[]>;
+/**
+ * Find the best tree to deposit into.
+ *
+ * Strategy (matches veilo-dapp):
+ * 1. Discard full trees.
+ * 2. Prefer the LOWEST tree ID with remaining capacity ≥ minCapacity (default 0.01%).
+ * 3. Ensures trees fill sequentially: 0 → 1 → 2 → …
+ * 4. Fallback to the tree with the most remaining capacity.
+ */
+export declare function getBestTreeForDeposit<T extends Idl>(program: Program<T>, mintAddress: PublicKey, minCapacity?: number): Promise<TreeInfo | null>;
+/**
+ * Convert a Solana/Anchor transaction error into a user-friendly message.
+ * Maps privacy_pool program error codes (6000–6060) to readable strings.
+ * Mirrors relayer-server/src/controllers/transaction.helpers.ts `parseOnChainError`.
+ */
+export declare function parseOnChainError(error: any): string;
+/**
+ * Initialize the global config (one-time setup).
+ */
+export declare function initializeGlobalConfig<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    payer: Keypair;
+}): Promise<void>;
+/**
+ * Initialize a privacy pool with the new parameters.
+ * Creates the first merkle tree (tree ID 0).
+ */
+export declare function initializePool<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    payer: Keypair;
+    feeBps: number;
+    mintAddress: PublicKey;
+    minDepositAmount?: bigint;
+    maxDepositAmount?: bigint;
+    minWithdrawAmount?: bigint;
+    maxWithdrawAmount?: bigint;
+}): Promise<void>;
+/**
+ * Update pool configuration.
+ */
+export declare function updatePoolConfig<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    mintAddress: PublicKey;
+    minDepositAmount?: bigint;
+    maxDepositAmount?: bigint;
+    minWithdrawAmount?: bigint;
+    maxWithdrawAmount?: bigint;
+    feeBps?: number;
+    feeErrorMarginBps?: number;
+    minWithdrawalFee?: bigint;
+    minSwapFee?: bigint;
+    swapFeeBps?: number;
+}): Promise<void>;
+/**
+ * Add a new Merkle tree to the pool.
+ * The treeId must equal the current num_trees value in the pool config.
+ */
+export declare function addMerkleTree<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    mintAddress: PublicKey;
+    treeId: number;
+}): Promise<void>;
+/**
+ * Get the pool configuration account.
+ */
+export declare function getPoolConfig<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<PrivacyConfigAccount>;
+/**
+ * Add a relayer to the pool.
+ */
+export declare function addRelayer<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    mintAddress: PublicKey;
+    newRelayer: PublicKey;
+}): Promise<void>;
+/**
+ * Set the paused state of a pool.
+ */
+export declare function setPaused<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    mintAddress: PublicKey;
+    paused: boolean;
+}): Promise<void>;
+/**
+ * Execute a transaction on the privacy pool.
+ * This is the low-level function that calls the on-chain `transact` instruction.
+ *
+ * @param publicAmount - Positive for deposits, negative for withdrawals, 0 for transfers
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where output commitments will be inserted
+ */
+export declare function transact<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    recipient: PublicKey;
+    mintAddress: PublicKey;
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    publicAmount: bigint;
+    inputNullifiers: [Uint8Array, Uint8Array];
+    outputCommitments: [Uint8Array, Uint8Array];
+    extData: ExtData;
+    proof: TransactionProofStruct;
+    /** Unix timestamp after which the tx is invalid. Defaults to 0 (no deadline). */
+    deadline?: bigint;
+    vaultTokenAccount?: PublicKey;
+    userTokenAccount?: PublicKey;
+    recipientTokenAccount?: PublicKey;
+    relayerTokenAccount?: PublicKey;
+}): Promise<string>;
+/**
+ * Result of a deposit operation, produced by `DepositBuild.commit()` after the
+ * caller has successfully submitted the deposit transaction on-chain.
+ */
+export type DepositResult = {
+    /** The output UTXOs created by the deposit */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /** The leaf indices where the UTXOs were inserted */
+    leafIndices: [number, number];
+    /** The new Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * The return of `deposit()`. Instead of submitting the transaction itself,
+ * `deposit()` hands back an unsigned {@link Transaction} so the caller can
+ * sign it with whatever wallet they control (Solana wallet-adapter, Ledger,
+ * anchor NodeWallet, etc.) and submit it on their own terms.
+ *
+ * Usage pattern (browser / wallet-adapter):
+ *
+ *     const { transaction, commit } = await deposit({ ... });
+ *     const signed = await wallet.signTransaction(transaction);
+ *     const sig = await connection.sendRawTransaction(signed.serialize());
+ *     await connection.confirmTransaction(sig, "confirmed");
+ *     const result = commit();   // updates the local tree, returns DepositResult
+ */
+export type DepositBuild = {
+    /**
+     * Unsigned {@link Transaction} for the deposit. `feePayer` and
+     * `recentBlockhash` are already populated, so the caller only needs to sign
+     * and send.
+     */
+    transaction: Transaction;
+    /**
+     * Output UTXOs created by this deposit. Safe to read before submission —
+     * the commitment values are deterministic from the circuit inputs and do
+     * not depend on the on-chain result.
+     */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /**
+     * Inserts the two output commitments into the local {@link MerkleTree} and
+     * returns the receipt. Call this **only after** the on-chain transaction
+     * has been confirmed — deferring the insert keeps the local tree
+     * consistent with chain state if the submission fails.
+     *
+     * Calling `commit()` more than once is unsupported and will corrupt the
+     * local tree.
+     */
+    commit: () => DepositResult;
+};
+/**
+ * Build an unsigned deposit {@link Transaction} for the privacy pool.
+ *
+ * For deposits, we use zero input UTXOs (amount=0) and create output UTXOs
+ * with the deposit amount. `publicAmount` is positive. The caller is
+ * responsible for signing and submitting the returned transaction, and then
+ * calling `commit()` once it confirms.
+ *
+ * @param amount - Amount to deposit in lamports/token units
+ * @param recipientPubkey - UTXO public key that will own the deposited funds
+ * @param treeId - The tree ID to deposit into (defaults to 0)
+ */
+export declare function deposit<T extends Idl>(params: {
+    program: Program<T>;
+    /**
+     * Account that will pay for and sign the deposit transaction. Only
+     * `publicKey` is read — `deposit()` never touches a secret key. A browser
+     * wallet-adapter wallet, a Node `anchor.Wallet`, or a raw `Keypair` are all
+     * structurally acceptable.
+     */
+    depositor: {
+        publicKey: PublicKey;
+    };
+    amount: bigint;
+    mintAddress: PublicKey;
+    recipientPubkey: bigint;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    treeId?: number;
+    extData?: Partial<ExtData>;
+}): Promise<DepositBuild>;
+/**
+ * Result of a withdrawal operation.
+ */
+export type WithdrawResult = {
+    /** Change UTXO (remaining balance) */
+    changeUTXO: SerializedUTXO;
+    /** Leaf index of the change UTXO */
+    leafIndex: number;
+    /** New Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * Withdraw funds from the privacy pool.
+ *
+ * For withdrawals, we spend input UTXOs and create change output UTXOs.
+ * The publicAmount is negative (funds flowing out).
+ *
+ * @param withdrawAmount - Amount to withdraw in lamports/token units
+ * @param inputUTXOs - The UTXOs being spent
+ * @param changePubkey - UTXO public key for the change output
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where change outputs will be inserted
+ */
+export declare function withdraw<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    recipient: PublicKey;
+    mintAddress: PublicKey;
+    inputUTXOs: [InputUTXO, InputUTXO];
+    changePubkey: bigint;
+    withdrawAmount: bigint;
+    fee: bigint;
+    refund: bigint;
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+}): Promise<WithdrawResult>;
+/**
+ * Result of a private transfer operation.
+ */
+export type TransferResult = {
+    /** Output UTXOs created by the transfer */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /** Leaf indices where the UTXOs were inserted */
+    leafIndices: [number, number];
+    /** New Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * Execute a private transfer within the pool.
+ *
+ * For transfers, the publicAmount is 0 (no funds enter or leave the pool).
+ * Input amounts must equal output amounts.
+ *
+ * @param inputUTXOs - The UTXOs being spent
+ * @param outputPubkeys - UTXO public keys for the recipients
+ * @param outputAmounts - Amounts for each output (must sum to input total)
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where output commitments will be inserted
+ */
+export declare function privateTransfer<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    mintAddress: PublicKey;
+    inputUTXOs: [InputUTXO, InputUTXO];
+    outputPubkeys: [bigint, bigint];
+    outputAmounts: [bigint, bigint];
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    fee?: bigint;
+}): Promise<TransferResult>;
+/**
+ * Update the global config.
+ * Currently takes no extra args — only admin verification.
+ */
+export declare function updateGlobalConfig<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+}): Promise<void>;
+/**
+ * Get the swap executor PDA.
+ * Seeds: ["swap_executor", source_mint, dest_mint, input_nullifier_0, relayer]
+ */
+export declare function getSwapExecutorPda(programId: PublicKey, sourceMint: PublicKey, destMint: PublicKey, inputNullifier0: Uint8Array, relayer: PublicKey): PublicKey;
+/**
+ * Build the `fund_native_source` instruction that pre-funds the swap executor
+ * with native SOL from the source vault. Only for native SOL source pools.
+ *
+ * This instruction MUST be the first instruction in the same atomic transaction
+ * as `transactSwap`. Call `transactSwap` directly — it handles this internally.
+ */
+export declare function fundNativeSource<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    inputNullifier0: Uint8Array;
+    swapAmount: bigint;
+}): Promise<anchor.web3.TransactionInstruction>;
+/**
+ * Swap proof struct (same encoding as TransactionProofStruct).
+ */
+export type SwapProofStruct = TransactionProofStruct;
+/**
+ * Swap params committed to in the ZK proof.
+ */
+export type SwapParams = {
+    minAmountOut: bigint;
+    deadline: bigint;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    destAmount: bigint;
+    /** SHA-256 of raw swap instruction bytes; use all-zeros for CPMM/AMM swaps. */
+    swapDataHash: Uint8Array;
+};
+/**
+ * Execute an atomic cross-pool private swap.
+ *
+ * For native SOL source pools (`sourceMint === NATIVE_SOL_MINT`), this function
+ * automatically prepends the `fund_native_source` instruction in the same
+ * transaction so the on-chain atomicity requirement is always satisfied.
+ *
+ * @param swapProgram          - Jupiter/Raydium CPMM/AMM program ID
+ * @param swapData             - Raw DEX instruction bytes
+ */
+export declare function transactSwap<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    sourceRoot: Uint8Array;
+    sourceTreeId: number;
+    destTreeId: number;
+    inputNullifiers: [Uint8Array, Uint8Array];
+    outputCommitments: [Uint8Array, Uint8Array];
+    proof: SwapProofStruct;
+    swapParams: SwapParams;
+    swapAmount: bigint;
+    swapData: Buffer;
+    extData: ExtData;
+    sourceVaultTokenAccount: PublicKey;
+    sourceMintAccount: PublicKey;
+    destVaultTokenAccount: PublicKey;
+    destMintAccount: PublicKey;
+    relayerTokenAccount: PublicKey;
+    swapProgram: PublicKey;
+    jupiterEventAuthority: PublicKey;
+}): Promise<string>;

package/dist/esm/client.js

@@ -1,10 +1,14 @@
-import { BN } from "@coral-xyz/anchor";
+import * as anchor from "@coral-xyz/anchor";
+// Pulled off the namespace rather than named-imported. @coral-xyz/anchor is CJS
+// with no `exports` map, and Node ESM's named-export detection cannot see `BN`
+// (it is re-exported from bn.js), so `import { BN }` throws at runtime under ESM.
+const { BN } = anchor;
 import { PublicKey, SystemProgram, Transaction, SYSVAR_INSTRUCTIONS_PUBKEY, ComputeBudgetProgram, } from "@solana/web3.js";
 import { TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID, NATIVE_MINT, getAssociatedTokenAddress, } from "@solana/spl-token";
-import { computeExtDataHash, prepareTransactionInputs, encodeSnarkjsProofToTransactionProof, } from "./proof";
-import { createUTXO, createOwnedZeroUTXO, generateKeypair, } from "./utxo";
-import { NATIVE_SOL_MINT } from "./config";
-import { withRpcRetry } from "./retry";
+import { computeExtDataHash, prepareTransactionInputs, encodeSnarkjsProofToTransactionProof, } from "./proof.js";
+import { createUTXO, createOwnedZeroUTXO, generateKeypair, } from "./utxo.js";
+import { NATIVE_SOL_MINT } from "./config.js";
+import { withRpcRetry } from "./retry.js";
 // -----------------------------------------------------------------------------
 // PDA Helpers
 // -----------------------------------------------------------------------------

package/dist/esm/compactNote.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Compact note ciphers — the 80-byte payload carried inside the on-chain
+ * `transact` instruction (`note_ciphers: Option<NoteCiphers>`) and re-emitted in
+ * `CommitmentEvent`.
+ *
+ * This is what makes a note recoverable from chain data alone: a recipient who
+ * was never told about a deposit can still find it by scanning `view_tag` and
+ * decrypting the blob. Without it, note delivery depends on someone calling the
+ * relayer, which a third-party integrator cannot be trusted to do.
+ *
+ * ## Byte-compatibility is load-bearing
+ *
+ * Four sibling implementations already exist (relayer-server, extension ×2,
+ * wallet-app). This is the canonical one, and it MUST agree with them byte for
+ * byte in both directions:
+ *
+ *   - disagree on encrypt → new notes are invisible to every existing client
+ *   - disagree on decrypt → the entire historical note corpus becomes unreadable
+ *
+ * Three details are easy to get wrong and are individually fatal:
+ *
+ *  1. The KDF is `nacl.hash(x).slice(0, 32)` — **truncated SHA-512**, despite the
+ *     sibling helper being named `sha256ForNotes`. See `kdfSHA512_256` in utxo.ts.
+ *  2. The ephemeral key published on-chain is **Ed25519**; it is converted to
+ *     X25519 only for the Diffie-Hellman. Scanners convert it back.
+ *  3. `viewTag` is the first byte of the hash of the **raw shared secret**, not of
+ *     the derived key. A wrong view tag makes every note invisible to the scan
+ *     loop, which rejects ~255/256 candidates on this byte alone.
+ *
+ * The ECDH primitives are imported from `utxo.ts` rather than reimplemented — a
+ * fifth independent Edwards→Montgomery implementation is exactly how the current
+ * drift risk between the four siblings arose.
+ *
+ * Verified against the siblings by `tests/compact-note.test.ts` (golden vectors)
+ * and `scripts/verify-compact-cipher-parity.mjs` (differential).
+ */
+/** Size of the on-chain compact blob: nonce[24] || secretbox(40-byte plaintext)[56]. */
+export declare const COMPACT_BLOB_LENGTH = 80;
+export type CompactNoteCipher = {
+    /** Ed25519 ephemeral public key, published on-chain. */
+    ephemeralPublicKey: Uint8Array;
+    /** 80 bytes: nonce[24] || ciphertext[56]. */
+    compactBlob: Uint8Array;
+    /** 1-byte scan filter. */
+    viewTag: number;
+};
+/**
+ * Test-only determinism hook. NOT part of the public contract — it exists so
+ * golden vectors can pin exact bytes against the sibling implementations, which
+ * is the only way to prove byte-compatibility rather than assume it.
+ *
+ * @internal
+ */
+export type CompactNoteDeterminism = {
+    ephemeralSeed: Uint8Array;
+    nonce: Uint8Array;
+};
+/**
+ * Encrypt a note's secret material to a recipient's Solana wallet key.
+ *
+ * The recipient does not need to be the signer of the transaction, or to have
+ * any prior relationship with the sender — this is what makes shielding to an
+ * arbitrary owner possible.
+ *
+ * @param recipientWalletPubkey 32-byte Ed25519 Solana wallet public key
+ * @param blinding              32-byte big-endian blinding factor
+ * @param amount                note amount in base units
+ */
+export declare function createCompactNoteCipher(recipientWalletPubkey: Uint8Array, blinding: Uint8Array, amount: bigint, 
+/** @internal */ __det?: CompactNoteDeterminism): CompactNoteCipher;
+/**
+ * Recover a note's blinding and amount from an on-chain compact cipher.
+ *
+ * Returns `null` when the blob was not encrypted to this key — the expected
+ * outcome for the overwhelming majority of candidates during a scan, so callers
+ * should filter on `viewTag` first (see {@link matchesViewTag}) and only attempt
+ * decryption on the ~1/256 that survive.
+ *
+ * @param walletSecretKey 32-byte Ed25519 seed or 64-byte secret key
+ */
+export declare function decryptCompactNoteCipher(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, compactBlob: Uint8Array, precomputed?: {
+    sharedSecret?: Uint8Array;
+    x25519Private?: Uint8Array;
+}): {
+    blinding: Uint8Array;
+    amount: bigint;
+} | null;
+/**
+ * Cheap scan filter: does this on-chain cipher plausibly belong to us?
+ *
+ * Rejects ~255/256 candidates for the cost of one scalar multiplication and one
+ * hash, versus a full secretbox open. Hoist `x25519Private` across a scan loop
+ * with {@link toX25519Private}.
+ */
+export declare function matchesViewTag(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, viewTag: number, precomputed?: {
+    x25519Private?: Uint8Array;
+}): {
+    matches: boolean;
+    sharedSecret: Uint8Array;
+};
+/**
+ * Convert an Ed25519 wallet secret key to its X25519 scalar once, for reuse
+ * across a scan loop.
+ */
+export declare function toX25519Private(walletSecretKey: Uint8Array): Uint8Array;
+/** The all-zero cipher the program treats as "no note here". */
+export declare function emptyNoteCipher(): CompactNoteCipher;

package/dist/esm/compactNote.js

@@ -0,0 +1,156 @@
+import nacl from "tweetnacl";
+import { ed25519PublicKeyToX25519, ed25519SeedToX25519Private, kdfSHA512_256, } from "./utxo.js";
+import { randomBytes } from "./random.js";
+/**
+ * Compact note ciphers — the 80-byte payload carried inside the on-chain
+ * `transact` instruction (`note_ciphers: Option<NoteCiphers>`) and re-emitted in
+ * `CommitmentEvent`.
+ *
+ * This is what makes a note recoverable from chain data alone: a recipient who
+ * was never told about a deposit can still find it by scanning `view_tag` and
+ * decrypting the blob. Without it, note delivery depends on someone calling the
+ * relayer, which a third-party integrator cannot be trusted to do.
+ *
+ * ## Byte-compatibility is load-bearing
+ *
+ * Four sibling implementations already exist (relayer-server, extension ×2,
+ * wallet-app). This is the canonical one, and it MUST agree with them byte for
+ * byte in both directions:
+ *
+ *   - disagree on encrypt → new notes are invisible to every existing client
+ *   - disagree on decrypt → the entire historical note corpus becomes unreadable
+ *
+ * Three details are easy to get wrong and are individually fatal:
+ *
+ *  1. The KDF is `nacl.hash(x).slice(0, 32)` — **truncated SHA-512**, despite the
+ *     sibling helper being named `sha256ForNotes`. See `kdfSHA512_256` in utxo.ts.
+ *  2. The ephemeral key published on-chain is **Ed25519**; it is converted to
+ *     X25519 only for the Diffie-Hellman. Scanners convert it back.
+ *  3. `viewTag` is the first byte of the hash of the **raw shared secret**, not of
+ *     the derived key. A wrong view tag makes every note invisible to the scan
+ *     loop, which rejects ~255/256 candidates on this byte alone.
+ *
+ * The ECDH primitives are imported from `utxo.ts` rather than reimplemented — a
+ * fifth independent Edwards→Montgomery implementation is exactly how the current
+ * drift risk between the four siblings arose.
+ *
+ * Verified against the siblings by `tests/compact-note.test.ts` (golden vectors)
+ * and `scripts/verify-compact-cipher-parity.mjs` (differential).
+ */
+/** Size of the on-chain compact blob: nonce[24] || secretbox(40-byte plaintext)[56]. */
+export const COMPACT_BLOB_LENGTH = 80;
+/** Plaintext layout: blinding[32] || amount as little-endian u64[8]. */
+const COMPACT_PLAINTEXT_LENGTH = 40;
+const NONCE_LENGTH = 24;
+/**
+ * Encrypt a note's secret material to a recipient's Solana wallet key.
+ *
+ * The recipient does not need to be the signer of the transaction, or to have
+ * any prior relationship with the sender — this is what makes shielding to an
+ * arbitrary owner possible.
+ *
+ * @param recipientWalletPubkey 32-byte Ed25519 Solana wallet public key
+ * @param blinding              32-byte big-endian blinding factor
+ * @param amount                note amount in base units
+ */
+export function createCompactNoteCipher(recipientWalletPubkey, blinding, amount, 
+/** @internal */ __det) {
+    if (recipientWalletPubkey.length !== 32) {
+        throw new Error(`recipientWalletPubkey must be 32 bytes, got ${recipientWalletPubkey.length}`);
+    }
+    if (blinding.length < 32) {
+        throw new Error(`blinding must be at least 32 bytes, got ${blinding.length}`);
+    }
+    if (amount < 0n || amount > 0xffffffffffffffffn) {
+        throw new Error(`amount ${amount} does not fit in a u64`);
+    }
+    // Ed25519 ephemeral keypair. `nacl.sign.keyPair.fromSeed(seed)` produces the
+    // same public key as web3.js `Keypair.generate()` for the same seed, which is
+    // what the sibling implementations use — but without pulling @solana/web3.js
+    // into the crypto path.
+    const ephemeralSeed = __det?.ephemeralSeed ?? randomBytes(32);
+    const ephemeralPublicKey = nacl.sign.keyPair.fromSeed(ephemeralSeed).publicKey;
+    const sharedSecret = deriveSharedSecret(ephemeralSeed, recipientWalletPubkey);
+    const key = kdfSHA512_256(sharedSecret);
+    const plaintext = new Uint8Array(COMPACT_PLAINTEXT_LENGTH);
+    plaintext.set(blinding.slice(0, 32), 0);
+    let amt = amount;
+    for (let i = 0; i < 8; i++) {
+        plaintext[32 + i] = Number(amt & 0xffn);
+        amt >>= 8n;
+    }
+    const nonce = __det?.nonce ?? nacl.randomBytes(NONCE_LENGTH);
+    const encrypted = nacl.secretbox(plaintext, nonce, key);
+    const compactBlob = new Uint8Array(COMPACT_BLOB_LENGTH);
+    compactBlob.set(nonce, 0);
+    compactBlob.set(encrypted, NONCE_LENGTH);
+    // First byte of the hash of the RAW shared secret — not of `key`.
+    const viewTag = nacl.hash(sharedSecret)[0];
+    return { ephemeralPublicKey, compactBlob, viewTag };
+}
+/**
+ * Recover a note's blinding and amount from an on-chain compact cipher.
+ *
+ * Returns `null` when the blob was not encrypted to this key — the expected
+ * outcome for the overwhelming majority of candidates during a scan, so callers
+ * should filter on `viewTag` first (see {@link matchesViewTag}) and only attempt
+ * decryption on the ~1/256 that survive.
+ *
+ * @param walletSecretKey 32-byte Ed25519 seed or 64-byte secret key
+ */
+export function decryptCompactNoteCipher(walletSecretKey, ephemeralPublicKey, compactBlob, precomputed) {
+    if (compactBlob.length !== COMPACT_BLOB_LENGTH)
+        return null;
+    const sharedSecret = precomputed?.sharedSecret ??
+        (precomputed?.x25519Private
+            ? nacl.scalarMult(precomputed.x25519Private, ed25519PublicKeyToX25519(ephemeralPublicKey))
+            : deriveSharedSecret(walletSecretKey, ephemeralPublicKey));
+    const key = kdfSHA512_256(sharedSecret);
+    const nonce = compactBlob.slice(0, NONCE_LENGTH);
+    const encrypted = compactBlob.slice(NONCE_LENGTH);
+    const plaintext = nacl.secretbox.open(encrypted, nonce, key);
+    if (!plaintext)
+        return null;
+    const blinding = new Uint8Array(plaintext.slice(0, 32));
+    let amount = 0n;
+    for (let i = 7; i >= 0; i--) {
+        amount = (amount << 8n) | BigInt(plaintext[32 + i]);
+    }
+    return { blinding, amount };
+}
+/**
+ * Cheap scan filter: does this on-chain cipher plausibly belong to us?
+ *
+ * Rejects ~255/256 candidates for the cost of one scalar multiplication and one
+ * hash, versus a full secretbox open. Hoist `x25519Private` across a scan loop
+ * with {@link toX25519Private}.
+ */
+export function matchesViewTag(walletSecretKey, ephemeralPublicKey, viewTag, precomputed) {
+    const sharedSecret = precomputed?.x25519Private
+        ? nacl.scalarMult(precomputed.x25519Private, ed25519PublicKeyToX25519(ephemeralPublicKey))
+        : deriveSharedSecret(walletSecretKey, ephemeralPublicKey);
+    return { matches: nacl.hash(sharedSecret)[0] === viewTag, sharedSecret };
+}
+/**
+ * Convert an Ed25519 wallet secret key to its X25519 scalar once, for reuse
+ * across a scan loop.
+ */
+export function toX25519Private(walletSecretKey) {
+    return ed25519SeedToX25519Private(seedOf(walletSecretKey));
+}
+/** The all-zero cipher the program treats as "no note here". */
+export function emptyNoteCipher() {
+    return {
+        ephemeralPublicKey: new Uint8Array(32),
+        compactBlob: new Uint8Array(COMPACT_BLOB_LENGTH),
+        viewTag: 0,
+    };
+}
+// -- internal -----------------------------------------------------------------
+/** Accept either a 32-byte Ed25519 seed or a 64-byte secret key, as the siblings do. */
+function seedOf(secretKey) {
+    return secretKey.length === 64 ? secretKey.slice(0, 32) : secretKey;
+}
+function deriveSharedSecret(mySecretKey, theirEd25519PublicKey) {
+    return nacl.scalarMult(ed25519SeedToX25519Private(seedOf(mySecretKey)), ed25519PublicKeyToX25519(theirEd25519PublicKey));
+}