@psavelis/enterprise-blockchain 0.1.0 → 1.1.1

package/dist/stark-settlement/index.js

@@ -0,0 +1,193 @@
+/**
+ * @enterprise-blockchain/stark-settlement
+ *
+ * Aggregated STARK Settlement Layer with Recursive Proof Composition
+ *
+ * A production-grade, quantum-resistant settlement system that:
+ * - Uses zk-STARK proofs for verifiable state transitions
+ * - Aggregates thousands of transactions into single block proofs
+ * - Settles to multiple external chains (Solana, Bitcoin, Fiat)
+ * - Provides post-quantum security via ML-DSA-65 signatures
+ *
+ * Architecture:
+ * - Hexagonal (ports & adapters) with no SDK imports in domain layer
+ * - 3-tier recursive proof aggregation (Base → Tier-1 → Tier-2)
+ * - Exactly-once settlement semantics via idempotency keys
+ * - Full observability with OpenTelemetry
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   LedgerService,
+ *   AggregatorService,
+ *   SettlementService,
+ *   createDefaultContext,
+ * } from "@enterprise-blockchain/stark-settlement";
+ *
+ * // Create services with default adapters
+ * const ctx = createDefaultContext();
+ * const ledger = new LedgerService(ctx);
+ * const aggregator = new AggregatorService(ctx);
+ * const settler = new SettlementService(ctx);
+ *
+ * // Submit a transaction
+ * const tx = await ledger.submitTransaction({
+ *   type: "transfer",
+ *   fromAccountId: "alice",
+ *   toAccountId: "bob",
+ *   assetType: "SOL",
+ *   amount: 1000000000n, // 1 SOL in lamports
+ * });
+ *
+ * // Generate proofs and settle
+ * const blockProof = await aggregator.processToBlockProof();
+ * const result = await settler.settleAllRails(blockProof);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { ASSET_CONFIGS } from "./domain/entities.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Value Objects
+// ─────────────────────────────────────────────────────────────────────────────
+export { STARK_PRIME, STARK_GENERATOR, FieldElement, IdempotencyKey, ProofCommitment, StateRoot, Amount, sha256, sha256Bytes, pedersenHash, } from "./domain/value-objects.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Infrastructure Adapters
+// ─────────────────────────────────────────────────────────────────────────────
+// Persistence
+export { InMemoryLedgerStore } from "./infrastructure/persistence/ledger-store.js";
+export { InMemoryOutboxStore } from "./infrastructure/persistence/outbox-store.js";
+export { InMemoryOffsetStore } from "./infrastructure/persistence/offset-store.js";
+// STARK Proofs
+export { MockStarkAdapter, FlexibleMockStarkAdapter, } from "./infrastructure/adapters/mock-stark-adapter.js";
+// Clock
+export { SystemClock, FixedClock, defaultClock, } from "./infrastructure/adapters/clock-adapter.js";
+// Events
+export { InMemoryEventEmitter, AsyncEventEmitter, defaultEventEmitter, } from "./infrastructure/adapters/event-emitter-adapter.js";
+// Signing
+export { DilithiumSigningAdapter, TransactionSigningAdapter, MockDilithiumAdapter, defaultDilithiumAdapter, createTransactionSigningAdapter, } from "./infrastructure/adapters/dilithium-adapter.js";
+// Audit
+export { InMemoryAuditLog, defaultAuditLog, } from "./infrastructure/adapters/audit-adapter.js";
+// StarkNet
+export { StarknetProofAdapter, createStarknetProofAdapter, } from "./infrastructure/adapters/starknet-proof-adapter.js";
+// Stone Prover (Production)
+export { StoneProofAdapter, createStoneProofAdapter, } from "./infrastructure/adapters/stone-proof-adapter.js";
+// External Chains
+export { SolanaDevnetAdapter, MockSolanaAdapter, } from "./infrastructure/adapters/solana-adapter.js";
+export { BitcoinTestnetAdapter, MockBitcoinAdapter, } from "./infrastructure/adapters/bitcoin-adapter.js";
+export { FiatMockAdapter, MockFiatAdapter, } from "./infrastructure/adapters/fiat-adapter.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Application Services
+// ─────────────────────────────────────────────────────────────────────────────
+export { LedgerService } from "./application/ledger-service.js";
+export { AggregatorService } from "./application/aggregator-service.js";
+export { SettlementService } from "./application/settlement-service.js";
+import { InMemoryLedgerStore } from "./infrastructure/persistence/ledger-store.js";
+import { InMemoryOutboxStore } from "./infrastructure/persistence/outbox-store.js";
+import { InMemoryOffsetStore } from "./infrastructure/persistence/offset-store.js";
+import { FlexibleMockStarkAdapter } from "./infrastructure/adapters/mock-stark-adapter.js";
+import { StoneProofAdapter } from "./infrastructure/adapters/stone-proof-adapter.js";
+import { SystemClock } from "./infrastructure/adapters/clock-adapter.js";
+import { InMemoryEventEmitter } from "./infrastructure/adapters/event-emitter-adapter.js";
+import { DilithiumSigningAdapter, TransactionSigningAdapter, } from "./infrastructure/adapters/dilithium-adapter.js";
+import { InMemoryAuditLog } from "./infrastructure/adapters/audit-adapter.js";
+/**
+ * Create a settlement context with default or custom adapters.
+ *
+ * @example
+ * ```typescript
+ * // Default context (all in-memory, mock STARK)
+ * const ctx = createDefaultContext();
+ *
+ * // Custom batch sizes for demos
+ * const demoCtx = createDefaultContext({
+ *   tier1BatchSize: 4,
+ *   tier2BatchSize: 2,
+ * });
+ *
+ * // Custom adapters (clock must be passed to StarknetProofAdapter)
+ * const clock = new SystemClock();
+ * const prodCtx = createDefaultContext({
+ *   clock,
+ *   starkProver: new StarknetProofAdapter(clock),
+ *   ledgerStore: new PostgresLedgerStore(connectionString),
+ * });
+ * ```
+ */
+export function createDefaultContext(options = {}) {
+    const clock = options.clock ?? new SystemClock();
+    const ledgerStore = options.ledgerStore ?? new InMemoryLedgerStore();
+    const outboxStore = options.outboxStore ?? new InMemoryOutboxStore();
+    const offsetStore = options.offsetStore ?? new InMemoryOffsetStore();
+    const dilithium = options.dilithium ?? new DilithiumSigningAdapter();
+    const transactionSigning = options.transactionSigning ?? new TransactionSigningAdapter(dilithium);
+    const auditLog = options.auditLog ?? new InMemoryAuditLog();
+    const events = options.events ?? new InMemoryEventEmitter();
+    // Default to small batch sizes for demos (full: 128/64)
+    const tier1BatchSize = options.tier1BatchSize ?? 8;
+    const tier2BatchSize = options.tier2BatchSize ?? 4;
+    const starkProver = options.starkProver ??
+        new FlexibleMockStarkAdapter(clock, {
+            tier1BatchSize,
+            tier2BatchSize,
+        });
+    return {
+        clock,
+        ledgerStore,
+        outboxStore,
+        offsetStore,
+        starkProver,
+        dilithium,
+        transactionSigning,
+        auditLog,
+        events,
+    };
+}
+/**
+ * Create a context for production with full batch sizes.
+ *
+ * By default, uses the StoneProofAdapter for real STARK proof generation.
+ * Set useMockProver: true to use the mock adapter for testing without Docker.
+ *
+ * Requires 128 * 64 = 8,192 transactions per block proof.
+ */
+export function createProductionContext(options = {}) {
+    const clock = options.clock ?? new SystemClock();
+    // Use Stone prover by default, mock if explicitly requested
+    let starkProver = options.starkProver;
+    if (!starkProver) {
+        if (options.useMockProver) {
+            starkProver = new FlexibleMockStarkAdapter(clock, {
+                tier1BatchSize: 128,
+                tier2BatchSize: 64,
+            });
+        }
+        else {
+            starkProver = new StoneProofAdapter(clock, {
+                proverEndpoint: options.proverEndpoint ?? "localhost:10000",
+                cairoArtifactsPath: options.cairoArtifactsPath ?? "./cairo/artifacts",
+                tier1BatchSize: 128,
+                tier2BatchSize: 64,
+            });
+        }
+    }
+    return createDefaultContext({
+        ...options,
+        clock,
+        starkProver,
+        tier1BatchSize: 128,
+        tier2BatchSize: 64,
+    });
+}
+/**
+ * Create a context for testing with minimal batch sizes.
+ *
+ * Requires only 2 * 2 = 4 transactions per block proof.
+ */
+export function createTestContext(options = {}) {
+    return createDefaultContext({
+        ...options,
+        tier1BatchSize: 2,
+        tier2BatchSize: 2,
+    });
+}

package/dist/stark-settlement/infrastructure/adapters/audit-adapter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Audit Adapter
+ *
+ * Implements AuditPort for compliance logging.
+ * Maintains a cryptographically chained audit log.
+ *
+ * @see domain/ports.ts for AuditPort interface
+ */
+import type { AuditRecord } from "../../domain/entities.js";
+import type { AuditPort } from "../../domain/ports.js";
+/**
+ * In-memory audit log with chain integrity verification.
+ */
+export declare class InMemoryAuditLog implements AuditPort {
+    private readonly records;
+    private readonly recordsById;
+    private readonly recordsByEntity;
+    private lastHash;
+    append(record: Omit<AuditRecord, "recordId" | "previousHash" | "recordHash">): Promise<AuditRecord>;
+    getRecordsForEntity(entityId: string): Promise<readonly AuditRecord[]>;
+    verifyChainIntegrity(): Promise<{
+        valid: boolean;
+        lastValidRecord: string | null;
+        errorMessage: string | null;
+    }>;
+    getLatestRecord(): Promise<AuditRecord | null>;
+    /**
+     * Get all records (for debugging/export).
+     */
+    getAllRecords(): readonly AuditRecord[];
+    /**
+     * Get the total number of records.
+     */
+    getRecordCount(): number;
+    /**
+     * Get records by event type.
+     */
+    getRecordsByEventType(eventType: AuditRecord["eventType"]): readonly AuditRecord[];
+    /**
+     * Export audit log as JSON (for compliance reporting).
+     */
+    exportAsJson(): string;
+    /**
+     * Clear all records (for testing).
+     */
+    clear(): void;
+}
+/**
+ * Default audit log instance.
+ */
+export declare const defaultAuditLog: InMemoryAuditLog;
+//# sourceMappingURL=audit-adapter.d.ts.map

package/dist/stark-settlement/infrastructure/adapters/audit-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-adapter.d.ts","sourceRoot":"","sources":["../../../../src/stark-settlement/infrastructure/adapters/audit-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA+B;IAC/D,OAAO,CAAC,QAAQ,CAAkB;IAE5B,MAAM,CACV,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,cAAc,GAAG,YAAY,CAAC,GACpE,OAAO,CAAC,WAAW,CAAC;IAoCjB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC;IAetE,oBAAoB,IAAI,OAAO,CAAC;QACpC,KAAK,EAAE,OAAO,CAAC;QACf,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;IAoDI,eAAe,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IASpD;;OAEG;IACH,aAAa,IAAI,SAAS,WAAW,EAAE;IAIvC;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,qBAAqB,CACnB,SAAS,EAAE,WAAW,CAAC,WAAW,CAAC,GAClC,SAAS,WAAW,EAAE;IAIzB;;OAEG;IACH,YAAY,IAAI,MAAM;IAatB;;OAEG;IACH,KAAK,IAAI,IAAI;CAMd;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,kBAAyB,CAAC"}

package/dist/stark-settlement/infrastructure/adapters/audit-adapter.js

@@ -0,0 +1,154 @@
+/**
+ * Audit Adapter
+ *
+ * Implements AuditPort for compliance logging.
+ * Maintains a cryptographically chained audit log.
+ *
+ * @see domain/ports.ts for AuditPort interface
+ */
+/* eslint-disable @typescript-eslint/require-await */
+import { createHash, randomUUID } from "node:crypto";
+/**
+ * In-memory audit log with chain integrity verification.
+ */
+export class InMemoryAuditLog {
+    records = [];
+    recordsById = new Map(); // recordId -> AuditRecord (O(1) lookup)
+    recordsByEntity = new Map(); // entityId -> recordIds
+    lastHash = "0".repeat(64); // Genesis hash
+    async append(record) {
+        const recordId = randomUUID();
+        const previousHash = this.lastHash;
+        // Compute record hash (includes previous hash for chain integrity)
+        // IMPORTANT: Use explicit property order for deterministic hashing
+        const hashInput = JSON.stringify({
+            recordId,
+            eventType: record.eventType,
+            entityId: record.entityId,
+            entityType: record.entityType,
+            actor: record.actor,
+            timestamp: record.timestamp,
+            data: record.data,
+            previousHash,
+        });
+        const recordHash = createHash("sha256").update(hashInput).digest("hex");
+        const fullRecord = {
+            recordId,
+            ...record,
+            previousHash,
+            recordHash,
+        };
+        this.records.push(fullRecord);
+        this.recordsById.set(recordId, fullRecord); // O(1) lookup index
+        this.lastHash = recordHash;
+        // Index by entity
+        const existingRecordIds = this.recordsByEntity.get(record.entityId) ?? [];
+        this.recordsByEntity.set(record.entityId, [...existingRecordIds, recordId]);
+        return fullRecord;
+    }
+    async getRecordsForEntity(entityId) {
+        const recordIds = this.recordsByEntity.get(entityId) ?? [];
+        const records = [];
+        // Use recordsById Map for O(1) lookup instead of O(n) find()
+        for (const recordId of recordIds) {
+            const record = this.recordsById.get(recordId);
+            if (record) {
+                records.push(record);
+            }
+        }
+        return records.sort((a, b) => a.timestamp - b.timestamp);
+    }
+    async verifyChainIntegrity() {
+        if (this.records.length === 0) {
+            return { valid: true, lastValidRecord: null, errorMessage: null };
+        }
+        let expectedPreviousHash = "0".repeat(64); // Genesis hash
+        let lastValidRecordId = null;
+        for (let i = 0; i < this.records.length; i++) {
+            const record = this.records[i];
+            // Check previous hash
+            if (record.previousHash !== expectedPreviousHash) {
+                return {
+                    valid: false,
+                    lastValidRecord: lastValidRecordId,
+                    errorMessage: `Chain broken at record ${record.recordId}: expected previousHash ${expectedPreviousHash}, got ${record.previousHash}`,
+                };
+            }
+            // Verify record hash
+            const hashInput = JSON.stringify({
+                recordId: record.recordId,
+                eventType: record.eventType,
+                entityId: record.entityId,
+                entityType: record.entityType,
+                actor: record.actor,
+                timestamp: record.timestamp,
+                data: record.data,
+                previousHash: record.previousHash,
+            });
+            const computedHash = createHash("sha256").update(hashInput).digest("hex");
+            if (record.recordHash !== computedHash) {
+                return {
+                    valid: false,
+                    lastValidRecord: lastValidRecordId,
+                    errorMessage: `Hash mismatch at record ${record.recordId}: expected ${computedHash}, got ${record.recordHash}`,
+                };
+            }
+            lastValidRecordId = record.recordId;
+            expectedPreviousHash = record.recordHash;
+        }
+        return {
+            valid: true,
+            lastValidRecord: lastValidRecordId,
+            errorMessage: null,
+        };
+    }
+    async getLatestRecord() {
+        if (this.records.length === 0) {
+            return null;
+        }
+        return this.records[this.records.length - 1] ?? null;
+    }
+    // ─── Utilities ──────────────────────────────────────────────────────────
+    /**
+     * Get all records (for debugging/export).
+     */
+    getAllRecords() {
+        return [...this.records];
+    }
+    /**
+     * Get the total number of records.
+     */
+    getRecordCount() {
+        return this.records.length;
+    }
+    /**
+     * Get records by event type.
+     */
+    getRecordsByEventType(eventType) {
+        return this.records.filter((r) => r.eventType === eventType);
+    }
+    /**
+     * Export audit log as JSON (for compliance reporting).
+     */
+    exportAsJson() {
+        return JSON.stringify({
+            exportedAt: new Date().toISOString(),
+            recordCount: this.records.length,
+            chainIntegrity: "pending-verification",
+            records: this.records,
+        }, null, 2);
+    }
+    /**
+     * Clear all records (for testing).
+     */
+    clear() {
+        this.records.length = 0;
+        this.recordsById.clear();
+        this.recordsByEntity.clear();
+        this.lastHash = "0".repeat(64);
+    }
+}
+/**
+ * Default audit log instance.
+ */
+export const defaultAuditLog = new InMemoryAuditLog();

package/dist/stark-settlement/infrastructure/adapters/bitcoin-adapter.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Bitcoin Settlement Adapter
+ *
+ * Implements BitcoinSettlementPort for Bitcoin testnet settlement.
+ * Uses PSBT (Partially Signed Bitcoin Transactions) for batched UTXO spends.
+ *
+ * Features:
+ * - Batched outputs in single transaction
+ * - PSBT format for multi-party signing
+ * - OP_RETURN for proof commitment
+ * - Address watching for deposit detection
+ *
+ * @see https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki for PSBT
+ * @see domain/ports.ts for BitcoinSettlementPort interface
+ */
+import type { NetTransfer, Tier2BlockProof, BitcoinSettlementResult, DepositEvent } from "../../domain/entities.js";
+import type { BitcoinSettlementPort, ClockPort } from "../../domain/ports.js";
+/**
+ * Configuration for Bitcoin adapter.
+ */
+export interface BitcoinAdapterConfig {
+    /** API endpoint (default: Blockstream testnet) */
+    apiUrl?: string;
+    /** Network (testnet or mainnet) */
+    network?: "testnet" | "mainnet";
+    /** Fee rate in sat/vB (default: 10) */
+    feeRate?: number;
+    /** Confirmation threshold for deposits (default: 1) */
+    confirmationThreshold?: number;
+}
+/**
+ * Bitcoin testnet adapter for settlement operations.
+ */
+export declare class BitcoinTestnetAdapter implements BitcoinSettlementPort {
+    private readonly clock;
+    private readonly config;
+    private readonly watchedAddresses;
+    private watchCounter;
+    constructor(clock: ClockPort, config?: BitcoinAdapterConfig);
+    executeBatchedSpend(transfers: readonly NetTransfer[], blockProof: Tier2BlockProof): Promise<BitcoinSettlementResult>;
+    watchAddresses(addresses: readonly string[], callback: (deposit: DepositEvent) => void): Promise<{
+        unwatch: () => void;
+    }>;
+    getHealth(): Promise<{
+        healthy: boolean;
+        blockHeight: number;
+    }>;
+    getUtxos(address: string): Promise<readonly {
+        txid: string;
+        vout: number;
+        value: bigint;
+        confirmed: boolean;
+    }[]>;
+    /**
+     * Simulate a deposit event (for testing).
+     */
+    simulateDeposit(address: string, amount: bigint, txid: string, confirmations: number): void;
+    private generateMockTxid;
+    private generateMockPsbt;
+}
+/**
+ * Mock Bitcoin adapter for testing without network.
+ */
+export declare class MockBitcoinAdapter implements BitcoinSettlementPort {
+    private readonly clock;
+    private blockHeight;
+    readonly settlements: Array<{
+        transfers: readonly NetTransfer[];
+        blockProofId: string;
+        result: BitcoinSettlementResult;
+    }>;
+    constructor(clock: ClockPort);
+    executeBatchedSpend(transfers: readonly NetTransfer[], blockProof: Tier2BlockProof): Promise<BitcoinSettlementResult>;
+    watchAddresses(_addresses: readonly string[], _callback: (deposit: DepositEvent) => void): Promise<{
+        unwatch: () => void;
+    }>;
+    getHealth(): Promise<{
+        healthy: boolean;
+        blockHeight: number;
+    }>;
+    getUtxos(_address: string): Promise<readonly {
+        txid: string;
+        vout: number;
+        value: bigint;
+        confirmed: boolean;
+    }[]>;
+}
+//# sourceMappingURL=bitcoin-adapter.d.ts.map

package/dist/stark-settlement/infrastructure/adapters/bitcoin-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bitcoin-adapter.d.ts","sourceRoot":"","sources":["../../../../src/stark-settlement/infrastructure/adapters/bitcoin-adapter.ts"],"names":[],"mappings":"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"}

package/dist/stark-settlement/infrastructure/adapters/bitcoin-adapter.js

@@ -0,0 +1,187 @@
+/**
+ * Bitcoin Settlement Adapter
+ *
+ * Implements BitcoinSettlementPort for Bitcoin testnet settlement.
+ * Uses PSBT (Partially Signed Bitcoin Transactions) for batched UTXO spends.
+ *
+ * Features:
+ * - Batched outputs in single transaction
+ * - PSBT format for multi-party signing
+ * - OP_RETURN for proof commitment
+ * - Address watching for deposit detection
+ *
+ * @see https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki for PSBT
+ * @see domain/ports.ts for BitcoinSettlementPort interface
+ */
+/* eslint-disable @typescript-eslint/require-await, @typescript-eslint/no-unused-vars */
+import { createHash } from "node:crypto";
+import { ProofCommitment } from "../../domain/value-objects.js";
+/**
+ * Bitcoin testnet adapter for settlement operations.
+ */
+export class BitcoinTestnetAdapter {
+    clock;
+    config;
+    watchedAddresses = new Map();
+    watchCounter = 0;
+    constructor(clock, config) {
+        this.clock = clock;
+        this.config = {
+            apiUrl: config?.apiUrl ?? "https://blockstream.info/testnet/api",
+            network: config?.network ?? "testnet",
+            feeRate: config?.feeRate ?? 10,
+            confirmationThreshold: config?.confirmationThreshold ?? 1,
+        };
+    }
+    async executeBatchedSpend(transfers, blockProof) {
+        // Compute proof commitment for OP_RETURN
+        const proofCommitment = ProofCommitment.create(blockProof.blockProofId, blockProof.finalProof, blockProof.publicInputs);
+        // In production, this would:
+        // 1. Gather UTXOs from all source addresses
+        // 2. Build PSBT with outputs for each transfer
+        // 3. Add OP_RETURN output with proof commitment
+        // 4. Sign all inputs
+        // 5. Broadcast via API
+        // Simulate transaction
+        const txid = this.generateMockTxid(proofCommitment.toString());
+        const psbtBase64 = this.generateMockPsbt(transfers, proofCommitment.toString());
+        // Estimate fee (simplified)
+        const inputSize = 148n; // P2PKH input
+        const outputSize = 34n; // P2PKH output
+        const opReturnSize = 43n; // OP_RETURN with 32 bytes
+        const txOverhead = 10n;
+        const estimatedSize = txOverhead +
+            inputSize * BigInt(transfers.length) +
+            outputSize * BigInt(transfers.length) +
+            opReturnSize;
+        const fee = estimatedSize * BigInt(this.config.feeRate);
+        // Mock UTXOs spent
+        const utxosSpent = transfers.map((t, i) => `${this.generateMockTxid(t.externalAddress)}:${i}`);
+        console.log(`[Bitcoin] Settled ${transfers.length} transfers`);
+        console.log(`[Bitcoin] Txid: ${txid}`);
+        console.log(`[Bitcoin] OP_RETURN: ${proofCommitment.toString().slice(0, 40)}...`);
+        return {
+            txid,
+            psbtBase64,
+            utxosSpent,
+            fee,
+            opReturnData: proofCommitment.toString(),
+            confirmations: 0, // Just broadcast
+        };
+    }
+    async watchAddresses(addresses, callback) {
+        const watchId = `watch-${this.watchCounter++}`;
+        for (const address of addresses) {
+            this.watchedAddresses.set(`${watchId}:${address}`, { callback });
+        }
+        console.log(`[Bitcoin] Watching ${addresses.length} addresses for deposits`);
+        return {
+            unwatch: () => {
+                for (const address of addresses) {
+                    this.watchedAddresses.delete(`${watchId}:${address}`);
+                }
+                console.log(`[Bitcoin] Stopped watching addresses (${watchId})`);
+            },
+        };
+    }
+    async getHealth() {
+        // In production, this would call /blocks/tip/height
+        const blockHeight = Math.floor(Date.now() / 600000) + 2500000; // ~10 min blocks
+        return { healthy: true, blockHeight };
+    }
+    async getUtxos(address) {
+        // In production, this would call /address/{address}/utxo
+        // Return mock UTXOs for testing
+        return [
+            {
+                txid: this.generateMockTxid(address),
+                vout: 0,
+                value: 100000n, // 0.001 BTC
+                confirmed: true,
+            },
+        ];
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Test Helpers
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Simulate a deposit event (for testing).
+     */
+    simulateDeposit(address, amount, txid, confirmations) {
+        const event = {
+            eventId: this.clock.uuid(),
+            assetType: "BTC",
+            externalAddress: address,
+            amount,
+            externalTxId: txid,
+            confirmations,
+            detectedAt: this.clock.now(),
+            mirrored: false,
+        };
+        for (const [key, { callback }] of this.watchedAddresses) {
+            if (key.endsWith(`:${address}`)) {
+                callback(event);
+            }
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────────────────────────────────
+    generateMockTxid(seed) {
+        return createHash("sha256").update(seed).digest("hex");
+    }
+    generateMockPsbt(transfers, proofCommitment) {
+        // Generate a mock PSBT structure (simplified)
+        const psbtData = {
+            inputs: transfers.map((t) => ({
+                txid: this.generateMockTxid(t.externalAddress),
+                vout: 0,
+            })),
+            outputs: [
+                ...transfers.map((t) => ({
+                    address: t.externalAddress,
+                    value: t.netAmount,
+                })),
+                { opReturn: proofCommitment },
+            ],
+        };
+        return Buffer.from(JSON.stringify(psbtData)).toString("base64");
+    }
+}
+/**
+ * Mock Bitcoin adapter for testing without network.
+ */
+export class MockBitcoinAdapter {
+    clock;
+    blockHeight = 2500000;
+    settlements = [];
+    constructor(clock) {
+        this.clock = clock;
+    }
+    async executeBatchedSpend(transfers, blockProof) {
+        this.blockHeight++;
+        const result = {
+            txid: `mock-txid-${this.blockHeight}`,
+            psbtBase64: "mock-psbt-base64",
+            utxosSpent: transfers.map((_, i) => `mock-utxo:${i}`),
+            fee: 1000n + BigInt(transfers.length) * 148n * 10n,
+            opReturnData: blockProof.stateRoot,
+            confirmations: 0,
+        };
+        this.settlements.push({
+            transfers,
+            blockProofId: blockProof.blockProofId,
+            result,
+        });
+        return result;
+    }
+    async watchAddresses(_addresses, _callback) {
+        return { unwatch: () => { } };
+    }
+    async getHealth() {
+        return { healthy: true, blockHeight: this.blockHeight };
+    }
+    async getUtxos(_address) {
+        return [{ txid: "mock-utxo", vout: 0, value: 100000n, confirmed: true }];
+    }
+}