@soteria1/sdk 0.1.0

package/dist/pool/note.js

@@ -0,0 +1,66 @@
+import { buildPoseidon } from "circomlibjs";
+// BN254 scalar field order. nullifier/secret must be reduced mod this.
+const FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+let _poseidon;
+async function poseidon() {
+    if (!_poseidon)
+        _poseidon = await buildPoseidon();
+    return _poseidon;
+}
+function randomFieldElement() {
+    // 31 bytes = 248 bits < field order, so a single reduction is unbiased enough.
+    const bytes = new Uint8Array(31);
+    globalThis.crypto.getRandomValues(bytes);
+    let v = 0n;
+    for (const b of bytes)
+        v = (v << 8n) | BigInt(b);
+    return v % FIELD;
+}
+/** Generate a fresh note for a pool. */
+export function randomNote(poolId) {
+    return {
+        poolId: BigInt(poolId),
+        nullifier: randomFieldElement(),
+        secret: randomFieldElement(),
+    };
+}
+/** Note commitment = Poseidon(nullifier, secret) — the tree leaf. */
+export async function commitment(note) {
+    const p = await poseidon();
+    return BigInt(p.F.toString(p([note.nullifier, note.secret])));
+}
+/** nullifierHash = Poseidon(nullifier) — revealed at withdraw, public. */
+export async function nullifierHash(note) {
+    const p = await poseidon();
+    return BigInt(p.F.toString(p([note.nullifier])));
+}
+const PREFIX = "soteria-note-v1";
+function toHex(v) {
+    return v.toString(16);
+}
+/** Serialize a note to the backup string the user must save to claim funds. */
+export function encodeNote(note) {
+    return [PREFIX, note.poolId.toString(), toHex(note.nullifier), toHex(note.secret)].join(":");
+}
+/** Parse a backup string back into a note. */
+export function decodeNote(s) {
+    const parts = s.trim().split(":");
+    if (parts.length !== 4 || parts[0] !== PREFIX) {
+        throw new Error("invalid note backup string");
+    }
+    return {
+        poolId: BigInt(parts[1]),
+        nullifier: BigInt("0x" + parts[2]),
+        secret: BigInt("0x" + parts[3]),
+    };
+}
+/** 32-byte big-endian encoding of a field element (tree leaf / PDA seed). */
+export function toBytes32(v) {
+    const out = new Uint8Array(32);
+    let x = v;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(x & 0xffn);
+        x >>= 8n;
+    }
+    return out;
+}

package/dist/pool/pdas.d.ts

@@ -0,0 +1,54 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import type { FormattedProof } from "./prover.js";
+export declare const POOL_PROGRAM_ID: PublicKey;
+export declare function poolPda(poolId: bigint | number): [PublicKey, number];
+export declare function vaultPda(poolId: bigint | number): [PublicKey, number];
+export declare function commitmentPda(poolId: bigint | number, commitment: bigint): [PublicKey, number];
+export declare function poolNullifierPda(poolId: bigint | number, nullifierHash: bigint): [PublicKey, number];
+/** Accounts for `init_pool(pool_id, denomination)`. */
+export declare function buildInitPoolAccounts(authority: PublicKey, poolId: bigint | number): {
+    programId: PublicKey;
+    keys: {
+        pubkey: PublicKey;
+        isSigner: boolean;
+        isWritable: boolean;
+    }[];
+};
+/** Accounts for `deposit(commitment)`. */
+export declare function buildDepositAccounts(depositor: PublicKey, poolId: bigint | number, commitment: bigint): {
+    programId: PublicKey;
+    keys: {
+        pubkey: PublicKey;
+        isSigner: boolean;
+        isWritable: boolean;
+    }[];
+};
+/**
+ * Full `deposit(commitment)` instruction, signed client-side by the depositor.
+ * Build a transaction with this and send it through the wallet — the SDK has no
+ * Anchor dependency, so the discriminator is encoded directly.
+ */
+export declare function depositInstruction(depositor: PublicKey, poolId: bigint | number, commitment: bigint): TransactionInstruction;
+/** Accounts for `publish_pool_root` / `set_association_root` (authority only). */
+export declare function buildUpdatePoolRootAccounts(authority: PublicKey, poolId: bigint | number): {
+    programId: PublicKey;
+    keys: {
+        pubkey: PublicKey;
+        isSigner: boolean;
+        isWritable: boolean;
+    }[];
+};
+/**
+ * Accounts for `withdraw(...)`. `nullifierHash` is publicInputs[0] decoded back
+ * to a bigint; pass the same value used to derive the proof.
+ */
+export declare function buildWithdrawAccounts(relayer: PublicKey, poolId: bigint | number, recipient: PublicKey, nullifierHash: bigint): {
+    programId: PublicKey;
+    keys: {
+        pubkey: PublicKey;
+        isSigner: boolean;
+        isWritable: boolean;
+    }[];
+};
+/** Convenience: the bigint nullifierHash carried in a formatted proof. */
+export declare function nullifierHashFromProof(proof: FormattedProof): bigint;

package/dist/pool/pdas.js

@@ -0,0 +1,109 @@
+import { PublicKey, SystemProgram, TransactionInstruction } from "@solana/web3.js";
+import { toBytes32 } from "./note.js";
+export const POOL_PROGRAM_ID = new PublicKey("9HNLpUVFX61pX759oy1vuMMwQaQaGnK9KgMyhTrDrRGs");
+// sha256("global:deposit")[0..8] — the Anchor instruction discriminator.
+const DEPOSIT_DISCRIMINATOR = new Uint8Array([242, 35, 198, 137, 82, 225, 242, 182]);
+function u64le(n) {
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(BigInt(n));
+    return b;
+}
+export function poolPda(poolId) {
+    return PublicKey.findProgramAddressSync([Buffer.from("pool"), u64le(poolId)], POOL_PROGRAM_ID);
+}
+export function vaultPda(poolId) {
+    return PublicKey.findProgramAddressSync([Buffer.from("vault"), u64le(poolId)], POOL_PROGRAM_ID);
+}
+export function commitmentPda(poolId, commitment) {
+    const [pool] = poolPda(poolId);
+    return PublicKey.findProgramAddressSync([Buffer.from("commit"), pool.toBuffer(), Buffer.from(toBytes32(commitment))], POOL_PROGRAM_ID);
+}
+export function poolNullifierPda(poolId, nullifierHash) {
+    const [pool] = poolPda(poolId);
+    return PublicKey.findProgramAddressSync([Buffer.from("pool_null"), pool.toBuffer(), Buffer.from(toBytes32(nullifierHash))], POOL_PROGRAM_ID);
+}
+const SYS = { pubkey: SystemProgram.programId, isSigner: false, isWritable: false };
+/** Accounts for `init_pool(pool_id, denomination)`. */
+export function buildInitPoolAccounts(authority, poolId) {
+    const [pool] = poolPda(poolId);
+    const [vault] = vaultPda(poolId);
+    return {
+        programId: POOL_PROGRAM_ID,
+        keys: [
+            { pubkey: authority, isSigner: true, isWritable: true },
+            { pubkey: pool, isSigner: false, isWritable: true },
+            { pubkey: vault, isSigner: false, isWritable: false },
+            SYS,
+        ],
+    };
+}
+/** Accounts for `deposit(commitment)`. */
+export function buildDepositAccounts(depositor, poolId, commitment) {
+    const [pool] = poolPda(poolId);
+    const [vault] = vaultPda(poolId);
+    const [commitmentRecord] = commitmentPda(poolId, commitment);
+    return {
+        programId: POOL_PROGRAM_ID,
+        keys: [
+            { pubkey: depositor, isSigner: true, isWritable: true },
+            { pubkey: pool, isSigner: false, isWritable: true },
+            { pubkey: vault, isSigner: false, isWritable: true },
+            { pubkey: commitmentRecord, isSigner: false, isWritable: true },
+            SYS,
+        ],
+    };
+}
+/**
+ * Full `deposit(commitment)` instruction, signed client-side by the depositor.
+ * Build a transaction with this and send it through the wallet — the SDK has no
+ * Anchor dependency, so the discriminator is encoded directly.
+ */
+export function depositInstruction(depositor, poolId, commitment) {
+    const { keys } = buildDepositAccounts(depositor, poolId, commitment);
+    const data = new Uint8Array(8 + 32);
+    data.set(DEPOSIT_DISCRIMINATOR, 0);
+    data.set(toBytes32(commitment), 8);
+    return new TransactionInstruction({
+        programId: POOL_PROGRAM_ID,
+        keys,
+        data: Buffer.from(data),
+    });
+}
+/** Accounts for `publish_pool_root` / `set_association_root` (authority only). */
+export function buildUpdatePoolRootAccounts(authority, poolId) {
+    const [pool] = poolPda(poolId);
+    return {
+        programId: POOL_PROGRAM_ID,
+        keys: [
+            { pubkey: authority, isSigner: true, isWritable: false },
+            { pubkey: pool, isSigner: false, isWritable: true },
+        ],
+    };
+}
+/**
+ * Accounts for `withdraw(...)`. `nullifierHash` is publicInputs[0] decoded back
+ * to a bigint; pass the same value used to derive the proof.
+ */
+export function buildWithdrawAccounts(relayer, poolId, recipient, nullifierHash) {
+    const [pool] = poolPda(poolId);
+    const [vault] = vaultPda(poolId);
+    const [nullifier] = poolNullifierPda(poolId, nullifierHash);
+    return {
+        programId: POOL_PROGRAM_ID,
+        keys: [
+            { pubkey: relayer, isSigner: true, isWritable: true },
+            { pubkey: pool, isSigner: false, isWritable: false },
+            { pubkey: vault, isSigner: false, isWritable: true },
+            { pubkey: recipient, isSigner: false, isWritable: true },
+            { pubkey: nullifier, isSigner: false, isWritable: true },
+            SYS,
+        ],
+    };
+}
+/** Convenience: the bigint nullifierHash carried in a formatted proof. */
+export function nullifierHashFromProof(proof) {
+    let v = 0n;
+    for (const byte of proof.publicInputs[0])
+        v = (v << 8n) | BigInt(byte);
+    return v;
+}

package/dist/pool/prover.d.ts

@@ -0,0 +1,44 @@
+import { PublicKey } from "@solana/web3.js";
+import { PoseidonMerkleTree } from "../zk/merkle.js";
+import { Note } from "./note.js";
+/** Split a 32-byte pubkey into two 128-bit field limbs (hi = first 16 bytes). */
+export declare function recipientLimbs(recipient: PublicKey): {
+    hi: bigint;
+    lo: bigint;
+};
+export interface WithdrawInputs {
+    note: Note;
+    /** Pool deposit tree and the note's leaf index in it. */
+    depositTree: PoseidonMerkleTree;
+    depositLeafIndex: number;
+    /** Association-set tree and the note's leaf index in it. For a non-gated pool
+     *  this is the same tree as `depositTree`. */
+    assocTree: PoseidonMerkleTree;
+    assocLeafIndex: number;
+    recipient: PublicKey;
+    fee: bigint;
+}
+export interface FormattedProof {
+    proofA: number[];
+    proofB: number[];
+    proofC: number[];
+    publicInputs: number[][];
+}
+export interface RawProof {
+    proof: {
+        pi_a: string[];
+        pi_b: string[][];
+        pi_c: string[];
+    };
+    publicSignals: string[];
+}
+/**
+ * Raw snarkjs proof + public signals. Use this for the relay path (the relayer
+ * formats bytes server-side). Requires app/public/withdraw.{wasm,zkey}.
+ */
+export declare function proveWithdrawRaw(inputs: WithdrawInputs, wasmPath: string, zkeyPath: string): Promise<RawProof>;
+/**
+ * Withdraw proof formatted for the on-chain `withdraw` instruction (direct
+ * submission). For the relay path, use proveWithdrawRaw.
+ */
+export declare function proveWithdraw(inputs: WithdrawInputs, wasmPath: string, zkeyPath: string): Promise<FormattedProof>;

package/dist/pool/prover.js

@@ -0,0 +1,73 @@
+import { groth16 } from "snarkjs";
+// BN254 base field prime (for negating proof.A, per groth16-solana convention).
+const Q = 21888242871839275222246405745257275088696311157297823662689037894645226208583n;
+function toBE32(dec) {
+    let v = BigInt(dec);
+    const out = new Array(32).fill(0);
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
+/** Split a 32-byte pubkey into two 128-bit field limbs (hi = first 16 bytes). */
+export function recipientLimbs(recipient) {
+    const b = recipient.toBytes();
+    let hi = 0n;
+    for (let i = 0; i < 16; i++)
+        hi = (hi << 8n) | BigInt(b[i]);
+    let lo = 0n;
+    for (let i = 16; i < 32; i++)
+        lo = (lo << 8n) | BigInt(b[i]);
+    return { hi, lo };
+}
+function buildWitness(inputs) {
+    const { note, depositTree, depositLeafIndex, assocTree, assocLeafIndex, recipient, fee } = inputs;
+    const dep = depositTree.proof(depositLeafIndex);
+    const assoc = assocTree.proof(assocLeafIndex);
+    const { hi, lo } = recipientLimbs(recipient);
+    return {
+        nullifier: note.nullifier.toString(),
+        secret: note.secret.toString(),
+        depositPathElements: dep.pathElements.map((x) => x.toString()),
+        depositPathIndices: dep.pathIndices.map((x) => x.toString()),
+        assocPathElements: assoc.pathElements.map((x) => x.toString()),
+        assocPathIndices: assoc.pathIndices.map((x) => x.toString()),
+        depositRoot: depositTree.root().toString(),
+        associationRoot: assocTree.root().toString(),
+        recipientHi: hi.toString(),
+        recipientLo: lo.toString(),
+        fee: fee.toString(),
+    };
+}
+/**
+ * Raw snarkjs proof + public signals. Use this for the relay path (the relayer
+ * formats bytes server-side). Requires app/public/withdraw.{wasm,zkey}.
+ */
+export async function proveWithdrawRaw(inputs, wasmPath, zkeyPath) {
+    const witness = buildWitness(inputs);
+    const { proof, publicSignals } = await groth16.fullProve(witness, wasmPath, zkeyPath);
+    return { proof, publicSignals };
+}
+/**
+ * Withdraw proof formatted for the on-chain `withdraw` instruction (direct
+ * submission). For the relay path, use proveWithdrawRaw.
+ */
+export async function proveWithdraw(inputs, wasmPath, zkeyPath) {
+    const { proof, publicSignals } = await proveWithdrawRaw(inputs, wasmPath, zkeyPath);
+    // proof.A : negate y, then x||y big-endian (groth16-solana wants -A)
+    const ax = BigInt(proof.pi_a[0]);
+    const ay = (Q - (BigInt(proof.pi_a[1]) % Q)) % Q;
+    const proofA = [...toBE32(ax), ...toBE32(ay)];
+    // proof.B : G2, swap the c0/c1 ordering snarkjs emits
+    const proofB = [
+        ...toBE32(proof.pi_b[0][1]),
+        ...toBE32(proof.pi_b[0][0]),
+        ...toBE32(proof.pi_b[1][1]),
+        ...toBE32(proof.pi_b[1][0]),
+    ];
+    // proof.C : x||y big-endian
+    const proofC = [...toBE32(proof.pi_c[0]), ...toBE32(proof.pi_c[1])];
+    const publicInputs = publicSignals.map((s) => toBE32(s));
+    return { proofA, proofB, proofC, publicInputs };
+}

package/dist/shielded/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./keypair.js";
+export * from "./note.js";
+export * from "./prover.js";
+export * from "./scan.js";
+export * from "./instruction.js";

package/dist/shielded/index.js

@@ -0,0 +1,5 @@
+export * from "./keypair.js";
+export * from "./note.js";
+export * from "./prover.js";
+export * from "./scan.js";
+export * from "./instruction.js";

package/dist/shielded/instruction.d.ts

@@ -0,0 +1,20 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import type { FormattedTx } from "./prover.js";
+export declare const SHIELDED_PROGRAM_ID: PublicKey;
+export declare function shieldedPda(id: bigint | number): PublicKey;
+export declare function shieldedVaultPda(id: bigint | number): PublicKey;
+export declare function shieldedNullifierPda(id: bigint | number, nullifier: number[]): PublicKey;
+/**
+ * Build the `transact` instruction (client-signed — used for deposits, where the
+ * signer funds the vault). The SDK has no Anchor dep, so the args are encoded by
+ * hand: disc ++ proofA ++ proofB ++ proofC ++ publicInputs(7*32) ++ ext(i64) ++ fee(u64).
+ */
+export declare function transactInstruction(opts: {
+    shieldedId: bigint | number;
+    signer: PublicKey;
+    recipient: PublicKey;
+    relayer: PublicKey;
+    tx: FormattedTx;
+    extAmount: bigint;
+    fee: bigint;
+}): TransactionInstruction;

package/dist/shielded/instruction.js

@@ -0,0 +1,50 @@
+import { PublicKey, SystemProgram, TransactionInstruction } from "@solana/web3.js";
+export const SHIELDED_PROGRAM_ID = new PublicKey("9HNLpUVFX61pX759oy1vuMMwQaQaGnK9KgMyhTrDrRGs");
+// sha256("global:transact")[0..8]
+const TRANSACT_DISCRIMINATOR = new Uint8Array([217, 149, 130, 143, 221, 52, 252, 119]);
+function u64le(n) {
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(BigInt(n));
+    return b;
+}
+export function shieldedPda(id) {
+    return PublicKey.findProgramAddressSync([Buffer.from("shielded"), u64le(id)], SHIELDED_PROGRAM_ID)[0];
+}
+export function shieldedVaultPda(id) {
+    return PublicKey.findProgramAddressSync([Buffer.from("shvault"), u64le(id)], SHIELDED_PROGRAM_ID)[0];
+}
+export function shieldedNullifierPda(id, nullifier) {
+    return PublicKey.findProgramAddressSync([Buffer.from("shnull"), shieldedPda(id).toBuffer(), Buffer.from(nullifier)], SHIELDED_PROGRAM_ID)[0];
+}
+/**
+ * Build the `transact` instruction (client-signed — used for deposits, where the
+ * signer funds the vault). The SDK has no Anchor dep, so the args are encoded by
+ * hand: disc ++ proofA ++ proofB ++ proofC ++ publicInputs(7*32) ++ ext(i64) ++ fee(u64).
+ */
+export function transactInstruction(opts) {
+    const { shieldedId, signer, recipient, relayer, tx, extAmount, fee } = opts;
+    const flatPublicInputs = tx.publicInputs.flat(); // 7 * 32 = 224 bytes
+    const extLe = Buffer.alloc(8);
+    extLe.writeBigInt64LE(extAmount);
+    const data = Buffer.concat([
+        Buffer.from(TRANSACT_DISCRIMINATOR),
+        Buffer.from(tx.proofA),
+        Buffer.from(tx.proofB),
+        Buffer.from(tx.proofC),
+        Buffer.from(flatPublicInputs),
+        extLe,
+        u64le(fee),
+    ]);
+    const keys = [
+        { pubkey: signer, isSigner: true, isWritable: true },
+        { pubkey: shieldedPda(shieldedId), isSigner: false, isWritable: true },
+        { pubkey: shieldedVaultPda(shieldedId), isSigner: false, isWritable: true },
+        { pubkey: recipient, isSigner: false, isWritable: true },
+        { pubkey: relayer, isSigner: false, isWritable: true },
+        // publicInputs[3], [4] = the two nullifiers (byte form), per the circuit order
+        { pubkey: shieldedNullifierPda(shieldedId, tx.publicInputs[3]), isSigner: false, isWritable: true },
+        { pubkey: shieldedNullifierPda(shieldedId, tx.publicInputs[4]), isSigner: false, isWritable: true },
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ];
+    return new TransactionInstruction({ programId: SHIELDED_PROGRAM_ID, keys, data });
+}

package/dist/shielded/keypair.d.ts

@@ -0,0 +1,23 @@
+export declare const FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+export declare function poseidon(): Promise<any>;
+export declare function H(xs: bigint[]): Promise<bigint>;
+/**
+ * A shielded identity. `privateKey`/`publicKey` are the in-circuit spending key
+ * (used to derive note nullifiers); `encPriv`/`encPub` are an X25519 pair used
+ * to encrypt note secrets to the owner. Both are derived from one wallet
+ * signature, so the whole identity is recoverable and nothing is stored.
+ */
+export interface ShieldedKeypair {
+    privateKey: bigint;
+    publicKey: bigint;
+    encPriv: Uint8Array;
+    encPub: Uint8Array;
+}
+/** Derive a shielded identity from a 32+ byte seed (e.g. a wallet signature). */
+export declare function deriveShieldedKeypair(seed: Uint8Array): Promise<ShieldedKeypair>;
+/** Shareable shielded address = base64url(publicKey || encPub). */
+export declare function encodeShieldedAddress(kp: ShieldedKeypair): string;
+export declare function decodeShieldedAddress(s: string): {
+    publicKey: bigint;
+    encPub: Uint8Array;
+};

package/dist/shielded/keypair.js

@@ -0,0 +1,72 @@
+import { buildPoseidon } from "circomlibjs";
+import { x25519 } from "@noble/curves/ed25519";
+import { sha256 } from "@noble/hashes/sha256";
+// BN254 scalar field.
+export const FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+let _poseidon;
+export async function poseidon() {
+    if (!_poseidon)
+        _poseidon = await buildPoseidon();
+    return _poseidon;
+}
+export async function H(xs) {
+    const p = await poseidon();
+    return BigInt(p.F.toString(p(xs)));
+}
+const enc = new TextEncoder();
+function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+function bytesToField(b) {
+    let v = 0n;
+    for (const x of b)
+        v = (v << 8n) | BigInt(x);
+    return v % FIELD;
+}
+function toBytes32(v) {
+    const out = new Uint8Array(32);
+    let x = v;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(x & 0xffn);
+        x >>= 8n;
+    }
+    return out;
+}
+function b64url(bytes) {
+    let s = "";
+    for (const x of bytes)
+        s += String.fromCharCode(x);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64url(s) {
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** Derive a shielded identity from a 32+ byte seed (e.g. a wallet signature). */
+export async function deriveShieldedKeypair(seed) {
+    const privateKey = bytesToField(sha256(concat(seed, enc.encode("soteria-shielded-spend"))));
+    const encPriv = sha256(concat(seed, enc.encode("soteria-shielded-enc")));
+    return {
+        privateKey,
+        publicKey: await H([privateKey]),
+        encPriv,
+        encPub: x25519.getPublicKey(encPriv),
+    };
+}
+/** Shareable shielded address = base64url(publicKey || encPub). */
+export function encodeShieldedAddress(kp) {
+    return b64url(concat(toBytes32(kp.publicKey), kp.encPub));
+}
+export function decodeShieldedAddress(s) {
+    const bytes = unb64url(s.trim());
+    if (bytes.length !== 64)
+        throw new Error("invalid shielded address");
+    return { publicKey: bytesToField(bytes.slice(0, 32)), encPub: bytes.slice(32, 64) };
+}

package/dist/shielded/note.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A shielded UTXO. `amount` and `blinding` are secret; `pubkey` is the owner's
+ * shielded publicKey. commitment = Poseidon(amount, pubkey, blinding).
+ */
+export interface Note {
+    amount: bigint;
+    pubkey: bigint;
+    blinding: bigint;
+}
+export declare function randomBlinding(): bigint;
+export declare function newNote(amount: bigint, pubkey: bigint): Note;
+export declare const commitment: (n: Note) => Promise<bigint>;
+/** nullifier = Poseidon(commitment, Poseidon(privateKey, commitment)). Needs the
+ *  owner's spending key, so only the owner can spend the note. */
+export declare function nullifier(n: Note, privateKey: bigint): Promise<bigint>;
+/** Encrypt a note's secret (amount, blinding) to a recipient's X25519 enc key. */
+export declare function encryptNoteSecret(n: Note, recipientEncPub: Uint8Array): Promise<string>;
+/** Decrypt a note secret with the owner's X25519 enc key. Throws if not ours. */
+export declare function decryptNoteSecret(blob: string, encPriv: Uint8Array): Promise<{
+    amount: bigint;
+    blinding: bigint;
+}>;

package/dist/shielded/note.js

@@ -0,0 +1,32 @@
+import { H, FIELD } from "./keypair.js";
+import { encryptNote as eciesEncrypt, decryptNote as eciesDecrypt } from "../pool/crypto.js";
+export function randomBlinding() {
+    const b = new Uint8Array(31);
+    globalThis.crypto.getRandomValues(b);
+    let v = 0n;
+    for (const x of b)
+        v = (v << 8n) | BigInt(x);
+    return v % FIELD;
+}
+export function newNote(amount, pubkey) {
+    return { amount, pubkey, blinding: randomBlinding() };
+}
+export const commitment = (n) => H([n.amount, n.pubkey, n.blinding]);
+/** nullifier = Poseidon(commitment, Poseidon(privateKey, commitment)). Needs the
+ *  owner's spending key, so only the owner can spend the note. */
+export async function nullifier(n, privateKey) {
+    const cm = await commitment(n);
+    const sig = await H([privateKey, cm]);
+    return H([cm, sig]);
+}
+// ── note-secret encryption (so a recipient can find + spend the note) ──
+/** Encrypt a note's secret (amount, blinding) to a recipient's X25519 enc key. */
+export function encryptNoteSecret(n, recipientEncPub) {
+    return eciesEncrypt(`${n.amount.toString(16)}:${n.blinding.toString(16)}`, recipientEncPub);
+}
+/** Decrypt a note secret with the owner's X25519 enc key. Throws if not ours. */
+export async function decryptNoteSecret(blob, encPriv) {
+    const s = await eciesDecrypt(blob, encPriv);
+    const [a, b] = s.split(":");
+    return { amount: BigInt("0x" + a), blinding: BigInt("0x" + b) };
+}

package/dist/shielded/prover.d.ts

@@ -0,0 +1,46 @@
+import { PublicKey } from "@solana/web3.js";
+import { ShieldedKeypair } from "./keypair.js";
+import { Note } from "./note.js";
+export declare function extDataHash(recipient: PublicKey, relayer: PublicKey, extAmount: bigint, fee: bigint): bigint;
+/** publicAmount = (extAmount - fee) mod p. */
+export declare function publicAmount(extAmount: bigint, fee: bigint): bigint;
+export interface TxInput {
+    note: Note;
+    pathElements: bigint[];
+    pathIndices: number[];
+}
+export interface TxOutput {
+    note: Note;
+    /** Recipient's X25519 enc key; the note secret is encrypted to it. */
+    encPub: Uint8Array;
+}
+export interface BuildTxParams {
+    /** Real notes being spent (0–2). Padded to 2 with dummies. */
+    inputs: TxInput[];
+    /** Outputs (1–2). Padded to 2 with a dummy owned by the spender. */
+    outputs: TxOutput[];
+    /** Spender — owns every input and any padding dummies. */
+    spendKeypair: ShieldedKeypair;
+    extAmount: bigint;
+    fee: bigint;
+    recipient: PublicKey;
+    relayer: PublicKey;
+    root: bigint;
+    wasmPath: string;
+    zkeyPath: string;
+}
+export interface FormattedTx {
+    proofA: number[];
+    proofB: number[];
+    proofC: number[];
+    publicInputs: number[][];
+    nullifiers: bigint[];
+    outputCommitments: bigint[];
+    /** Encrypted note secrets, aligned to outputCommitments — hand to the operator. */
+    encryptedSecrets: string[];
+}
+/**
+ * Build a hidden-amount transaction proof for the on-chain `transact`
+ * instruction. Caller must ensure Σinputs + extAmount == Σoutputs + fee.
+ */
+export declare function buildTransaction(p: BuildTxParams): Promise<FormattedTx>;