@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/logger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+export declare function debug(tag: string, ...args: unknown[]): void;
+export declare function warn(tag: string, ...args: unknown[]): void;
+/** Force-enable or disable debug logging at runtime */
+export declare function setDebug(enabled: boolean): void;

package/packages/sdk/dist/logger.js

@@ -0,0 +1,40 @@
+/**
+ * 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 = null;
+function isEnabled() {
+    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, ...args) {
+    if (isEnabled())
+        console.log(`[utxo:${tag}]`, ...args);
+}
+export function warn(tag, ...args) {
+    console.warn(`[utxo:${tag}]`, ...args);
+}
+/** Force-enable or disable debug logging at runtime */
+export function setDebug(enabled) {
+    _enabled = enabled;
+}

package/packages/sdk/dist/magicblock.d.ts

@@ -0,0 +1,90 @@
+import { type Address } from "@solana/kit";
+import { Connection as MagicBlockConnection } from "@magicblock-labs/ephemeral-rollups-kit";
+import { 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 declare const MAGICBLOCK_DELEGATION_PROGRAM_ID: Address;
+export declare const MAGICBLOCK_PERMISSION_PROGRAM_ID: Address;
+export declare const MAGICBLOCK_MAGIC_PROGRAM_ID: Address;
+export declare const MAGICBLOCK_MAGIC_CONTEXT_ID: Address;
+export declare const MAGICBLOCK_EPHEMERAL_VAULT_ID: Address;
+export declare const MAGICBLOCK_DEVNET_ROUTER_URL = "https://devnet-router.magicblock.app";
+export declare const MAGICBLOCK_DEVNET_ROUTER_WS_URL = "wss://devnet-router.magicblock.app";
+export declare const MAGICBLOCK_VALIDATOR_IDENTITIES: Record<MagicBlockValidatorRegion, Address>;
+export declare const MAGICBLOCK_PER_MEMBER_FLAGS: {
+    readonly authority: number;
+    readonly txLogs: number;
+    readonly txBalances: number;
+    readonly txMessage: number;
+    readonly accountSignatures: number;
+};
+export declare const MAGICBLOCK_MAX_PER_MEMBERS = 8;
+export type MagicBlockPerMemberFlagName = keyof typeof MAGICBLOCK_PER_MEMBER_FLAGS;
+export declare function buildMagicBlockPerMemberFlags(flags: MagicBlockPerMemberFlagName[]): number;
+export declare function getMagicBlockValidatorIdentity(region: MagicBlockValidatorRegion): Address;
+export declare function deriveMagicBlockDelegationRecordPDA(delegatedAccount: Address): Promise<[Address, number]>;
+export declare function deriveMagicBlockDelegationMetadataPDA(delegatedAccount: Address): Promise<[Address, number]>;
+export declare function deriveMagicBlockDelegateBufferPDA(delegatedAccount: Address, ownerProgram: Address): Promise<[Address, number]>;
+export declare function deriveMagicBlockUndelegateBufferPDA(delegatedAccount: Address): Promise<[Address, number]>;
+export declare function deriveMagicBlockCommitStatePDA(delegatedAccount: Address): Promise<[Address, number]>;
+export declare function deriveMagicBlockCommitRecordPDA(delegatedAccount: Address): Promise<[Address, number]>;
+export declare function deriveMagicBlockPermissionPDA(permissionedAccount: Address): Promise<[Address, number]>;
+export declare function buildDefaultPrivacyDomain(config: NetworkConfig, options?: BuildPrivacyDomainOptions): PrivacyDomainConfig;
+export declare function requiresMagicBlockEndpoint(mode: MagicBlockExecutionMode): boolean;
+export declare function getMagicBlockEndpoint(domain: PrivacyDomainConfig, mode?: MagicBlockExecutionMode): string | undefined;
+export declare function assertMagicBlockRouteReady(domain: PrivacyDomainConfig): void;
+export declare function assertDomainExecutionPolicy(domain: PrivacyDomainConfig): void;
+/**
+ * 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 declare function createMagicBlockRouterConnection(domain: PrivacyDomainConfig): Promise<MagicBlockConnection>;

package/packages/sdk/dist/magicblock.js

@@ -0,0 +1,164 @@
+import { getAddressEncoder, getProgramDerivedAddress } from "@solana/kit";
+import { Connection as MagicBlockConnection } from "@magicblock-labs/ephemeral-rollups-kit";
+import { address } from "./config";
+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 = {
+    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,
+};
+export const MAGICBLOCK_MAX_PER_MEMBERS = 8;
+export function buildMagicBlockPerMemberFlags(flags) {
+    return flags.reduce((acc, flag) => acc | MAGICBLOCK_PER_MEMBER_FLAGS[flag], 0);
+}
+export function getMagicBlockValidatorIdentity(region) {
+    return MAGICBLOCK_VALIDATOR_IDENTITIES[region];
+}
+function magicBlockAddressBytes(value) {
+    return new Uint8Array(getAddressEncoder().encode(value));
+}
+export async function deriveMagicBlockDelegationRecordPDA(delegatedAccount) {
+    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) {
+    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, ownerProgram) {
+    const result = await getProgramDerivedAddress({
+        programAddress: ownerProgram,
+        seeds: [new TextEncoder().encode("buffer"), magicBlockAddressBytes(delegatedAccount)],
+    });
+    return [result[0], result[1]];
+}
+export async function deriveMagicBlockUndelegateBufferPDA(delegatedAccount) {
+    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) {
+    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) {
+    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) {
+    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, options = {}) {
+    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) {
+    return mode === "er" || mode === "per";
+}
+export function getMagicBlockEndpoint(domain, mode = domain.executionMode) {
+    if (mode === "er") {
+        return domain.magicblock?.erUrl;
+    }
+    if (mode === "per") {
+        return domain.magicblock?.perUrl;
+    }
+    return undefined;
+}
+export function assertMagicBlockRouteReady(domain) {
+    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) {
+    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) {
+    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/packages/sdk/dist/merkle.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+export declare const TREE_DEPTH = 16;
+export declare const ROOT_HISTORY_SIZE = 30;
+export declare const MAX_LEAVES: number;
+export declare const ZERO_VALUE: Uint8Array<ArrayBufferLike>;
+/**
+ * Merkle proof structure
+ */
+export interface MerkleProof {
+    pathElements: Uint8Array[];
+    pathIndices: number[];
+    leafIndex: number;
+    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 declare function createMerkleProof(pathElements: Uint8Array[], pathIndices: number[], leafIndex: number, root: Uint8Array): MerkleProof;
+/**
+ * Create a Merkle proof from bigint values
+ */
+export declare function createMerkleProofFromBigints(pathElements: bigint[], pathIndices: number[], leafIndex: number, root: bigint): MerkleProof;
+/**
+ * Convert Merkle proof to format expected by circom circuits
+ */
+export declare function proofToCircomFormat(proof: MerkleProof): {
+    merkle_path: string[];
+    path_indices: string[];
+    merkle_root: string;
+};
+/**
+ * Convert Merkle proof to format expected by on-chain program
+ */
+export declare function proofToOnChainFormat(proof: MerkleProof): {
+    siblings: number[][];
+    path: boolean[];
+};
+/**
+ * Compute leaf index from path indices
+ */
+export declare function pathIndicesToLeafIndex(pathIndices: number[]): number;
+/**
+ * Compute path indices from leaf index
+ */
+export declare function leafIndexToPathIndices(leafIndex: number, depth?: number): number[];
+/**
+ * Create an empty/placeholder Merkle proof
+ * Used when constructing proofs before on-chain data is available
+ */
+export declare function createEmptyMerkleProof(): MerkleProof;
+/**
+ * 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 declare function parseMerkleProofResponse(response: {
+    root: string;
+    siblings: string[];
+    indices: number[];
+}): {
+    root: bigint;
+    pathElements: bigint[];
+    pathIndices: number[];
+};
+/**
+ * Validate Merkle proof structure
+ */
+export declare function validateMerkleProofStructure(proof: MerkleProof): boolean;

package/packages/sdk/dist/merkle.js

@@ -0,0 +1,141 @@
+/**
+ * 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 } 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);
+/**
+ * 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, pathIndices, leafIndex, root) {
+    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, pathIndices, leafIndex, root) {
+    return createMerkleProof(pathElements.map(bigintToBytes), pathIndices, leafIndex, bigintToBytes(root));
+}
+/**
+ * Convert Merkle proof to format expected by circom circuits
+ */
+export function proofToCircomFormat(proof) {
+    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) {
+    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) {
+    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, depth = TREE_DEPTH) {
+    const indices = [];
+    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() {
+    const pathElements = [];
+    const pathIndices = [];
+    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) {
+    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) {
+    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;
+}