@unionlabs/payments 0.1.0 → 0.2.0

package/src/attestation.ts

@@ -0,0 +1,69 @@
+import type { Address, Hex } from "viem";
+import type { AttestationRequest, AttestationResponse } from "./types.js";
+
+interface AttestationServiceResponse {
+  id: string;
+  hash: Hex;
+  signature: {
+    r: Hex;
+    s: Hex;
+    v: number;
+  };
+  signerAddress: Address;
+}
+
+/**
+ * Client for attestation service that signs poseidon(unspendable_address, beneficiary)
+ * @public
+ */
+export class AttestationClient {
+  private baseUrl: string;
+  private apiKey: string;
+
+  constructor(baseUrl: string, apiKey: string) {
+    this.baseUrl = baseUrl.replace(/\/$/, ""); // Remove trailing slash
+    this.apiKey = apiKey;
+  }
+
+  async getAttestation(
+    unspendableAddress: Address,
+    beneficiary: Address,
+  ): Promise<AttestationResponse> {
+    const request: AttestationRequest = {
+      unspendableAddress,
+      beneficiary,
+    };
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    headers["x-api-key"] = this.apiKey;
+
+    const response = await fetch(this.baseUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(request),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Attestation service error: ${response.status} ${errorText}`,
+      );
+    }
+
+    const data = (await response.json()) as AttestationServiceResponse;
+
+    // Combine r, s, v into 65-byte signature
+    const r = data.signature.r.slice(2);
+    const s = data.signature.s.slice(2);
+    const v = data.signature.v.toString(16).padStart(2, "0");
+    const signature = `0x${r}${s}${v}` as Hex;
+
+    return {
+      attestedMessage: data.hash,
+      signature,
+    };
+  }
+}

package/src/cli/commands/balance.ts

@@ -0,0 +1,88 @@
+import { Command } from "commander";
+import { UnionPrivatePayments } from "../../legacy/client.js";
+import { loadConfig } from "../config.js";
+import { formatAmount, parseBeneficiaries, validateSecret } from "../utils.js";
+
+export const balanceCommand = new Command("balance")
+  .description("Query balance via light client")
+  .requiredOption("--secret <hex>", "32-byte secret (0x-prefixed hex)")
+  .option(
+    "--beneficiaries <addresses>",
+    "Comma-separated beneficiary addresses",
+  )
+  .requiredOption("--client-id <id>", "Light client ID to use")
+  .option(
+    "--config <path>",
+    "Path to config file",
+    "./private-payments.config.json",
+  )
+  .action(async (options) => {
+    try {
+      const config = loadConfig(options.config);
+      const secret = validateSecret(options.secret);
+      const beneficiaries = parseBeneficiaries(options.beneficiaries);
+      const clientId = parseInt(options.clientId, 10);
+
+      if (isNaN(clientId) || clientId < 0) {
+        throw new Error("Invalid light client ID");
+      }
+
+      const client = new UnionPrivatePayments({
+        proverUrl: config.proverUrl,
+        sourceRpcUrl: config.sourceRpcUrl,
+        destinationRpcUrl: config.destinationRpcUrl,
+        srcZAssetAddress: config.srcZAssetAddress,
+        dstZAssetAddress: config.dstZAssetAddress,
+        sourceChainId: BigInt(config.sourceChainId),
+        destinationChainId: BigInt(config.destinationChainId),
+      });
+
+      const depositAddress = client.getDepositAddress(secret, beneficiaries);
+      const nullifier = client.getNullifier(secret);
+
+      console.log("Querying balance...");
+      console.log("Deposit Address:", depositAddress);
+      console.log("Light Client ID:", clientId);
+
+      const balance = await client.getBalance({
+        depositAddress,
+        nullifier,
+        clientId,
+      });
+      const tokenInfo = await client.getSrcZAssetInfo();
+
+      console.log("");
+
+      console.log(`Latest height: ${balance.latestHeight}`);
+      console.log(`Light client height: ${balance.lightClientHeight}`);
+      console.log(
+        `Light client lag: ${balance.latestHeight - balance.lightClientHeight}`,
+      );
+      console.log(`Balance:`);
+      console.log(
+        "  Pending:",
+        formatAmount(balance.pending, tokenInfo.decimals, tokenInfo.symbol),
+      );
+      console.log(
+        "  Confirmed:",
+        formatAmount(balance.confirmed, tokenInfo.decimals, tokenInfo.symbol),
+      );
+      console.log(
+        "  Redeemed:",
+        formatAmount(balance.redeemed, tokenInfo.decimals, tokenInfo.symbol),
+      );
+      console.log(
+        "  Available:",
+        formatAmount(balance.available, tokenInfo.decimals, tokenInfo.symbol),
+      );
+      console.log("");
+      console.log("Raw balance:");
+      console.log("  Pending:", balance.pending.toString());
+      console.log("  Confirmed:", balance.confirmed.toString());
+      console.log("  Redeemed:", balance.redeemed.toString());
+      console.log("  Available:", balance.available.toString());
+    } catch (e) {
+      console.error("Error:", (e as Error).message);
+      process.exit(1);
+    }
+  });

package/src/cli/commands/deposit.ts

@@ -0,0 +1,104 @@
+import { Command } from "commander";
+import { type Chain, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { computeUnspendableAddress } from "../../poseidon2.js";
+import { depositToZAsset } from "../../rpc.js";
+import { loadConfig } from "../config.js";
+import {
+  getExplorerUrl,
+  padBeneficiaries,
+  parseBeneficiaries,
+  validateSecret,
+} from "../utils.js";
+
+export const depositCommand = new Command("deposit")
+  .description("Wrap underlying tokens and deposit to ZAsset")
+  .requiredOption(
+    "--amount <amount>",
+    'Amount to deposit in smallest units (e.g., "50000000" for 50 USDC)',
+  )
+  .requiredOption(
+    "--secret <hex>",
+    "32-byte secret to derive deposit address (0x-prefixed hex)",
+  )
+  .option(
+    "--beneficiaries <addresses>",
+    "Comma-separated beneficiary addresses (max 4, empty = unbounded)",
+  )
+  .option(
+    "--private-key <key>",
+    "Private key to sign transaction (or env SENDER_PRIVATE_KEY)",
+  )
+  .option(
+    "--config <path>",
+    "Path to config file",
+    "./private-payments.config.json",
+  )
+  .action(async (options) => {
+    try {
+      const privateKey = options.privateKey ?? process.env.SENDER_PRIVATE_KEY;
+
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Use --private-key or set SENDER_PRIVATE_KEY env var",
+        );
+      }
+
+      if (!privateKey.startsWith("0x")) {
+        throw new Error("Private key must start with 0x");
+      }
+
+      const config = loadConfig(options.config);
+      const secret = validateSecret(options.secret);
+
+      const beneficiaries = parseBeneficiaries(options.beneficiaries);
+      const paddedBeneficiaries = padBeneficiaries(beneficiaries);
+
+      // Use source chain RPC and ZAsset from config
+      const rpcUrl = config.sourceRpcUrl;
+      const zAssetAddress = config.srcZAssetAddress;
+
+      // Parse amount as bigint (smallest units)
+      const amount = BigInt(options.amount);
+
+      // Derive deposit address from secret
+      const depositAddress = computeUnspendableAddress(
+        secret,
+        BigInt(config.destinationChainId),
+        paddedBeneficiaries,
+      );
+
+      // Create wallet client from private key
+      const account = privateKeyToAccount(privateKey as `0x${string}`);
+      const walletClient = createWalletClient({
+        account,
+        chain: { id: config.sourceChainId } as Chain,
+        transport: http(rpcUrl),
+      });
+
+      console.log("Depositing to ZAsset...");
+      console.log("  ZAsset:", zAssetAddress);
+      console.log("  Amount:", amount.toString());
+      console.log("  Deposit Address:", depositAddress);
+      console.log("");
+
+      const result = await depositToZAsset(
+        rpcUrl,
+        zAssetAddress,
+        depositAddress,
+        amount,
+        walletClient,
+      );
+
+      console.log("");
+      console.log("Deposit complete!");
+      console.log("  Tx Hash:", result.txHash);
+      console.log(
+        "  Explorer:",
+        getExplorerUrl(Number(result.chainId), result.txHash),
+      );
+    } catch (e) {
+      console.error("Error:", (e as Error).message);
+      process.exit(1);
+    }
+  });

package/src/cli/commands/export-verifier.ts

@@ -0,0 +1,28 @@
+import { writeFileSync } from "node:fs";
+import { Command } from "commander";
+import { ProverClient } from "../../legacy/prover.js";
+
+export const exportVerifierCommand = new Command("export-verifier")
+  .description("Export the Solidity verifier contract from the prover server")
+  .option("--prover-url <url>", "Prover gRPC-web URL", "http://localhost:8080")
+  .option("--output <file>", "Save verifier to file (default: stdout)")
+  .action(async (options) => {
+    try {
+      const proverClient = new ProverClient(options.proverUrl);
+
+      console.error("Exporting verifier contract...");
+      console.error("  Prover URL:", options.proverUrl);
+
+      const verifierContract = await proverClient.exportVerifier();
+
+      if (options.output) {
+        writeFileSync(options.output, verifierContract);
+        console.error(`Verifier saved to: ${options.output}`);
+      } else {
+        console.log(verifierContract);
+      }
+    } catch (e) {
+      console.error("Error:", (e as Error).message);
+      process.exit(1);
+    }
+  });

package/src/cli/commands/generate.ts

@@ -0,0 +1,86 @@
+import { Command } from "commander";
+import {
+  computeNullifier,
+  computeUnspendableAddress,
+  generatePaymentKey,
+} from "../../poseidon2.js";
+import { loadConfig } from "../config.js";
+import {
+  padBeneficiaries,
+  parseBeneficiaries,
+  validateSecret,
+} from "../utils.js";
+
+export const generateCommand = new Command("generate")
+  .description(
+    "Generate a new unspendable address (generates random secret by default)",
+  )
+  .option(
+    "--secret <hex>",
+    "Use existing 32-byte secret (0x-prefixed hex) instead of generating",
+  )
+  .option(
+    "--beneficiaries <addresses>",
+    "Comma-separated beneficiary addresses (max 4, empty = unbounded)",
+  )
+  .option(
+    "--config <path>",
+    "Path to config file",
+    "./private-payments.config.json",
+  )
+  .action(async (options) => {
+    try {
+      const config = loadConfig(options.config);
+      const secret = options.secret
+        ? validateSecret(options.secret)
+        : generatePaymentKey();
+      const isNewSecret = !options.secret;
+
+      const beneficiaries = parseBeneficiaries(options.beneficiaries);
+      const paddedBeneficiaries = padBeneficiaries(beneficiaries);
+
+      const depositAddress = computeUnspendableAddress(
+        secret,
+        BigInt(config.destinationChainId),
+        paddedBeneficiaries,
+      );
+
+      const nullifier = computeNullifier(
+        secret,
+        BigInt(config.destinationChainId),
+      );
+
+      const isUnbounded = beneficiaries.length === 0;
+
+      if (isNewSecret) {
+        console.log("Secret:", secret);
+        console.log("");
+        console.log(
+          "WARNING: Save this secret! It is required to redeem funds.",
+        );
+        console.log("");
+      }
+
+      console.log("Deposit Address:", depositAddress);
+      console.log(
+        "Nullifier:",
+        "0x" + nullifier.toString(16).padStart(64, "0"),
+      );
+      console.log(
+        "Mode:",
+        isUnbounded
+          ? "Unbounded (any beneficiary allowed)"
+          : `Bounded (${beneficiaries.length} beneficiaries)`,
+      );
+
+      if (!isUnbounded) {
+        console.log("Beneficiaries:");
+        for (const addr of beneficiaries) {
+          console.log(`  - ${addr}`);
+        }
+      }
+    } catch (e) {
+      console.error("Error:", (e as Error).message);
+      process.exit(1);
+    }
+  });

package/src/cli/commands/history.ts

@@ -0,0 +1,91 @@
+import { Command } from "commander";
+import { UnionPrivatePayments } from "../../legacy/client.js";
+import { RpcClient } from "../../rpc.js";
+import { loadConfig } from "../config.js";
+import { formatAmount, getExplorerUrl, validateSecret } from "../utils.js";
+
+export const historyCommand = new Command("history")
+  .description("List redemption transactions for a secret")
+  .requiredOption("--secret <hex>", "32-byte secret (0x-prefixed hex)")
+  .option("--from-block <number>", "Start block number (default: earliest)")
+  .option("--to-block <number>", "End block number (default: latest)")
+  .option(
+    "--config <path>",
+    "Path to config file",
+    "./private-payments.config.json",
+  )
+  .action(async (options) => {
+    try {
+      const config = loadConfig(options.config);
+      const secret = validateSecret(options.secret);
+
+      const client = new UnionPrivatePayments({
+        proverUrl: config.proverUrl,
+        sourceRpcUrl: config.sourceRpcUrl,
+        destinationRpcUrl: config.destinationRpcUrl,
+        srcZAssetAddress: config.srcZAssetAddress,
+        dstZAssetAddress: config.dstZAssetAddress,
+        sourceChainId: BigInt(config.sourceChainId),
+        destinationChainId: BigInt(config.destinationChainId),
+      });
+
+      const nullifier = client.getNullifier(secret);
+      const nullifierHex = "0x" + nullifier.toString(16).padStart(64, "0");
+
+      console.log("Querying redemption history...");
+      console.log("Nullifier:", nullifierHex);
+      console.log("");
+
+      const fromBlock = options.fromBlock
+        ? BigInt(options.fromBlock)
+        : undefined;
+      const toBlock = options.toBlock ? BigInt(options.toBlock) : undefined;
+
+      const dstRpcClient = new RpcClient(config.destinationRpcUrl);
+      const history = await dstRpcClient.getRedemptionHistory(
+        config.dstZAssetAddress,
+        nullifier,
+        fromBlock,
+        toBlock,
+      );
+
+      if (history.length === 0) {
+        console.log("No redemptions found for this secret.");
+        return;
+      }
+
+      // Get token info for formatting
+      const tokenInfo = await client.getDstZAssetInfo();
+
+      console.log(
+        `Found ${history.length} redemption${history.length > 1 ? "s" : ""}:`,
+      );
+      console.log("");
+
+      for (let i = 0; i < history.length; i++) {
+        const entry = history[i]!;
+        console.log(`#${i + 1}  Block: ${entry.blockNumber}`);
+        console.log(`    Tx: ${entry.txHash}`);
+        console.log(
+          `    Amount: ${formatAmount(entry.redeemAmount, tokenInfo.decimals, tokenInfo.symbol)}`,
+        );
+        console.log(`    Beneficiary: ${entry.beneficiary}`);
+        console.log(
+          `    Explorer: ${getExplorerUrl(config.destinationChainId, entry.txHash)}`,
+        );
+        console.log("");
+      }
+
+      // Show total redeemed
+      const totalRedeemed = history.reduce(
+        (sum, h) => sum + h.redeemAmount,
+        0n,
+      );
+      console.log(
+        `Total redeemed: ${formatAmount(totalRedeemed, tokenInfo.decimals, tokenInfo.symbol)}`,
+      );
+    } catch (e) {
+      console.error("Error:", (e as Error).message);
+      process.exit(1);
+    }
+  });

package/src/cli/commands/prove.ts

@@ -0,0 +1,133 @@
+import { writeFileSync } from "node:fs";
+import { Command } from "commander";
+import { UnionPrivatePayments } from "../../legacy/client.js";
+import { parseProofJson } from "../../rpc.js";
+import { loadConfig } from "../config.js";
+import {
+  parseBeneficiaries,
+  parseClientIds,
+  validateAddress,
+  validateSecret,
+} from "../utils.js";
+
+export const proveCommand = new Command("prove")
+  .description("Generate ZK proof for redemption")
+  .requiredOption("--secret <hex>", "32-byte secret (0x-prefixed hex)")
+  .option(
+    "--beneficiaries <addresses>",
+    "Comma-separated beneficiary addresses for address derivation",
+  )
+  .requiredOption("--beneficiary <address>", "Address to redeem to")
+  .requiredOption(
+    "--amount <value>",
+    'Amount to redeem in smallest units (e.g., "2000000" for 2 USDC)',
+  )
+  .requiredOption(
+    "--client-ids <ids>",
+    "Comma-separated light client IDs for anonymity set",
+  )
+  .requiredOption("--selected-client <id>", "Which client ID to use for proof")
+  .option("--output <file>", "Save proof JSON to file (default: stdout)")
+  .option(
+    "--config <path>",
+    "Path to config file",
+    "./private-payments.config.json",
+  )
+  .action(async (options) => {
+    try {
+      const config = loadConfig(options.config);
+      const secret = validateSecret(options.secret);
+      const beneficiaries = parseBeneficiaries(options.beneficiaries);
+      const beneficiary = validateAddress(options.beneficiary, "beneficiary");
+      const clientIds = parseClientIds(options.clientIds);
+      const selectedClientId = parseInt(options.selectedClient, 10);
+
+      if (isNaN(selectedClientId)) {
+        throw new Error("Invalid selected client ID");
+      }
+
+      if (!clientIds.includes(selectedClientId)) {
+        throw new Error(
+          `Selected client ${selectedClientId} not in client IDs: ${clientIds.join(", ")}`,
+        );
+      }
+
+      const client = new UnionPrivatePayments({
+        proverUrl: config.proverUrl,
+        sourceRpcUrl: config.sourceRpcUrl,
+        destinationRpcUrl: config.destinationRpcUrl,
+        srcZAssetAddress: config.srcZAssetAddress,
+        dstZAssetAddress: config.dstZAssetAddress,
+        sourceChainId: BigInt(config.sourceChainId),
+        destinationChainId: BigInt(config.destinationChainId),
+      });
+
+      const amount = BigInt(options.amount);
+
+      console.error("Generating proof...");
+      console.error("  Secret:", secret.slice(0, 10) + "...");
+      console.error("  Beneficiary:", beneficiary);
+      console.error("  Amount:", amount.toString());
+      console.error("  Client IDs:", clientIds.join(", "));
+      console.error("  Selected Client:", selectedClientId);
+
+      const result = await client.generateProof(
+        secret,
+        beneficiaries,
+        beneficiary,
+        amount,
+        clientIds,
+        selectedClientId,
+      );
+
+      if (
+        !result.proof.success ||
+        !result.proof.proofJson ||
+        !result.metadata
+      ) {
+        throw new Error(result.proof.error ?? "Proof generation failed");
+      }
+
+      console.error("Proof generated successfully!");
+
+      const proofJson = parseProofJson(result.proof.proofJson);
+      const output = {
+        proof: proofJson,
+        metadata: {
+          depositAddress: result.metadata.depositAddress,
+          beneficiary: result.metadata.beneficiary,
+          value: result.metadata.value.toString(),
+          nullifier:
+            "0x" + result.metadata.nullifier.toString(16).padStart(64, "0"),
+          lightClients: result.metadata.lightClients.map((lc) => ({
+            clientId: lc.clientId,
+            height: lc.height.toString(),
+            stateRoot: lc.stateRoot,
+          })),
+        },
+      };
+
+      const jsonOutput = JSON.stringify(output, null, 2);
+
+      if (options.output) {
+        writeFileSync(options.output, jsonOutput);
+        console.error(`Proof saved to: ${options.output}`);
+      } else {
+        console.log(jsonOutput);
+      }
+
+      console.error("");
+      console.error("Metadata:");
+      console.error("  Deposit Address:", result.metadata.depositAddress);
+      console.error("  Beneficiary:", result.metadata.beneficiary);
+      console.error("  Value:", result.metadata.value.toString());
+      console.error(
+        "  Nullifier:",
+        "0x" + result.metadata.nullifier.toString(16).padStart(64, "0"),
+      );
+      console.error("  Light Clients:", result.metadata.lightClients.length);
+    } catch (e) {
+      console.error("Error:", (e as Error).message);
+      process.exit(1);
+    }
+  });