@atomicfinance/bitcoin-ddk-provider 4.1.0

package/README.md

@@ -0,0 +1,142 @@
+# Bitcoin DDK Provider
+
+A Bitcoin provider that implements DLC (Discreet Log Contract) functionality using the DDK (Discreet Log Contract Development Kit) interface.
+
+## Features
+
+- **Interface-based design**: Uses a `DdkInterface` that allows different DDK implementations to be injected
+- **Flexible**: Can work with `ddk-ts`, `ddk-rn`, or any custom DDK implementation
+- **Type-safe**: Full TypeScript support with proper type definitions
+- **Testable**: Easy to mock for unit testing
+
+## Installation
+
+```bash
+npm install @atomicfinance/bitcoin-ddk-provider
+```
+
+## Usage
+
+### Basic Usage with ddk-ts
+
+```typescript
+import BitcoinDdkProvider from '@atomicfinance/bitcoin-ddk-provider';
+import * as ddkTs from '@bennyblader/ddk-ts';
+import { BitcoinNetwork } from 'bitcoin-networks';
+
+// Create provider with ddk-ts implementation
+const network = BitcoinNetwork.MAINNET;
+const provider = new BitcoinDdkProvider(network, ddkTs);
+
+// Use the provider
+const version = await provider.getVersion();
+console.log(`DDK Version: ${version}`);
+```
+
+### Usage with ddk-rn
+
+```typescript
+import BitcoinDdkProvider from '@atomicfinance/bitcoin-ddk-provider';
+import * as ddkRn from '@bennyblader/ddk-rn';
+import { BitcoinNetwork } from 'bitcoin-networks';
+
+// Create provider with ddk-rn implementation
+const network = BitcoinNetwork.MAINNET;
+const provider = new BitcoinDdkProvider(network, ddkRn);
+```
+
+### Custom DDK Implementation
+
+```typescript
+import BitcoinDdkProvider from '@atomicfinance/bitcoin-ddk-provider';
+import { DdkInterface, DlcOutcome, PartyParams, DlcTransactions } from '@atomicfinance/types';
+
+// Create your own DDK implementation
+class MyCustomDdk implements DdkInterface {
+  createDlcTransactions(
+    outcomes: DlcOutcome[],
+    localParams: PartyParams,
+    remoteParams: PartyParams,
+    refundLocktime: number,
+    feeRate: bigint,
+    fundLockTime: number,
+    cetLockTime: number,
+    fundOutputSerialId: bigint,
+  ): DlcTransactions {
+    // Your custom implementation
+    return {
+      fund: { /* ... */ },
+      cets: [],
+      refund: { /* ... */ },
+      fundingScriptPubkey: Buffer.alloc(0),
+    };
+  }
+
+  // Implement all other required methods...
+  createCet(/* ... */) { /* ... */ }
+  createCets(/* ... */) { /* ... */ }
+  // ... etc
+}
+
+// Use your custom implementation
+const network = BitcoinNetwork.MAINNET;
+const customDdk = new MyCustomDdk();
+const provider = new BitcoinDdkProvider(network, customDdk);
+```
+
+### Testing with Mock Implementation
+
+```typescript
+import BitcoinDdkProvider from '@atomicfinance/bitcoin-ddk-provider';
+import { DdkInterface } from '@atomicfinance/types';
+
+// Create a mock for testing
+const mockDdk: DdkInterface = {
+  createDlcTransactions: jest.fn().mockResolvedValue(/* mock data */),
+  createFundTxLockingScript: jest.fn().mockReturnValue(Buffer.alloc(0)),
+  // ... implement other methods as needed
+};
+
+const provider = new BitcoinDdkProvider(BitcoinNetwork.TESTNET, mockDdk);
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+constructor(network: BitcoinNetwork, ddkLib: DdkInterface)
+```
+
+- `network`: The Bitcoin network to use (mainnet, testnet, etc.)
+- `ddkLib`: A DDK implementation that conforms to the `DdkInterface`
+
+### Methods
+
+The provider implements all the standard DLC methods:
+
+- `createDlcTransactions()` - Create DLC transactions
+- `createFundTx()` - Create funding transaction
+- `createCet()` - Create CET (Contract Execution Transaction)
+- `createCets()` - Create multiple CETs
+- `createRefundTransaction()` - Create refund transaction
+- `createCetAdaptorSignature()` - Create CET adaptor signature
+- `signFundTransactionInput()` - Sign funding transaction input
+- `verifyFundTxSignature()` - Verify funding transaction signature
+- `getVersion()` - Get DDK version
+- `getChangeOutputAndFees()` - Calculate change output and fees
+- `getTotalInputVsize()` - Get total input vsize
+- `isDustOutput()` - Check if output is dust
+- `createSplicedDlcTransactions()` - Create spliced DLC transactions
+
+## Benefits of Interface-Based Design
+
+1. **Dependency Injection**: Easy to swap implementations
+2. **Testing**: Simple to mock for unit tests
+3. **Flexibility**: Support multiple DDK libraries
+4. **Maintainability**: Clear contract for what any DDK implementation must provide
+5. **Future-Proof**: Easy to add new DDK implementations or remove dependencies
+
+## Type Safety
+
+All methods are fully typed using TypeScript interfaces from `@atomicfinance/types`. The provider ensures type safety while maintaining flexibility through the interface-based design.

package/dist/BitcoinDdkProvider.d.ts

@@ -0,0 +1,297 @@
+import Provider from '@atomicfinance/provider';
+import { DdkInterface, DlcInputInfoRequest, Input, InputSupplementationMode, Messages, PayoutRequest } from '@atomicfinance/types';
+import { Tx } from '@node-dlc/bitcoin';
+import { CetAdaptorSignatures, ContractInfo, DlcAccept, DlcClose, DlcCloseMetadata, DlcOffer, DlcSign, DlcTransactions, FundingInput, HyperbolaPayoutCurvePiece, NumericalDescriptor, OracleAttestation, PolynomialPayoutCurvePiece } from '@node-dlc/messaging';
+import { BitcoinNetwork } from 'bitcoin-networks';
+export default class BitcoinDdkProvider extends Provider {
+    private _network;
+    private _ddk;
+    constructor(network: BitcoinNetwork, ddkLib: DdkInterface);
+    DdkLoaded(): Promise<void>;
+    /**
+     * Find private key for DLC funding pubkey by deriving wallet addresses
+     */
+    private findDlcFundingPrivateKey;
+    private GetPrivKeysForInputs;
+    GetCfdNetwork(): Promise<string>;
+    /**
+     * Get inputs for amount with explicit supplementation control
+     */
+    GetInputsForAmountWithMode(amounts: bigint[], feeRatePerVb: bigint, fixedInputs?: Input[], supplementation?: InputSupplementationMode): Promise<Input[]>;
+    GetInputsForAmount(amounts: bigint[], feeRatePerVb: bigint, fixedInputs?: Input[]): Promise<Input[]>;
+    private Initialize;
+    /**
+     * TODO: Add GetPayoutFromOutcomes
+     *
+     * private GetPayoutsFromOutcomes(
+     *   contractDescriptor: ContractDescriptorV0,
+     *   totalCollateral: bigint,
+     * ): PayoutRequest[] {}
+     */
+    private GetPayoutsFromPayoutFunction;
+    private GetPayoutsFromPolynomialPayoutFunction;
+    private GetPayouts;
+    private FlattenPayouts;
+    private GetIndicesFromPayouts;
+    private GetPayoutsFromEnumeratedDescriptor;
+    private GetPayoutsFromContractDescriptor;
+    /**
+     * Converts a @node-dlc/bitcoin Tx to a DDK Transaction
+     * @param tx The @node-dlc/bitcoin transaction
+     * @returns DDK Transaction object
+     */
+    private convertTxToDdkTransaction;
+    createDlcTxs(dlcOffer: DlcOffer, dlcAccept: DlcAccept): Promise<CreateDlcTxsResponse>;
+    /**
+     * Computes DLC-spec compliant tagged attestation message digest
+     * This matches what the oracle should sign according to the DLC specification
+     */
+    private computeTaggedAttestationMessage;
+    /**
+     * Convert message lists to the format expected by DDK FFI
+     * DDK expects 32-byte message digests (tagged attestation messages)
+     */
+    private convertMessagesForDdk;
+    private GenerateEnumMessages;
+    private convertToJsonSerializable;
+    private GenerateDigitDecompositionMessages;
+    private GenerateMessages;
+    private GetContractOraclePairs;
+    private getFundOutputValueSats;
+    private CreateCetAdaptorAndRefundSigs;
+    private VerifyCetAdaptorAndRefundSigs;
+    private CreateFundingSigsAlt;
+    private VerifyFundingSigsAlt;
+    private VerifyRefundSignatureAlt;
+    private CreateFundingScript;
+    private CreateFundingTx;
+    FindOutcomeIndexFromPolynomialPayoutCurvePiece(dlcOffer: DlcOffer, contractDescriptor: NumericalDescriptor, contractOraclePairIndex: number, polynomialPayoutCurvePiece: PolynomialPayoutCurvePiece, oracleAttestation: OracleAttestation, outcome: bigint): Promise<FindOutcomeResponse>;
+    FindOutcomeIndexFromHyperbolaPayoutCurvePiece(_dlcOffer: DlcOffer, contractDescriptor: NumericalDescriptor, contractOraclePairIndex: number, hyperbolaPayoutCurvePiece: HyperbolaPayoutCurvePiece, oracleAttestation: OracleAttestation, outcome: bigint): Promise<FindOutcomeResponse>;
+    FindOutcomeIndex(dlcOffer: DlcOffer, oracleAttestation: OracleAttestation): Promise<FindOutcomeResponse>;
+    ValidateEvent(dlcOffer: DlcOffer, oracleAttestation: OracleAttestation): void;
+    FindAndSignCet(dlcOffer: DlcOffer, dlcAccept: DlcAccept, dlcSign: DlcSign, dlcTxs: DlcTransactions, oracleAttestation: OracleAttestation, isOfferer?: boolean): Promise<Tx>;
+    private GetFundAddress;
+    private GetFundKeyPair;
+    private GetFundPrivateKey;
+    CreateCloseRawTxs(dlcOffer: DlcOffer, dlcAccept: DlcAccept, dlcTxs: DlcTransactions, closeInputAmount: bigint, isOfferer: boolean, _dlcCloses?: DlcClose[], fundingInputs?: FundingInput[], initiatorPayouts?: bigint[]): Promise<string[]>;
+    CreateSignatureHashes(_dlcOffer: DlcOffer, _dlcAccept: DlcAccept, _dlcTxs: DlcTransactions, rawCloseTxs: string[]): Promise<string[]>;
+    CalculateEcSignatureHashes(sigHashes: string[], privKey: string): Promise<string[]>;
+    VerifySignatures(_dlcOffer: DlcOffer, _dlcAccept: DlcAccept, _dlcTxs: DlcTransactions, _dlcCloses: DlcClose[], rawCloseTxs: string[], isOfferer: boolean): Promise<boolean>;
+    /**
+     * Check whether wallet is offerer of DlcOffer or DlcAccept
+     * @param dlcOffer Dlc Offer Message
+     * @param dlcAccept Dlc Accept Message
+     * @returns {Promise<boolean>}
+     */
+    isOfferer(_dlcOffer: DlcOffer, _dlcAccept: DlcAccept): Promise<boolean>;
+    /**
+     * Create DLC Offer Message
+     * @param contractInfo ContractInfo TLV (V0 or V1)
+     * @param offerCollateralSatoshis Amount DLC Initiator is putting into the contract
+     * @param feeRatePerVb Fee rate in satoshi per virtual byte that both sides use to compute fees in funding tx
+     * @param cetLocktime The nLockTime to be put on CETs
+     * @param refundLocktime The nLockTime to be put on the refund transaction
+     * @param fixedInputs Optional fixed inputs - can be Input[] for regular inputs or FundingInput[] for DLC inputs
+     * @returns {Promise<DlcOffer>}
+     */
+    createDlcOffer(contractInfo: ContractInfo, offerCollateralSatoshis: bigint, feeRatePerVb: bigint, cetLocktime: number, refundLocktime: number, fixedInputs?: Input[] | FundingInput[], inputSupplementationMode?: InputSupplementationMode): Promise<DlcOffer>;
+    /**
+     * Accept DLC Offer (supports single-funded DLCs when accept collateral is 0)
+     * @param _dlcOffer Dlc Offer Message
+     * @param fixedInputs Optional inputs to use for Funding Inputs
+     * @returns {Promise<AcceptDlcOfferResponse}
+     */
+    acceptDlcOffer(_dlcOffer: DlcOffer, fixedInputs?: Input[] | FundingInput[]): Promise<AcceptDlcOfferResponse>;
+    /**
+     * Sign Dlc Accept Message
+     * @param _dlcOffer Dlc Offer Message
+     * @param _dlcAccept Dlc Accept Message
+     * @returns {Promise<SignDlcAcceptResponse}
+     */
+    signDlcAccept(dlcOffer: DlcOffer, dlcAccept: DlcAccept): Promise<SignDlcAcceptResponse>;
+    /**
+     * Finalize Dlc Sign
+     * @param dlcOffer Dlc Offer Message
+     * @param dlcAccept Dlc Accept Message
+     * @param dlcSign Dlc Sign Message
+     * @param dlcTxs Dlc Transactions Message
+     * @returns {Promise<Tx>}
+     */
+    finalizeDlcSign(dlcOffer: DlcOffer, dlcAccept: DlcAccept, dlcSign: DlcSign, dlcTxs: DlcTransactions): Promise<Tx>;
+    /**
+     * Execute DLC
+     * @param _dlcOffer Dlc Offer Message
+     * @param _dlcAccept Dlc Accept Message
+     * @param _dlcSign Dlc Sign Message
+     * @param _dlcTxs Dlc Transactions Message
+     * @param oracleAttestation Oracle Attestations TLV (V0)
+     * @param isOfferer Whether party is Dlc Offerer
+     * @returns {Promise<Tx>}
+     */
+    execute(dlcOffer: DlcOffer, dlcAccept: DlcAccept, dlcSign: DlcSign, dlcTxs: DlcTransactions, oracleAttestation: OracleAttestation, isOfferer?: boolean): Promise<Tx>;
+    /**
+     * Refund DLC
+     * @param dlcOffer Dlc Offer Message
+     * @param dlcAccept Dlc Accept Message
+     * @param dlcSign Dlc Sign Message
+     * @param dlcTxs Dlc Transactions message
+     * @returns {Promise<Tx>}
+     */
+    refund(dlcOffer: DlcOffer, dlcAccept: DlcAccept, dlcSign: DlcSign, dlcTxs: DlcTransactions): Promise<Tx>;
+    /**
+     * Goal of createDlcClose is for alice (the initiator) to
+     * 1. take dlcoffer, accept, and sign messages. Create a dlcClose message.
+     * 2. Build a close tx, sign.
+     * 3. return dlcClose message (no psbt)
+     */
+    /**
+     * Generate DlcClose messagetype for closing DLC with Mutual Consent
+     * @param _dlcOffer DlcOffer TLV (V0)
+     * @param _dlcAccept DlcAccept TLV (V0)
+     * @param _dlcTxs DlcTransactions TLV (V0)
+     * @param initiatorPayoutSatoshis Amount initiator expects as a payout
+     * @param isOfferer Whether offerer or not
+     * @param _inputs Optionally specified closing inputs
+     * @returns {Promise<DlcClose>}
+     */
+    createDlcClose(_dlcOffer: DlcOffer, _dlcAccept: DlcAccept, _dlcTxs: DlcTransactions, initiatorPayoutSatoshis: bigint, isOfferer?: boolean, _inputs?: Input[]): Promise<DlcClose>;
+    /**
+     * Generate multiple DlcClose messagetypes for closing DLC with Mutual Consent
+     * @param _dlcOffer DlcOffer TLV (V0)
+     * @param _dlcAccept DlcAccept TLV (V0)
+     * @param _dlcTxs DlcTransactions TLV (V0)
+     * @param initiatorPayouts Array of amounts initiator expects as payouts
+     * @param isOfferer Whether offerer or not
+     * @param _inputs Optionally specified closing inputs
+     * @returns {Promise<DlcClose[]>}
+     */
+    createBatchDlcClose(_dlcOffer: DlcOffer, _dlcAccept: DlcAccept, _dlcTxs: DlcTransactions, initiatorPayouts: bigint[], isOfferer?: boolean, _inputs?: Input[]): Promise<DlcClose[]>;
+    verifyBatchDlcCloseUsingMetadata(dlcCloseMetadata: DlcCloseMetadata, _dlcCloses: DlcClose[], isOfferer?: boolean): Promise<void>;
+    /**
+     * Verify multiple DlcClose messagetypes for closing DLC with Mutual Consent
+     * @param _dlcOffer DlcOffer TLV (V0)
+     * @param _dlcAccept DlcAccept TLV (V0)
+     * @param _dlcTxs DlcTransactions TLV (V0)
+     * @param _dlcCloses DlcClose[] TLV (V0)
+     * @param isOfferer Whether offerer or not
+     * @returns {Promise<void>}
+     */
+    verifyBatchDlcClose(_dlcOffer: DlcOffer, _dlcAccept: DlcAccept, _dlcTxs: DlcTransactions, _dlcCloses: DlcClose[], isOfferer?: boolean): Promise<void>;
+    /**
+     * Goal of finalize Dlc Close is for bob to
+     * 1. take the dlcClose created by alice using createDlcClose,
+     * 2. Build a psbt using Alice's dlcClose message
+     * 3. Sign psbt with bob's privkey
+     * 4. return a tx ready to be broadcast
+     */
+    /**
+     * Finalize Dlc Close
+     * @param _dlcOffer Dlc Offer Message
+     * @param _dlcAccept Dlc Accept Message
+     * @param _dlcClose Dlc Close Message
+     * @param _dlcTxs Dlc Transactions Message
+     * @returns {Promise<Tx>}
+     */
+    finalizeDlcClose(_dlcOffer: DlcOffer, _dlcAccept: DlcAccept, _dlcClose: DlcClose, _dlcTxs: DlcTransactions): Promise<string>;
+    fundingInputToInput(_input: FundingInput, findDerivationPath?: boolean): Promise<Input>;
+    inputToFundingInput(input: Input): Promise<FundingInput>;
+    getConnectedNetwork(): Promise<BitcoinNetwork>;
+    /**
+     * Convert BitcoinNetwork to bitcoinjs-lib network format
+     */
+    private getBitcoinJsNetwork;
+    /**
+     * Calculate the maximum collateral possible with given inputs
+     * @param inputs Array of Input objects to use for funding
+     * @param feeRatePerVb Fee rate in satoshis per virtual byte
+     * @param contractCount Number of DLC contracts (default: 1)
+     * @returns Maximum collateral amount in satoshis
+     */
+    calculateMaxCollateral(inputs: Input[], feeRatePerVb: bigint, contractCount?: number): Promise<bigint>;
+    /**
+     * Create a funding input with DLC input information for splicing
+     * @param dlcInputInfo DLC input information
+     * @param fundingTxHex Raw transaction hex of the funding transaction
+     */
+    createDlcFundingInput(dlcInputInfo: DlcInputInfoRequest, fundingTxHex: string): Promise<FundingInput>;
+}
+export interface BasicInitializeResponse {
+    fundingPubKey: Buffer;
+    payoutSPK: Buffer;
+    payoutSerialId: bigint;
+    changeSPK: Buffer;
+    changeSerialId: bigint;
+}
+export interface InitializeResponse extends BasicInitializeResponse {
+    fundingInputs: FundingInput[];
+}
+export interface BatchBaseInitializeResponse {
+    fundingPubKey: Buffer;
+    payoutSPK: Buffer;
+    payoutSerialId: bigint;
+}
+export interface BatchInitializeResponse {
+    initializeResponses: BatchBaseInitializeResponse[];
+    fundingInputs: FundingInput[];
+    changeSPK: Buffer;
+    changeSerialId: bigint;
+}
+export interface AcceptDlcOfferResponse {
+    dlcAccept: DlcAccept;
+    dlcTransactions: DlcTransactions;
+}
+export interface BatchAcceptDlcOfferResponse {
+    dlcAccepts: DlcAccept[];
+    dlcTransactionsList: DlcTransactions[];
+}
+export interface SignDlcAcceptResponse {
+    dlcSign: DlcSign;
+    dlcTransactions: DlcTransactions;
+}
+export interface BatchSignDlcAcceptResponse {
+    dlcSigns: DlcSign[];
+    dlcTransactionsList: DlcTransactions[];
+}
+export interface GetPayoutsResponse {
+    payouts: PayoutRequest[];
+    payoutGroups: PayoutGroup[];
+    messagesList: Messages[];
+}
+export interface CreateDlcTxsResponse {
+    dlcTransactions: DlcTransactions;
+    messagesList: Messages[];
+}
+export interface CreateBatchDlcTxsResponse {
+    dlcTransactionsList: DlcTransactions[];
+    nestedMessagesList: Messages[][];
+}
+export interface CreateCetAdaptorAndRefundSigsResponse {
+    cetSignatures: CetAdaptorSignatures;
+    refundSignature: Buffer;
+}
+interface PayoutGroup {
+    payout: bigint;
+    groups: number[][];
+}
+interface FindOutcomeResponse {
+    index: number;
+    groupLength: number;
+}
+export interface Change {
+    value: number;
+}
+export interface Output {
+    value: number;
+    id?: string;
+}
+export interface InputsForAmountResponse {
+    inputs: Input[];
+    change: Change;
+    outputs: Output[];
+    fee: number;
+}
+export interface InputsForDualAmountResponse {
+    inputs: Input[];
+    fee: number;
+}
+export {};