@umbra-privacy/sdk 1.0.0 → 2.0.0

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 };

package/dist/chunk-4RHXVBNI.js

@@ -0,0 +1,203 @@
+import { __name } from './chunk-7QVYU63E.js';
+import { address } from '@solana/kit';
+
+var ENDPOINTS = {
+  /** Fetches relayer address, supported mints, and active stealth pool indices. */
+  RELAYER_INFO: `/v1/relayer/info`,
+  /** Submits a claim request (relayer builds transactions from crypto data). */
+  CLAIM_SUBMIT: `/v1/claims`,
+  /** Polls claim status by request ID. `{id}` is replaced at call time. */
+  CLAIM_STATUS: `/v1/claims/{id}`
+};
+var RelayerError = class _RelayerError extends Error {
+  static {
+    __name(this, "RelayerError");
+  }
+  /** The relayer operation that failed (e.g. `"getRelayerAddress"`, `"claimSubmit"`). */
+  operation;
+  /** HTTP status code if the server responded, `undefined` for transport errors. */
+  statusCode;
+  /** Machine-readable error code from the API error body. */
+  errorCode;
+  constructor(operation, message, statusCode, errorCode, cause) {
+    super(`Relayer operation '${operation}' failed: ${message}`);
+    this.name = "RelayerError";
+    this.operation = operation;
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.cause = cause;
+    if (Error.captureStackTrace !== void 0) {
+      Error.captureStackTrace(this, _RelayerError);
+    }
+  }
+};
+async function makeRequest(endpoint, fetchImpl, options) {
+  const { method = "GET", body, operation } = options;
+  try {
+    const requestInit = {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      }
+    };
+    if (body !== void 0) {
+      requestInit.body = JSON.stringify(body);
+    }
+    const response = await fetchImpl(endpoint, requestInit);
+    const data = await response.json();
+    if (!response.ok) {
+      const errorData = data;
+      const message = errorData.error?.message ?? errorData.message ?? `HTTP ${String(response.status)}`;
+      const code = errorData.error?.code ?? errorData.error_code;
+      throw new RelayerError(operation, message, response.status, code);
+    }
+    return data;
+  } catch (error) {
+    if (error instanceof RelayerError) {
+      throw error;
+    }
+    throw new RelayerError(
+      operation,
+      error instanceof Error ? error.message : "Unknown error",
+      void 0,
+      void 0,
+      error instanceof Error ? error : void 0
+    );
+  }
+}
+__name(makeRequest, "makeRequest");
+function convertClaimStatusResponse(api) {
+  return {
+    requestId: api.request_id,
+    status: api.status,
+    variant: api.variant,
+    resolvedVariant: api.resolved_variant,
+    txSignature: api.tx_signature,
+    callbackSignature: api.callback_signature,
+    computationAccount: api.computation_account,
+    failureReason: api.failure_reason,
+    createdAt: api.created_at,
+    updatedAt: api.updated_at
+  };
+}
+__name(convertClaimStatusResponse, "convertClaimStatusResponse");
+function getUmbraRelayer(args, deps) {
+  const { apiEndpoint } = args;
+  const fetchImpl = deps?.fetch ?? globalThis.fetch;
+  if (apiEndpoint === "") {
+    throw new RelayerError("initialization", "apiEndpoint must be a non-empty string");
+  }
+  const normalizedEndpoint = apiEndpoint.replace(/\/$/, "");
+  let cachedAddress = null;
+  let cachedInfo = null;
+  async function fetchInfo() {
+    if (cachedInfo !== null) {
+      return cachedInfo;
+    }
+    const response = await makeRequest(
+      `${normalizedEndpoint}${ENDPOINTS.RELAYER_INFO}`,
+      fetchImpl,
+      { operation: "getRelayerInfo" }
+    );
+    cachedInfo = response;
+    cachedAddress = address(response.address);
+    return response;
+  }
+  __name(fetchInfo, "fetchInfo");
+  return {
+    apiEndpoint: normalizedEndpoint,
+    async getFeePayer() {
+      if (cachedAddress !== null) {
+        return cachedAddress;
+      }
+      const info = await fetchInfo();
+      return address(info.address);
+    },
+    async getRelayerAddress() {
+      if (cachedAddress !== null) {
+        return cachedAddress;
+      }
+      const info = await fetchInfo();
+      return address(info.address);
+    },
+    async getSupportedMints() {
+      const info = await fetchInfo();
+      return {
+        relayer: info.address,
+        mints: info.supported_mints,
+        count: BigInt(info.supported_mints.length)
+      };
+    },
+    async submitClaim(request) {
+      const response = await makeRequest(
+        `${normalizedEndpoint}${ENDPOINTS.CLAIM_SUBMIT}`,
+        fetchImpl,
+        { method: "POST", body: request, operation: "claimSubmit" }
+      );
+      return {
+        requestId: response.request_id,
+        status: response.status
+      };
+    },
+    async pollClaimStatus(requestId) {
+      const url = `${normalizedEndpoint}${ENDPOINTS.CLAIM_STATUS.replace("{id}", requestId)}`;
+      const response = await makeRequest(url, fetchImpl, {
+        operation: "claimStatus"
+      });
+      return convertClaimStatusResponse(response);
+    }
+  };
+}
+__name(getUmbraRelayer, "getUmbraRelayer");
+var TERMINAL_CLAIM_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "timed_out"
+]);
+async function pollClaimUntilTerminal(pollClaimStatus, requestId, options) {
+  const pollingIntervalMs = options?.pollingIntervalMs ?? 3e3;
+  const timeoutMs = options?.timeoutMs ?? 12e4;
+  const onProgress = options?.onProgress;
+  const startTime = Date.now();
+  while (true) {
+    const status = await pollClaimStatus(requestId);
+    if (onProgress !== void 0) {
+      onProgress({
+        requestId: status.requestId,
+        status: status.status,
+        resolvedVariant: status.resolvedVariant,
+        txSignature: status.txSignature,
+        callbackSignature: status.callbackSignature,
+        failureReason: status.failureReason
+      });
+    }
+    if (TERMINAL_CLAIM_STATUSES.has(status.status)) {
+      const result = {
+        requestId: status.requestId,
+        status: status.status,
+        txSignature: status.txSignature,
+        callbackSignature: status.callbackSignature,
+        resolvedVariant: status.resolvedVariant,
+        failureReason: status.failureReason
+      };
+      return result;
+    }
+    if (Date.now() - startTime >= timeoutMs) {
+      const timedOutResult = {
+        requestId: status.requestId,
+        status: "timed_out",
+        failureReason: `Polling timed out after ${String(timeoutMs)}ms (last status: ${String(status.status)})`
+      };
+      return timedOutResult;
+    }
+    await new Promise((resolve) => {
+      setTimeout(resolve, pollingIntervalMs);
+    });
+  }
+}
+__name(pollClaimUntilTerminal, "pollClaimUntilTerminal");
+
+export { RelayerError, getUmbraRelayer, pollClaimUntilTerminal };
+//# sourceMappingURL=chunk-4RHXVBNI.js.map
+//# sourceMappingURL=chunk-4RHXVBNI.js.map

package/dist/chunk-4RHXVBNI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/umbra/relayer.ts"],"names":[],"mappings":"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","file":"chunk-4RHXVBNI.js","sourcesContent":["/**\n * Relayer Module (V2 API).\n *\n * @remarks\n * This module provides the `getUmbraRelayer` factory for creating relayer instances\n * that interact with the Umbra relayer's V2 API. The relayer builds, signs, and\n * submits claim transactions on behalf of users.\n *\n * **What is the Relayer?**\n * The Umbra relayer is a semi-trusted intermediary that submits privacy-preserving\n * transactions on behalf of users. It receives cryptographic data (ZK proofs,\n * nullifiers, linker encryptions) and builds all Solana transactions server-side.\n *\n * **Trust Model (Semi-Trusted):**\n * The relayer is SEMI-TRUSTED. It can observe transaction contents (amounts,\n * mints, timing) because it must broadcast them. However, it CANNOT:\n * - Steal funds — ZK proofs and nullifier commitments prevent double-spending\n * - Forge signatures — Transactions use cryptographic commitments verified on-chain\n * - Link sender to recipient — Merkle commitments and ZK proofs sever that link\n *\n * **API Endpoints Used:**\n * - `GET /v1/relayer/info` — Get relayer address, supported mints, active pools\n * - `POST /v1/claims` — Submit a claim request (relayer builds transactions)\n * - `GET /v1/claims/{id}` — Poll claim status\n *\n * @packageDocumentation\n */\n\nimport { address, type Address } from \"@solana/kit\";\nimport type { U32 } from \"../types\";\nimport type {\n  IUmbraRelayer,\n  GetUmbraRelayerArgs,\n  GetUmbraRelayerDeps,\n  SupportedMintsResponse,\n  ClaimRequest,\n  ClaimSubmitResponse,\n  ClaimStatusResponse,\n  ClaimStatus,\n  ClaimBatchResult,\n} from \"./interfaces\";\n\n// ============================================================================\n// Constants\n// ============================================================================\n\n/**\n * Canonical endpoint paths for all relayer API operations.\n * @internal\n */\nconst ENDPOINTS = {\n  /** Fetches relayer address, supported mints, and active stealth pool indices. */\n  RELAYER_INFO: `/v1/relayer/info`,\n  /** Submits a claim request (relayer builds transactions from crypto data). */\n  CLAIM_SUBMIT: `/v1/claims`,\n  /** Polls claim status by request ID. `{id}` is replaced at call time. */\n  CLAIM_STATUS: `/v1/claims/{id}`,\n} as const;\n\n// ============================================================================\n// Error Class\n// ============================================================================\n\n/**\n * Error class for relayer-related failures.\n *\n * @remarks\n * Thrown when relayer API calls fail due to network issues, invalid responses,\n * transaction rejections, or server errors. Provides structured fields for\n * programmatic error handling.\n *\n * @public\n */\nexport class RelayerError extends Error {\n  /** The relayer operation that failed (e.g. `\"getRelayerAddress\"`, `\"claimSubmit\"`). */\n  public readonly operation: string;\n  /** HTTP status code if the server responded, `undefined` for transport errors. */\n  public readonly statusCode: number | undefined;\n  /** Machine-readable error code from the API error body. */\n  public readonly errorCode: string | undefined;\n\n  constructor(\n    operation: string,\n    message: string,\n    statusCode?: number,\n    errorCode?: string,\n    cause?: Error,\n  ) {\n    super(`Relayer operation '${operation}' failed: ${message}`);\n    this.name = \"RelayerError\";\n    this.operation = operation;\n    this.statusCode = statusCode;\n    this.errorCode = errorCode;\n    this.cause = cause;\n\n    if (Error.captureStackTrace !== undefined) {\n      Error.captureStackTrace(this, RelayerError);\n    }\n  }\n}\n\n// ============================================================================\n// Internal Types (API Response Shapes)\n// ============================================================================\n\n/** @internal */\ninterface ApiErrorResponse {\n  error?: {\n    code: string;\n    message: string;\n  };\n  success?: false;\n  error_code?: string;\n  message?: string;\n}\n\n/** Shape of `GET /v1/relayer/info` response. @internal */\ninterface ApiRelayerInfoResponse {\n  address: string;\n  supported_mints: string[];\n  active_stealth_pool_indices: string[];\n}\n\n/** Shape of `POST /v1/claims` response. @internal */\ninterface ApiClaimSubmitResponse {\n  request_id: string;\n  status: \"received\";\n}\n\n/** Shape of `GET /v1/claims/{id}` response. @internal */\ninterface ApiClaimStatusResponse {\n  request_id: string;\n  status: string;\n  variant: string;\n  resolved_variant?: string;\n  tx_signature?: string;\n  callback_signature?: string;\n  computation_account?: string;\n  failure_reason?: string | null;\n  created_at: string;\n  updated_at: string;\n}\n\n// ============================================================================\n// Internal Helpers\n// ============================================================================\n\n/**\n * Generic HTTP request helper with structured error handling.\n * @internal\n */\nasync function makeRequest<T>(\n  endpoint: string,\n  fetchImpl: typeof globalThis.fetch,\n  options: {\n    method?: \"GET\" | \"POST\";\n    body?: unknown;\n    operation: string;\n  },\n): Promise<T> {\n  const { method = \"GET\", body, operation } = options;\n\n  try {\n    const requestInit: RequestInit = {\n      method,\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Accept: \"application/json\",\n      },\n    };\n    if (body !== undefined) {\n      requestInit.body = JSON.stringify(body);\n    }\n    const response = await fetchImpl(endpoint, requestInit);\n\n    const data = (await response.json()) as T | ApiErrorResponse;\n\n    if (!response.ok) {\n      const errorData = data as ApiErrorResponse;\n      const message =\n        errorData.error?.message ?? errorData.message ?? `HTTP ${String(response.status)}`;\n      const code = errorData.error?.code ?? errorData.error_code;\n      throw new RelayerError(operation, message, response.status, code);\n    }\n\n    return data as T;\n  } catch (error) {\n    if (error instanceof RelayerError) {\n      throw error;\n    }\n    throw new RelayerError(\n      operation,\n      error instanceof Error ? error.message : \"Unknown error\",\n      undefined,\n      undefined,\n      error instanceof Error ? error : undefined,\n    );\n  }\n}\n\n/** Converts wire-format claim status response to SDK type. @internal */\nfunction convertClaimStatusResponse(api: ApiClaimStatusResponse): ClaimStatusResponse {\n  return {\n    requestId: api.request_id,\n    status: api.status as ClaimStatus,\n    variant: api.variant as ClaimStatusResponse[\"variant\"],\n    resolvedVariant: api.resolved_variant,\n    txSignature: api.tx_signature,\n    callbackSignature: api.callback_signature,\n    computationAccount: api.computation_account,\n    failureReason: api.failure_reason,\n    createdAt: api.created_at,\n    updatedAt: api.updated_at,\n  };\n}\n\n// ============================================================================\n// Core Relayer Factory\n// ============================================================================\n\n/**\n * Creates an Umbra relayer instance.\n *\n * @remarks\n * The returned `IUmbraRelayer` object provides all methods needed by claim\n * services: relayer info, claim submission, and status polling. Pass it\n * directly as the `relayer` dependency to any claim function.\n *\n * **Address caching:**\n * `getRelayerAddress()` and `getFeePayer()` cache the result after the first\n * HTTP call. The cache is per-instance.\n *\n * @param args - Required arguments\n * @param args.apiEndpoint - The base URL of the relayer API\n * @param deps - Optional dependencies for testing\n * @param deps.fetch - Custom fetch implementation; defaults to `globalThis.fetch`\n * @returns An {@link IUmbraRelayer} instance\n *\n * @example\n * ```typescript\n * const relayer = getUmbraRelayer({ apiEndpoint: \"https://relayer.umbra.finance\" });\n *\n * // Use directly with claim functions\n * const claim = getSelfClaimableUtxoToEncryptedBalanceClaimerFunction(\n *   { client },\n *   { zkProver, relayer },\n * );\n * ```\n *\n * @public\n */\nexport function getUmbraRelayer(\n  args: GetUmbraRelayerArgs,\n  deps?: GetUmbraRelayerDeps,\n): IUmbraRelayer {\n  const { apiEndpoint } = args;\n  const fetchImpl = deps?.fetch ?? globalThis.fetch;\n\n  if (apiEndpoint === \"\") {\n    throw new RelayerError(\"initialization\", \"apiEndpoint must be a non-empty string\");\n  }\n\n  const normalizedEndpoint = apiEndpoint.replace(/\\/$/, \"\");\n\n  // Shared cache for relayer address (used by both getFeePayer and getRelayerAddress)\n  let cachedAddress: Address | null = null;\n  let cachedInfo: ApiRelayerInfoResponse | null = null;\n\n  async function fetchInfo(): Promise<ApiRelayerInfoResponse> {\n    if (cachedInfo !== null) {\n      return cachedInfo;\n    }\n    const response = await makeRequest<ApiRelayerInfoResponse>(\n      `${normalizedEndpoint}${ENDPOINTS.RELAYER_INFO}`,\n      fetchImpl,\n      { operation: \"getRelayerInfo\" },\n    );\n    cachedInfo = response;\n    cachedAddress = address(response.address);\n    return response;\n  }\n\n  return {\n    apiEndpoint: normalizedEndpoint,\n\n    async getFeePayer(): Promise<Address> {\n      if (cachedAddress !== null) {\n        return cachedAddress;\n      }\n      const info = await fetchInfo();\n      return address(info.address);\n    },\n\n    async getRelayerAddress(): Promise<Address> {\n      if (cachedAddress !== null) {\n        return cachedAddress;\n      }\n      const info = await fetchInfo();\n      return address(info.address);\n    },\n\n    async getSupportedMints(): Promise<SupportedMintsResponse> {\n      const info = await fetchInfo();\n      return {\n        relayer: info.address,\n        mints: info.supported_mints,\n        count: BigInt(info.supported_mints.length) as U32,\n      };\n    },\n\n    async submitClaim(request: ClaimRequest): Promise<ClaimSubmitResponse> {\n      const response = await makeRequest<ApiClaimSubmitResponse>(\n        `${normalizedEndpoint}${ENDPOINTS.CLAIM_SUBMIT}`,\n        fetchImpl,\n        { method: \"POST\", body: request, operation: \"claimSubmit\" },\n      );\n      return {\n        requestId: response.request_id,\n        status: response.status,\n      };\n    },\n\n    async pollClaimStatus(requestId: string): Promise<ClaimStatusResponse> {\n      const url = `${normalizedEndpoint}${ENDPOINTS.CLAIM_STATUS.replace(\"{id}\", requestId)}`;\n      const response = await makeRequest<ApiClaimStatusResponse>(url, fetchImpl, {\n        operation: \"claimStatus\",\n      });\n      return convertClaimStatusResponse(response);\n    },\n  };\n}\n\n// ============================================================================\n// Claim Polling Utility\n// ============================================================================\n\n/**\n * Terminal claim statuses. Polling stops when the status matches one of these.\n * @internal\n */\nconst TERMINAL_CLAIM_STATUSES: ReadonlySet<ClaimStatus> = new Set([\n  \"completed\",\n  \"failed\",\n  \"timed_out\",\n]);\n\n/**\n * Polls a claim request until it reaches a terminal status or times out.\n *\n * @remarks\n * Terminal statuses are: `completed`, `failed`, `timed_out`.\n * The `onProgress` callback is invoked after each poll with the latest status.\n *\n * @param pollClaimStatus - Function to poll claim status\n * @param requestId - The claim request ID to poll\n * @param options - Polling configuration\n * @returns The final {@link ClaimBatchResult}\n *\n * @public\n */\nexport async function pollClaimUntilTerminal(\n  pollClaimStatus: (requestId: string) => Promise<ClaimStatusResponse>,\n  requestId: string,\n  options?: {\n    pollingIntervalMs?: number;\n    timeoutMs?: number;\n    onProgress?: (event: {\n      readonly requestId: string;\n      readonly status: ClaimStatus;\n      readonly resolvedVariant?: string;\n      readonly txSignature?: string;\n      readonly callbackSignature?: string;\n      readonly failureReason?: string | null;\n    }) => void;\n  },\n): Promise<ClaimBatchResult> {\n  const pollingIntervalMs: number = options?.pollingIntervalMs ?? 3000;\n  const timeoutMs: number = options?.timeoutMs ?? 120_000;\n  const onProgress = options?.onProgress;\n\n  const startTime: number = Date.now();\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- polling loop\n  while (true) {\n    const status: ClaimStatusResponse = await pollClaimStatus(requestId);\n\n    if (onProgress !== undefined) {\n      onProgress({\n        requestId: status.requestId,\n        status: status.status,\n        resolvedVariant: status.resolvedVariant,\n        txSignature: status.txSignature,\n        callbackSignature: status.callbackSignature,\n        failureReason: status.failureReason,\n      });\n    }\n\n    if (TERMINAL_CLAIM_STATUSES.has(status.status)) {\n      const result: ClaimBatchResult = {\n        requestId: status.requestId,\n        status: status.status,\n        txSignature: status.txSignature,\n        callbackSignature: status.callbackSignature,\n        resolvedVariant: status.resolvedVariant,\n        failureReason: status.failureReason,\n      };\n      return result;\n    }\n\n    if (Date.now() - startTime >= timeoutMs) {\n      const timedOutResult: ClaimBatchResult = {\n        requestId: status.requestId,\n        status: \"timed_out\" as ClaimStatus,\n        failureReason: `Polling timed out after ${String(timeoutMs)}ms (last status: ${String(status.status)})`,\n      };\n      return timedOutResult;\n    }\n\n    await new Promise<void>((resolve) => {\n      setTimeout(resolve, pollingIntervalMs);\n    });\n  }\n}\n"]}