@utxopia/sdk 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/logger.ts

@@ -0,0 +1,41 @@
+/**
+ * Conditional debug logger for UTXOPIA SDK.
+ *
+ * Set `UTXOPIA_DEBUG=1` (Node.js) or `localStorage.utxopiaDebug = "1"` (browser)
+ * to enable debug output. All logs are suppressed by default.
+ */
+
+let _enabled: boolean | null = null;
+
+function isEnabled(): boolean {
+  if (_enabled !== null) return _enabled;
+  try {
+    // Node.js
+    if (typeof process !== "undefined" && process.env?.UTXOPIA_DEBUG === "1") {
+      _enabled = true;
+      return true;
+    }
+  } catch { /* not Node */ }
+  try {
+    // Browser
+    if (typeof localStorage !== "undefined" && localStorage.getItem("utxopiaDebug") === "1") {
+      _enabled = true;
+      return true;
+    }
+  } catch { /* no localStorage */ }
+  _enabled = false;
+  return false;
+}
+
+export function debug(tag: string, ...args: unknown[]): void {
+  if (isEnabled()) console.log(`[utxo:${tag}]`, ...args);
+}
+
+export function warn(tag: string, ...args: unknown[]): void {
+  console.warn(`[utxo:${tag}]`, ...args);
+}
+
+/** Force-enable or disable debug logging at runtime */
+export function setDebug(enabled: boolean): void {
+  _enabled = enabled;
+}

package/src/magicblock.ts

@@ -0,0 +1,278 @@
+import { getAddressEncoder, getProgramDerivedAddress, type Address } from "@solana/kit";
+import { Connection as MagicBlockConnection } from "@magicblock-labs/ephemeral-rollups-kit";
+import { address, type NetworkConfig } from "./config";
+
+export type MagicBlockExecutionMode = "solana" | "er" | "per";
+export type MagicBlockPolicyMode = "disabled" | "per";
+export type MagicBlockValidatorRegion = "asia" | "eu" | "us" | "tee" | "local";
+
+export type PrivacyDomainKind = "public" | "institution";
+
+export interface MagicBlockEndpointConfig {
+  /** Magic Router HTTP endpoint used for delegated-account-aware routing. */
+  routerUrl?: string;
+  /** Magic Router WebSocket endpoint used for confirmations/subscriptions. */
+  routerWsUrl?: string;
+  /** MagicBlock ER endpoint used for low-latency public shielded transfers. */
+  erUrl?: string;
+  /** MagicBlock PER endpoint used for private institution policy execution. */
+  perUrl?: string;
+  /** Validator region selected for delegation. Use "tee" for PER. */
+  validatorRegion?: MagicBlockValidatorRegion;
+}
+
+export interface PrivacyDomainConfig {
+  /** Stable domain identifier. Bind this into future circuit bound params before multi-domain launch. */
+  domainId: string;
+  /** Human-readable label for UI and logs. */
+  label: string;
+  /** Product/compliance category for this privacy domain. */
+  kind: PrivacyDomainKind;
+  /** Execution lane selected for this domain. */
+  executionMode: MagicBlockExecutionMode;
+  /** Optional PER policy coprocessor. Asset execution remains Solana. */
+  policyMode: MagicBlockPolicyMode;
+  /** UTXOpia program instance for this domain. */
+  programId: Address;
+  /** Pool state PDA for this domain. */
+  poolStatePda: Address;
+  /** Active commitment tree PDA for this domain. */
+  commitmentTreePda: Address;
+  /** Optional auditor signer for permissioned domains. */
+  auditor?: Address;
+  /** Optional auditor viewing public key, encoded by the caller. */
+  auditorViewingPubkey?: string;
+  /** Optional MagicBlock endpoints for ER/PER routing. */
+  magicblock?: MagicBlockEndpointConfig;
+}
+
+export interface BuildPrivacyDomainOptions {
+  domainId?: string;
+  label?: string;
+  kind?: PrivacyDomainKind;
+  executionMode?: MagicBlockExecutionMode;
+  policyMode?: MagicBlockPolicyMode;
+  auditor?: Address;
+  auditorViewingPubkey?: string;
+  magicblock?: MagicBlockEndpointConfig;
+}
+
+export const MAGICBLOCK_DELEGATION_PROGRAM_ID = address(
+  "DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh"
+);
+
+export const MAGICBLOCK_PERMISSION_PROGRAM_ID = address(
+  "ACLseoPoyC3cBqoUtkbjZ4aDrkurZW86v19pXz2XQnp1"
+);
+
+export const MAGICBLOCK_MAGIC_PROGRAM_ID = address("Magic11111111111111111111111111111111111111");
+export const MAGICBLOCK_MAGIC_CONTEXT_ID = address(
+  "MagicContext1111111111111111111111111111111"
+);
+export const MAGICBLOCK_EPHEMERAL_VAULT_ID = address(
+  "MagicVau1t999999999999999999999999999999999"
+);
+
+export const MAGICBLOCK_DEVNET_ROUTER_URL = "https://devnet-router.magicblock.app";
+export const MAGICBLOCK_DEVNET_ROUTER_WS_URL = "wss://devnet-router.magicblock.app";
+
+export const MAGICBLOCK_VALIDATOR_IDENTITIES: Record<MagicBlockValidatorRegion, Address> = {
+  asia: address("MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"),
+  eu: address("MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e"),
+  us: address("MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd"),
+  tee: address("MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo"),
+  local: address("mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev"),
+};
+
+export const MAGICBLOCK_PER_MEMBER_FLAGS = {
+  authority: 1 << 0,
+  txLogs: 1 << 1,
+  txBalances: 1 << 2,
+  txMessage: 1 << 3,
+  accountSignatures: 1 << 4,
+} as const;
+
+export const MAGICBLOCK_MAX_PER_MEMBERS = 8;
+
+export type MagicBlockPerMemberFlagName = keyof typeof MAGICBLOCK_PER_MEMBER_FLAGS;
+
+export function buildMagicBlockPerMemberFlags(flags: MagicBlockPerMemberFlagName[]): number {
+  return flags.reduce((acc, flag) => acc | MAGICBLOCK_PER_MEMBER_FLAGS[flag], 0);
+}
+
+export function getMagicBlockValidatorIdentity(region: MagicBlockValidatorRegion): Address {
+  return MAGICBLOCK_VALIDATOR_IDENTITIES[region];
+}
+
+function magicBlockAddressBytes(value: Address): Uint8Array {
+  return new Uint8Array(getAddressEncoder().encode(value));
+}
+
+export async function deriveMagicBlockDelegationRecordPDA(
+  delegatedAccount: Address
+): Promise<[Address, number]> {
+  const result = await getProgramDerivedAddress({
+    programAddress: MAGICBLOCK_DELEGATION_PROGRAM_ID,
+    seeds: [new TextEncoder().encode("delegation"), magicBlockAddressBytes(delegatedAccount)],
+  });
+  return [result[0], result[1]];
+}
+
+export async function deriveMagicBlockDelegationMetadataPDA(
+  delegatedAccount: Address
+): Promise<[Address, number]> {
+  const result = await getProgramDerivedAddress({
+    programAddress: MAGICBLOCK_DELEGATION_PROGRAM_ID,
+    seeds: [
+      new TextEncoder().encode("delegation-metadata"),
+      magicBlockAddressBytes(delegatedAccount),
+    ],
+  });
+  return [result[0], result[1]];
+}
+
+export async function deriveMagicBlockDelegateBufferPDA(
+  delegatedAccount: Address,
+  ownerProgram: Address
+): Promise<[Address, number]> {
+  const result = await getProgramDerivedAddress({
+    programAddress: ownerProgram,
+    seeds: [new TextEncoder().encode("buffer"), magicBlockAddressBytes(delegatedAccount)],
+  });
+  return [result[0], result[1]];
+}
+
+export async function deriveMagicBlockUndelegateBufferPDA(
+  delegatedAccount: Address
+): Promise<[Address, number]> {
+  const result = await getProgramDerivedAddress({
+    programAddress: MAGICBLOCK_DELEGATION_PROGRAM_ID,
+    seeds: [new TextEncoder().encode("undelegate-buffer"), magicBlockAddressBytes(delegatedAccount)],
+  });
+  return [result[0], result[1]];
+}
+
+export async function deriveMagicBlockCommitStatePDA(
+  delegatedAccount: Address
+): Promise<[Address, number]> {
+  const result = await getProgramDerivedAddress({
+    programAddress: MAGICBLOCK_DELEGATION_PROGRAM_ID,
+    seeds: [new TextEncoder().encode("state-diff"), magicBlockAddressBytes(delegatedAccount)],
+  });
+  return [result[0], result[1]];
+}
+
+export async function deriveMagicBlockCommitRecordPDA(
+  delegatedAccount: Address
+): Promise<[Address, number]> {
+  const result = await getProgramDerivedAddress({
+    programAddress: MAGICBLOCK_DELEGATION_PROGRAM_ID,
+    seeds: [
+      new TextEncoder().encode("commit-state-record"),
+      magicBlockAddressBytes(delegatedAccount),
+    ],
+  });
+  return [result[0], result[1]];
+}
+
+export async function deriveMagicBlockPermissionPDA(
+  permissionedAccount: Address
+): Promise<[Address, number]> {
+  const result = await getProgramDerivedAddress({
+    programAddress: MAGICBLOCK_PERMISSION_PROGRAM_ID,
+    seeds: [
+      new TextEncoder().encode("permission:"),
+      magicBlockAddressBytes(permissionedAccount),
+    ],
+  });
+  return [result[0], result[1]];
+}
+
+export function buildDefaultPrivacyDomain(
+  config: NetworkConfig,
+  options: BuildPrivacyDomainOptions = {}
+): PrivacyDomainConfig {
+  return {
+    domainId: options.domainId ?? "public",
+    label: options.label ?? "Public Pool",
+    kind: options.kind ?? "public",
+    executionMode: options.executionMode ?? "solana",
+    policyMode: options.policyMode ?? "disabled",
+    programId: config.utxopiaProgramId,
+    poolStatePda: config.poolStatePda,
+    commitmentTreePda: config.commitmentTreePda,
+    auditor: options.auditor,
+    auditorViewingPubkey: options.auditorViewingPubkey,
+    magicblock: {
+      routerUrl: MAGICBLOCK_DEVNET_ROUTER_URL,
+      routerWsUrl: MAGICBLOCK_DEVNET_ROUTER_WS_URL,
+      validatorRegion: options.policyMode === "per" ? "tee" : "asia",
+      ...options.magicblock,
+    },
+  };
+}
+
+export function requiresMagicBlockEndpoint(mode: MagicBlockExecutionMode): boolean {
+  return mode === "er" || mode === "per";
+}
+
+export function getMagicBlockEndpoint(
+  domain: PrivacyDomainConfig,
+  mode: MagicBlockExecutionMode = domain.executionMode
+): string | undefined {
+  if (mode === "er") {
+    return domain.magicblock?.erUrl;
+  }
+  if (mode === "per") {
+    return domain.magicblock?.perUrl;
+  }
+  return undefined;
+}
+
+export function assertMagicBlockRouteReady(domain: PrivacyDomainConfig): void {
+  const mode = domain.executionMode;
+  if (!requiresMagicBlockEndpoint(mode)) {
+    return;
+  }
+
+  const endpoint = getMagicBlockEndpoint(domain, mode);
+  if (!endpoint) {
+    throw new Error(
+      `Privacy domain "${domain.domainId}" uses ${mode.toUpperCase()} but no MagicBlock ${mode.toUpperCase()} endpoint is configured`
+    );
+  }
+}
+
+export function assertDomainExecutionPolicy(domain: PrivacyDomainConfig): void {
+  if (domain.executionMode !== "solana") {
+    throw new Error("UTXOpia asset execution must remain on Solana");
+  }
+  if (domain.kind === "public" && domain.policyMode === "per") {
+    throw new Error("Public permissionless domains must not require PER policy");
+  }
+  if (domain.policyMode === "per" && domain.magicblock?.validatorRegion !== "tee") {
+    throw new Error("PER policy domains must use the TEE validator region");
+  }
+  if (domain.policyMode === "per" && !domain.magicblock?.perUrl) {
+    throw new Error(`Privacy domain "${domain.domainId}" requires a PER policy endpoint`);
+  }
+}
+
+/**
+ * Create the delegated-account-aware connection used for public ER traffic.
+ * PER uses the authenticated server relay because the kit connection does not
+ * expose request headers for the signed-challenge bearer token.
+ */
+export async function createMagicBlockRouterConnection(
+  domain: PrivacyDomainConfig
+): Promise<MagicBlockConnection> {
+  assertDomainExecutionPolicy(domain);
+  if (domain.executionMode !== "er") {
+    throw new Error("MagicBlock kit router connections are supported only for public ER domains");
+  }
+  const routerUrl = domain.magicblock?.routerUrl;
+  if (!routerUrl) {
+    throw new Error("MagicBlock router URL is required for ER execution");
+  }
+  return MagicBlockConnection.create(routerUrl, domain.magicblock?.routerWsUrl);
+}

package/src/merkle.ts

@@ -0,0 +1,197 @@
+/**
+ * Merkle tree utilities for UTXOpia
+ *
+ * Provides structures and helpers for Merkle proofs.
+ * Actual tree operations use Poseidon hashing which is computed
+ * on-chain or via circom circuits.
+ *
+ * Note: This module does NOT compute Poseidon hashes in JavaScript.
+ * The on-chain program maintains the Merkle tree. This SDK provides
+ * proof structures for interaction with the program.
+ */
+
+import { bigintToBytes, bytesToBigint } from "./crypto";
+import { toHex } from "./utils/encoding";
+
+// Tree configuration - matches on-chain constants (depth 16 = 65,536 leaves)
+export const TREE_DEPTH = 16;
+export const ROOT_HISTORY_SIZE = 30;
+export const MAX_LEAVES = 1 << TREE_DEPTH; // 65,536
+
+// Zero value for empty nodes (matches on-chain)
+export const ZERO_VALUE = bigintToBytes(
+  0x2fe54c60d3ada40e0000000000000000000000000000000000000000n
+);
+
+/**
+ * Merkle proof structure
+ */
+export interface MerkleProof {
+  // Sibling nodes along the path (20 elements for depth 20)
+  pathElements: Uint8Array[];
+  // Path indices (0 = left, 1 = right)
+  pathIndices: number[];
+  // Leaf index
+  leafIndex: number;
+  // Merkle root
+  root: Uint8Array;
+}
+
+/**
+ * Create a Merkle proof from on-chain data
+ *
+ * @param pathElements - Sibling hashes as 32-byte arrays
+ * @param pathIndices - Direction at each level (0=left, 1=right)
+ * @param leafIndex - Index of the leaf in the tree
+ * @param root - Current Merkle root
+ */
+export function createMerkleProof(
+  pathElements: Uint8Array[],
+  pathIndices: number[],
+  leafIndex: number,
+  root: Uint8Array
+): MerkleProof {
+  if (pathElements.length !== TREE_DEPTH) {
+    throw new Error(`Expected ${TREE_DEPTH} path elements, got ${pathElements.length}`);
+  }
+  if (pathIndices.length !== TREE_DEPTH) {
+    throw new Error(`Expected ${TREE_DEPTH} path indices, got ${pathIndices.length}`);
+  }
+
+  return {
+    pathElements: pathElements.map((el) => new Uint8Array(el)),
+    pathIndices: [...pathIndices],
+    leafIndex,
+    root: new Uint8Array(root),
+  };
+}
+
+/**
+ * Create a Merkle proof from bigint values
+ */
+export function createMerkleProofFromBigints(
+  pathElements: bigint[],
+  pathIndices: number[],
+  leafIndex: number,
+  root: bigint
+): MerkleProof {
+  return createMerkleProof(
+    pathElements.map(bigintToBytes),
+    pathIndices,
+    leafIndex,
+    bigintToBytes(root)
+  );
+}
+
+/**
+ * Convert Merkle proof to format expected by circom circuits
+ */
+export function proofToCircomFormat(proof: MerkleProof): {
+  merkle_path: string[];
+  path_indices: string[];
+  merkle_root: string;
+} {
+  return {
+    merkle_path: proof.pathElements.map(
+      (el) => "0x" + toHex(el)
+    ),
+    path_indices: proof.pathIndices.map((i) => i.toString()),
+    merkle_root: "0x" + toHex(proof.root),
+  };
+}
+
+/**
+ * Convert Merkle proof to format expected by on-chain program
+ */
+export function proofToOnChainFormat(proof: MerkleProof): {
+  siblings: number[][];
+  path: boolean[];
+} {
+  return {
+    siblings: proof.pathElements.map((el) => Array.from(el)),
+    path: proof.pathIndices.map((i) => i === 1),
+  };
+}
+
+/**
+ * Compute leaf index from path indices
+ */
+export function pathIndicesToLeafIndex(pathIndices: number[]): number {
+  let index = 0;
+  for (let i = 0; i < pathIndices.length; i++) {
+    if (pathIndices[i] === 1) {
+      index |= 1 << i;
+    }
+  }
+  return index;
+}
+
+/**
+ * Compute path indices from leaf index
+ */
+export function leafIndexToPathIndices(leafIndex: number, depth: number = TREE_DEPTH): number[] {
+  const indices: number[] = [];
+  let idx = leafIndex;
+  for (let i = 0; i < depth; i++) {
+    indices.push(idx & 1);
+    idx >>= 1;
+  }
+  return indices;
+}
+
+/**
+ * Create an empty/placeholder Merkle proof
+ * Used when constructing proofs before on-chain data is available
+ */
+export function createEmptyMerkleProof(): MerkleProof {
+  const pathElements: Uint8Array[] = [];
+  const pathIndices: number[] = [];
+
+  for (let i = 0; i < TREE_DEPTH; i++) {
+    pathElements.push(new Uint8Array(ZERO_VALUE));
+    pathIndices.push(0);
+  }
+
+  return {
+    pathElements,
+    pathIndices,
+    leafIndex: 0,
+    root: new Uint8Array(ZERO_VALUE),
+  };
+}
+
+/**
+ * Parse a merkle proof response (hex strings) into BigInt format for circuit input.
+ * Accepts the response from /api/merkle/proof or /api/tree/proof.
+ */
+export function parseMerkleProofResponse(response: {
+  root: string;
+  siblings: string[];
+  indices: number[];
+}): { root: bigint; pathElements: bigint[]; pathIndices: number[] } {
+  return {
+    root: BigInt("0x" + response.root),
+    pathElements: response.siblings.map((s) => BigInt("0x" + s)),
+    pathIndices: response.indices,
+  };
+}
+
+/**
+ * Validate Merkle proof structure
+ */
+export function validateMerkleProofStructure(proof: MerkleProof): boolean {
+  if (proof.pathElements.length !== TREE_DEPTH) return false;
+  if (proof.pathIndices.length !== TREE_DEPTH) return false;
+  if (proof.leafIndex < 0 || proof.leafIndex >= MAX_LEAVES) return false;
+  if (proof.root.length !== 32) return false;
+
+  for (const el of proof.pathElements) {
+    if (el.length !== 32) return false;
+  }
+
+  for (const idx of proof.pathIndices) {
+    if (idx !== 0 && idx !== 1) return false;
+  }
+
+  return true;
+}