@unionlabs/payments 0.1.0 → 0.2.0

package/src/cli/commands/redeem.ts

@@ -0,0 +1,277 @@
+import { readFileSync } from "node:fs";
+import { Command } from "commander";
+import type { Chain } from "viem";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { arbitrum, base, mainnet, optimism, polygon } from "viem/chains";
+import { AttestationClient } from "../../attestation.js";
+import { UnionPrivatePayments } from "../../legacy/client.js";
+import {
+  parseProofJson,
+  proofJsonToRedeemParams,
+  submitRedeem,
+} from "../../rpc.js";
+import type { LightClientData, ProofJSON } from "../../types.js";
+import { loadConfig } from "../config.js";
+import {
+  getExplorerUrl,
+  parseBeneficiaries,
+  parseClientIds,
+  validateAddress,
+  validateSecret,
+} from "../utils.js";
+
+interface ProofFileData {
+  proof: ProofJSON;
+  metadata: {
+    depositAddress: string;
+    beneficiary: string;
+    value: string;
+    nullifier: string;
+    lightClients: Array<{
+      clientId: number;
+      height: string;
+      stateRoot: string;
+    }>;
+  };
+}
+
+const CHAIN_MAP: Record<number, Chain> = {
+  1: mainnet,
+  8453: base,
+  42161: arbitrum,
+  10: optimism,
+  137: polygon,
+};
+
+export const redeemCommand = new Command("redeem")
+  .description(
+    "Submit redemption transaction (with existing proof or generate on the fly)",
+  )
+  .option("--proof <file>", "Path to proof JSON file (from prove command)")
+  .option(
+    "--secret <hex>",
+    "32-byte secret (0x-prefixed hex) - required if no --proof",
+  )
+  .option(
+    "--beneficiaries <addresses>",
+    "Comma-separated beneficiary addresses for address derivation",
+  )
+  .option(
+    "--beneficiary <address>",
+    "Address to redeem to - required if no --proof",
+  )
+  .option(
+    "--amount <value>",
+    "Amount to redeem in smallest units - required if no --proof",
+  )
+  .option(
+    "--client-ids <ids>",
+    "Comma-separated light client IDs for anonymity set - required if no --proof",
+  )
+  .option(
+    "--selected-client <id>",
+    "Which client ID to use for proof - required if no --proof",
+  )
+  .option(
+    "--private-key <key>",
+    "Private key to send transaction (or env SENDER_PRIVATE_KEY)",
+  )
+  .option(
+    "--config <path>",
+    "Path to config file",
+    "./private-payments.config.json",
+  )
+  .action(async (options) => {
+    try {
+      const config = loadConfig(options.config);
+      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");
+      }
+
+      if (!config.attestorUrl) {
+        throw new Error("attestorUrl required in config for redemption");
+      }
+
+      if (!config.attestorApiKey) {
+        throw new Error("attestorApiKey required in config for redemption");
+      }
+
+      let proofData: ProofFileData;
+
+      if (options.proof) {
+        // Mode 1: Load existing proof from file
+        const proofContent = readFileSync(options.proof, "utf-8");
+        proofData = JSON.parse(proofContent) as ProofFileData;
+        console.log("Loading proof from:", options.proof);
+      } else {
+        // Mode 2: Generate proof on the fly
+        if (
+          !options.secret ||
+          !options.beneficiary ||
+          !options.amount ||
+          !options.clientIds ||
+          !options.selectedClient
+        ) {
+          throw new Error(
+            "When not using --proof, you must provide: --secret, --beneficiary, --amount, --client-ids, --selected-client",
+          );
+        }
+
+        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.log("Generating proof...");
+        console.log("  Secret:", secret.slice(0, 10) + "...");
+        console.log("  Beneficiary:", beneficiary);
+        console.log("  Amount:", amount.toString());
+        console.log("  Client IDs:", clientIds.join(", "));
+        console.log("  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.log("Proof generated successfully!");
+
+        const proofJson = parseProofJson(result.proof.proofJson);
+        proofData = {
+          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 lightClients: LightClientData[] =
+        proofData.metadata.lightClients.map((lc) => ({
+          clientId: lc.clientId,
+          height: BigInt(lc.height),
+          stateRoot: lc.stateRoot as `0x${string}`,
+        }));
+
+      const nullifier = BigInt(proofData.metadata.nullifier);
+      const value = BigInt(proofData.metadata.value);
+      const beneficiary = proofData.metadata.beneficiary as `0x${string}`;
+      const depositAddress = proofData.metadata.depositAddress as `0x${string}`;
+
+      console.log("");
+      console.log("Redemption details:");
+      console.log("  Deposit Address:", depositAddress);
+      console.log("  Beneficiary:", beneficiary);
+      console.log("  Value:", value.toString());
+      console.log("  Nullifier:", proofData.metadata.nullifier);
+      console.log("  Light Clients:", lightClients.length);
+
+      console.log("");
+      console.log("Requesting attestation...");
+      const attestationClient = new AttestationClient(
+        config.attestorUrl,
+        config.attestorApiKey,
+      );
+
+      const attestation = await attestationClient.getAttestation(
+        depositAddress,
+        beneficiary,
+      );
+      console.log("  Attested Message:", attestation.attestedMessage);
+      console.log("  Signature:", attestation.signature.slice(0, 20) + "...");
+
+      const redeemParams = proofJsonToRedeemParams(proofData.proof, {
+        lightClients,
+        nullifier,
+        value,
+        beneficiary,
+        attestedMessage: attestation.attestedMessage,
+        signature: attestation.signature,
+      });
+
+      const chain = CHAIN_MAP[config.destinationChainId];
+      if (!chain) {
+        throw new Error(
+          `Unsupported destination chain ID: ${config.destinationChainId}`,
+        );
+      }
+
+      // Create wallet client from private key
+      const account = privateKeyToAccount(privateKey as `0x${string}`);
+      const walletClient = createWalletClient({
+        account,
+        chain,
+        transport: http(config.destinationRpcUrl),
+      });
+
+      console.log("");
+      console.log("Submitting redeem transaction...");
+      const txHash = await submitRedeem(
+        config.dstZAssetAddress,
+        redeemParams,
+        walletClient,
+      );
+
+      console.log("");
+      console.log("Transaction submitted!");
+      console.log("Hash:", txHash);
+      console.log(
+        "Explorer:",
+        getExplorerUrl(config.destinationChainId, txHash),
+      );
+    } catch (e) {
+      console.error("Error:", (e as Error).message);
+      process.exit(1);
+    }
+  });

package/src/cli/commands/update-client.ts

@@ -0,0 +1,96 @@
+import { Command } from "commander";
+import { type Chain, createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { updateLoopbackClient } from "../../rpc.js";
+import { getExplorerUrl } from "../utils.js";
+
+export const updateClientCommand = new Command("update-client")
+  .description("Update loopback light client to a specific block height")
+  .requiredOption("--rpc <url>", "RPC URL for the chain")
+  .requiredOption("--client-id <id>", "Light client ID to update")
+  .option(
+    "--height <height>",
+    "Block height to update to (default: latest)",
+    "latest",
+  )
+  .requiredOption("--ibc-handler <address>", "IBCHandler contract address")
+  .option(
+    "--private-key <key>",
+    "Private key to send transaction (or env SENDER_PRIVATE_KEY)",
+  )
+  .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 clientId = parseInt(options.clientId, 10);
+      if (isNaN(clientId)) {
+        throw new Error("Invalid client ID: must be a number");
+      }
+
+      const ibcHandlerAddress = options.ibcHandler as `0x${string}`;
+      if (
+        !ibcHandlerAddress.startsWith("0x") ||
+        ibcHandlerAddress.length !== 42
+      ) {
+        throw new Error("Invalid IBC handler address");
+      }
+
+      const height: bigint | "latest" =
+        options.height === "latest" ? "latest" : BigInt(options.height);
+
+      // Get chain ID from RPC first
+      const publicClient = createPublicClient({
+        transport: http(options.rpc),
+      });
+      const chainId = await publicClient.getChainId();
+
+      // Create wallet client from private key
+      const account = privateKeyToAccount(privateKey as `0x${string}`);
+      const walletClient = createWalletClient({
+        account,
+        chain: { id: chainId } as Chain,
+        transport: http(options.rpc),
+      });
+
+      console.log("Updating loopback light client...");
+      console.log("  RPC:", options.rpc);
+      console.log("  IBC Handler:", ibcHandlerAddress);
+      console.log("  Client ID:", clientId);
+      console.log(
+        "  Height:",
+        height === "latest" ? "latest" : height.toString(),
+      );
+      console.log("");
+
+      const result = await updateLoopbackClient(
+        options.rpc,
+        ibcHandlerAddress,
+        clientId,
+        height,
+        walletClient,
+      );
+
+      console.log("Light client updated successfully!");
+      console.log("  Chain ID:", result.chainId.toString());
+      console.log("  Block Number:", result.blockNumber.toString());
+      console.log("  State Root:", result.stateRoot);
+      console.log("  Transaction:", 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/config.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { Address } from "viem";
+
+export interface CliConfig {
+  proverUrl: string;
+  sourceRpcUrl: string;
+  destinationRpcUrl: string;
+  srcZAssetAddress: Address;
+  dstZAssetAddress: Address;
+  sourceChainId: number;
+  destinationChainId: number;
+  attestorUrl?: string;
+  attestorApiKey?: string;
+}
+
+const DEFAULT_CONFIG_PATH = "./private-payments.config.json";
+
+export function loadConfig(configPath?: string): CliConfig {
+  const path = configPath ?? DEFAULT_CONFIG_PATH;
+
+  if (!existsSync(path)) {
+    throw new Error(
+      `Config file not found: ${path}\nCreate a private-payments.config.json file or specify --config <path>`,
+    );
+  }
+
+  try {
+    const content = readFileSync(path, "utf-8");
+    const config = JSON.parse(content) as CliConfig;
+
+    // Validate required fields
+    const required: (keyof CliConfig)[] = [
+      "proverUrl",
+      "sourceRpcUrl",
+      "destinationRpcUrl",
+      "srcZAssetAddress",
+      "dstZAssetAddress",
+      "sourceChainId",
+      "destinationChainId",
+    ];
+
+    for (const field of required) {
+      if (config[field] === undefined) {
+        throw new Error(`Missing required field in config: ${field}`);
+      }
+    }
+
+    return config;
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      throw new Error(`Invalid JSON in config file: ${path}`);
+    }
+    throw e;
+  }
+}

package/src/cli/utils.ts

@@ -0,0 +1,136 @@
+import type { Address, Hex } from "viem";
+
+const ZERO_ADDRESS: Address = "0x0000000000000000000000000000000000000000";
+
+export function parseBeneficiaries(input: string | undefined): Address[] {
+  if (!input || input.trim() === "") {
+    return [];
+  }
+
+  const addresses = input
+    .split(",")
+    .map((s) => s.trim().toLowerCase() as Address);
+
+  if (addresses.length > 4) {
+    throw new Error("Maximum 4 beneficiaries allowed");
+  }
+
+  for (const addr of addresses) {
+    if (!isValidAddress(addr)) {
+      throw new Error(`Invalid address: ${addr}`);
+    }
+  }
+
+  return addresses;
+}
+
+export function padBeneficiaries(
+  beneficiaries: Address[],
+): [Address, Address, Address, Address] {
+  return [
+    beneficiaries[0] ?? ZERO_ADDRESS,
+    beneficiaries[1] ?? ZERO_ADDRESS,
+    beneficiaries[2] ?? ZERO_ADDRESS,
+    beneficiaries[3] ?? ZERO_ADDRESS,
+  ];
+}
+
+export function parseClientIds(input: string): number[] {
+  const ids = input.split(",").map((s) => {
+    const id = parseInt(s.trim(), 10);
+    if (isNaN(id) || id < 0) {
+      throw new Error(`Invalid client ID: ${s}`);
+    }
+    return id;
+  });
+
+  if (ids.length === 0) {
+    throw new Error("At least one client ID is required");
+  }
+
+  return ids;
+}
+
+export function validateSecret(secret: string): Hex {
+  if (!secret.startsWith("0x")) {
+    throw new Error("Secret must start with 0x");
+  }
+
+  if (secret.length !== 66) {
+    throw new Error("Secret must be 32 bytes (66 characters with 0x prefix)");
+  }
+
+  if (!/^0x[0-9a-fA-F]{64}$/.test(secret)) {
+    throw new Error("Secret must be a valid hex string");
+  }
+
+  return secret.toLowerCase() as Hex;
+}
+
+export function isValidAddress(address: string): address is Address {
+  return /^0x[0-9a-fA-F]{40}$/.test(address);
+}
+
+export function validateAddress(address: string, name: string): Address {
+  if (!isValidAddress(address)) {
+    throw new Error(`Invalid ${name} address: ${address}`);
+  }
+  return address.toLowerCase() as Address;
+}
+
+export function formatAmount(
+  amount: bigint,
+  decimals: number,
+  symbol?: string,
+): string {
+  const divisor = 10n ** BigInt(decimals);
+  const whole = amount / divisor;
+  const fraction = amount % divisor;
+  const fractionStr = fraction.toString().padStart(decimals, "0");
+
+  const trimmedFraction = fractionStr.replace(/0+$/, "");
+  const formatted = trimmedFraction
+    ? `${whole}.${trimmedFraction}`
+    : whole.toString();
+
+  return symbol ? `${formatted} ${symbol}` : formatted;
+}
+
+export function parseAmount(input: string, decimals: number): bigint {
+  const parts = input.split(".");
+  if (parts.length > 2) {
+    throw new Error(`Invalid amount: ${input}`);
+  }
+
+  const whole = parts[0] ?? "0";
+  let fraction = parts[1] ?? "";
+
+  if (fraction.length > decimals) {
+    fraction = fraction.slice(0, decimals);
+  } else {
+    fraction = fraction.padEnd(decimals, "0");
+  }
+
+  const wholeBigInt = BigInt(whole);
+  const fractionBigInt = BigInt(fraction);
+  const divisor = 10n ** BigInt(decimals);
+
+  return wholeBigInt * divisor + fractionBigInt;
+}
+
+export function getExplorerUrl(chainId: number, txHash: string): string {
+  const explorers: Record<number, string> = {
+    1: "https://etherscan.io",
+    8453: "https://basescan.org",
+    42161: "https://arbiscan.io",
+    10: "https://optimistic.etherscan.io",
+    137: "https://polygonscan.com",
+  };
+
+  const explorer = explorers[chainId];
+  if (explorer) {
+    return `${explorer}/tx/${txHash}`;
+  }
+
+  return txHash;
+}

package/src/cli.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { balanceCommand } from "./cli/commands/balance.js";
+import { depositCommand } from "./cli/commands/deposit.js";
+import { exportVerifierCommand } from "./cli/commands/export-verifier.js";
+import { generateCommand } from "./cli/commands/generate.js";
+import { historyCommand } from "./cli/commands/history.js";
+import { proveCommand } from "./cli/commands/prove.js";
+import { redeemCommand } from "./cli/commands/redeem.js";
+import { updateClientCommand } from "./cli/commands/update-client.js";
+
+const program = new Command();
+
+program
+  .name("payments")
+  .description(
+    "CLI for Union Private Payments - privacy-preserving transfers using ZK proofs",
+  )
+  .version("0.1.0");
+
+program.addCommand(generateCommand);
+program.addCommand(balanceCommand);
+program.addCommand(proveCommand);
+program.addCommand(redeemCommand);
+program.addCommand(updateClientCommand);
+program.addCommand(depositCommand);
+program.addCommand(historyCommand);
+program.addCommand(exportVerifierCommand);
+
+program.parse();

package/src/constants/ibc-core-registry.ts

@@ -0,0 +1,44 @@
+import { type Brand, Effect, flow, Option } from "effect";
+import * as Domain from "../Domain.js";
+import * as Error from "../Error.js";
+
+export type ZAssetAddress = `0x${string}` & Brand.Brand<"ZAssetAddress">;
+
+export const IBC_CORE_REGISTRY: {
+  [chainId: string]: Domain.IbcHandlerAddress;
+} = {
+  "8453": Domain.IbcHandlerAddress(
+    "0xee4ea8d358473f0fcebf0329feed95d56e8c04d7",
+  ),
+} as const;
+
+export function getIbcHandler(
+  chainId: bigint,
+): Option.Option<Domain.IbcHandlerAddress> {
+  return Option.fromNullable(IBC_CORE_REGISTRY[`${chainId}`]);
+}
+
+export const getIbcHandlerOrError = flow(
+  getIbcHandler,
+  Effect.mapError(
+    (cause) =>
+      new Error.SystemError({
+        module: "IbcCoreRegistry",
+        reason: "InvalidData",
+        method: "getIbcHandlerOrError",
+        cause,
+      }),
+  ),
+);
+
+export const getIbcHandlerOrThrow = flow(
+  getIbcHandler,
+  Option.getOrThrowWith(
+    () =>
+      new Error.SystemError({
+        module: "IbcCoreRegistry",
+        reason: "InvalidData",
+        method: "getIbcHandlerOrError",
+      }),
+  ),
+);

package/src/constants/services.ts

@@ -0,0 +1,4 @@
+export const DEFAULT_PROVER_URL = "https://prover.payments.union.build";
+
+export const DEFAULT_ATTESTOR_URL =
+  "https://attestor.payments.union.build/functions/v1/attest";

package/src/constants/z-asset-registry.ts

@@ -0,0 +1,47 @@
+import { Effect, flow, Option } from "effect";
+import type { Erc20Address } from "../Domain.js";
+import * as Domain from "../Domain.js";
+import * as Error from "../Error.js";
+
+export const Z_ASSET_REGISTRY: {
+  [chainId: string]: {
+    [assetAddress: Erc20Address]: Domain.ZAssetAddress;
+  };
+} = {
+  "8453": {
+    [Domain.Erc20Address("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")]:
+      Domain.ZAssetAddress("0xF0000101561619d8A61ABd045F47Af4f41Afe62D"),
+  },
+} as const;
+
+export function getZAsset(
+  chainId: bigint,
+  assetAddress: Erc20Address,
+): Option.Option<Domain.ZAssetAddress> {
+  return Option.fromNullable(Z_ASSET_REGISTRY[`${chainId}`]?.[assetAddress]);
+}
+
+export const getZAssetOrError = flow(
+  getZAsset,
+  Effect.mapError(
+    (cause) =>
+      new Error.SystemError({
+        method: "approveZAssetToSpendErc20",
+        module: "EvmWalletClient",
+        reason: "InvalidData",
+        cause,
+      }),
+  ),
+);
+
+export const getZAssetOrThrow = flow(
+  getZAsset,
+  Option.getOrThrowWith(
+    () =>
+      new Error.SystemError({
+        method: "approveZAssetToSpendErc20",
+        module: "EvmWalletClient",
+        reason: "InvalidData",
+      }),
+  ),
+);