@fiber-pay/agent 0.1.0-rc.1

package/dist/index.js

@@ -0,0 +1,1526 @@
+// src/fiber-pay.ts
+import { randomUUID } from "crypto";
+import { join } from "path";
+import { ensureFiberBinary, ProcessManager } from "@fiber-pay/node";
+import { JobManager, SqliteJobStore } from "@fiber-pay/runtime";
+import {
+  ChannelState,
+  ckbToShannons,
+  createKeyManager,
+  FiberRpcClient,
+  fromHex,
+  InvoiceVerifier,
+  LiquidityAnalyzer,
+  PaymentProofManager,
+  PolicyEngine,
+  randomBytes32,
+  shannonsToCkb,
+  toHex
+} from "@fiber-pay/sdk";
+var FiberPay = class {
+  config;
+  process = null;
+  rpc = null;
+  policy;
+  keys;
+  initialized = false;
+  invoiceVerifier = null;
+  paymentProofManager = null;
+  liquidityAnalyzer = null;
+  runtimeJobStore = null;
+  runtimeJobManager = null;
+  constructor(config) {
+    this.config = {
+      chain: "testnet",
+      autoStart: true,
+      rpcPort: 8227,
+      p2pPort: 8228,
+      useRuntimeJobs: true,
+      ...config
+    };
+    const defaultPolicy = {
+      name: "default",
+      version: "1.0.0",
+      enabled: true,
+      spending: {
+        maxPerTransaction: "0x2540be400",
+        // 100 CKB
+        maxPerWindow: "0x174876e800",
+        // 1000 CKB
+        windowSeconds: 3600
+      },
+      rateLimit: {
+        maxTransactions: 100,
+        windowSeconds: 3600,
+        cooldownSeconds: 1
+      },
+      recipients: {
+        allowUnknown: true
+      },
+      channels: {
+        allowOpen: true,
+        allowClose: true,
+        allowForceClose: false,
+        maxChannels: 10
+      },
+      auditLogging: true
+    };
+    this.policy = new PolicyEngine(config.policy || defaultPolicy);
+    this.keys = createKeyManager(config.dataDir, {
+      encryptionPassword: config.keyPassword,
+      autoGenerate: true
+    });
+  }
+  // ===========================================================================
+  // Lifecycle Methods
+  // ===========================================================================
+  /**
+   * Initialize the FiberPay instance
+   * - Downloads the binary if needed (and autoDownload is true)
+   * - Generates or loads keys
+   * - Starts the Fiber node (if autoStart is true)
+   * - Connects to RPC
+   */
+  async initialize(options) {
+    try {
+      let binaryPath = this.config.binaryPath;
+      if (!binaryPath) {
+        if (this.config.autoDownload !== false) {
+          binaryPath = await ensureFiberBinary({
+            installDir: `${this.config.dataDir}/bin`,
+            onProgress: options?.onDownloadProgress
+          });
+        } else {
+          return this.errorResult(
+            new Error("Binary path not provided and autoDownload is disabled"),
+            "BINARY_NOT_FOUND",
+            true
+          );
+        }
+      }
+      const _keyInfo = await this.keys.initialize();
+      this.process = new ProcessManager({
+        binaryPath,
+        dataDir: this.config.dataDir,
+        configFilePath: this.config.configFilePath,
+        chain: this.config.chain,
+        ckbRpcUrl: this.config.ckbRpcUrl,
+        keyPassword: this.config.keyPassword,
+        rpcListeningAddr: `127.0.0.1:${this.config.rpcPort}`,
+        fiberListeningAddr: `/ip4/0.0.0.0/tcp/${this.config.p2pPort}`,
+        bootnodeAddrs: this.config.bootnodes
+      });
+      const rpcUrl = this.config.rpcUrl || `http://127.0.0.1:${this.config.rpcPort}`;
+      this.rpc = new FiberRpcClient({
+        url: rpcUrl
+      });
+      if (this.config.autoStart) {
+        await this.process.start();
+        await this.rpc.waitForReady({ timeout: 6e4 });
+      }
+      this.invoiceVerifier = new InvoiceVerifier(this.rpc);
+      this.paymentProofManager = new PaymentProofManager(this.config.dataDir);
+      await this.paymentProofManager.load();
+      this.liquidityAnalyzer = new LiquidityAnalyzer(this.rpc);
+      if (this.config.useRuntimeJobs !== false) {
+        this.runtimeJobStore = new SqliteJobStore(
+          this.config.runtimeJobsDbPath ?? join(this.config.dataDir, "runtime-jobs.db")
+        );
+        this.runtimeJobManager = new JobManager(this.rpc, this.runtimeJobStore);
+        this.runtimeJobManager.start();
+      }
+      this.initialized = true;
+      const nodeInfo = await this.rpc.nodeInfo();
+      this.policy.addAuditEntry("NODE_STARTED", true, {
+        nodeId: nodeInfo.node_id
+      });
+      return {
+        success: true,
+        data: {
+          nodeId: nodeInfo.node_id
+        },
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "INIT_FAILED", false);
+    }
+  }
+  /**
+   * Shutdown the FiberPay instance
+   */
+  async shutdown() {
+    try {
+      if (this.paymentProofManager) {
+        await this.paymentProofManager.save();
+      }
+      if (this.runtimeJobManager) {
+        await this.runtimeJobManager.stop();
+      }
+      if (this.runtimeJobStore) {
+        this.runtimeJobStore.close();
+      }
+      if (this.process?.isRunning()) {
+        await this.process.stop();
+      }
+      this.policy.addAuditEntry("NODE_STOPPED", true, {});
+      this.initialized = false;
+      return { success: true, metadata: { timestamp: Date.now() } };
+    } catch (error) {
+      return this.errorResult(error, "SHUTDOWN_FAILED", true);
+    }
+  }
+  // ===========================================================================
+  // Payment Methods (AI Agent Friendly)
+  // ===========================================================================
+  /**
+   * Pay an invoice or send directly to a node
+   *
+   * @example
+   * // Pay invoice
+   * await fiber.pay({ invoice: 'fibt1...' });
+   *
+   * // Send directly (keysend)
+   * await fiber.pay({
+   *   recipientNodeId: 'QmXXX...',
+   *   amountCkb: 10,
+   * });
+   */
+  async pay(params) {
+    this.ensureInitialized();
+    try {
+      let amountHex;
+      let recipient;
+      if (params.invoice) {
+        const parsed = await this.getRpc().parseInvoice({ invoice: params.invoice });
+        amountHex = parsed.invoice.amount || "0x0";
+        recipient = params.invoice;
+      } else if (params.recipientNodeId && params.amountCkb) {
+        amountHex = ckbToShannons(params.amountCkb);
+        recipient = params.recipientNodeId;
+      } else {
+        return this.errorResult(
+          new Error("Either invoice or (recipientNodeId + amountCkb) required"),
+          "INVALID_PARAMS",
+          true
+        );
+      }
+      const policyCheck = this.policy.checkPayment({
+        amount: amountHex,
+        recipient
+      });
+      if (!policyCheck.allowed) {
+        this.policy.addAuditEntry("POLICY_VIOLATION", false, params, policyCheck.violations);
+        return {
+          success: false,
+          error: {
+            code: "POLICY_VIOLATION",
+            message: policyCheck.violations.map((v) => v.message).join("; "),
+            recoverable: false,
+            suggestion: "Reduce amount or wait for spending window to reset"
+          },
+          metadata: { timestamp: Date.now(), policyCheck }
+        };
+      }
+      const paymentParams = {
+        invoice: params.invoice,
+        target_pubkey: params.recipientNodeId,
+        amount: params.recipientNodeId ? amountHex : void 0,
+        keysend: params.recipientNodeId ? true : void 0,
+        max_fee_amount: params.maxFeeCkb ? ckbToShannons(params.maxFeeCkb) : void 0,
+        custom_records: params.customRecords,
+        max_parts: params.maxParts ? toHex(params.maxParts) : void 0
+      };
+      let result;
+      if (this.runtimeJobManager) {
+        const job = await this.runtimeJobManager.ensurePayment(
+          {
+            invoice: params.invoice,
+            sendPaymentParams: paymentParams
+          },
+          {
+            idempotencyKey: params.invoice ? `payment:invoice:${params.invoice}` : void 0
+          }
+        );
+        const terminal = await this.waitForRuntimeJobTerminal(job.id, 12e4);
+        if (terminal.type !== "payment" || terminal.state !== "succeeded" || !terminal.result) {
+          throw new Error(terminal.error?.message ?? "Runtime payment job failed");
+        }
+        result = {
+          payment_hash: terminal.result.paymentHash,
+          status: terminal.result.status,
+          fee: terminal.result.fee,
+          failed_error: terminal.result.failedError,
+          created_at: "0x0",
+          last_updated_at: "0x0",
+          custom_records: void 0,
+          routers: void 0
+        };
+      } else {
+        result = await this.getRpc().sendPayment(paymentParams);
+      }
+      if (result.status === "Success") {
+        this.policy.recordPayment(amountHex);
+      }
+      const paymentResult = {
+        paymentHash: result.payment_hash,
+        status: result.status === "Success" ? "success" : result.status === "Failed" ? "failed" : "pending",
+        amountCkb: shannonsToCkb(amountHex),
+        feeCkb: shannonsToCkb(result.fee),
+        failureReason: result.failed_error
+      };
+      if (this.paymentProofManager && result.status === "Success") {
+        this.paymentProofManager.recordPaymentProof(
+          result.payment_hash,
+          params.invoice || "",
+          {
+            paymentHash: result.payment_hash,
+            amountCkb: paymentResult.amountCkb,
+            description: ""
+          },
+          {
+            amountCkb: paymentResult.amountCkb,
+            feeCkb: paymentResult.feeCkb,
+            actualTimestamp: Date.now(),
+            requestTimestamp: Date.now()
+          },
+          result.status,
+          {
+            preimage: void 0
+            // Would need to get from RPC if available
+          }
+        );
+        this.paymentProofManager.save().catch(() => {
+        });
+      }
+      this.policy.addAuditEntry("PAYMENT_SENT", result.status === "Success", {
+        ...paymentResult,
+        recipient
+      });
+      return {
+        success: result.status === "Success",
+        data: paymentResult,
+        metadata: { timestamp: Date.now(), policyCheck }
+      };
+    } catch (error) {
+      return this.errorResult(error, "PAYMENT_FAILED", true);
+    }
+  }
+  /**
+   * Create an invoice to receive payment
+   *
+   * @example
+   * const invoice = await fiber.createInvoice({
+   *   amountCkb: 10,
+   *   description: 'For coffee',
+   *   expiryMinutes: 60,
+   * });
+   * console.log(invoice.data?.invoice); // Share this with payer
+   */
+  async createInvoice(params) {
+    this.ensureInitialized();
+    try {
+      const amountHex = ckbToShannons(params.amountCkb);
+      const expirySeconds = (params.expiryMinutes || 60) * 60;
+      const preimage = randomBytes32();
+      const invoiceParams = {
+        amount: amountHex,
+        currency: this.config.chain === "mainnet" ? "Fibb" : "Fibt",
+        description: params.description,
+        expiry: toHex(expirySeconds),
+        payment_preimage: preimage
+      };
+      let invoiceAddress;
+      let paymentHash;
+      if (this.runtimeJobManager) {
+        const job = await this.runtimeJobManager.manageInvoice({
+          action: "create",
+          newInvoiceParams: invoiceParams,
+          waitForTerminal: false
+        });
+        const terminal = await this.waitForRuntimeJobTerminal(job.id, 12e4);
+        if (terminal.type !== "invoice" || terminal.state !== "succeeded" || !terminal.result?.invoiceAddress || !terminal.result.paymentHash) {
+          throw new Error(terminal.error?.message ?? "Runtime invoice job failed");
+        }
+        invoiceAddress = terminal.result.invoiceAddress;
+        paymentHash = terminal.result.paymentHash;
+      } else {
+        const result = await this.getRpc().newInvoice(invoiceParams);
+        invoiceAddress = result.invoice_address;
+        paymentHash = result.invoice.data.payment_hash;
+      }
+      const expiresAt = new Date(Date.now() + expirySeconds * 1e3).toISOString();
+      const invoiceResult = {
+        invoice: invoiceAddress,
+        paymentHash,
+        amountCkb: params.amountCkb,
+        expiresAt,
+        status: "open"
+      };
+      this.policy.addAuditEntry("INVOICE_CREATED", true, { ...invoiceResult });
+      return {
+        success: true,
+        data: invoiceResult,
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "INVOICE_FAILED", true);
+    }
+  }
+  /**
+   * Get current balance information
+   */
+  async getBalance() {
+    this.ensureInitialized();
+    try {
+      const channels = await this.getRpc().listChannels({});
+      let totalLocal = 0n;
+      let totalRemote = 0n;
+      let activeChannels = 0;
+      for (const channel of channels.channels) {
+        if (channel.state.state_name === ChannelState.ChannelReady) {
+          totalLocal += fromHex(channel.local_balance);
+          totalRemote += fromHex(channel.remote_balance);
+          activeChannels++;
+        }
+      }
+      const allowance = this.policy.getRemainingAllowance();
+      return {
+        success: true,
+        data: {
+          totalCkb: Number(totalLocal) / 1e8,
+          availableToSend: Number(totalLocal) / 1e8,
+          availableToReceive: Number(totalRemote) / 1e8,
+          channelCount: activeChannels,
+          spendingAllowance: Number(allowance.perWindow) / 1e8
+        },
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "BALANCE_FAILED", true);
+    }
+  }
+  /**
+   * Check payment status
+   */
+  async getPaymentStatus(paymentHash) {
+    this.ensureInitialized();
+    try {
+      const result = await this.getRpc().getPayment({ payment_hash: paymentHash });
+      return {
+        success: true,
+        data: {
+          paymentHash: result.payment_hash,
+          status: result.status === "Success" ? "success" : result.status === "Failed" ? "failed" : "pending",
+          amountCkb: 0,
+          // Amount not returned from get_payment
+          feeCkb: shannonsToCkb(result.fee),
+          failureReason: result.failed_error
+        },
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "STATUS_CHECK_FAILED", true);
+    }
+  }
+  /**
+   * Check invoice status
+   */
+  async getInvoiceStatus(paymentHash) {
+    this.ensureInitialized();
+    try {
+      const result = await this.getRpc().getInvoice({ payment_hash: paymentHash });
+      const amountCkb = result.invoice.amount ? shannonsToCkb(result.invoice.amount) : 0;
+      const expiresAt = this.getInvoiceExpiryIso(result.invoice);
+      return {
+        success: true,
+        data: {
+          invoice: result.invoice_address,
+          paymentHash: result.invoice.data.payment_hash,
+          amountCkb,
+          expiresAt,
+          status: this.mapInvoiceStatus(result.status)
+        },
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "INVOICE_STATUS_FAILED", true);
+    }
+  }
+  // ===========================================================================
+  // Channel Management
+  // ===========================================================================
+  /**
+   * List all channels
+   */
+  async listChannels() {
+    this.ensureInitialized();
+    try {
+      const result = await this.getRpc().listChannels({});
+      const channels = result.channels.map((ch) => ({
+        id: ch.channel_id,
+        peerId: ch.peer_id,
+        localBalanceCkb: shannonsToCkb(ch.local_balance),
+        remoteBalanceCkb: shannonsToCkb(ch.remote_balance),
+        state: ch.state.state_name,
+        isPublic: ch.is_public
+      }));
+      return {
+        success: true,
+        data: channels,
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "LIST_CHANNELS_FAILED", true);
+    }
+  }
+  /**
+   * Open a new channel
+   */
+  async openChannel(params) {
+    this.ensureInitialized();
+    try {
+      const fundingHex = ckbToShannons(params.fundingCkb);
+      const channels = await this.getRpc().listChannels({});
+      const policyCheck = this.policy.checkChannelOperation({
+        operation: "open",
+        fundingAmount: fundingHex,
+        currentChannelCount: channels.channels.length
+      });
+      if (!policyCheck.allowed) {
+        this.policy.addAuditEntry("POLICY_VIOLATION", false, params, policyCheck.violations);
+        return {
+          success: false,
+          error: {
+            code: "POLICY_VIOLATION",
+            message: policyCheck.violations.map((v) => v.message).join("; "),
+            recoverable: false
+          },
+          metadata: { timestamp: Date.now(), policyCheck }
+        };
+      }
+      if (params.peer.includes("/")) {
+        await this.getRpc().connectPeer({ address: params.peer });
+        const peerIdMatch = params.peer.match(/\/p2p\/([^/]+)/);
+        if (peerIdMatch) {
+          params.peer = peerIdMatch[1];
+        }
+      }
+      const openParams = {
+        peer_id: params.peer,
+        funding_amount: fundingHex,
+        public: params.isPublic ?? true
+      };
+      const idempotencyKey = params.idempotencyKey ?? `open:${openParams.peer_id}:${randomUUID()}`;
+      let temporaryChannelId;
+      if (this.runtimeJobManager) {
+        const job = await this.runtimeJobManager.manageChannel(
+          {
+            action: "open",
+            openChannelParams: openParams,
+            waitForReady: false,
+            peerId: params.peer
+          },
+          { idempotencyKey }
+        );
+        const terminal = await this.waitForRuntimeJobTerminal(job.id, 12e4);
+        if (terminal.type !== "channel" || terminal.state !== "succeeded" || !terminal.result?.temporaryChannelId) {
+          throw new Error(terminal.error?.message ?? "Runtime channel open job failed");
+        }
+        temporaryChannelId = terminal.result.temporaryChannelId;
+      } else {
+        const result = await this.getRpc().openChannel(openParams);
+        temporaryChannelId = result.temporary_channel_id;
+      }
+      this.policy.addAuditEntry("CHANNEL_OPENED", true, {
+        channelId: temporaryChannelId,
+        peer: params.peer,
+        fundingCkb: params.fundingCkb
+      });
+      return {
+        success: true,
+        data: { channelId: temporaryChannelId },
+        metadata: { timestamp: Date.now(), policyCheck }
+      };
+    } catch (error) {
+      return this.errorResult(error, "OPEN_CHANNEL_FAILED", true);
+    }
+  }
+  /**
+   * Close a channel
+   */
+  async closeChannel(params) {
+    this.ensureInitialized();
+    try {
+      const operation = params.force ? "force_close" : "close";
+      const policyCheck = this.policy.checkChannelOperation({ operation });
+      if (!policyCheck.allowed) {
+        this.policy.addAuditEntry("POLICY_VIOLATION", false, params, policyCheck.violations);
+        return {
+          success: false,
+          error: {
+            code: "POLICY_VIOLATION",
+            message: policyCheck.violations.map((v) => v.message).join("; "),
+            recoverable: false
+          },
+          metadata: { timestamp: Date.now(), policyCheck }
+        };
+      }
+      if (this.runtimeJobManager) {
+        const job = await this.runtimeJobManager.manageChannel(
+          {
+            action: "shutdown",
+            channelId: params.channelId,
+            shutdownChannelParams: {
+              channel_id: params.channelId,
+              force: params.force
+            },
+            waitForClosed: false
+          },
+          { idempotencyKey: `channel:shutdown:${params.channelId}` }
+        );
+        const terminal = await this.waitForRuntimeJobTerminal(job.id, 12e4);
+        if (terminal.type !== "channel" || terminal.state !== "succeeded") {
+          throw new Error(terminal.error?.message ?? "Runtime channel close job failed");
+        }
+      } else {
+        await this.getRpc().shutdownChannel({
+          channel_id: params.channelId,
+          force: params.force
+        });
+      }
+      this.policy.addAuditEntry("CHANNEL_CLOSED", true, params);
+      return {
+        success: true,
+        metadata: { timestamp: Date.now(), policyCheck }
+      };
+    } catch (error) {
+      return this.errorResult(error, "CLOSE_CHANNEL_FAILED", true);
+    }
+  }
+  // ===========================================================================
+  // Node Information
+  // ===========================================================================
+  /**
+   * Get node information
+   */
+  async getNodeInfo() {
+    this.ensureInitialized();
+    try {
+      const info = await this.getRpc().nodeInfo();
+      return {
+        success: true,
+        data: {
+          nodeId: info.node_id,
+          version: info.version,
+          channelCount: parseInt(info.channel_count, 16),
+          peersCount: parseInt(info.peers_count, 16)
+        },
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "NODE_INFO_FAILED", true);
+    }
+  }
+  // ===========================================================================
+  // Verification & Validation Methods
+  // ===========================================================================
+  /**
+   * Validate an invoice before payment
+   * Checks format, expiry, amount, cryptographic correctness, and peer connectivity
+   *
+   * @example
+   * ```typescript
+   * const validation = await fiber.validateInvoice('fibt1...');
+   * if (validation.data?.recommendation === 'reject') {
+   *   console.log('Do not pay:', validation.data.reason);
+   * }
+   * ```
+   */
+  async validateInvoice(invoice) {
+    this.ensureInitialized();
+    try {
+      if (!this.invoiceVerifier) {
+        throw new Error("Invoice verifier not initialized");
+      }
+      const result = await this.invoiceVerifier.verifyInvoice(invoice);
+      this.policy.addAuditEntry("INVOICE_VALIDATED", true, {
+        paymentHash: result.details.paymentHash,
+        amountCkb: result.details.amountCkb,
+        valid: result.valid
+      });
+      return {
+        success: true,
+        data: result,
+        metadata: {
+          timestamp: Date.now()
+        }
+      };
+    } catch (error) {
+      return this.errorResult(error, "INVOICE_VALIDATION_FAILED", true);
+    }
+  }
+  /**
+   * Get payment proof (cryptographic evidence of payment)
+   * Returns stored proof if available, or creates one from RPC status
+   */
+  async getPaymentProof(paymentHash) {
+    this.ensureInitialized();
+    try {
+      if (!this.paymentProofManager) {
+        throw new Error("Payment proof manager not initialized");
+      }
+      const storedProof = this.paymentProofManager.getProof(paymentHash);
+      if (storedProof) {
+        const verification = this.paymentProofManager.verifyProof(storedProof);
+        await this.paymentProofManager.save();
+        return {
+          success: true,
+          data: {
+            proof: storedProof,
+            verified: verification.valid,
+            status: verification.reason
+          },
+          metadata: { timestamp: Date.now() }
+        };
+      }
+      const paymentStatus = await this.getRpc().getPayment({
+        payment_hash: paymentHash
+      });
+      return {
+        success: true,
+        data: {
+          proof: null,
+          verified: paymentStatus.status === "Success",
+          status: `Payment status: ${paymentStatus.status}`
+        },
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "PROOF_FETCH_FAILED", true);
+    }
+  }
+  /**
+   * Get payment proof summary for audit trail
+   */
+  async getPaymentProofSummary() {
+    this.ensureInitialized();
+    try {
+      if (!this.paymentProofManager) {
+        throw new Error("Payment proof manager not initialized");
+      }
+      const summary = this.paymentProofManager.getSummary();
+      return {
+        success: true,
+        data: summary,
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "PROOF_SUMMARY_FAILED", true);
+    }
+  }
+  /**
+   * Export payment audit report
+   */
+  async getPaymentAuditReport(options) {
+    this.ensureInitialized();
+    try {
+      if (!this.paymentProofManager) {
+        throw new Error("Payment proof manager not initialized");
+      }
+      const report = this.paymentProofManager.exportAuditReport(
+        options?.startTime,
+        options?.endTime
+      );
+      return {
+        success: true,
+        data: report,
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "AUDIT_REPORT_FAILED", true);
+    }
+  }
+  // ===========================================================================
+  // Hold Invoice & Settlement Methods
+  // ===========================================================================
+  /**
+   * Create a hold invoice (for escrow / conditional payments)
+   * The payer's funds are held until you explicitly settle with the preimage,
+   * or cancelled if you don't settle before expiry.
+   *
+   * @example
+   * ```typescript
+   * const invoice = await fiber.createHoldInvoice({
+   *   amountCkb: 10,
+   *   paymentHash: '0x...',  // SHA-256 hash of your secret preimage
+   *   description: 'Escrow for service',
+   * });
+   * // Share invoice.data.invoice with the payer
+   * // When conditions are met, call settleInvoice() with the preimage
+   * ```
+   */
+  async createHoldInvoice(params) {
+    this.ensureInitialized();
+    try {
+      const amountHex = ckbToShannons(params.amountCkb);
+      const expirySeconds = (params.expiryMinutes || 60) * 60;
+      const holdInvoiceParams = {
+        amount: amountHex,
+        currency: this.config.chain === "mainnet" ? "Fibb" : "Fibt",
+        description: params.description,
+        expiry: toHex(expirySeconds),
+        payment_hash: params.paymentHash
+      };
+      let invoiceAddress;
+      let paymentHash;
+      if (this.runtimeJobManager) {
+        const job = await this.runtimeJobManager.manageInvoice(
+          {
+            action: "create",
+            newInvoiceParams: holdInvoiceParams,
+            waitForTerminal: false
+          },
+          { idempotencyKey: `invoice:create:${params.paymentHash}` }
+        );
+        const terminal = await this.waitForRuntimeJobTerminal(job.id, 12e4);
+        if (terminal.type !== "invoice" || terminal.state !== "succeeded" || !terminal.result?.invoiceAddress || !terminal.result.paymentHash) {
+          throw new Error(terminal.error?.message ?? "Runtime hold invoice job failed");
+        }
+        invoiceAddress = terminal.result.invoiceAddress;
+        paymentHash = terminal.result.paymentHash;
+      } else {
+        const result = await this.getRpc().newInvoice(holdInvoiceParams);
+        invoiceAddress = result.invoice_address;
+        paymentHash = result.invoice.data.payment_hash;
+      }
+      const expiresAt = new Date(Date.now() + expirySeconds * 1e3).toISOString();
+      const invoiceResult = {
+        invoice: invoiceAddress,
+        paymentHash,
+        amountCkb: params.amountCkb,
+        expiresAt,
+        status: "open"
+      };
+      this.policy.addAuditEntry("HOLD_INVOICE_CREATED", true, { ...invoiceResult });
+      return {
+        success: true,
+        data: invoiceResult,
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "HOLD_INVOICE_FAILED", true);
+    }
+  }
+  /**
+   * Settle a hold invoice by revealing the preimage
+   * This releases the held funds to you. No policy check needed since
+   * settling receives money, it doesn't spend it.
+   *
+   * @example
+   * ```typescript
+   * await fiber.settleInvoice({
+   *   paymentHash: '0x...',
+   *   preimage: '0x...',  // The secret preimage whose hash matches paymentHash
+   * });
+   * ```
+   */
+  async settleInvoice(params) {
+    this.ensureInitialized();
+    try {
+      if (this.runtimeJobManager) {
+        const job = await this.runtimeJobManager.manageInvoice(
+          {
+            action: "settle",
+            settleInvoiceParams: {
+              payment_hash: params.paymentHash,
+              payment_preimage: params.preimage
+            }
+          },
+          { idempotencyKey: `invoice:settle:${params.paymentHash}` }
+        );
+        const terminal = await this.waitForRuntimeJobTerminal(job.id, 12e4);
+        if (terminal.type !== "invoice" || terminal.state !== "succeeded") {
+          throw new Error(terminal.error?.message ?? "Runtime settle invoice job failed");
+        }
+      } else {
+        await this.getRpc().settleInvoice({
+          payment_hash: params.paymentHash,
+          payment_preimage: params.preimage
+        });
+      }
+      this.policy.addAuditEntry("HOLD_INVOICE_SETTLED", true, {
+        paymentHash: params.paymentHash
+      });
+      return {
+        success: true,
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "SETTLE_INVOICE_FAILED", true);
+    }
+  }
+  // ===========================================================================
+  // Waiting / Watching Methods
+  // ===========================================================================
+  /**
+   * Wait for a payment to complete (Success or Failed)
+   * Wraps the SDK-level polling helper with AgentResult return type.
+   */
+  async waitForPayment(paymentHash, options) {
+    this.ensureInitialized();
+    try {
+      const result = await this.getRpc().waitForPayment(paymentHash, {
+        timeout: options?.timeoutMs
+      });
+      return {
+        success: result.status === "Success",
+        data: {
+          paymentHash: result.payment_hash,
+          status: result.status === "Success" ? "success" : result.status === "Failed" ? "failed" : "pending",
+          amountCkb: 0,
+          // Amount not returned from get_payment
+          feeCkb: shannonsToCkb(result.fee),
+          failureReason: result.failed_error
+        },
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "WAIT_PAYMENT_FAILED", true);
+    }
+  }
+  /**
+   * Wait for a channel to become ready (ChannelReady state)
+   * Useful after opening a channel — waits for on-chain confirmation.
+   */
+  async waitForChannelReady(channelId, options) {
+    this.ensureInitialized();
+    try {
+      const channel = await this.getRpc().waitForChannelReady(channelId, {
+        timeout: options?.timeoutMs
+      });
+      return {
+        success: true,
+        data: {
+          id: channel.channel_id,
+          peerId: channel.peer_id,
+          localBalanceCkb: shannonsToCkb(channel.local_balance),
+          remoteBalanceCkb: shannonsToCkb(channel.remote_balance),
+          state: channel.state.state_name,
+          isPublic: channel.is_public
+        },
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "WAIT_CHANNEL_FAILED", true);
+    }
+  }
+  // ===========================================================================
+  // Liquidity & Fund Management Methods
+  // ===========================================================================
+  /**
+   * Analyze liquidity across all channels
+   * Provides detailed health metrics and recommendations
+   *
+   * @example
+   * ```typescript
+   * const analysis = await fiber.analyzeLiquidity();
+   * console.log(`Health score: ${analysis.data?.channels.averageHealthScore}`);
+   * console.log(analysis.data?.summary);
+   * ```
+   */
+  async analyzeLiquidity() {
+    this.ensureInitialized();
+    try {
+      if (!this.liquidityAnalyzer) {
+        throw new Error("Liquidity analyzer not initialized");
+      }
+      const report = await this.liquidityAnalyzer.analyzeLiquidity();
+      return {
+        success: true,
+        data: report,
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "LIQUIDITY_ANALYSIS_FAILED", true);
+    }
+  }
+  /**
+   * Check if you have enough liquidity to send a specific amount
+   */
+  async canSend(amountCkb) {
+    this.ensureInitialized();
+    try {
+      if (!this.liquidityAnalyzer) {
+        throw new Error("Liquidity analyzer not initialized");
+      }
+      const result = await this.liquidityAnalyzer.getMissingLiquidityForAmount(amountCkb);
+      const balance = await this.getBalance();
+      const availableCkb = balance.data?.availableToSend || 0;
+      return {
+        success: true,
+        data: {
+          canSend: result.canSend,
+          shortfallCkb: result.shortfallCkb,
+          availableCkb,
+          recommendation: result.recommendation
+        },
+        metadata: { timestamp: Date.now() }
+      };
+    } catch (error) {
+      return this.errorResult(error, "LIQUIDITY_CHECK_FAILED", true);
+    }
+  }
+  // ===========================================================================
+  // Policy Management
+  // ===========================================================================
+  /**
+   * Get remaining spending allowance
+   */
+  getSpendingAllowance() {
+    const allowance = this.policy.getRemainingAllowance();
+    return {
+      perTransactionCkb: Number(allowance.perTransaction) / 1e8,
+      perWindowCkb: Number(allowance.perWindow) / 1e8
+    };
+  }
+  /**
+   * Get audit log
+   */
+  getAuditLog(options) {
+    return this.policy.getAuditLog(options);
+  }
+  // ===========================================================================
+  // Private Helpers
+  // ===========================================================================
+  ensureInitialized() {
+    if (!this.initialized) {
+      throw new Error("FiberPay not initialized. Call initialize() first.");
+    }
+  }
+  getRpc() {
+    if (!this.rpc) {
+      throw new Error("RPC client not initialized. Call initialize() first.");
+    }
+    return this.rpc;
+  }
+  async waitForRuntimeJobTerminal(jobId, timeoutMs) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+      const job = this.runtimeJobManager?.getJob(jobId);
+      if (!job) {
+        throw new Error(`Runtime job not found: ${jobId}`);
+      }
+      if (job.state === "succeeded" || job.state === "failed" || job.state === "cancelled") {
+        return job;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 300));
+    }
+    throw new Error(`Runtime job ${jobId} timed out after ${timeoutMs}ms`);
+  }
+  /**
+   * Map RPC CkbInvoiceStatus to agent-level status string
+   */
+  mapInvoiceStatus(status) {
+    switch (status) {
+      case "Open":
+        return "open";
+      case "Received":
+        return "accepted";
+      case "Paid":
+        return "settled";
+      case "Cancelled":
+      case "Expired":
+        return "cancelled";
+      default:
+        return "open";
+    }
+  }
+  getInvoiceExpiryIso(invoice) {
+    try {
+      const createdSeconds = fromHex(invoice.data.timestamp);
+      const expiryDeltaSeconds = this.getAttributeU64(invoice.data.attrs, "ExpiryTime") ?? BigInt(60 * 60);
+      return new Date(Number(createdSeconds + expiryDeltaSeconds) * 1e3).toISOString();
+    } catch {
+      return "";
+    }
+  }
+  getAttributeU64(attrs, key) {
+    for (const attr of attrs) {
+      if (key in attr) {
+        return fromHex(attr[key]);
+      }
+    }
+    return void 0;
+  }
+  errorResult(error, code, recoverable) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      error: {
+        code,
+        message,
+        recoverable
+      },
+      metadata: { timestamp: Date.now() }
+    };
+  }
+};
+function createFiberPay(options) {
+  const dataDir = options?.dataDir || `${process.env.HOME}/.fiber-pay`;
+  return new FiberPay({
+    binaryPath: options?.binaryPath,
+    dataDir,
+    configFilePath: options?.configFilePath,
+    chain: options?.chain || options?.network || "testnet",
+    autoDownload: options?.autoDownload ?? true,
+    autoStart: options?.autoStart ?? true,
+    rpcUrl: options?.rpcUrl,
+    keyPassword: options?.keyPassword
+  });
+}
+
+// src/mcp-tools.ts
+var MCP_TOOLS = {
+  fiber_pay: {
+    name: "fiber_pay",
+    description: `Pay an invoice or send CKB directly to a node on the Lightning Network.
+    
+Examples:
+- Pay an invoice: fiber_pay({ invoice: "fibt1..." })
+- Send directly: fiber_pay({ recipientNodeId: "QmXXX...", amountCkb: 10 })
+
+Returns payment status and tracking hash.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        invoice: {
+          type: "string",
+          description: "Lightning invoice string to pay (starts with fibt or fibb)"
+        },
+        recipientNodeId: {
+          type: "string",
+          description: "Recipient node ID for direct payment (keysend)"
+        },
+        amountCkb: {
+          type: "number",
+          description: "Amount to send in CKB (required for keysend)"
+        },
+        maxFeeCkb: {
+          type: "number",
+          description: "Maximum fee willing to pay in CKB"
+        }
+      },
+      oneOf: [{ required: ["invoice"] }, { required: ["recipientNodeId", "amountCkb"] }]
+    }
+  },
+  fiber_create_invoice: {
+    name: "fiber_create_invoice",
+    description: `Create an invoice to receive payment.
+    
+Example: fiber_create_invoice({ amountCkb: 10, description: "For coffee" })
+
+Returns invoice string to share with payer.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        amountCkb: {
+          type: "number",
+          description: "Amount to receive in CKB"
+        },
+        description: {
+          type: "string",
+          description: "Description for the payer"
+        },
+        expiryMinutes: {
+          type: "number",
+          description: "Invoice expiry time in minutes (default: 60)"
+        }
+      },
+      required: ["amountCkb"]
+    }
+  },
+  fiber_get_balance: {
+    name: "fiber_get_balance",
+    description: `Get current balance information including:
+- Total balance in CKB
+- Available to send
+- Available to receive
+- Number of channels
+- Remaining spending allowance
+
+No parameters required.`,
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  fiber_get_payment_status: {
+    name: "fiber_get_payment_status",
+    description: `Check the status of a payment by its hash.
+    
+Example: fiber_get_payment_status({ paymentHash: "0x..." })`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        paymentHash: {
+          type: "string",
+          description: "Payment hash to check"
+        }
+      },
+      required: ["paymentHash"]
+    }
+  },
+  fiber_get_invoice_status: {
+    name: "fiber_get_invoice_status",
+    description: `Check the status of an invoice (whether it's been paid).
+    
+Example: fiber_get_invoice_status({ paymentHash: "0x..." })`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        paymentHash: {
+          type: "string",
+          description: "Payment hash of the invoice"
+        }
+      },
+      required: ["paymentHash"]
+    }
+  },
+  fiber_list_channels: {
+    name: "fiber_list_channels",
+    description: `List all payment channels with their balances and states.
+
+No parameters required.`,
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  fiber_open_channel: {
+    name: "fiber_open_channel",
+    description: `Open a new payment channel with a peer.
+    
+Example: fiber_open_channel({ 
+  peer: "/ip4/x.x.x.x/tcp/8228/p2p/QmXXX...", 
+  fundingCkb: 100 
+})
+
+Note: This requires on-chain CKB for funding.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        peer: {
+          type: "string",
+          description: "Peer multiaddr or node ID"
+        },
+        fundingCkb: {
+          type: "number",
+          description: "Amount of CKB to fund the channel"
+        },
+        isPublic: {
+          type: "boolean",
+          description: "Whether to make the channel public (default: true)"
+        }
+      },
+      required: ["peer", "fundingCkb"]
+    }
+  },
+  fiber_close_channel: {
+    name: "fiber_close_channel",
+    description: `Close a payment channel and settle funds on-chain.
+    
+Example: fiber_close_channel({ channelId: "0x..." })
+
+Use force: true only if peer is unresponsive.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        channelId: {
+          type: "string",
+          description: "Channel ID to close"
+        },
+        force: {
+          type: "boolean",
+          description: "Force close (unilateral, use only if peer unresponsive)"
+        }
+      },
+      required: ["channelId"]
+    }
+  },
+  fiber_get_node_info: {
+    name: "fiber_get_node_info",
+    description: `Get information about this node including node ID, public key, and statistics.
+
+No parameters required.`,
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  fiber_get_spending_allowance: {
+    name: "fiber_get_spending_allowance",
+    description: `Get remaining spending allowance based on security policy.
+
+Returns:
+- Per-transaction limit in CKB
+- Remaining allowance for current time window
+
+No parameters required.`,
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  fiber_download_binary: {
+    name: "fiber_download_binary",
+    description: `Download and install the Fiber Network Node (fnn) binary for the current platform.
+
+This is required before using any Fiber payment features. The binary will be automatically 
+downloaded from GitHub releases and installed to the data directory.
+
+Examples:
+- Download latest: fiber_download_binary({})
+- Download specific version: fiber_download_binary({ version: "v0.4.0" })
+- Force re-download: fiber_download_binary({ force: true })
+
+Returns the path to the installed binary.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        version: {
+          type: "string",
+          description: 'Specific version to download (e.g., "v0.4.0"). Defaults to latest.'
+        },
+        force: {
+          type: "boolean",
+          description: "Force re-download even if binary already exists"
+        }
+      }
+    }
+  },
+  fiber_validate_invoice: {
+    name: "fiber_validate_invoice",
+    description: `Validate an invoice before payment. Checks format, cryptographic correctness, expiry, 
+amount, and peer connectivity. Returns recommendation to proceed, warn, or reject.
+
+Use this BEFORE paying an invoice to ensure safety.
+
+Example: fiber_validate_invoice({ invoice: "fibt1..." })
+
+Returns:
+- valid: boolean (overall validity)
+- details: parsed invoice details (amount, expiry, payment hash)
+- checks: individual validation results (format, expiry, amount, preimage, peer)
+- issues: list of warnings and critical issues found
+- recommendation: 'proceed' | 'warn' | 'reject'
+- reason: human-readable recommendation reason`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        invoice: {
+          type: "string",
+          description: "Invoice string to validate (starts with fibt or fibb)"
+        }
+      },
+      required: ["invoice"]
+    }
+  },
+  fiber_get_payment_proof: {
+    name: "fiber_get_payment_proof",
+    description: `Get cryptographic proof of payment execution. Useful for audit trail and reconciliation.
+
+Example: fiber_get_payment_proof({ paymentHash: "0x..." })
+
+Returns stored payment proof including:
+- Invoice original
+- Preimage (if available)
+- Fee breakdown
+- Verification status
+- Proof metadata`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        paymentHash: {
+          type: "string",
+          description: "Payment hash to retrieve proof for"
+        }
+      },
+      required: ["paymentHash"]
+    }
+  },
+  fiber_analyze_liquidity: {
+    name: "fiber_analyze_liquidity",
+    description: `Comprehensive liquidity analysis across all channels. Provides health metrics,
+identifies issues, and generates recommendations for rebalancing and funding.
+
+Use this to:
+- Understand current channel health
+- Identify liquidity gaps
+- Get rebalancing recommendations
+- Estimate available runway
+
+No parameters required.
+
+Returns:
+- balance: total, available to send/receive
+- channels: health metrics for each channel
+- liquidity: gaps and runway estimation
+- recommendations: rebalance suggestions and funding needs
+- summary: human-readable status`,
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  fiber_can_send: {
+    name: "fiber_can_send",
+    description: `Check if you have enough liquidity to send a specific amount. Returns shortfall 
+if insufficient and recommendations.
+
+Use this BEFORE attempting a payment to verify you have enough liquidity.
+
+Example: fiber_can_send({ amountCkb: 100 })
+
+Returns:
+- canSend: boolean
+- shortfallCkb: missing amount (0 if can send)
+- availableCkb: current available balance
+- recommendation: what to do if insufficient`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        amountCkb: {
+          type: "number",
+          description: "Amount in CKB to check"
+        }
+      },
+      required: ["amountCkb"]
+    }
+  },
+  fiber_create_hold_invoice: {
+    name: "fiber_create_hold_invoice",
+    description: `Create a hold invoice for escrow or conditional payments.
+    
+A hold invoice locks the payer's funds until you explicitly settle with the preimage,
+or the invoice expires. This enables escrow patterns without a trusted third party.
+
+Example: fiber_create_hold_invoice({ 
+  amountCkb: 10, 
+  paymentHash: "0x...", 
+  description: "Escrow for service delivery" 
+})
+
+Flow:
+1. Generate a secret preimage and compute its SHA-256 hash
+2. Create hold invoice with the hash
+3. Share invoice with payer \u2014 their funds are held when they pay
+4. When conditions are met, call fiber_settle_invoice with the preimage
+5. If conditions are NOT met, let the invoice expire (funds return to payer)
+
+Returns invoice string and payment hash.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        amountCkb: {
+          type: "number",
+          description: "Amount to receive in CKB"
+        },
+        paymentHash: {
+          type: "string",
+          description: "SHA-256 hash of your secret preimage (0x-prefixed hex)"
+        },
+        description: {
+          type: "string",
+          description: "Description for the payer"
+        },
+        expiryMinutes: {
+          type: "number",
+          description: "Invoice expiry time in minutes (default: 60)"
+        }
+      },
+      required: ["amountCkb", "paymentHash"]
+    }
+  },
+  fiber_settle_invoice: {
+    name: "fiber_settle_invoice",
+    description: `Settle a hold invoice by revealing the preimage.
+    
+This releases the held funds to you. Only call this after conditions are met.
+The preimage must hash (SHA-256) to the payment_hash used when creating the hold invoice.
+
+Example: fiber_settle_invoice({ 
+  paymentHash: "0x...", 
+  preimage: "0x..." 
+})`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        paymentHash: {
+          type: "string",
+          description: "Payment hash of the hold invoice"
+        },
+        preimage: {
+          type: "string",
+          description: "Secret preimage (0x-prefixed hex, 32 bytes)"
+        }
+      },
+      required: ["paymentHash", "preimage"]
+    }
+  },
+  fiber_wait_for_payment: {
+    name: "fiber_wait_for_payment",
+    description: `Wait for a payment to complete (reach Success or Failed status).
+    
+Polls the payment status until it reaches a terminal state. Useful after sending
+a payment to wait for confirmation.
+
+Example: fiber_wait_for_payment({ paymentHash: "0x...", timeoutMs: 60000 })
+
+Returns the final payment status.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        paymentHash: {
+          type: "string",
+          description: "Payment hash to wait for"
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Timeout in milliseconds (default: 120000 = 2 min)"
+        }
+      },
+      required: ["paymentHash"]
+    }
+  },
+  fiber_wait_for_channel_ready: {
+    name: "fiber_wait_for_channel_ready",
+    description: `Wait for a channel to become ready after opening.
+    
+After opening a channel, it takes time for the funding transaction to be confirmed
+on-chain. This tool polls until the channel reaches ChannelReady state.
+
+Example: fiber_wait_for_channel_ready({ channelId: "0x...", timeoutMs: 300000 })
+
+Returns channel info once ready.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        channelId: {
+          type: "string",
+          description: "Channel ID to wait for"
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Timeout in milliseconds (default: 300000 = 5 min)"
+        }
+      },
+      required: ["channelId"]
+    }
+  }
+};
+export {
+  FiberPay,
+  MCP_TOOLS,
+  createFiberPay
+};
+//# sourceMappingURL=index.js.map