@soteria1/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soteria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @soteria1/sdk
+
+Client SDK for **Soteria** — privacy primitives for Solana. Runs in the browser
+(keys never leave the device) or Node.
+
+```bash
+npm install @soteria1/sdk
+```
+
+## Modules
+
+```ts
+import { shielded, pool, zk, stealth, confidential } from "@soteria1/sdk";
+```
+
+| Module | What it does |
+|--------|--------------|
+| **`shielded`** | Hidden-amount UTXO payments: deposit any amount, pay anyone (amounts encrypted), change + multi-recipient, scan for incoming notes. |
+| **`pool`** | Fixed-denomination compliant privacy pool (ZK deposit/withdraw, association set). |
+| **`zk`** | ZK selective disclosure: prove set membership without revealing identity; Poseidon Merkle tree. |
+| **`stealth`** | Dual-key stealth addresses (one-time receive addresses). |
+| **`confidential`** | Token-2022 confidential-transfer helpers (hidden amounts with an auditor key). |
+
+## Example — a private payment (shielded)
+
+```ts
+import { shielded } from "@soteria1/sdk";
+
+// derive a recoverable shielded identity from a wallet signature
+const me = await shielded.deriveShieldedKeypair(signature);
+const address = shielded.encodeShieldedAddress(me); // share this to get paid
+
+// build a transfer proof (amounts hidden, change handled)
+const tx = await shielded.buildTransaction({
+  inputs, outputs, spendKeypair: me,
+  extAmount: 0n, fee: 5000n, recipient, relayer, root,
+  wasmPath: "/transaction.wasm", zkeyPath: "/transaction_final.zkey",
+});
+
+// find notes paid to you
+const mine = await shielded.scanOutputs(records, me);
+const total = shielded.balance(mine);
+```
+
+Proof artifacts (`transaction.wasm`, `transaction_final.zkey`) come from the
+project's trusted setup (`scripts/setup-transaction.sh`); serve them statically.
+
+## ⚠️ Status
+
+Experimental. The ZK circuits are **unaudited** and the trusted setups are
+single-contributor (dev). **Do not use with real funds** without a professional
+audit and a real multi-party ceremony.
+
+MIT licensed.

package/dist/confidential/confidential.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Confidential amounts via the Token-2022 Confidential Transfer extension.
+ *
+ * Hides transfer AMOUNTS and balances (not the transfer graph) using twisted
+ * ElGamal encryption + ZK proofs verified on-chain by Solana's ZK ElGamal Proof
+ * program. A mint-level `auditor` ElGamal key can decrypt every amount for
+ * compliance — wire it in via `createMint({ auditorElGamalPubkey })`.
+ *
+ * This module uses the @solana/kit (web3.js v2) stack internally because the
+ * confidential-transfer instruction + proof helpers ship for it. Callers work
+ * with plain values (base58 addresses, bigint amounts) and the zk-sdk key
+ * objects; no kit knowledge is required.
+ *
+ * Proofs that exceed transaction size (transfer, withdraw) are verified into
+ * dedicated context-state accounts, created and torn down automatically by the
+ * underlying instruction-plan helpers.
+ */
+import { type Address, type KeyPairSigner, type TransactionSigner } from "@solana/kit";
+import { AeKey, ElGamalKeypair } from "@solana/zk-sdk/bundler";
+export { AeKey, ElGamalKeypair };
+/** Encode a 32-byte ElGamal public key as a base58 Address. */
+export declare function elGamalPubkeyToAddress(keypair: ElGamalKeypair): Address;
+/** Signs an arbitrary message and returns a 64-byte ed25519 signature. */
+export type SignMessage = (message: Uint8Array) => Promise<Uint8Array> | Uint8Array;
+export interface AccountKeys {
+    elgamalKeypair: ElGamalKeypair;
+    aesKey: AeKey;
+}
+/**
+ * Deterministically derive an account's confidential keys from the owner's
+ * signature over a domain-separated message, bound to `(owner, mint)`.
+ *
+ * The same `(sign, owner, mint)` always yields the same keys, so an owner can
+ * recover them from their wallet alone — nothing secret is ever stored or
+ * transmitted, and the binding prevents key reuse across mints. In the browser,
+ * pass a wallet adapter's `signMessage`; on a server, sign with the owner's
+ * ed25519 secret key.
+ */
+export declare function deriveAccountKeys(params: {
+    sign: SignMessage;
+    owner: Address;
+    mint: Address;
+}): Promise<AccountKeys>;
+export interface ConfidentialClientConfig {
+    /** Solana JSON-RPC HTTP endpoint, e.g. https://api.devnet.solana.com */
+    rpcUrl: string;
+    /** Fee payer; signs and pays for every transaction. */
+    payer: KeyPairSigner;
+}
+export interface CreateMintParams {
+    mint: KeyPairSigner;
+    decimals: number;
+    mintAuthority: TransactionSigner;
+    /** Auditor ElGamal pubkey (compliance). Pass null to run without an auditor. */
+    auditorElGamalPubkey?: Address | null;
+    /** When true, accounts may transact immediately without authority approval. */
+    autoApproveNewAccounts?: boolean;
+}
+export interface ConfigureAccountParams {
+    owner: TransactionSigner;
+    mint: Address;
+    elgamalKeypair: ElGamalKeypair;
+    aesKey: AeKey;
+    maximumPendingBalanceCreditCounter?: number | bigint;
+}
+export interface DepositParams {
+    token: Address;
+    mint: Address;
+    authority: TransactionSigner;
+    amount: bigint;
+    decimals: number;
+}
+export interface ApplyPendingParams {
+    token: Address;
+    authority: TransactionSigner;
+    elgamalKeypair: ElGamalKeypair;
+    aesKey: AeKey;
+}
+export interface TransferParams {
+    source: Address;
+    destination: Address;
+    mint: Address;
+    authority: TransactionSigner;
+    amount: bigint;
+    sourceElgamalKeypair: ElGamalKeypair;
+    sourceAesKey: AeKey;
+    auditorElGamalPubkey?: Address;
+}
+export interface WithdrawParams {
+    token: Address;
+    mint: Address;
+    authority: TransactionSigner;
+    amount: bigint;
+    decimals: number;
+    elgamalKeypair: ElGamalKeypair;
+    aesKey: AeKey;
+}
+/**
+ * A confidential-transfer client bound to one RPC endpoint and fee payer.
+ * Each method submits the on-chain transaction(s) for one lifecycle step.
+ */
+export declare class ConfidentialClient {
+    private readonly rpc;
+    private readonly payer;
+    private readonly planner;
+    private readonly executor;
+    constructor(config: ConfidentialClientConfig);
+    /** Poll signature status until confirmed (WebSocket-free). */
+    private confirm;
+    private run;
+    /** Fetch a decoded token account, retrying transient RPC failures. */
+    private fetchTokenAccount;
+    /** Associated token address for an owner on a given mint. */
+    associatedTokenAddress(owner: Address, mint: Address): Promise<Address>;
+    /** Create a Token-2022 mint with the confidential-transfer extension + auditor. */
+    createMint(params: CreateMintParams): Promise<Address>;
+    /**
+     * Configure a token account for confidential transfers (creates the ATA,
+     * reallocates, configures, and verifies the pubkey-validity proof).
+     * Returns the associated token address.
+     */
+    configureAccount(params: ConfigureAccountParams): Promise<Address>;
+    /** Mint public (plaintext) tokens to a token account. */
+    mintTo(params: {
+        mint: Address;
+        token: Address;
+        mintAuthority: TransactionSigner;
+        amount: bigint;
+    }): Promise<void>;
+    /** Move a public balance into the encrypted pending balance. */
+    deposit(params: DepositParams): Promise<void>;
+    /** Move the encrypted pending balance into the spendable available balance. */
+    applyPending(params: ApplyPendingParams): Promise<void>;
+    /** Confidentially transfer an amount between two accounts (amount hidden). */
+    transfer(params: TransferParams): Promise<void>;
+    /** Move an encrypted available balance back to a public (plaintext) balance. */
+    withdraw(params: WithdrawParams): Promise<void>;
+    /** The plaintext (public) token amount visible on-chain. */
+    getPublicAmount(token: Address): Promise<bigint>;
+    /** Decrypt an account's available balance with its owner's AES key. */
+    decryptAvailableBalance(token: Address, aesKey: AeKey): Promise<bigint>;
+}

package/dist/confidential/confidential.js

@@ -0,0 +1,266 @@
+/**
+ * Confidential amounts via the Token-2022 Confidential Transfer extension.
+ *
+ * Hides transfer AMOUNTS and balances (not the transfer graph) using twisted
+ * ElGamal encryption + ZK proofs verified on-chain by Solana's ZK ElGamal Proof
+ * program. A mint-level `auditor` ElGamal key can decrypt every amount for
+ * compliance — wire it in via `createMint({ auditorElGamalPubkey })`.
+ *
+ * This module uses the @solana/kit (web3.js v2) stack internally because the
+ * confidential-transfer instruction + proof helpers ship for it. Callers work
+ * with plain values (base58 addresses, bigint amounts) and the zk-sdk key
+ * objects; no kit knowledge is required.
+ *
+ * Proofs that exceed transaction size (transfer, withdraw) are verified into
+ * dedicated context-state accounts, created and torn down automatically by the
+ * underlying instruction-plan helpers.
+ */
+import { createSolanaRpc, createTransactionMessage, createTransactionPlanExecutor, createTransactionPlanner, getAddressDecoder, getAddressEncoder, getBase64EncodedWireTransaction, getSignatureFromTransaction, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, singleInstructionPlan, some, } from "@solana/kit";
+import { TOKEN_2022_PROGRAM_ADDRESS, extension, fetchToken, findAssociatedTokenPda, getConfidentialDepositInstruction, getCreateMintInstructionPlan, getMintToInstruction, } from "@solana-program/token-2022";
+import { getApplyConfidentialPendingBalanceInstructionFromToken, getConfidentialTransferInstructionPlan, getConfidentialWithdrawInstructionPlan, getCreateConfidentialTransferAccountInstructionPlan, } from "@solana-program/token-2022/confidential";
+import { AeCiphertext, AeKey, ElGamalKeypair } from "@solana/zk-sdk/bundler";
+export { AeKey, ElGamalKeypair };
+/** Encode a 32-byte ElGamal public key as a base58 Address. */
+export function elGamalPubkeyToAddress(keypair) {
+    return getAddressDecoder().decode(keypair.pubkey().toBytes());
+}
+/**
+ * Deterministically derive an account's confidential keys from the owner's
+ * signature over a domain-separated message, bound to `(owner, mint)`.
+ *
+ * The same `(sign, owner, mint)` always yields the same keys, so an owner can
+ * recover them from their wallet alone — nothing secret is ever stored or
+ * transmitted, and the binding prevents key reuse across mints. In the browser,
+ * pass a wallet adapter's `signMessage`; on a server, sign with the owner's
+ * ed25519 secret key.
+ */
+export async function deriveAccountKeys(params) {
+    const encode = getAddressEncoder();
+    const seed = new Uint8Array([
+        ...encode.encode(params.owner),
+        ...encode.encode(params.mint),
+    ]);
+    const elgamalKeypair = ElGamalKeypair.fromSignature(await params.sign(Uint8Array.from(ElGamalKeypair.signerMessage(seed))));
+    const aesKey = AeKey.fromSignature(await params.sign(Uint8Array.from(AeKey.signerMessage(seed))));
+    return { elgamalKeypair, aesKey };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Retry transient RPC failures (rate limits, network blips) with backoff. */
+async function withRetry(fn, attempts = 8) {
+    let delay = 500;
+    let lastErr;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            const msg = String(err?.message ?? err);
+            const retriable = /429|Too Many Requests|fetch failed|ENOTFOUND|ETIMEDOUT|50[023]|socket|network/i.test(msg);
+            if (!retriable || i === attempts - 1)
+                throw err;
+            await sleep(delay);
+            delay = Math.min(delay * 2, 8000);
+        }
+    }
+    throw lastErr;
+}
+/**
+ * A confidential-transfer client bound to one RPC endpoint and fee payer.
+ * Each method submits the on-chain transaction(s) for one lifecycle step.
+ */
+export class ConfidentialClient {
+    constructor(config) {
+        const { rpcUrl, payer } = config;
+        this.payer = payer;
+        this.rpc = createSolanaRpc(rpcUrl);
+        this.planner = createTransactionPlanner({
+            createTransactionMessage: () => pipe(createTransactionMessage({ version: 0 }), (m) => setTransactionMessageFeePayerSigner(payer, m)),
+        });
+        // Confirm via RPC polling rather than a WebSocket subscription: devnet WS
+        // is flaky under the transfer's parallel proof sends, and polling works
+        // identically in Node and the browser.
+        this.executor = createTransactionPlanExecutor({
+            executeTransactionMessage: async (_ctx, message) => {
+                const { value: blockhash } = await withRetry(() => this.rpc.getLatestBlockhash().send());
+                const signed = await signTransactionMessageWithSigners(setTransactionMessageLifetimeUsingBlockhash(blockhash, message));
+                const signature = getSignatureFromTransaction(signed);
+                const wire = getBase64EncodedWireTransaction(signed);
+                await withRetry(() => this.rpc
+                    .sendTransaction(wire, {
+                    encoding: "base64",
+                    preflightCommitment: "confirmed",
+                })
+                    .send());
+                await this.confirm(signature);
+                return signature;
+            },
+        });
+    }
+    /** Poll signature status until confirmed (WebSocket-free). */
+    async confirm(signature, timeoutMs = 60000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const { value } = await withRetry(() => this.rpc
+                .getSignatureStatuses([
+                signature,
+            ])
+                .send());
+            const status = value[0];
+            if (status) {
+                if (status.err) {
+                    throw new Error(`transaction ${signature} failed: ${JSON.stringify(status.err)}`);
+                }
+                if (status.confirmationStatus === "confirmed" ||
+                    status.confirmationStatus === "finalized") {
+                    return;
+                }
+            }
+            await sleep(1500);
+        }
+        throw new Error(`timed out confirming transaction ${signature}`);
+    }
+    async run(plan) {
+        await this.executor(await this.planner(plan));
+    }
+    /** Fetch a decoded token account, retrying transient RPC failures. */
+    async fetchTokenAccount(token) {
+        return (await withRetry(() => fetchToken(this.rpc, token))).data;
+    }
+    /** Associated token address for an owner on a given mint. */
+    async associatedTokenAddress(owner, mint) {
+        const [pda] = await findAssociatedTokenPda({
+            owner,
+            tokenProgram: TOKEN_2022_PROGRAM_ADDRESS,
+            mint,
+        });
+        return pda;
+    }
+    /** Create a Token-2022 mint with the confidential-transfer extension + auditor. */
+    async createMint(params) {
+        const { mint, decimals, mintAuthority, auditorElGamalPubkey = null, autoApproveNewAccounts = true, } = params;
+        await this.run(getCreateMintInstructionPlan({
+            payer: this.payer,
+            newMint: mint,
+            decimals,
+            mintAuthority,
+            extensions: [
+                extension("ConfidentialTransferMint", {
+                    authority: some(mintAuthority.address),
+                    autoApproveNewAccounts,
+                    auditorElgamalPubkey: auditorElGamalPubkey
+                        ? some(auditorElGamalPubkey)
+                        : null,
+                }),
+            ],
+        }));
+        return mint.address;
+    }
+    /**
+     * Configure a token account for confidential transfers (creates the ATA,
+     * reallocates, configures, and verifies the pubkey-validity proof).
+     * Returns the associated token address.
+     */
+    async configureAccount(params) {
+        const { owner, mint, elgamalKeypair, aesKey } = params;
+        await this.run(await getCreateConfidentialTransferAccountInstructionPlan({
+            payer: this.payer,
+            owner,
+            mint,
+            rpc: this.rpc,
+            elgamalKeypair,
+            aesKey,
+            maximumPendingBalanceCreditCounter: params.maximumPendingBalanceCreditCounter,
+        }));
+        return this.associatedTokenAddress(owner.address, mint);
+    }
+    /** Mint public (plaintext) tokens to a token account. */
+    async mintTo(params) {
+        await this.run(singleInstructionPlan(getMintToInstruction({
+            mint: params.mint,
+            token: params.token,
+            mintAuthority: params.mintAuthority,
+            amount: params.amount,
+        })));
+    }
+    /** Move a public balance into the encrypted pending balance. */
+    async deposit(params) {
+        await this.run(singleInstructionPlan(getConfidentialDepositInstruction({
+            token: params.token,
+            mint: params.mint,
+            authority: params.authority,
+            amount: params.amount,
+            decimals: params.decimals,
+        })));
+    }
+    /** Move the encrypted pending balance into the spendable available balance. */
+    async applyPending(params) {
+        const account = await this.fetchTokenAccount(params.token);
+        await this.run(singleInstructionPlan(getApplyConfidentialPendingBalanceInstructionFromToken({
+            token: params.token,
+            tokenAccount: account,
+            authority: params.authority,
+            elgamalSecretKey: params.elgamalKeypair.secret(),
+            aesKey: params.aesKey,
+        })));
+    }
+    /** Confidentially transfer an amount between two accounts (amount hidden). */
+    async transfer(params) {
+        const sourceAccount = await this.fetchTokenAccount(params.source);
+        const destinationAccount = await this.fetchTokenAccount(params.destination);
+        await this.run(await getConfidentialTransferInstructionPlan({
+            sourceToken: params.source,
+            mint: params.mint,
+            destinationToken: params.destination,
+            sourceTokenAccount: sourceAccount,
+            destinationTokenAccount: destinationAccount,
+            auditorElgamalPubkey: params.auditorElGamalPubkey,
+            authority: params.authority,
+            amount: params.amount,
+            sourceElgamalKeypair: params.sourceElgamalKeypair,
+            aesKey: params.sourceAesKey,
+            payer: this.payer,
+            rpc: this.rpc,
+        }));
+    }
+    /** Move an encrypted available balance back to a public (plaintext) balance. */
+    async withdraw(params) {
+        const account = await this.fetchTokenAccount(params.token);
+        await this.run(await getConfidentialWithdrawInstructionPlan({
+            token: params.token,
+            mint: params.mint,
+            tokenAccount: account,
+            authority: params.authority,
+            amount: params.amount,
+            decimals: params.decimals,
+            elgamalKeypair: params.elgamalKeypair,
+            aesKey: params.aesKey,
+            payer: this.payer,
+            rpc: this.rpc,
+        }));
+    }
+    /** The plaintext (public) token amount visible on-chain. */
+    async getPublicAmount(token) {
+        return (await this.fetchTokenAccount(token)).amount;
+    }
+    /** Decrypt an account's available balance with its owner's AES key. */
+    async decryptAvailableBalance(token, aesKey) {
+        const account = await this.fetchTokenAccount(token);
+        // `extensions` is a kit Option<Extension[]>; unwrap defensively (shape is
+        // dynamic on-chain data, so we read it untyped).
+        const raw = account.extensions;
+        const list = Array.isArray(raw)
+            ? raw
+            : raw && raw.__option === "Some"
+                ? raw.value
+                : [];
+        const ct = list.find((e) => e.__kind === "ConfidentialTransferAccount");
+        if (!ct) {
+            throw new Error("account is not configured for confidential transfers");
+        }
+        const cipher = AeCiphertext.fromBytes(Uint8Array.from(ct.decryptableAvailableBalance));
+        if (!cipher)
+            throw new Error("failed to decode available-balance ciphertext");
+        return aesKey.decrypt(cipher);
+    }
+}

package/dist/confidential/index.d.ts

@@ -0,0 +1 @@
+export * from "./confidential.js";

package/dist/confidential/index.js

@@ -0,0 +1 @@
+export * from "./confidential.js";

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Soteria SDK — privacy primitives for Solana.
+ *
+ *   zk           Selective disclosure: prove membership/eligibility without
+ *                revealing which identity. (mainnet-ready)
+ *   stealth      One-time receive addresses so a main wallet isn't exposed.
+ *                (mainnet-ready)
+ *   confidential Token-2022 confidential amounts with an auditor key.
+ *                (verified end-to-end on devnet via ConfidentialClient)
+ *   pool         Compliant fixed-denomination privacy pool: ZK deposit/withdraw
+ *                that severs the on-chain link, gated by an association set and
+ *                auditable via a curated root. (path C — needs setup-pool.sh)
+ *   shielded     Hidden-amount UTXO pool (Option B): arbitrary amounts, partial
+ *                spends, change, multi-recipient — values stay encrypted.
+ *                (needs setup-transaction.sh; verified on devnet)
+ *
+ * Every privacy feature keeps a disclosure/audit path: the pool is gated by an
+ * association set rather than being an unconditional tumbler.
+ */
+export * as zk from "./zk/index.js";
+export * as stealth from "./stealth/index.js";
+export * as confidential from "./confidential/index.js";
+export * as pool from "./pool/index.js";
+export * as shielded from "./shielded/index.js";

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * Soteria SDK — privacy primitives for Solana.
+ *
+ *   zk           Selective disclosure: prove membership/eligibility without
+ *                revealing which identity. (mainnet-ready)
+ *   stealth      One-time receive addresses so a main wallet isn't exposed.
+ *                (mainnet-ready)
+ *   confidential Token-2022 confidential amounts with an auditor key.
+ *                (verified end-to-end on devnet via ConfidentialClient)
+ *   pool         Compliant fixed-denomination privacy pool: ZK deposit/withdraw
+ *                that severs the on-chain link, gated by an association set and
+ *                auditable via a curated root. (path C — needs setup-pool.sh)
+ *   shielded     Hidden-amount UTXO pool (Option B): arbitrary amounts, partial
+ *                spends, change, multi-recipient — values stay encrypted.
+ *                (needs setup-transaction.sh; verified on devnet)
+ *
+ * Every privacy feature keeps a disclosure/audit path: the pool is gated by an
+ * association set rather than being an unconditional tumbler.
+ */
+export * as zk from "./zk/index.js";
+export * as stealth from "./stealth/index.js";
+export * as confidential from "./confidential/index.js";
+export * as pool from "./pool/index.js";
+export * as shielded from "./shielded/index.js";

package/dist/pool/crypto.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Derive a recipient's X25519 receiving keypair from a 32+ byte seed — e.g. the
+ * bytes of a wallet signature over a fixed message, so the identity is
+ * recoverable from the wallet alone and nothing is ever stored.
+ */
+export declare function receiveKeypairFromSeed(seed: Uint8Array): {
+    priv: Uint8Array;
+    pub: Uint8Array;
+};
+/** Shareable encoding of a receiving public key (a "private-payment address"). */
+export declare function encodeReceiveAddress(pub: Uint8Array): string;
+export declare function decodeReceiveAddress(s: string): Uint8Array;
+/** Encrypt a note string to a recipient's receiving public key. */
+export declare function encryptNote(noteStr: string, recipientPub: Uint8Array): Promise<string>;
+export declare function isEncryptedNote(s: string): boolean;
+/** Decrypt an encrypted note with the recipient's receiving private key. */
+export declare function decryptNote(blobStr: string, recipientPriv: Uint8Array): Promise<string>;

package/dist/pool/crypto.js

@@ -0,0 +1,79 @@
+import { x25519 } from "@noble/curves/ed25519";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+// Encrypt a pool note to a recipient so a claim link can travel over a public
+// channel: only the holder of the matching private key can decrypt it. ECIES =
+// ephemeral X25519 ECDH -> HKDF-SHA256 -> AES-256-GCM. No extra deps (WebCrypto
+// is present in the browser and in Node 20+).
+const ENC_PREFIX = "soteria-enc-v1";
+function b64url(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64url(s) {
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = "=".repeat((4 - (b64.length % 4)) % 4);
+    const bin = atob(b64 + pad);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+// A concrete ArrayBuffer copy, so the WebCrypto BufferSource types don't trip on
+// the ArrayBufferLike/SharedArrayBuffer generic.
+function buf(u) {
+    return u.slice().buffer;
+}
+/**
+ * Derive a recipient's X25519 receiving keypair from a 32+ byte seed — e.g. the
+ * bytes of a wallet signature over a fixed message, so the identity is
+ * recoverable from the wallet alone and nothing is ever stored.
+ */
+export function receiveKeypairFromSeed(seed) {
+    const priv = sha256(seed); // 32 bytes; X25519 clamps internally
+    return { priv, pub: x25519.getPublicKey(priv) };
+}
+/** Shareable encoding of a receiving public key (a "private-payment address"). */
+export function encodeReceiveAddress(pub) {
+    return b64url(pub);
+}
+export function decodeReceiveAddress(s) {
+    const pub = unb64url(s.trim());
+    if (pub.length !== 32)
+        throw new Error("invalid private-payment address");
+    return pub;
+}
+async function aesKey(shared) {
+    const raw = hkdf(sha256, shared, undefined, "soteria-pool-note", 32);
+    return crypto.subtle.importKey("raw", buf(raw), "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+/** Encrypt a note string to a recipient's receiving public key. */
+export async function encryptNote(noteStr, recipientPub) {
+    const eph = x25519.utils.randomPrivateKey();
+    const ephPub = x25519.getPublicKey(eph);
+    const shared = x25519.getSharedSecret(eph, recipientPub);
+    const key = await aesKey(shared);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, buf(new TextEncoder().encode(noteStr))));
+    const blob = new Uint8Array(32 + 12 + ct.length);
+    blob.set(ephPub, 0);
+    blob.set(iv, 32);
+    blob.set(ct, 44);
+    return `${ENC_PREFIX}:${b64url(blob)}`;
+}
+export function isEncryptedNote(s) {
+    return s.trim().startsWith(ENC_PREFIX + ":");
+}
+/** Decrypt an encrypted note with the recipient's receiving private key. */
+export async function decryptNote(blobStr, recipientPriv) {
+    const blob = unb64url(blobStr.trim().slice(ENC_PREFIX.length + 1));
+    const ephPub = blob.slice(0, 32);
+    const iv = blob.slice(32, 44);
+    const ct = blob.slice(44);
+    const shared = x25519.getSharedSecret(recipientPriv, ephPub);
+    const key = await aesKey(shared);
+    const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: buf(iv) }, key, buf(ct));
+    return new TextDecoder().decode(pt);
+}

package/dist/pool/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./note.js";
+export * from "./prover.js";
+export * from "./pdas.js";
+export * from "./crypto.js";

package/dist/pool/index.js

@@ -0,0 +1,4 @@
+export * from "./note.js";
+export * from "./prover.js";
+export * from "./pdas.js";
+export * from "./crypto.js";

package/dist/pool/note.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A pool note. Whoever holds (nullifier, secret) can withdraw the deposit whose
+ * commitment = Poseidon(nullifier, secret). Losing it loses the funds — there is
+ * no server-side copy.
+ */
+export interface Note {
+    poolId: bigint;
+    nullifier: bigint;
+    secret: bigint;
+}
+/** Generate a fresh note for a pool. */
+export declare function randomNote(poolId: bigint | number): Note;
+/** Note commitment = Poseidon(nullifier, secret) — the tree leaf. */
+export declare function commitment(note: Note): Promise<bigint>;
+/** nullifierHash = Poseidon(nullifier) — revealed at withdraw, public. */
+export declare function nullifierHash(note: Note): Promise<bigint>;
+/** Serialize a note to the backup string the user must save to claim funds. */
+export declare function encodeNote(note: Note): string;
+/** Parse a backup string back into a note. */
+export declare function decodeNote(s: string): Note;
+/** 32-byte big-endian encoding of a field element (tree leaf / PDA seed). */
+export declare function toBytes32(v: bigint): Uint8Array;