@unionlabs/payments 0.1.0 → 0.2.0

package/src/types.ts

@@ -0,0 +1,281 @@
+import type { Address, Hash, Hex } from "viem";
+
+/**
+ * Configuration for the UnionPrivatePayments client.
+ * @public
+ */
+export interface UnionPrivatePaymentsConfig {
+  /** URL of the ZK prover server (gRPC-web endpoint) */
+  proverUrl: string;
+  /** RPC URL for the source chain where deposits are made */
+  sourceRpcUrl: string;
+  /** RPC URL for the destination chain where redemptions occur */
+  destinationRpcUrl: string;
+  /** ZAsset contract address on the source chain */
+  srcZAssetAddress: Address;
+  /** ZAsset contract address on the destination chain */
+  dstZAssetAddress: Address;
+  /** Chain ID of the source chain */
+  sourceChainId: bigint;
+  /** Chain ID of the destination chain */
+  destinationChainId: bigint;
+  /** Optional attestation service URL for redemptions */
+  attestorUrl?: string;
+  /** Optional attestation service API key */
+  attestorApiKey?: string;
+}
+
+/**
+ * @public
+ */
+export interface AttestationRequest {
+  unspendableAddress: Address;
+  beneficiary: Address;
+}
+
+/**
+ * @public
+ */
+export interface AttestationResponse {
+  /** Poseidon hash of (unspendableAddress, beneficiary) */
+  attestedMessage: Hex;
+  signature: Hex;
+}
+
+/**
+ * @public
+ */
+export interface BalanceInfo {
+  /** Pending deposits not yet visible to light client */
+  pending: bigint;
+  /** Deposits visible to the light client (provable balance) */
+  confirmed: bigint;
+  /** Already redeemed via nullifier */
+  redeemed: bigint;
+  /** Available for redemption (confirmed - redeemed) */
+  available: bigint;
+  /** Light client height used for confirmed balance */
+  lightClientHeight: bigint;
+  /** Latest height for the pending balance */
+  latestHeight: bigint;
+}
+
+/**
+ * Light client state data used for proof generation and balance queries.
+ * Light clients provide verified blockchain state roots via IBC.
+ * @public
+ */
+export interface LightClientData {
+  /** Unique identifier for this light client */
+  clientId: number;
+  /** Block height at which this state was captured */
+  height: bigint;
+  /** Ethereum state root at this height */
+  stateRoot: Hash;
+}
+
+/**
+ * @public
+ */
+export interface MptProofData {
+  accountProof: Hex[];
+  storageProof: Hex[];
+  storageValue: Hex;
+  storageRoot: Hash;
+}
+
+/**
+ * @public
+ */
+export interface WitnessData {
+  secret: Hex;
+  dstChainId: bigint;
+  beneficiaries: [Address, Address, Address, Address];
+  beneficiary: Address;
+  redeemAmount: bigint;
+  alreadyRedeemed: bigint;
+  lightClients: LightClientData[];
+  selectedClientIndex: number;
+  mptProof: MptProofData;
+  srcZAssetAddress: Address;
+  mappingSlot: Hex;
+}
+
+/**
+ * Result from the prover server after proof generation.
+ * @public
+ */
+export interface ProofResult {
+  /** Whether proof generation succeeded */
+  success: boolean;
+  /** Serialized proof data (only present on success) */
+  proofJson?: Uint8Array;
+  /** Error message (only present on failure) */
+  error?: string;
+  /** Timestamp when the proof was created */
+  createdAt?: Date;
+}
+
+/**
+ * Client-side metadata derived from witness inputs (NOT from the prover)
+ * @public
+ */
+export interface ProofMetadata {
+  depositAddress: Address;
+  beneficiary: Address;
+  value: bigint;
+  lightClients: LightClientData[];
+  nullifier: bigint;
+}
+
+/**
+ * Combined result from generateProof() containing the proof and associated metadata.
+ * @public
+ */
+export interface GenerateProofResult {
+  /** Proof generation result from the prover */
+  proof: ProofResult;
+  /** Metadata for constructing the redeem transaction (present on success) */
+  metadata?: ProofMetadata;
+}
+
+/**
+ * @public
+ */
+export interface RedeemResult {
+  txHash: Hash;
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * @public
+ */
+export interface RedeemTransaction {
+  txHash: Hash;
+  blockNumber: bigint;
+  timestamp: bigint;
+  nullifier: bigint;
+  value: bigint;
+  beneficiary: Address;
+}
+
+/**
+ * @public
+ */
+export interface ProofJSON {
+  proof: [string, string, string, string, string, string, string, string];
+  commitments: [string, string];
+  commitmentPok: [string, string];
+  publicInputs: string[];
+}
+
+/**
+ * @public
+ */
+export interface RedeemParams {
+  proof: [bigint, bigint, bigint, bigint, bigint, bigint, bigint, bigint];
+  commitments: [bigint, bigint];
+  commitmentPok: [bigint, bigint];
+  lightClients: { clientId: number; height: bigint }[];
+  nullifier: bigint;
+  value: bigint;
+  beneficiary: Address;
+  attestedMessage: Hex;
+  signature: Hex;
+}
+
+/**
+ * Token metadata from getSrcZAssetInfo() or getDstZAssetInfo().
+ * @public
+ */
+export interface TokenInfo {
+  /** Token symbol (e.g., "USDC") */
+  symbol: string;
+  /** Number of decimal places */
+  decimals: number;
+}
+
+/**
+ * @public
+ */
+export interface ConsensusState {
+  stateRoot: Hash;
+}
+
+/**
+ * @public
+ */
+export interface CounterpartyInfo {
+  tokenAddressKey: Hash;
+  balanceSlot: Hash;
+}
+
+/**
+ * A single redemption event from getRedemptionHistory().
+ * @public
+ */
+export interface RedemptionHistoryEntry {
+  /** Transaction hash of the redemption */
+  txHash: Hash;
+  /** Block number when the redemption was confirmed */
+  blockNumber: bigint;
+  /** Amount redeemed in this transaction */
+  redeemAmount: bigint;
+  /** Address that received the redeemed tokens */
+  beneficiary: Address;
+}
+
+/**
+ * Result from deposit() after wrapping and transferring tokens to the unspendable address.
+ * @public
+ */
+export interface DepositResult {
+  /** Transaction hash of the deposit */
+  txHash: Hash;
+  /** The unspendable deposit address derived from the secret */
+  depositAddress: Address;
+  /** Address of the underlying token that was wrapped */
+  underlyingToken: Address;
+  /** Chain ID where the deposit occurred */
+  chainId: bigint;
+  /** Block height of deposit transaction */
+  height: bigint;
+}
+
+/**
+ * @public
+ */
+export interface DepositToZAssetResult {
+  txHash: Hash;
+  underlyingToken: Address;
+  chainId: bigint;
+}
+
+/**
+ * Result from updateLightClient() after updating a loopback light client.
+ * @public
+ */
+export interface UpdateLightClientResult {
+  /** Transaction hash of the update */
+  txHash: Hash;
+  /** Block number the light client was updated to */
+  blockNumber: bigint;
+  /** State root at the updated block height */
+  stateRoot: Hash;
+  /** Chain ID where the update occurred */
+  chainId: bigint;
+}
+
+/**
+ * Result from redeem() containing the transaction hash and proof details.
+ * @public
+ */
+export interface FullRedeemResult {
+  /** Transaction hash of the redemption */
+  txHash: Hash;
+  /** The generated proof (for record-keeping) */
+  proof: ProofJSON;
+  /** Metadata about the redemption */
+  metadata: ProofMetadata;
+}

package/types/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": [],
+  "main": "../dist/cjs/types.js",
+  "module": "../dist/esm/types.js",
+  "types": "../dist/dts/types.d.ts"
+}

package/dist/LICENSE

@@ -1 +0,0 @@
-Copyright (c) 2025 Union.fi Labs, Inc. All rights reserved.