feat(multisig): add domain types, adapter interface, and validation schemas

Define MultisigChain, MultisigEscrow, MultisigProposal types.
Create ChainAdapter interface with createMultisig, proposeTransaction,
verifySignature, and broadcastTransaction methods.
Add Zod validation for all multisig operations.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ralyodio

src/lib/multisig/adapters/interface.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Chain Adapter Interface Tests
+ *
+ * Tests the adapter type resolution utility.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getAdapterType } from './interface';
+
+describe('getAdapterType', () => {
+  it('should return "evm" for EVM chains', () => {
+    expect(getAdapterType('ETH')).toBe('evm');
+    expect(getAdapterType('POL')).toBe('evm');
+    expect(getAdapterType('BASE')).toBe('evm');
+    expect(getAdapterType('ARB')).toBe('evm');
+    expect(getAdapterType('OP')).toBe('evm');
+    expect(getAdapterType('BNB')).toBe('evm');
+    expect(getAdapterType('AVAX')).toBe('evm');
+  });
+
+  it('should return "utxo" for UTXO chains', () => {
+    expect(getAdapterType('BTC')).toBe('utxo');
+    expect(getAdapterType('LTC')).toBe('utxo');
+    expect(getAdapterType('DOGE')).toBe('utxo');
+  });
+
+  it('should return "solana" for SOL', () => {
+    expect(getAdapterType('SOL')).toBe('solana');
+  });
+
+  it('should throw for unsupported chains', () => {
+    expect(() => getAdapterType('XRP' as any)).toThrow('Unsupported multisig chain');
+    expect(() => getAdapterType('ADA' as any)).toThrow('Unsupported multisig chain');
+  });
+});

src/lib/multisig/adapters/interface.ts

@@ -0,0 +1,77 @@
+/**
+ * Chain Adapter Interface
+ *
+ * Abstract interface for all multisig chain adapters.
+ * Each adapter implements chain-specific multisig operations:
+ * - EVM: Safe (Gnosis Safe) protocol
+ * - BTC/UTXO: P2WSH 2-of-3 multisig with PSBT
+ * - Solana: Squads-style multisig PDA
+ */
+
+import type {
+  MultisigChain,
+  MultisigParticipants,
+  CreateMultisigResult,
+  ProposeTransactionInput,
+  ProposeTransactionResult,
+  BroadcastResult,
+} from '../types';
+
+export interface ChainAdapter {
+  /** Chain identifier(s) this adapter supports */
+  readonly supportedChains: readonly MultisigChain[];
+
+  /**
+   * Create a new 2-of-3 multisig wallet/account on-chain.
+   * Returns the escrow address and any chain-specific metadata.
+   */
+  createMultisig(
+    chain: MultisigChain,
+    participants: MultisigParticipants,
+    threshold: number,
+  ): Promise<CreateMultisigResult>;
+
+  /**
+   * Build a transaction proposal for the multisig.
+   * Returns transaction data that signers need to sign.
+   */
+  proposeTransaction(
+    chain: MultisigChain,
+    input: ProposeTransactionInput,
+  ): Promise<ProposeTransactionResult>;
+
+  /**
+   * Verify that a signature is valid for the given transaction data.
+   * Returns true if the signature is valid and from an authorized signer.
+   */
+  verifySignature(
+    chain: MultisigChain,
+    txData: Record<string, unknown>,
+    signature: string,
+    signerPubkey: string,
+  ): Promise<boolean>;
+
+  /**
+   * Combine signatures and broadcast the transaction on-chain.
+   * Requires at least `threshold` valid signatures.
+   */
+  broadcastTransaction(
+    chain: MultisigChain,
+    txData: Record<string, unknown>,
+    signatures: Array<{ pubkey: string; signature: string }>,
+  ): Promise<BroadcastResult>;
+}
+
+/**
+ * Determine adapter type from chain identifier
+ */
+export function getAdapterType(chain: MultisigChain): 'evm' | 'utxo' | 'solana' {
+  const evmChains: MultisigChain[] = ['ETH', 'POL', 'BASE', 'ARB', 'OP', 'BNB', 'AVAX'];
+  const utxoChains: MultisigChain[] = ['BTC', 'LTC', 'DOGE'];
+
+  if (evmChains.includes(chain)) return 'evm';
+  if (utxoChains.includes(chain)) return 'utxo';
+  if (chain === 'SOL') return 'solana';
+
+  throw new Error(`Unsupported multisig chain: ${chain}`);
+}

src/lib/multisig/types.ts

@@ -0,0 +1,180 @@
+/**
+ * Multisig Escrow Types
+ *
+ * 2-of-3 multisig escrow: Depositor, Beneficiary, CoinPay (Arbiter).
+ * CoinPay can never move funds alone — always requires 2 of 3 signers.
+ */
+
+// ── Chain Types ─────────────────────────────────────────────
+
+/** EVM chains supported by Safe adapter */
+export type EvmChain = 'ETH' | 'POL' | 'BASE' | 'ARB' | 'OP' | 'BNB' | 'AVAX';
+
+/** UTXO chains supported by BTC multisig adapter */
+export type UtxoChain = 'BTC' | 'LTC' | 'DOGE';
+
+/** Solana chain */
+export type SolanaChain = 'SOL';
+
+/** All chains supported by multisig */
+export type MultisigChain = EvmChain | UtxoChain | SolanaChain;
+
+// ── Escrow Model ────────────────────────────────────────────
+
+export type EscrowModel = 'custodial' | 'multisig_2of3';
+
+export type MultisigEscrowStatus =
+  | 'pending'
+  | 'funded'
+  | 'released'
+  | 'settled'
+  | 'disputed'
+  | 'refunded'
+  | 'expired';
+
+export type DisputeStatus =
+  | 'open'
+  | 'under_review'
+  | 'resolved_release'
+  | 'resolved_refund';
+
+export type ProposalType = 'release' | 'refund';
+
+export type ProposalStatus = 'pending' | 'approved' | 'executed' | 'cancelled';
+
+export type SignerRole = 'depositor' | 'beneficiary' | 'arbiter';
+
+// ── Core Interfaces ─────────────────────────────────────────
+
+export interface MultisigParticipants {
+  depositor_pubkey: string;
+  beneficiary_pubkey: string;
+  arbiter_pubkey: string;
+}
+
+export interface CreateMultisigEscrowInput {
+  chain: MultisigChain;
+  amount: number;
+  depositor_pubkey: string;
+  beneficiary_pubkey: string;
+  arbiter_pubkey: string;
+  metadata?: Record<string, unknown>;
+  business_id?: string;
+  expires_in_hours?: number;
+}
+
+export interface MultisigEscrow {
+  id: string;
+  escrow_model: 'multisig_2of3';
+  chain: MultisigChain;
+  threshold: 2;
+  depositor_pubkey: string;
+  beneficiary_pubkey: string;
+  arbiter_pubkey: string;
+  escrow_address: string;
+  chain_metadata: Record<string, unknown>;
+  amount: number;
+  amount_usd: number | null;
+  status: MultisigEscrowStatus;
+  dispute_status: DisputeStatus | null;
+  dispute_reason: string | null;
+  metadata: Record<string, unknown>;
+  business_id: string | null;
+  funded_at: string | null;
+  settled_at: string | null;
+  created_at: string;
+  expires_at: string;
+}
+
+export interface MultisigProposal {
+  id: string;
+  escrow_id: string;
+  proposal_type: ProposalType;
+  to_address: string;
+  amount: number;
+  chain_tx_data: Record<string, unknown>;
+  status: ProposalStatus;
+  created_by: string;
+  created_at: string;
+  executed_at: string | null;
+  tx_hash: string | null;
+}
+
+export interface MultisigSignature {
+  id: string;
+  proposal_id: string;
+  signer_role: SignerRole;
+  signer_pubkey: string;
+  signature: string;
+  signed_at: string;
+}
+
+// ── Adapter Interfaces ──────────────────────────────────────
+
+/** Result of creating a multisig wallet on-chain */
+export interface CreateMultisigResult {
+  escrow_address: string;
+  chain_metadata: Record<string, unknown>;
+}
+
+/** Data needed to propose a transaction */
+export interface ProposeTransactionInput {
+  escrow_address: string;
+  to_address: string;
+  amount: number;
+  chain_metadata: Record<string, unknown>;
+}
+
+/** Result of proposing a transaction */
+export interface ProposeTransactionResult {
+  tx_data: Record<string, unknown>;
+  tx_hash_to_sign: string;
+}
+
+/** Result of adding a signature */
+export interface AddSignatureResult {
+  signatures_collected: number;
+  threshold_met: boolean;
+}
+
+/** Result of broadcasting */
+export interface BroadcastResult {
+  tx_hash: string;
+  success: boolean;
+}
+
+// ── API Response Types ──────────────────────────────────────
+
+export interface CreateMultisigEscrowResult {
+  success: boolean;
+  escrow?: MultisigEscrow;
+  error?: string;
+}
+
+export interface ProposeResult {
+  success: boolean;
+  proposal?: MultisigProposal;
+  tx_data?: Record<string, unknown>;
+  error?: string;
+}
+
+export interface SignResult {
+  success: boolean;
+  signature?: MultisigSignature;
+  signatures_collected?: number;
+  threshold_met?: boolean;
+  error?: string;
+}
+
+export interface BroadcastResultResponse {
+  success: boolean;
+  tx_hash?: string;
+  proposal?: MultisigProposal;
+  error?: string;
+}
+
+export interface DisputeResult {
+  success: boolean;
+  escrow?: MultisigEscrow;
+  error?: string;
+}