@umbra-privacy/sdk 1.0.0 → 2.0.1

package/README.md

@@ -12,23 +12,23 @@ pnpm add @umbra-privacy/sdk
 
 ```typescript
 import {
-  createInMemorySigner,
-  getUmbraClientFromSigner,
+  getInMemorySigner,
+  getUmbraClient,
   getUserRegistrationFunction,
-  getDirectDepositIntoEncryptedBalanceFunction,
-  getDirectWithdrawIntoPublicBalanceV3Function,
+  getPublicBalanceToEncryptedBalanceDirectDepositorFunction,
+  getEncryptedBalanceToPublicBalanceDirectWithdrawerFunction,
 } from "@umbra-privacy/sdk";
 
 // 1. Create a signer (use a wallet adapter in production)
-const signer = await createInMemorySigner();
+const signer = await getInMemorySigner();
 
 // 2. Create the Umbra client
-const client = await getUmbraClientFromSigner({
+const client = await getUmbraClient({
   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",
+  indexerApiEndpoint: "https://indexer.umbraprivacy.com",
 });
 
 // 3. Register (idempotent — safe to call even if already registered)
@@ -36,13 +36,13 @@ 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);
+const deposit = getPublicBalanceToEncryptedBalanceDirectDepositorFunction({ client });
+const USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+await deposit(signer.address, USDC, 1_000_000n);
 
 // 5. Withdraw back to public wallet
-const withdraw = getDirectWithdrawIntoPublicBalanceV3Function({ client });
-await withdraw(signer.address, MINT, 1_000_000n);
+const withdraw = getEncryptedBalanceToPublicBalanceDirectWithdrawerFunction({ client });
+await withdraw(signer.address, USDC, 1_000_000n);
 ```
 
 ## Features
@@ -58,9 +58,12 @@ await withdraw(signer.address, MINT, 1_000_000n);
 The SDK provides granular subpath exports to keep bundle sizes small:
 
 - `@umbra-privacy/sdk` — Client construction, service factories, cryptographic operations
+- `@umbra-privacy/sdk/crypto` — Rescue cipher, Poseidon hash, AES, key derivation, Fiat-Shamir challenges
+- `@umbra-privacy/sdk/pda` — Program Derived Address derivation for all Umbra and Arcium accounts
+- `@umbra-privacy/sdk/solana` — RPC providers, signers, transaction forwarding
+- `@umbra-privacy/sdk/math` — BN254 and Curve25519 field arithmetic
 - `@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
 
@@ -69,10 +72,10 @@ The SDK provides granular subpath exports to keep bundle sizes small:
 Every SDK operation follows the same two-step pattern:
 
 ```typescript
-// Build the function once (captures client config and optional dependency overrides)
+// Step 1: Build the function once (captures client config and optional dependency overrides)
 const operation = getOperationFunction({ client }, optionalDeps);
 
-// Call it at runtime
+// Step 2: Call it at runtime (can be called many times with different args)
 const result = await operation(/* runtime arguments */);
 ```
 
@@ -80,15 +83,91 @@ The optional `deps` argument accepts injectable overrides for RPC providers, key
 
 ## 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
+### Token Flow (Source → Destination → Action)
+
+- **Direct Deposit** — `getPublicBalanceToEncryptedBalanceDirectDepositorFunction` — Move tokens from public wallet into encrypted balance
+- **Direct Withdraw** — `getEncryptedBalanceToPublicBalanceDirectWithdrawerFunction` — Move tokens from encrypted balance to public wallet
+
+### UTXO Creation (Stealth Pool Deposits)
+
+- `getPublicBalanceToSelfClaimableUtxoCreatorFunction` — Shield your own public tokens into the mixer
+- `getEncryptedBalanceToSelfClaimableUtxoCreatorFunction` — Shield your own encrypted tokens into the mixer
+- `getPublicBalanceToReceiverClaimableUtxoCreatorFunction` — Send public tokens to a receiver via the mixer
+- `getEncryptedBalanceToReceiverClaimableUtxoCreatorFunction` — Send encrypted tokens to a receiver via the mixer
+
+### UTXO Scanning & Claiming
+
+- `getClaimableUtxoScannerFunction` — Scan Merkle trees for UTXOs addressed to your keys
+- `getSelfClaimableUtxoToEncryptedBalanceClaimerFunction` — Claim your own UTXO into encrypted balance
+- `getSelfClaimableUtxoToPublicBalanceClaimerFunction` — Claim your own UTXO into public wallet
+- `getReceiverClaimableUtxoToEncryptedBalanceClaimerFunction` — Claim a received UTXO into encrypted balance
+
+### User Account Management
+
+- `getUserRegistrationFunction` — Account init, X25519 key registration, anonymous usage setup
+- `getUserEncryptionKeyRotatorFunction` — Rotate user account X25519 encryption key
+- `getMasterViewingKeyRotatorFunction` — Rotate master viewing key
+- `getUserEntropySeedRotatorFunction` — Rotate user-level entropy seed
+- `getTokenEntropySeedRotatorFunction` — Rotate per-token entropy seed
+- `getStagedSolRecovererFunction` — Recover SOL stuck from failed MPC callbacks
+- `getStagedSplRecovererFunction` — Recover SPL tokens stuck from failed MPC callbacks
+
+### Query
+
+- `getUserAccountQuerierFunction` — Read user account state
+- `getEncryptedBalanceQuerierFunction` — Read and decrypt encrypted token balance
+
+### Conversion
+
+- `getNetworkEncryptionToSharedEncryptionConverterFunction` — Convert from network-only to shared encryption mode
+- `getMintEncryptionKeyRotatorFunction` — Rotate per-mint encryption key
+
+### Compliance
+
+- `getComplianceGrantIssuerFunction` — Authorize an auditor to view encrypted data
+- `getComplianceGrantRevokerFunction` — Revoke auditor access
+- `getSharedCiphertextReencryptorForUserGrantFunction` — Re-encrypt shared balance for a user-granted auditor
+- `getNetworkCiphertextReencryptorForNetworkGrantFunction` — Re-encrypt network balance for a network-granted auditor
+- `getSharedCiphertextReencryptorForNetworkGrantFunction` — Re-encrypt shared balance for a network-granted auditor
+
+## PDA Derivation
+
+All Program Derived Address functions use the `find*Pda` convention:
+
+```typescript
+import {
+  findEncryptedTokenAccountPda,
+  findStealthPoolPda,
+  findNullifierSetPdas,
+} from "@umbra-privacy/sdk/pda";
+
+const tokenAccountPda = await findEncryptedTokenAccountPda(userAddress, mintAddress, programId);
+const stealthPoolPda = await findStealthPoolPda(treeIndex, programId);
+const nullifierPdas = await findNullifierSetPdas(treeIndex, programId);
+```
+
+## Cryptography
+
+```typescript
+import {
+  getRescueEncryptorFromPrivateKey,
+  getRescueDecryptorFromPrivateKey,
+  getPoseidonHasher,
+  getMasterViewingKeyDeriver,
+} from "@umbra-privacy/sdk/crypto";
+
+// Rescue cipher encryption
+const encryptor = getRescueEncryptorFromPrivateKey(privateKey);
+const { ciphertexts, nonce } = await encryptor([plaintext]);
+
+// Poseidon hashing
+const hasher = getPoseidonHasher();
+const hash = hasher([input1, input2]);
+
+// Key derivation
+const deriveMvk = getMasterViewingKeyDeriver({ client });
+const masterViewingKey = await deriveMvk();
+```
 
 ## ZK Provers
 
@@ -102,7 +181,7 @@ pnpm add @umbra-privacy/web-zk-prover
 import { getCreateReceiverClaimableUtxoFromPublicBalanceProver } from "@umbra-privacy/web-zk-prover";
 
 const zkProver = getCreateReceiverClaimableUtxoFromPublicBalanceProver();
-const createUtxo = getCreateReceiverClaimableUtxoFromPublicBalanceFunction(
+const createUtxo = getPublicBalanceToReceiverClaimableUtxoCreatorFunction(
   { client },
   { zkProver },
 );

package/dist/{addresses-Brzgurv_.d.ts → addresses-B7HybtbJ.d.ts}

@@ -1,5 +1,5 @@
 import { Address } from '@solana/kit';
-import { U as U128 } from './cryptography-BTGC72u-.js';
+import { U as U128 } from './types-C_V_CaKK.js';
 
 /**
  * Address Utilities
@@ -34,6 +34,7 @@ import { U as U128 } from './cryptography-BTGC72u-.js';
  * Poseidon hash calls, and the TypeScript SDK.
  *
  * @packageDocumentation
+ * @since 2.0.0
  * @module utils/miscellaneous/addresses
  */
 

package/dist/{addresses-D_0YAS6B.d.cts → addresses-CTVY1oi7.d.cts}

@@ -1,5 +1,5 @@
 import { Address } from '@solana/kit';
-import { U as U128 } from './cryptography-BTGC72u-.cjs';
+import { U as U128 } from './types-C_V_CaKK.cjs';
 
 /**
  * Address Utilities
@@ -34,6 +34,7 @@ import { U as U128 } from './cryptography-BTGC72u-.cjs';
  * Poseidon hash calls, and the TypeScript SDK.
  *
  * @packageDocumentation
+ * @since 2.0.0
  * @module utils/miscellaneous/addresses
  */
 

package/dist/arcium-BXXlryfe.d.cts

@@ -0,0 +1,20 @@
+/**
+ * Arcium Protocol Types
+ *
+ * Branded types for Arcium-specific protocol values.
+ *
+ * @since 2.0.0
+ * @module types/arcium
+ */
+/**
+ * Micro-lamports per Arcium Computation Unit.
+ *
+ * This is a branded bigint representing the price a user is willing to pay
+ * per ACU of Arcium computation. The value is passed directly to the on-chain
+ * `priorityFees` instruction field.
+ */
+type MicroLamportsPerAcu = bigint & {
+    readonly __brand: "MicroLamportsPerAcu";
+};
+
+export type { MicroLamportsPerAcu as M };

package/dist/arcium-BXXlryfe.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Arcium Protocol Types
+ *
+ * Branded types for Arcium-specific protocol values.
+ *
+ * @since 2.0.0
+ * @module types/arcium
+ */
+/**
+ * Micro-lamports per Arcium Computation Unit.
+ *
+ * This is a branded bigint representing the price a user is willing to pay
+ * per ACU of Arcium computation. The value is passed directly to the on-chain
+ * `priorityFees` instruction field.
+ */
+type MicroLamportsPerAcu = bigint & {
+    readonly __brand: "MicroLamportsPerAcu";
+};
+
+export type { MicroLamportsPerAcu as M };