@t402/btc 2.7.0

package/README.md

@@ -0,0 +1,120 @@
+# @t402/btc
+
+Bitcoin & Lightning Network payment mechanism for the t402 protocol.
+
+Supports:
+
+- **BTC On-chain**: PSBT-based payments using the `exact` scheme
+- **Lightning Network**: BOLT11 invoice payments with preimage verification
+
+## Installation
+
+```bash
+npm install @t402/btc @t402/core
+# or
+pnpm add @t402/btc @t402/core
+```
+
+For PSBT construction with bitcoinjs-lib (optional):
+
+```bash
+npm install bitcoinjs-lib
+```
+
+## Networks
+
+| Network           | CAIP-2 ID                                 |
+| ----------------- | ----------------------------------------- |
+| BTC Mainnet       | `bip122:000000000019d6689c085ae165831e93` |
+| BTC Testnet       | `bip122:000000000933ea01ad0ee984209779ba` |
+| Lightning Mainnet | `lightning:mainnet`                       |
+| Lightning Testnet | `lightning:testnet`                       |
+
+## Usage
+
+### BTC On-chain Client
+
+```typescript
+import { registerExactBtcScheme } from '@t402/btc/exact/client'
+import { t402Client } from '@t402/core/client'
+
+const client = new t402Client()
+registerExactBtcScheme(client, {
+  signer: {
+    signPsbt: async (psbt) => {
+      /* sign PSBT */
+    },
+    getAddress: () => 'bc1q...',
+    getPublicKey: () => '02...',
+  },
+})
+```
+
+### Lightning Client
+
+```typescript
+import { registerLightningScheme } from '@t402/btc/lightning/client'
+import { t402Client } from '@t402/core/client'
+
+const client = new t402Client()
+registerLightningScheme(client, {
+  signer: {
+    payInvoice: async (bolt11) => {
+      // Pay invoice via your Lightning node
+      return { preimage: '...', paymentHash: '...' }
+    },
+    getNodePubKey: () => '02...',
+  },
+})
+```
+
+### Server (Resource Server)
+
+```typescript
+import { registerExactBtcScheme } from '@t402/btc/exact/server'
+import { registerLightningScheme } from '@t402/btc/lightning/server'
+import { t402ResourceServer } from '@t402/core/server'
+
+const server = new t402ResourceServer(facilitatorClient)
+
+// BTC on-chain
+registerExactBtcScheme(server, {
+  schemeConfig: { payTo: 'bc1q...' },
+})
+
+// Lightning
+registerLightningScheme(server, {
+  schemeConfig: {
+    generateInvoice: async (amountSats, description, expiry) => {
+      // Generate BOLT11 invoice via your Lightning node
+      return { bolt11Invoice: 'lnbc...', paymentHash: '...' }
+    },
+  },
+})
+```
+
+### Facilitator
+
+```typescript
+import { registerExactBtcScheme } from '@t402/btc/exact/facilitator'
+import { registerLightningScheme } from '@t402/btc/lightning/facilitator'
+import { t402Facilitator } from '@t402/core/facilitator'
+
+const facilitator = new t402Facilitator()
+
+// BTC on-chain
+registerExactBtcScheme(facilitator, {
+  signer: btcFacilitatorSigner,
+  networks: 'bip122:000000000019d6689c085ae165831e93',
+})
+
+// Lightning
+registerLightningScheme(facilitator, {
+  signer: lnFacilitatorSigner,
+  networks: 'lightning:mainnet',
+})
+```
+
+## License
+
+Apache-2.0

package/dist/cjs/exact/client/index.d.ts

@@ -0,0 +1,89 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload, Network } from '@t402/core/types';
+import { C as ClientBtcSigner } from '../../signer-B_Z4WGLa.js';
+import { PaymentPolicy, t402Client } from '@t402/core/client';
+
+/**
+ * Bitcoin On-chain Client Scheme Implementation
+ *
+ * Creates payment payloads for Bitcoin on-chain transfers using the exact scheme.
+ * Builds PSBTs (Partially Signed Bitcoin Transactions) and signs them with the client's wallet.
+ */
+
+/**
+ * Bitcoin client implementation for the Exact payment scheme.
+ *
+ * Creates signed PSBTs for on-chain Bitcoin payments that can be
+ * finalized and broadcast by a facilitator.
+ */
+declare class ExactBtcScheme implements SchemeNetworkClient {
+    private readonly signer;
+    readonly scheme = "exact";
+    /**
+     * Creates a new ExactBtcScheme instance.
+     *
+     * @param signer - The Bitcoin signer for client operations
+     */
+    constructor(signer: ClientBtcSigner);
+    /**
+     * Creates a payment payload for the Exact scheme.
+     *
+     * The payload contains a signed PSBT with a single output
+     * paying the required amount to the payTo address.
+     *
+     * @param t402Version - The t402 protocol version
+     * @param paymentRequirements - The payment requirements
+     * @returns Promise resolving to a payment payload
+     */
+    createPaymentPayload(t402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, 't402Version' | 'payload'>>;
+    /**
+     * Build an unsigned PSBT for the payment.
+     *
+     * Creates a minimal PSBT representation with the required output.
+     * The actual UTXO selection and fee calculation should be handled
+     * by the signer implementation (which typically has wallet context).
+     *
+     * @param requirements - Payment requirements
+     * @returns Base64-encoded unsigned PSBT
+     */
+    private buildUnsignedPsbt;
+}
+
+/**
+ * Configuration options for registering BTC schemes to an t402Client
+ */
+interface BtcClientConfig {
+    /**
+     * The Bitcoin signer to use for creating payment payloads
+     */
+    signer: ClientBtcSigner;
+    /**
+     * Optional policies to apply to the client
+     */
+    policies?: PaymentPolicy[];
+    /**
+     * Optional specific networks to register
+     * If not provided, registers wildcard support (bip122:*)
+     */
+    networks?: Network[];
+}
+/**
+ * Registers Bitcoin exact payment schemes to an t402Client instance.
+ *
+ * @param client - The t402Client instance to register schemes to
+ * @param config - Configuration for BTC client registration
+ * @returns The client instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactBtcScheme } from "@t402/btc/exact/client";
+ * import { t402Client } from "@t402/core/client";
+ *
+ * const client = new t402Client();
+ * registerExactBtcScheme(client, {
+ *   signer: myBtcSigner,
+ * });
+ * ```
+ */
+declare function registerExactBtcScheme(client: t402Client, config: BtcClientConfig): t402Client;
+
+export { type BtcClientConfig, ExactBtcScheme, registerExactBtcScheme };

package/dist/cjs/exact/client/index.js

@@ -0,0 +1,145 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/exact/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  ExactBtcScheme: () => ExactBtcScheme,
+  registerExactBtcScheme: () => registerExactBtcScheme
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/constants.ts
+var BTC_MAINNET = "bip122:000000000019d6689c085ae165831e93";
+var BTC_TESTNET = "bip122:000000000933ea01ad0ee984209779ba";
+var LIGHTNING_MAINNET = "lightning:mainnet";
+var LIGHTNING_TESTNET = "lightning:testnet";
+var BTC_NETWORKS = [BTC_MAINNET, BTC_TESTNET];
+var LIGHTNING_NETWORKS = [LIGHTNING_MAINNET, LIGHTNING_TESTNET];
+var ALL_NETWORKS = [...BTC_NETWORKS, ...LIGHTNING_NETWORKS];
+var DUST_LIMIT = 546;
+var SCHEME_EXACT = "exact";
+var MAINNET_ADDRESS_PREFIXES = ["bc1", "1", "3"];
+var TESTNET_ADDRESS_PREFIXES = ["tb1", "m", "n", "2"];
+
+// src/utils.ts
+function validateBitcoinAddress(address) {
+  if (!address || address.length < 14 || address.length > 90) {
+    return false;
+  }
+  const allPrefixes = [...MAINNET_ADDRESS_PREFIXES, ...TESTNET_ADDRESS_PREFIXES];
+  return allPrefixes.some((prefix) => address.startsWith(prefix));
+}
+
+// src/exact/client/scheme.ts
+var ExactBtcScheme = class {
+  /**
+   * Creates a new ExactBtcScheme instance.
+   *
+   * @param signer - The Bitcoin signer for client operations
+   */
+  constructor(signer) {
+    this.signer = signer;
+    __publicField(this, "scheme", SCHEME_EXACT);
+  }
+  /**
+   * Creates a payment payload for the Exact scheme.
+   *
+   * The payload contains a signed PSBT with a single output
+   * paying the required amount to the payTo address.
+   *
+   * @param t402Version - The t402 protocol version
+   * @param paymentRequirements - The payment requirements
+   * @returns Promise resolving to a payment payload
+   */
+  async createPaymentPayload(t402Version, paymentRequirements) {
+    if (!paymentRequirements.payTo) {
+      throw new Error("PayTo address is required");
+    }
+    if (!paymentRequirements.amount) {
+      throw new Error("Amount is required");
+    }
+    if (!validateBitcoinAddress(paymentRequirements.payTo)) {
+      throw new Error(`Invalid Bitcoin address: ${paymentRequirements.payTo}`);
+    }
+    const amountSats = BigInt(paymentRequirements.amount);
+    if (amountSats < BigInt(DUST_LIMIT)) {
+      throw new Error(`Amount ${amountSats} satoshis is below dust limit (${DUST_LIMIT})`);
+    }
+    const unsignedPsbt = this.buildUnsignedPsbt(paymentRequirements);
+    const signedPsbt = await this.signer.signPsbt(unsignedPsbt);
+    const payload = {
+      signedPsbt
+    };
+    return {
+      t402Version,
+      payload
+    };
+  }
+  /**
+   * Build an unsigned PSBT for the payment.
+   *
+   * Creates a minimal PSBT representation with the required output.
+   * The actual UTXO selection and fee calculation should be handled
+   * by the signer implementation (which typically has wallet context).
+   *
+   * @param requirements - Payment requirements
+   * @returns Base64-encoded unsigned PSBT
+   */
+  buildUnsignedPsbt(requirements) {
+    const psbtData = {
+      outputs: [
+        {
+          address: requirements.payTo,
+          value: requirements.amount
+        }
+      ],
+      network: requirements.network,
+      fromAddress: this.signer.getAddress(),
+      fromPubKey: this.signer.getPublicKey()
+    };
+    return Buffer.from(JSON.stringify(psbtData)).toString("base64");
+  }
+};
+
+// src/exact/client/register.ts
+function registerExactBtcScheme(client, config) {
+  const scheme = new ExactBtcScheme(config.signer);
+  if (config.networks && config.networks.length > 0) {
+    config.networks.forEach((network) => {
+      client.register(network, scheme);
+    });
+  } else {
+    client.register("bip122:*", scheme);
+  }
+  if (config.policies) {
+    config.policies.forEach((policy) => {
+      client.registerPolicy(policy);
+    });
+  }
+  return client;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExactBtcScheme,
+  registerExactBtcScheme
+});
+//# sourceMappingURL=index.js.map

package/dist/cjs/exact/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/exact/client/index.ts","../../../../src/constants.ts","../../../../src/utils.ts","../../../../src/exact/client/scheme.ts","../../../../src/exact/client/register.ts"],"sourcesContent":["export { ExactBtcScheme } from './scheme.js'\nexport { registerExactBtcScheme } from './register.js'\nexport type { BtcClientConfig } from './register.js'\n","/**\n * Bitcoin & Lightning Network Constants\n *\n * CAIP-2 network identifiers, dust limits, and fee constants.\n */\n\n/**\n * CAIP-2 Network Identifiers for Bitcoin\n * Uses BIP-122 chain genesis block hashes\n */\nexport const BTC_MAINNET = 'bip122:000000000019d6689c085ae165831e93'\nexport const BTC_TESTNET = 'bip122:000000000933ea01ad0ee984209779ba'\n\n/**\n * CAIP-2 Network Identifiers for Lightning Network\n */\nexport const LIGHTNING_MAINNET = 'lightning:mainnet'\nexport const LIGHTNING_TESTNET = 'lightning:testnet'\n\n/**\n * All supported BTC on-chain networks\n */\nexport const BTC_NETWORKS = [BTC_MAINNET, BTC_TESTNET] as const\n\n/**\n * All supported Lightning networks\n */\nexport const LIGHTNING_NETWORKS = [LIGHTNING_MAINNET, LIGHTNING_TESTNET] as const\n\n/**\n * All supported networks (on-chain + Lightning)\n */\nexport const ALL_NETWORKS = [...BTC_NETWORKS, ...LIGHTNING_NETWORKS] as const\n\nexport type BtcNetwork = (typeof BTC_NETWORKS)[number]\nexport type LightningNetwork = (typeof LIGHTNING_NETWORKS)[number]\n\n/**\n * Dust limit in satoshis - minimum viable output value\n * Outputs below this threshold are rejected by Bitcoin nodes\n */\nexport const DUST_LIMIT = 546\n\n/**\n * Minimum relay fee in satoshis\n * Transactions with fees below this are not relayed by default\n */\nexport const MIN_RELAY_FEE = 1000\n\n/**\n * Satoshis per BTC\n */\nexport const SATS_PER_BTC = 100_000_000\n\n/**\n * Scheme identifiers\n */\nexport const SCHEME_EXACT = 'exact'\n\n/**\n * Default timeout for payment validity (in seconds)\n */\nexport const DEFAULT_VALIDITY_DURATION = 3600 // 1 hour\n\n/**\n * Bitcoin address prefixes for basic validation\n */\nexport const MAINNET_ADDRESS_PREFIXES = ['bc1', '1', '3']\nexport const TESTNET_ADDRESS_PREFIXES = ['tb1', 'm', 'n', '2']\n","/**\n * Bitcoin & Lightning Utility Functions\n *\n * Helper functions for address validation, unit conversion,\n * and invoice validation.\n */\n\nimport { SATS_PER_BTC, MAINNET_ADDRESS_PREFIXES, TESTNET_ADDRESS_PREFIXES } from './constants.js'\n\n/**\n * Convert satoshis to BTC\n *\n * @param sats - Amount in satoshis\n * @returns Amount in BTC as string (to avoid floating point issues)\n */\nexport function satoshisToBtc(sats: bigint | number | string): string {\n  const satsBigInt = BigInt(sats)\n  const whole = satsBigInt / BigInt(SATS_PER_BTC)\n  const frac = satsBigInt % BigInt(SATS_PER_BTC)\n\n  if (frac === 0n) {\n    return whole.toString()\n  }\n\n  const fracStr = frac.toString().padStart(8, '0')\n  return `${whole}.${fracStr}`.replace(/\\.?0+$/, '')\n}\n\n/**\n * Convert BTC to satoshis\n *\n * @param btc - Amount in BTC (string or number)\n * @returns Amount in satoshis as bigint\n */\nexport function btcToSatoshis(btc: string | number): bigint {\n  const btcStr = typeof btc === 'number' ? btc.toString() : btc\n  const [wholePart, fracPart = ''] = btcStr.split('.')\n  const paddedFrac = fracPart.padEnd(8, '0').slice(0, 8)\n  const combined = wholePart + paddedFrac\n  const result = BigInt(combined.replace(/^0+/, '') || '0')\n  return result\n}\n\n/**\n * Validate a Bitcoin address (basic format validation)\n *\n * Checks address prefix against known formats:\n * - Mainnet: bc1 (bech32), 1 (P2PKH), 3 (P2SH)\n * - Testnet: tb1 (bech32), m/n (P2PKH), 2 (P2SH)\n *\n * @param address - Bitcoin address to validate\n * @returns true if the address has a valid format\n */\nexport function validateBitcoinAddress(address: string): boolean {\n  if (!address || address.length < 14 || address.length > 90) {\n    return false\n  }\n\n  const allPrefixes = [...MAINNET_ADDRESS_PREFIXES, ...TESTNET_ADDRESS_PREFIXES]\n  return allPrefixes.some((prefix) => address.startsWith(prefix))\n}\n\n/**\n * Check if a Bitcoin address is for mainnet\n *\n * @param address - Bitcoin address\n * @returns true if mainnet address\n */\nexport function isMainnetAddress(address: string): boolean {\n  return MAINNET_ADDRESS_PREFIXES.some((prefix) => address.startsWith(prefix))\n}\n\n/**\n * Check if a Bitcoin address is for testnet\n *\n * @param address - Bitcoin address\n * @returns true if testnet address\n */\nexport function isTestnetAddress(address: string): boolean {\n  return TESTNET_ADDRESS_PREFIXES.some((prefix) => address.startsWith(prefix))\n}\n\n/**\n * Validate a BOLT11 Lightning invoice (basic format validation)\n *\n * BOLT11 invoices follow the format:\n * - lnbc... for mainnet\n * - lntb... for testnet\n * - lnbcrt... for regtest\n *\n * @param invoice - BOLT11 invoice string\n * @returns true if the invoice has a valid format\n */\nexport function validateBolt11Invoice(invoice: string): boolean {\n  if (!invoice || invoice.length < 20) {\n    return false\n  }\n\n  const lower = invoice.toLowerCase()\n  return lower.startsWith('lnbc') || lower.startsWith('lntb') || lower.startsWith('lnbcrt')\n}\n\n/**\n * Validate a hex-encoded string\n *\n * @param hex - String to validate\n * @param expectedLength - Expected byte length (hex length / 2)\n * @returns true if valid hex of expected length\n */\nexport function isValidHex(hex: string, expectedLength?: number): boolean {\n  if (!/^[0-9a-fA-F]+$/.test(hex)) {\n    return false\n  }\n  if (expectedLength !== undefined && hex.length !== expectedLength * 2) {\n    return false\n  }\n  return true\n}\n","/**\n * Bitcoin On-chain Client Scheme Implementation\n *\n * Creates payment payloads for Bitcoin on-chain transfers using the exact scheme.\n * Builds PSBTs (Partially Signed Bitcoin Transactions) and signs them with the client's wallet.\n */\n\nimport type { PaymentPayload, PaymentRequirements, SchemeNetworkClient } from '@t402/core/types'\nimport type { ClientBtcSigner } from '../../signer.js'\nimport type { BtcOnchainPayload } from '../../types.js'\nimport { SCHEME_EXACT, DUST_LIMIT } from '../../constants.js'\nimport { validateBitcoinAddress } from '../../utils.js'\n\n/**\n * Bitcoin client implementation for the Exact payment scheme.\n *\n * Creates signed PSBTs for on-chain Bitcoin payments that can be\n * finalized and broadcast by a facilitator.\n */\nexport class ExactBtcScheme implements SchemeNetworkClient {\n  readonly scheme = SCHEME_EXACT\n\n  /**\n   * Creates a new ExactBtcScheme instance.\n   *\n   * @param signer - The Bitcoin signer for client operations\n   */\n  constructor(private readonly signer: ClientBtcSigner) {}\n\n  /**\n   * Creates a payment payload for the Exact scheme.\n   *\n   * The payload contains a signed PSBT with a single output\n   * paying the required amount to the payTo address.\n   *\n   * @param t402Version - The t402 protocol version\n   * @param paymentRequirements - The payment requirements\n   * @returns Promise resolving to a payment payload\n   */\n  async createPaymentPayload(\n    t402Version: number,\n    paymentRequirements: PaymentRequirements,\n  ): Promise<Pick<PaymentPayload, 't402Version' | 'payload'>> {\n    // Validate required fields\n    if (!paymentRequirements.payTo) {\n      throw new Error('PayTo address is required')\n    }\n    if (!paymentRequirements.amount) {\n      throw new Error('Amount is required')\n    }\n\n    // Validate address format\n    if (!validateBitcoinAddress(paymentRequirements.payTo)) {\n      throw new Error(`Invalid Bitcoin address: ${paymentRequirements.payTo}`)\n    }\n\n    // Validate amount is above dust limit\n    const amountSats = BigInt(paymentRequirements.amount)\n    if (amountSats < BigInt(DUST_LIMIT)) {\n      throw new Error(`Amount ${amountSats} satoshis is below dust limit (${DUST_LIMIT})`)\n    }\n\n    // Build an unsigned PSBT\n    // The PSBT contains: output to payTo address for the required amount\n    // Input selection and fee calculation are handled by the signer\n    const unsignedPsbt = this.buildUnsignedPsbt(paymentRequirements)\n\n    // Sign the PSBT\n    const signedPsbt = await this.signer.signPsbt(unsignedPsbt)\n\n    // Create payload\n    const payload: BtcOnchainPayload = {\n      signedPsbt,\n    }\n\n    return {\n      t402Version,\n      payload,\n    }\n  }\n\n  /**\n   * Build an unsigned PSBT for the payment.\n   *\n   * Creates a minimal PSBT representation with the required output.\n   * The actual UTXO selection and fee calculation should be handled\n   * by the signer implementation (which typically has wallet context).\n   *\n   * @param requirements - Payment requirements\n   * @returns Base64-encoded unsigned PSBT\n   */\n  private buildUnsignedPsbt(requirements: PaymentRequirements): string {\n    // Encode payment details as a JSON payload in the PSBT\n    // The signer is responsible for building the full PSBT\n    // with proper UTXO selection and fee estimation\n    const psbtData = {\n      outputs: [\n        {\n          address: requirements.payTo,\n          value: requirements.amount,\n        },\n      ],\n      network: requirements.network,\n      fromAddress: this.signer.getAddress(),\n      fromPubKey: this.signer.getPublicKey(),\n    }\n\n    // Encode as base64 for transport\n    return Buffer.from(JSON.stringify(psbtData)).toString('base64')\n  }\n}\n","import { t402Client, PaymentPolicy } from '@t402/core/client'\nimport { Network } from '@t402/core/types'\nimport { ClientBtcSigner } from '../../signer.js'\nimport { ExactBtcScheme } from './scheme.js'\n\n/**\n * Configuration options for registering BTC schemes to an t402Client\n */\nexport interface BtcClientConfig {\n  /**\n   * The Bitcoin signer to use for creating payment payloads\n   */\n  signer: ClientBtcSigner\n\n  /**\n   * Optional policies to apply to the client\n   */\n  policies?: PaymentPolicy[]\n\n  /**\n   * Optional specific networks to register\n   * If not provided, registers wildcard support (bip122:*)\n   */\n  networks?: Network[]\n}\n\n/**\n * Registers Bitcoin exact payment schemes to an t402Client instance.\n *\n * @param client - The t402Client instance to register schemes to\n * @param config - Configuration for BTC client registration\n * @returns The client instance for chaining\n *\n * @example\n * ```typescript\n * import { registerExactBtcScheme } from \"@t402/btc/exact/client\";\n * import { t402Client } from \"@t402/core/client\";\n *\n * const client = new t402Client();\n * registerExactBtcScheme(client, {\n *   signer: myBtcSigner,\n * });\n * ```\n */\nexport function registerExactBtcScheme(client: t402Client, config: BtcClientConfig): t402Client {\n  const scheme = new ExactBtcScheme(config.signer)\n\n  if (config.networks && config.networks.length > 0) {\n    config.networks.forEach((network) => {\n      client.register(network, scheme)\n    })\n  } else {\n    client.register('bip122:*', scheme)\n  }\n\n  if (config.policies) {\n    config.policies.forEach((policy) => {\n      client.registerPolicy(policy)\n    })\n  }\n\n  return client\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACUO,IAAM,cAAc;AACpB,IAAM,cAAc;AAKpB,IAAM,oBAAoB;AAC1B,IAAM,oBAAoB;AAK1B,IAAM,eAAe,CAAC,aAAa,WAAW;AAK9C,IAAM,qBAAqB,CAAC,mBAAmB,iBAAiB;AAKhE,IAAM,eAAe,CAAC,GAAG,cAAc,GAAG,kBAAkB;AAS5D,IAAM,aAAa;AAgBnB,IAAM,eAAe;AAUrB,IAAM,2BAA2B,CAAC,OAAO,KAAK,GAAG;AACjD,IAAM,2BAA2B,CAAC,OAAO,KAAK,KAAK,GAAG;;;ACftD,SAAS,uBAAuB,SAA0B;AAC/D,MAAI,CAAC,WAAW,QAAQ,SAAS,MAAM,QAAQ,SAAS,IAAI;AAC1D,WAAO;AAAA,EACT;AAEA,QAAM,cAAc,CAAC,GAAG,0BAA0B,GAAG,wBAAwB;AAC7E,SAAO,YAAY,KAAK,CAAC,WAAW,QAAQ,WAAW,MAAM,CAAC;AAChE;;;ACzCO,IAAM,iBAAN,MAAoD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQzD,YAA6B,QAAyB;AAAzB;AAP7B,wBAAS,UAAS;AAAA,EAOqC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYvD,MAAM,qBACJ,aACA,qBAC0D;AAE1D,QAAI,CAAC,oBAAoB,OAAO;AAC9B,YAAM,IAAI,MAAM,2BAA2B;AAAA,IAC7C;AACA,QAAI,CAAC,oBAAoB,QAAQ;AAC/B,YAAM,IAAI,MAAM,oBAAoB;AAAA,IACtC;AAGA,QAAI,CAAC,uBAAuB,oBAAoB,KAAK,GAAG;AACtD,YAAM,IAAI,MAAM,4BAA4B,oBAAoB,KAAK,EAAE;AAAA,IACzE;AAGA,UAAM,aAAa,OAAO,oBAAoB,MAAM;AACpD,QAAI,aAAa,OAAO,UAAU,GAAG;AACnC,YAAM,IAAI,MAAM,UAAU,UAAU,kCAAkC,UAAU,GAAG;AAAA,IACrF;AAKA,UAAM,eAAe,KAAK,kBAAkB,mBAAmB;AAG/D,UAAM,aAAa,MAAM,KAAK,OAAO,SAAS,YAAY;AAG1D,UAAM,UAA6B;AAAA,MACjC;AAAA,IACF;AAEA,WAAO;AAAA,MACL;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYQ,kBAAkB,cAA2C;AAInE,UAAM,WAAW;AAAA,MACf,SAAS;AAAA,QACP;AAAA,UACE,SAAS,aAAa;AAAA,UACtB,OAAO,aAAa;AAAA,QACtB;AAAA,MACF;AAAA,MACA,SAAS,aAAa;AAAA,MACtB,aAAa,KAAK,OAAO,WAAW;AAAA,MACpC,YAAY,KAAK,OAAO,aAAa;AAAA,IACvC;AAGA,WAAO,OAAO,KAAK,KAAK,UAAU,QAAQ,CAAC,EAAE,SAAS,QAAQ;AAAA,EAChE;AACF;;;AClEO,SAAS,uBAAuB,QAAoB,QAAqC;AAC9F,QAAM,SAAS,IAAI,eAAe,OAAO,MAAM;AAE/C,MAAI,OAAO,YAAY,OAAO,SAAS,SAAS,GAAG;AACjD,WAAO,SAAS,QAAQ,CAAC,YAAY;AACnC,aAAO,SAAS,SAAS,MAAM;AAAA,IACjC,CAAC;AAAA,EACH,OAAO;AACL,WAAO,SAAS,YAAY,MAAM;AAAA,EACpC;AAEA,MAAI,OAAO,UAAU;AACnB,WAAO,SAAS,QAAQ,CAAC,WAAW;AAClC,aAAO,eAAe,MAAM;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,SAAO;AACT;","names":[]}

package/dist/cjs/exact/facilitator/index.d.ts

@@ -0,0 +1,114 @@
+import { SchemeNetworkFacilitator, PaymentPayload, PaymentRequirements, VerifyResponse, SettleResponse, Network } from '@t402/core/types';
+import { t402Facilitator } from '@t402/core/facilitator';
+
+/**
+ * Bitcoin On-chain Facilitator Scheme Implementation
+ *
+ * Verifies and settles Bitcoin on-chain payments using the exact scheme.
+ * Validates signed PSBTs and broadcasts transactions to the Bitcoin network.
+ */
+
+/**
+ * Facilitator BTC signer interface for verify and settle operations
+ */
+interface FacilitatorBtcSigner {
+    /**
+     * Get all addresses this facilitator can use
+     */
+    getAddresses(): readonly string[];
+    /**
+     * Verify a signed PSBT
+     * Checks that outputs match expected values and signatures are valid
+     *
+     * @param params - Verification parameters
+     * @returns Verification result
+     */
+    verifyPsbt(params: {
+        signedPsbt: string;
+        expectedPayTo: string;
+        expectedAmount: string;
+    }): Promise<{
+        valid: boolean;
+        reason?: string;
+        payer?: string;
+    }>;
+    /**
+     * Finalize and broadcast a signed PSBT
+     *
+     * @param signedPsbt - Base64-encoded signed PSBT
+     * @returns Transaction ID
+     */
+    broadcastPsbt(signedPsbt: string): Promise<string>;
+    /**
+     * Wait for a transaction to be confirmed
+     *
+     * @param txId - Transaction ID
+     * @param confirmations - Number of confirmations to wait for
+     * @returns Confirmation result
+     */
+    waitForConfirmation(txId: string, confirmations?: number): Promise<{
+        confirmed: boolean;
+        txId: string;
+        blockHash?: string;
+        confirmations: number;
+    }>;
+}
+/**
+ * Bitcoin facilitator implementation for the Exact payment scheme.
+ *
+ * Verifies signed PSBTs and broadcasts transactions to settle payments.
+ */
+declare class ExactBtcScheme implements SchemeNetworkFacilitator {
+    private readonly signer;
+    readonly scheme = "exact";
+    readonly caipFamily = "bip122:*";
+    constructor(signer: FacilitatorBtcSigner);
+    /**
+     * Get mechanism-specific extra data for the supported kinds endpoint.
+     * Bitcoin on-chain has no extra data.
+     */
+    getExtra(_network: string): Record<string, unknown> | undefined;
+    /**
+     * Get signer addresses used by this facilitator.
+     */
+    getSigners(_network: string): string[];
+    /**
+     * Verifies a payment payload.
+     *
+     * Validates:
+     * 1. Scheme and network matching
+     * 2. PSBT structure and signatures
+     * 3. Output matches (payTo, amount)
+     * 4. Amount above dust limit
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settles a payment by finalizing and broadcasting the PSBT.
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+}
+
+/**
+ * Configuration options for registering BTC schemes to an t402Facilitator
+ */
+interface BtcFacilitatorConfig {
+    /**
+     * The Bitcoin signer for facilitator operations (verify and settle)
+     */
+    signer: FacilitatorBtcSigner;
+    /**
+     * Networks to register (single network or array of networks)
+     * Examples: "bip122:000000000019d6689c085ae165831e93"
+     */
+    networks: Network | Network[];
+}
+/**
+ * Registers Bitcoin exact payment schemes to an t402Facilitator instance.
+ *
+ * @param facilitator - The t402Facilitator instance to register schemes to
+ * @param config - Configuration for BTC facilitator registration
+ * @returns The facilitator instance for chaining
+ */
+declare function registerExactBtcScheme(facilitator: t402Facilitator, config: BtcFacilitatorConfig): t402Facilitator;
+
+export { type BtcFacilitatorConfig, ExactBtcScheme, type FacilitatorBtcSigner, registerExactBtcScheme };