@umbra-privacy/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Umbra Privacy
+
+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,122 @@
+# @umbra-privacy/sdk
+
+TypeScript SDK for the Umbra privacy protocol on Solana. Provides encrypted balances, anonymous transfers via an on-chain mixer, and full compliance tooling.
+
+## Installation
+
+```bash
+pnpm add @umbra-privacy/sdk
+```
+
+## Quick Start
+
+```typescript
+import {
+  createInMemorySigner,
+  getUmbraClientFromSigner,
+  getUserRegistrationFunction,
+  getDirectDepositIntoEncryptedBalanceFunction,
+  getDirectWithdrawIntoPublicBalanceV3Function,
+} from "@umbra-privacy/sdk";
+
+// 1. Create a signer (use a wallet adapter in production)
+const signer = await createInMemorySigner();
+
+// 2. Create the Umbra client
+const client = await getUmbraClientFromSigner({
+  signer,
+  network: "mainnet",
+  rpcUrl: "https://api.mainnet-beta.solana.com",
+  rpcSubscriptionsUrl: "wss://api.mainnet-beta.solana.com",
+  indexerApiEndpoint: "https://acqzie0a1h.execute-api.eu-central-1.amazonaws.com",
+});
+
+// 3. Register (idempotent — safe to call even if already registered)
+const register = getUserRegistrationFunction({ client });
+await register({ confidential: true, anonymous: true });
+
+// 4. Deposit tokens into an encrypted balance
+const deposit = getDirectDepositIntoEncryptedBalanceFunction({ client });
+const MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"; // USDC
+await deposit(signer.address, MINT, 1_000_000n);
+
+// 5. Withdraw back to public wallet
+const withdraw = getDirectWithdrawIntoPublicBalanceV3Function({ client });
+await withdraw(signer.address, MINT, 1_000_000n);
+```
+
+## Features
+
+- **Encrypted Balances** — Deposit SPL / Token-2022 tokens into on-chain encrypted accounts. Withdraw back to a public wallet at any time.
+- **Anonymous Transfers (Mixer)** — Create UTXOs in an Indexed Merkle Tree. Recipients claim with a Groth16 ZK proof, breaking any on-chain link to the sender.
+- **Compliance** — Master viewing key hierarchy and X25519 compliance grants for authorized auditors.
+- **Branded Types** — Runtime-validated `U64`, `U128`, `U256`, `Address`, `X25519PublicKey`, and other branded types prevent accidental misuse of cryptographic values.
+- **Dual Module Format** — Ships ESM and CommonJS bundles with full TypeScript declarations.
+
+## Entry Points
+
+The SDK provides granular subpath exports to keep bundle sizes small:
+
+- `@umbra-privacy/sdk` — Client construction, service factories, cryptographic operations
+- `@umbra-privacy/sdk/types` — Branded types and assertion functions (`assertU64`, `assertAddress`, etc.)
+- `@umbra-privacy/sdk/interfaces` — Function type signatures for all factory functions and dependencies
+- `@umbra-privacy/sdk/utils` — Converter utilities, PDA derivation helpers, address utilities
+- `@umbra-privacy/sdk/constants` — Network configs, program IDs, domain separators
+- `@umbra-privacy/sdk/errors` — Error classes, stage enums, and type guards
+
+## Service Factory Pattern
+
+Every SDK operation follows the same two-step pattern:
+
+```typescript
+// Build the function once (captures client config and optional dependency overrides)
+const operation = getOperationFunction({ client }, optionalDeps);
+
+// Call it at runtime
+const result = await operation(/* runtime arguments */);
+```
+
+The optional `deps` argument accepts injectable overrides for RPC providers, key generators, and ZK provers — useful for unit testing or custom infrastructure.
+
+## Available Services
+
+- **Registration** — `getUserRegistrationFunction` — Account init, X25519 key registration, anonymous usage setup
+- **Deposit** — `getDirectDepositIntoEncryptedBalanceFunction` — Shield tokens into encrypted accounts
+- **Withdraw** — `getDirectWithdrawIntoPublicBalanceV3Function` — Unshield tokens back to public wallets
+- **UTXO Creation** — `getCreateSelfClaimableUtxoFromPublicBalanceFunction`, `getCreateReceiverClaimableUtxoFromPublicBalanceFunction`, and encrypted-balance variants
+- **UTXO Fetching** — `getFetchClaimableUtxosFunction` — Scan Merkle trees for UTXOs addressed to your keys
+- **UTXO Claiming** — `getClaimSelfClaimableUtxoIntoEncryptedBalanceFunction`, `getClaimReceiverClaimableUtxoIntoEncryptedBalanceFunction`, and public-balance variants
+- **Query** — `getQueryUserAccountFunction`, `getQueryEncryptedBalanceFunction` — Read on-chain state
+- **Conversion** — `getConvertToSharedEncryptionFunction`, `getRotateMintX25519EncryptionKeyFunction`
+- **Compliance** — `getCreateUserGrantedComplianceGrantFunction`, `getDeleteUserGrantedComplianceGrantFunction`, re-encryption operations
+
+## ZK Provers
+
+UTXO creation and claim operations require a Groth16 prover. Install the companion package for browser-based proving:
+
+```bash
+pnpm add @umbra-privacy/web-zk-prover
+```
+
+```typescript
+import { getCreateReceiverClaimableUtxoFromPublicBalanceProver } from "@umbra-privacy/web-zk-prover";
+
+const zkProver = getCreateReceiverClaimableUtxoFromPublicBalanceProver();
+const createUtxo = getCreateReceiverClaimableUtxoFromPublicBalanceFunction(
+  { client },
+  { zkProver },
+);
+```
+
+## Requirements
+
+- Node.js 18+
+- Solana RPC endpoint
+
+## Documentation
+
+Full documentation at [docs.umbraprivacy.com](https://docs.umbraprivacy.com).
+
+## License
+
+MIT

package/dist/addresses-Brzgurv_.d.ts

@@ -0,0 +1,145 @@
+import { Address } from '@solana/kit';
+import { U as U128 } from './cryptography-BTGC72u-.js';
+
+/**
+ * Address Utilities
+ *
+ * This module provides utility functions for working with Solana public-key
+ * addresses in the context of zero-knowledge proof circuits used by the Umbra
+ * protocol.
+ *
+ * ## Problem Statement
+ *
+ * Solana addresses are 32-byte (256-bit) values. BN254-based ZK circuits
+ * (used by Groth16) operate over a scalar field whose prime is slightly less
+ * than 254 bits, making it impossible to represent a full 256-bit address in a
+ * single field element. To work around this, the SDK splits each address into
+ * two 128-bit halves that each fit comfortably within the BN254 field.
+ *
+ * ## Split Convention
+ *
+ * Given a 32-byte address `A`:
+ *
+ * ```
+ * low  = little-endian U128 of bytes A[0..15]
+ * high = little-endian U128 of bytes A[16..31]
+ * ```
+ *
+ * The original value can be reconstructed as:
+ * ```
+ * address_value = (high << 128) | low
+ * ```
+ *
+ * This convention is used consistently across Circom circuit inputs, on-chain
+ * Poseidon hash calls, and the TypeScript SDK.
+ *
+ * @packageDocumentation
+ * @module utils/miscellaneous/addresses
+ */
+
+/**
+ * Result of splitting a 32-byte Solana address into two 128-bit halves.
+ *
+ * Both halves are unsigned 128-bit integers interpreted from their respective
+ * byte ranges in little-endian order. Together they represent the full 256-bit
+ * address and can be passed independently as BN254 field element inputs to
+ * Poseidon hash functions or Groth16 circuit public inputs.
+ *
+ * @example
+ * ```typescript
+ * import { splitAddressToLowHigh } from "@umbra-privacy/sdk";
+ * import { address } from "@solana/kit";
+ *
+ * const { low, high } = splitAddressToLowHigh(
+ *   address("So11111111111111111111111111111111111111112"),
+ * );
+ *
+ * // Pass both halves as separate field elements to a Poseidon hash
+ * const digest = await poseidonHash([masterViewingKey, low, high]);
+ * ```
+ *
+ * @see {@link splitAddressToLowHigh} for the function that produces this result
+ * @public
+ */
+interface AddressSplitResult {
+    /**
+     * Lower 128 bits of the address.
+     *
+     * Derived by taking bytes 0–15 of the 32-byte address encoding and
+     * interpreting them as a little-endian 128-bit unsigned integer.
+     *
+     * @readonly
+     */
+    readonly low: U128;
+    /**
+     * Upper 128 bits of the address.
+     *
+     * Derived by taking bytes 16–31 of the 32-byte address encoding and
+     * interpreting them as a little-endian 128-bit unsigned integer.
+     *
+     * @readonly
+     */
+    readonly high: U128;
+}
+/**
+ * Splits a 32-byte Solana address into two little-endian 128-bit unsigned
+ * integers for use as BN254 circuit inputs.
+ *
+ * Solana addresses are 256-bit public keys. The BN254 scalar field used by
+ * Groth16 circuits cannot hold a full 256-bit value in a single field element,
+ * so addresses must be split into two 128-bit halves before being hashed or
+ * supplied as circuit public inputs. This function performs that split using
+ * the little-endian convention that matches the Umbra Circom circuit
+ * definitions.
+ *
+ * ## Algorithm
+ *
+ * 1. Encode `address` to its canonical 32-byte representation using
+ *    `@solana/kit`'s address encoder.
+ * 2. Slice bytes 0–15; interpret them as a little-endian `U128` → `low`.
+ * 3. Slice bytes 16–31; interpret them as a little-endian `U128` → `high`.
+ * 4. Return `{ low, high }`.
+ *
+ * ## Reconstruction
+ *
+ * The original 256-bit address integer can be recovered as:
+ * ```
+ * address_value = (high << 128n) | low
+ * ```
+ *
+ * This reconstruction is used by the on-chain Poseidon hash and the Circom
+ * circuits to verify that a claimed address matches the committed value.
+ *
+ * @param address - A Solana `Address` (base-58 encoded 32-byte public key).
+ *   The value must be a valid Solana address; the encoder will throw if the
+ *   input is malformed.
+ * @returns An {@link AddressSplitResult} containing the `low` and `high`
+ *   128-bit halves of the address, each expressed as a branded {@link U128}.
+ *
+ * @example
+ * ```typescript
+ * import { splitAddressToLowHigh } from "@umbra-privacy/sdk";
+ * import { address } from "@solana/kit";
+ *
+ * const mintAddress = address("So11111111111111111111111111111111111111112");
+ * const { low, high } = splitAddressToLowHigh(mintAddress);
+ *
+ * // Supply both halves as independent BN254 field elements in a Poseidon hash
+ * const viewingKeyForMint = await poseidonHash([masterViewingKey, low, high]);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reconstruct the original 256-bit address value from the split result
+ * const { low, high } = splitAddressToLowHigh(someAddress);
+ * const fullValue = (BigInt(high) << 128n) | BigInt(low);
+ * ```
+ *
+ * @see {@link AddressSplitResult} for the returned type
+ * @see {@link createU128LeBytes} for the byte-slice branding step
+ * @see {@link decodeU128LeBytesToU128} for the little-endian decode step
+ * @public
+ */
+declare function splitAddressToLowHigh(address: Address): AddressSplitResult;
+
+export { type AddressSplitResult as A, splitAddressToLowHigh as s };

package/dist/addresses-D_0YAS6B.d.cts

@@ -0,0 +1,145 @@
+import { Address } from '@solana/kit';
+import { U as U128 } from './cryptography-BTGC72u-.cjs';
+
+/**
+ * Address Utilities
+ *
+ * This module provides utility functions for working with Solana public-key
+ * addresses in the context of zero-knowledge proof circuits used by the Umbra
+ * protocol.
+ *
+ * ## Problem Statement
+ *
+ * Solana addresses are 32-byte (256-bit) values. BN254-based ZK circuits
+ * (used by Groth16) operate over a scalar field whose prime is slightly less
+ * than 254 bits, making it impossible to represent a full 256-bit address in a
+ * single field element. To work around this, the SDK splits each address into
+ * two 128-bit halves that each fit comfortably within the BN254 field.
+ *
+ * ## Split Convention
+ *
+ * Given a 32-byte address `A`:
+ *
+ * ```
+ * low  = little-endian U128 of bytes A[0..15]
+ * high = little-endian U128 of bytes A[16..31]
+ * ```
+ *
+ * The original value can be reconstructed as:
+ * ```
+ * address_value = (high << 128) | low
+ * ```
+ *
+ * This convention is used consistently across Circom circuit inputs, on-chain
+ * Poseidon hash calls, and the TypeScript SDK.
+ *
+ * @packageDocumentation
+ * @module utils/miscellaneous/addresses
+ */
+
+/**
+ * Result of splitting a 32-byte Solana address into two 128-bit halves.
+ *
+ * Both halves are unsigned 128-bit integers interpreted from their respective
+ * byte ranges in little-endian order. Together they represent the full 256-bit
+ * address and can be passed independently as BN254 field element inputs to
+ * Poseidon hash functions or Groth16 circuit public inputs.
+ *
+ * @example
+ * ```typescript
+ * import { splitAddressToLowHigh } from "@umbra-privacy/sdk";
+ * import { address } from "@solana/kit";
+ *
+ * const { low, high } = splitAddressToLowHigh(
+ *   address("So11111111111111111111111111111111111111112"),
+ * );
+ *
+ * // Pass both halves as separate field elements to a Poseidon hash
+ * const digest = await poseidonHash([masterViewingKey, low, high]);
+ * ```
+ *
+ * @see {@link splitAddressToLowHigh} for the function that produces this result
+ * @public
+ */
+interface AddressSplitResult {
+    /**
+     * Lower 128 bits of the address.
+     *
+     * Derived by taking bytes 0–15 of the 32-byte address encoding and
+     * interpreting them as a little-endian 128-bit unsigned integer.
+     *
+     * @readonly
+     */
+    readonly low: U128;
+    /**
+     * Upper 128 bits of the address.
+     *
+     * Derived by taking bytes 16–31 of the 32-byte address encoding and
+     * interpreting them as a little-endian 128-bit unsigned integer.
+     *
+     * @readonly
+     */
+    readonly high: U128;
+}
+/**
+ * Splits a 32-byte Solana address into two little-endian 128-bit unsigned
+ * integers for use as BN254 circuit inputs.
+ *
+ * Solana addresses are 256-bit public keys. The BN254 scalar field used by
+ * Groth16 circuits cannot hold a full 256-bit value in a single field element,
+ * so addresses must be split into two 128-bit halves before being hashed or
+ * supplied as circuit public inputs. This function performs that split using
+ * the little-endian convention that matches the Umbra Circom circuit
+ * definitions.
+ *
+ * ## Algorithm
+ *
+ * 1. Encode `address` to its canonical 32-byte representation using
+ *    `@solana/kit`'s address encoder.
+ * 2. Slice bytes 0–15; interpret them as a little-endian `U128` → `low`.
+ * 3. Slice bytes 16–31; interpret them as a little-endian `U128` → `high`.
+ * 4. Return `{ low, high }`.
+ *
+ * ## Reconstruction
+ *
+ * The original 256-bit address integer can be recovered as:
+ * ```
+ * address_value = (high << 128n) | low
+ * ```
+ *
+ * This reconstruction is used by the on-chain Poseidon hash and the Circom
+ * circuits to verify that a claimed address matches the committed value.
+ *
+ * @param address - A Solana `Address` (base-58 encoded 32-byte public key).
+ *   The value must be a valid Solana address; the encoder will throw if the
+ *   input is malformed.
+ * @returns An {@link AddressSplitResult} containing the `low` and `high`
+ *   128-bit halves of the address, each expressed as a branded {@link U128}.
+ *
+ * @example
+ * ```typescript
+ * import { splitAddressToLowHigh } from "@umbra-privacy/sdk";
+ * import { address } from "@solana/kit";
+ *
+ * const mintAddress = address("So11111111111111111111111111111111111111112");
+ * const { low, high } = splitAddressToLowHigh(mintAddress);
+ *
+ * // Supply both halves as independent BN254 field elements in a Poseidon hash
+ * const viewingKeyForMint = await poseidonHash([masterViewingKey, low, high]);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reconstruct the original 256-bit address value from the split result
+ * const { low, high } = splitAddressToLowHigh(someAddress);
+ * const fullValue = (BigInt(high) << 128n) | BigInt(low);
+ * ```
+ *
+ * @see {@link AddressSplitResult} for the returned type
+ * @see {@link createU128LeBytes} for the byte-slice branding step
+ * @see {@link decodeU128LeBytesToU128} for the little-endian decode step
+ * @public
+ */
+declare function splitAddressToLowHigh(address: Address): AddressSplitResult;
+
+export { type AddressSplitResult as A, splitAddressToLowHigh as s };

package/dist/chunk-2Q75CQQJ.js

@@ -0,0 +1,12 @@
+// src/constants/arcium.ts
+var ARCIUM_MXE_ACCOUNT_SEED = "MXEAccount";
+var ARCIUM_MEMPOOL_SEED = "Mempool";
+var ARCIUM_EXEC_POOL_SEED = "Execpool";
+var ARCIUM_COMPUTATION_SEED = "ComputationAccount";
+var ARCIUM_COMP_DEF_SEED = "ComputationDefinitionAccount";
+var ARCIUM_CLUSTER_SEED = "Cluster";
+var ARCIUM_OFFSET_BUFFER_SIZE = 4;
+
+export { ARCIUM_CLUSTER_SEED, ARCIUM_COMPUTATION_SEED, ARCIUM_COMP_DEF_SEED, ARCIUM_EXEC_POOL_SEED, ARCIUM_MEMPOOL_SEED, ARCIUM_MXE_ACCOUNT_SEED, ARCIUM_OFFSET_BUFFER_SIZE };
+//# sourceMappingURL=chunk-2Q75CQQJ.js.map
+//# sourceMappingURL=chunk-2Q75CQQJ.js.map

package/dist/chunk-2Q75CQQJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants/arcium.ts"],"names":[],"mappings":";AAeO,IAAM,uBAAA,GAA0B;AAQhC,IAAM,mBAAA,GAAsB;AAQ5B,IAAM,qBAAA,GAAwB;AAQ9B,IAAM,uBAAA,GAA0B;AAQhC,IAAM,oBAAA,GAAuB;AAQ7B,IAAM,mBAAA,GAAsB;AAQ5B,IAAM,yBAAA,GAA4B","file":"chunk-2Q75CQQJ.js","sourcesContent":["/**\n * Arcium Protocol Constants\n *\n * This module contains constants for interacting with the Arcium protocol,\n * including the program address and PDA seed prefixes for various account types.\n *\n * @module constants/arcium\n */\n\n/**\n * Seed prefix for MXE account PDAs.\n *\n * @remarks\n * Used to derive the MXE account address for a given program.\n */\nexport const ARCIUM_MXE_ACCOUNT_SEED = \"MXEAccount\";\n\n/**\n * Seed prefix for mempool account PDAs.\n *\n * @remarks\n * The mempool stores pending computations for a cluster.\n */\nexport const ARCIUM_MEMPOOL_SEED = \"Mempool\";\n\n/**\n * Seed prefix for executing pool account PDAs.\n *\n * @remarks\n * The executing pool tracks computations currently being processed.\n */\nexport const ARCIUM_EXEC_POOL_SEED = \"Execpool\";\n\n/**\n * Seed prefix for computation account PDAs.\n *\n * @remarks\n * Each computation gets its own account to track state and results.\n */\nexport const ARCIUM_COMPUTATION_SEED = \"ComputationAccount\";\n\n/**\n * Seed prefix for computation definition account PDAs.\n *\n * @remarks\n * Computation definitions describe the circuit/program to be executed.\n */\nexport const ARCIUM_COMP_DEF_SEED = \"ComputationDefinitionAccount\";\n\n/**\n * Seed prefix for cluster account PDAs.\n *\n * @remarks\n * Clusters are groups of MXE nodes that process computations together.\n */\nexport const ARCIUM_CLUSTER_SEED = \"Cluster\";\n\n/**\n * Buffer size for cluster/computation offsets in bytes.\n *\n * @remarks\n * Offsets are encoded as 4-byte little-endian unsigned integers.\n */\nexport const ARCIUM_OFFSET_BUFFER_SIZE = 4;\n"]}

package/dist/chunk-7QVYU63E.js

@@ -0,0 +1,6 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+export { __name };
+//# sourceMappingURL=chunk-7QVYU63E.js.map
+//# sourceMappingURL=chunk-7QVYU63E.js.map

package/dist/chunk-7QVYU63E.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-7QVYU63E.js"}