@atomiqlabs/sdk 7.0.12 → 8.0.8

package/src/bitcoin/wallet/BitcoinWallet.ts

@@ -0,0 +1,375 @@
+import {coinSelect, maxSendable, CoinselectAddressTypes, CoinselectTxInput} from "../coinselect2";
+import {BTC_NETWORK} from "@scure/btc-signer/utils"
+import {p2wpkh, OutScript, Transaction, p2tr, Address} from "@scure/btc-signer";
+import {IBitcoinWallet} from "./IBitcoinWallet";
+import {Buffer} from "buffer";
+import {randomBytes} from "../../utils/Utils";
+import {toCoinselectAddressType, toOutputScript} from "../../utils/BitcoinUtils";
+import {BitcoinRpcWithAddressIndex} from "../BitcoinRpcWithAddressIndex";
+import {TransactionInputUpdate} from "@scure/btc-signer/psbt";
+import {getLogger} from "../../utils/Logger";
+
+/**
+ * UTXO data structure for Bitcoin wallets
+ * @category Bitcoin
+ */
+export type BitcoinWalletUtxo = {
+    vout: number,
+    txId: string,
+    value: number,
+    type: CoinselectAddressTypes,
+    outputScript: Buffer,
+    address: string,
+    cpfp?: {
+        txVsize: number,
+        txEffectiveFeeRate: number
+    },
+    confirmed: boolean
+};
+
+/**
+ * Identifies the address type of a Bitcoin address
+ * @category Bitcoin
+ */
+export function identifyAddressType(address: string, network: BTC_NETWORK): CoinselectAddressTypes {
+    switch(Address(network).decode(address).type) {
+        case "pkh":
+            return "p2pkh";
+        case "wpkh":
+            return "p2wpkh";
+        case "tr":
+            return "p2tr";
+        case "sh":
+            return "p2sh-p2wpkh";
+        case "wsh":
+            return "p2wsh";
+        default:
+            throw new Error("Unknown address type of "+address);
+    }
+}
+
+const logger = getLogger("BitcoinWallet: ");
+
+/**
+ * Abstract base class for Bitcoin wallet implementations
+ * @category Bitcoin
+ */
+export abstract class BitcoinWallet implements IBitcoinWallet {
+
+    rpc: BitcoinRpcWithAddressIndex<any>;
+    network: BTC_NETWORK;
+    feeMultiplier: number;
+    feeOverride?: number;
+
+    constructor(mempoolApi: BitcoinRpcWithAddressIndex<any>, network: BTC_NETWORK, feeMultiplier: number = 1.25, feeOverride?: number) {
+        this.rpc = mempoolApi;
+        this.network = network;
+        this.feeMultiplier = feeMultiplier;
+        this.feeOverride = feeOverride;
+    }
+
+    async getFeeRate(): Promise<number> {
+        if(this.feeOverride!=null) {
+            return this.feeOverride;
+        }
+        return Math.floor((await this.rpc.getFeeRate())*this.feeMultiplier);
+    }
+
+    protected _sendTransaction(rawHex: string): Promise<string> {
+        return this.rpc.sendRawTransaction(rawHex);
+    }
+
+    protected _getBalance(address: string): Promise<{ confirmedBalance: bigint; unconfirmedBalance: bigint }> {
+        return this.rpc.getAddressBalances(address);
+    }
+
+    protected async _getUtxoPool(
+        sendingAddress: string,
+        sendingAddressType: CoinselectAddressTypes
+    ): Promise<BitcoinWalletUtxo[]> {
+        const utxos = await this.rpc.getAddressUTXOs(sendingAddress);
+
+        let totalSpendable = 0;
+
+        const outputScript = toOutputScript(this.network, sendingAddress);
+
+        const utxoPool: BitcoinWalletUtxo[] = [];
+
+        for(let utxo of utxos) {
+            const value = Number(utxo.value);
+            totalSpendable += value;
+            utxoPool.push({
+                vout: utxo.vout,
+                txId: utxo.txid,
+                value: value,
+                type: sendingAddressType,
+                outputScript: outputScript,
+                address: sendingAddress,
+                cpfp: !utxo.confirmed ? await this.rpc.getCPFPData(utxo.txid).then((result) => {
+                    if(result.effectiveFeePerVsize==null) return;
+                    return {
+                        txVsize: result.adjustedVsize,
+                        txEffectiveFeeRate: result.effectiveFeePerVsize
+                    }
+                }) : undefined,
+                confirmed: utxo.confirmed
+            })
+        }
+
+        logger.debug("_getUtxoPool(): Total spendable value: "+totalSpendable+" num utxos: "+utxoPool.length);
+
+        return utxoPool;
+    }
+
+    protected async _getPsbt(
+        sendingAccounts: {
+            pubkey: string,
+            address: string,
+            addressType: CoinselectAddressTypes,
+        }[],
+        recipient: string,
+        amount: number,
+        feeRate?: number
+    ): Promise<{
+        fee: number,
+        psbt?: Transaction,
+        inputAddressIndexes?: {[address: string]: number[]}
+    }> {
+        const psbt = new Transaction({PSBTVersion: 0});
+        psbt.addOutput({
+            amount: BigInt(amount),
+            script: toOutputScript(this.network, recipient)
+        });
+        return this._fundPsbt(sendingAccounts, psbt, feeRate);
+    }
+
+    protected async _fundPsbt(
+        sendingAccounts: {
+            pubkey: string,
+            address: string,
+            addressType: CoinselectAddressTypes,
+        }[],
+        psbt: Transaction,
+        feeRate?: number
+    ): Promise<{
+        fee: number,
+        psbt?: Transaction,
+        inputAddressIndexes?: {[address: string]: number[]}
+    }> {
+        if(feeRate==null) feeRate = await this.getFeeRate();
+
+        const utxoPool: BitcoinWalletUtxo[] = (await Promise.all(sendingAccounts.map(acc => this._getUtxoPool(acc.address, acc.addressType)))).flat();
+
+        logger.debug("_fundPsbt(): fee rate: "+feeRate+" utxo pool: ", utxoPool);
+
+        const accountPubkeys: Record<string, string> = {};
+        sendingAccounts.forEach(acc => accountPubkeys[acc.address] = acc.pubkey);
+
+        const requiredInputs: CoinselectTxInput[] = [];
+        for(let i=0;i<psbt.inputsLength;i++) {
+            const input = psbt.getInput(i);
+            if(input.index==null || input.txid==null) throw new Error("Inputs need txid & index!");
+            let amount: bigint;
+            let script: Uint8Array;
+            if(input.witnessUtxo!=null) {
+                amount = input.witnessUtxo.amount as bigint;
+                script = input.witnessUtxo.script as Uint8Array;
+            } else if(input.nonWitnessUtxo!=null) {
+                amount = input.nonWitnessUtxo.outputs[input.index].amount;
+                script = input.nonWitnessUtxo.outputs[input.index].script;
+            } else throw new Error("Either witnessUtxo or nonWitnessUtxo has to be defined!");
+            requiredInputs.push({
+                txId: Buffer.from(input.txid).toString('hex'),
+                vout: input.index,
+                value: Number(amount),
+                type: toCoinselectAddressType(script)
+            })
+        }
+
+        const targets: {value: number, script: Buffer}[] = [];
+        for(let i=0;i<psbt.outputsLength;i++) {
+            const output = psbt.getOutput(i);
+            if(output.amount==null || output.script==null) throw new Error("Outputs need amount & script defined!");
+            targets.push({
+                value: Number(output.amount),
+                script: Buffer.from(output.script)
+            })
+        }
+        logger.debug("_fundPsbt(): Coinselect targets: ", targets);
+
+        let coinselectResult = coinSelect(utxoPool, targets, feeRate, sendingAccounts[0].addressType, requiredInputs);
+        logger.debug("_fundPsbt(): Coinselect result: ", coinselectResult);
+
+        if(coinselectResult.inputs==null || coinselectResult.outputs==null) {
+            return {
+                fee: coinselectResult.fee
+            };
+        }
+
+        // Remove in/outs that are already in the PSBT
+        coinselectResult.inputs.splice(0, psbt.inputsLength);
+        coinselectResult.outputs.splice(0, psbt.outputsLength);
+
+        const inputAddressIndexes: {[address: string]: number[]} = {};
+        coinselectResult.inputs.forEach((input, index) => {
+            inputAddressIndexes[input.address!] ??= [];
+            inputAddressIndexes[input.address!].push(index);
+        });
+
+        const formattedInputs: TransactionInputUpdate[] = await Promise.all<TransactionInputUpdate>(coinselectResult.inputs.map(async (input) => {
+            switch(input.type) {
+                case "p2tr":
+                    const parsed = p2tr(Buffer.from(accountPubkeys[input.address!], "hex"));
+                    return {
+                        txid: input.txId,
+                        index: input.vout,
+                        witnessUtxo: {
+                            script: input.outputScript!,
+                            amount: BigInt(input.value)
+                        },
+                        tapInternalKey: parsed.tapInternalKey,
+                        tapMerkleRoot: parsed.tapMerkleRoot,
+                        tapLeafScript: parsed.tapLeafScript
+                    };
+                case "p2wpkh":
+                    return {
+                        txid: input.txId,
+                        index: input.vout,
+                        witnessUtxo: {
+                            script: input.outputScript!,
+                            amount: BigInt(input.value)
+                        },
+                        sighashType: 0x01
+                    };
+                case "p2sh-p2wpkh":
+                    return {
+                        txid: input.txId,
+                        index: input.vout,
+                        witnessUtxo: {
+                            script: input.outputScript!,
+                            amount: BigInt(input.value)
+                        },
+                        redeemScript: p2wpkh(Buffer.from(accountPubkeys[input.address!], "hex"), this.network).script,
+                        sighashType: 0x01
+                    };
+                case "p2pkh":
+                    const tx = await this.rpc.getTransaction(input.txId);
+                    if(tx==null) throw new Error("Cannot fetch existing tx "+input.txId);
+                    return {
+                        txid: input.txId,
+                        index: input.vout,
+                        nonWitnessUtxo: tx.raw,
+                        sighashType: 0x01
+                    };
+                default:
+                    throw new Error("Invalid input type: "+input.type);
+            }
+        }));
+
+        formattedInputs.forEach(input => psbt.addInput(input));
+
+        coinselectResult.outputs.forEach(output => {
+            if(output.script==null && output.address==null) {
+                //Change output
+                psbt.addOutput({
+                    script: toOutputScript(this.network, sendingAccounts[0].address),
+                    amount: BigInt(Math.floor(output.value))
+                });
+            } else {
+                psbt.addOutput({
+                    script: output.script ?? toOutputScript(this.network, output.address!),
+                    amount: BigInt(output.value)
+                });
+            }
+        });
+
+        return {
+            psbt,
+            fee: coinselectResult.fee,
+            inputAddressIndexes
+        };
+    }
+
+    protected async _getSpendableBalance(
+        sendingAccounts: {
+            address: string,
+            addressType: CoinselectAddressTypes,
+        }[],
+        psbt?: Transaction,
+        feeRate?: number
+    ): Promise<{
+        balance: bigint,
+        feeRate: number,
+        totalFee: number
+    }> {
+        feeRate ??= await this.getFeeRate();
+
+        const utxoPool: BitcoinWalletUtxo[] = (await Promise.all(sendingAccounts.map(acc => this._getUtxoPool(acc.address, acc.addressType)))).flat();
+
+        const requiredInputs: CoinselectTxInput[] = [];
+        if(psbt!=null) for(let i=0;i<psbt.inputsLength;i++) {
+            const input = psbt.getInput(i);
+            if(input.index==null || input.txid==null) throw new Error("Inputs need txid & index!");
+            let amount: bigint;
+            let script: Uint8Array;
+            if(input.witnessUtxo!=null) {
+                amount = input.witnessUtxo.amount as bigint;
+                script = input.witnessUtxo.script as Uint8Array;
+            } else if(input.nonWitnessUtxo!=null) {
+                amount = input.nonWitnessUtxo.outputs[input.index].amount;
+                script = input.nonWitnessUtxo.outputs[input.index].script;
+            } else throw new Error("Either witnessUtxo or nonWitnessUtxo has to be defined!");
+            requiredInputs.push({
+                txId: Buffer.from(input.txid).toString('hex'),
+                vout: input.index,
+                value: Number(amount),
+                type: toCoinselectAddressType(script)
+            })
+        }
+
+        const additionalOutputs: {value: number, script: Buffer}[] = [];
+        if(psbt!=null) for(let i=0;i<psbt.outputsLength;i++) {
+            const output = psbt.getOutput(i);
+            if(output.amount==null || output.script==null) throw new Error("Outputs need amount & script!");
+            additionalOutputs.push({
+                value: Number(output.amount),
+                script: Buffer.from(output.script)
+            })
+        }
+
+        const target = OutScript.encode({
+            type: "wsh",
+            hash: randomBytes(32)
+        });
+
+        let coinselectResult = maxSendable(utxoPool, {script: Buffer.from(target), type: "p2wsh"}, feeRate, requiredInputs, additionalOutputs);
+
+        logger.debug("_getSpendableBalance(): Max spendable result: ", coinselectResult);
+
+        return {
+            feeRate: feeRate,
+            balance: BigInt(Math.floor(coinselectResult.value)),
+            totalFee: coinselectResult.fee
+        }
+    }
+
+    abstract sendTransaction(address: string, amount: bigint, feeRate?: number): Promise<string>;
+    abstract fundPsbt(psbt: Transaction, feeRate?: number): Promise<Transaction>;
+    abstract signPsbt(psbt: Transaction, signInputs: number[]): Promise<Transaction>;
+
+    abstract getTransactionFee(address: string, amount: bigint, feeRate?: number): Promise<number>;
+    abstract getFundedPsbtFee(psbt: Transaction, feeRate?: number): Promise<number>;
+
+    abstract getReceiveAddress(): string;
+    abstract getBalance(): Promise<{
+        confirmedBalance: bigint,
+        unconfirmedBalance: bigint
+    }>;
+    abstract getSpendableBalance(psbt?: Transaction, feeRate?: number): Promise<{
+        balance: bigint,
+        feeRate: number,
+        totalFee: number
+    }>;
+
+
+}

package/src/bitcoin/wallet/IBitcoinWallet.ts

@@ -0,0 +1,44 @@
+import {Transaction} from "@scure/btc-signer";
+
+/**
+ * Type guard to check if an object implements IBitcoinWallet
+ * @category Bitcoin
+ */
+export function isIBitcoinWallet(val: any): val is IBitcoinWallet {
+    return val!==null &&
+        typeof(val.sendTransaction)==="function" &&
+        typeof(val.fundPsbt)==="function" &&
+        typeof(val.signPsbt)==="function" &&
+        typeof(val.getFeeRate)==="function" &&
+        typeof(val.getTransactionFee)==="function" &&
+        typeof(val.getFundedPsbtFee)==="function" &&
+        typeof(val.getReceiveAddress)==="function" &&
+        typeof(val.getBalance)==="function" &&
+        typeof(val.getSpendableBalance)==="function";
+}
+
+/**
+ * Interface for Bitcoin wallet operations
+ * @category Bitcoin
+ */
+export interface IBitcoinWallet {
+    sendTransaction(address: string, amount: bigint, feeRate?: number): Promise<string>;
+    fundPsbt(psbt: Transaction, feeRate?: number): Promise<Transaction>;
+    signPsbt(psbt: Transaction, signInputs: number[]): Promise<Transaction>;
+
+    getFeeRate(): Promise<number>;
+
+    getTransactionFee(address: string, amount: bigint, feeRate?: number): Promise<number>;
+    getFundedPsbtFee(psbt: Transaction, feeRate?: number): Promise<number>;
+
+    getReceiveAddress(): string;
+    getBalance(): Promise<{
+        confirmedBalance: bigint,
+        unconfirmedBalance: bigint
+    }>;
+    getSpendableBalance(psbt?: Transaction, feeRate?: number): Promise<{
+        balance: bigint,
+        feeRate: number,
+        totalFee: number
+    }>;
+}

package/src/bitcoin/wallet/MinimalBitcoinWalletInterface.ts

@@ -0,0 +1,19 @@
+import {Transaction} from "@scure/btc-signer";
+
+/**
+ * A type with minimum possible required data about a bitcoin wallet to be able to estimate fees and produce unsigned
+ *  PSBTs
+ * @category Bitcoin
+ */
+export type MinimalBitcoinWalletInterface = {
+    address: string,
+    publicKey: string
+};
+
+/**
+ * A type with minimum possible required data about a bitcoin wallet to be able to estimate fees and sign PSBTs
+ * @category Bitcoin
+ */
+export type MinimalBitcoinWalletInterfaceWithSigner = MinimalBitcoinWalletInterface & {
+    signPsbt: (psbtToSign: {psbt: Transaction, psbtHex: string, psbtBase64: string}, signInputs: number[]) => Promise<Transaction | string>
+};

package/src/bitcoin/wallet/MinimalLightningNetworkWalletInterface.ts

@@ -0,0 +1,7 @@
+/**
+ * A type with minimum possible required functionality to be usable with lightning network swaps
+ * @category Bitcoin
+ */
+export type MinimalLightningNetworkWalletInterface = {
+    payInvoice: (bolt11PaymentRequest: string) => Promise<string>
+}

package/src/bitcoin/wallet/SingleAddressBitcoinWallet.ts

@@ -0,0 +1,108 @@
+import {CoinselectAddressTypes} from "../coinselect2";
+import {BTC_NETWORK, pubECDSA, randomPrivateKeyBytes} from "@scure/btc-signer/utils"
+import {getAddress, Transaction, WIF} from "@scure/btc-signer";
+import {Buffer} from "buffer";
+import {identifyAddressType, BitcoinWallet} from "./BitcoinWallet";
+import {BitcoinRpcWithAddressIndex} from "../BitcoinRpcWithAddressIndex";
+
+/**
+ * Bitcoin wallet implementation for single-address scenarios
+ * @category Bitcoin
+ */
+export class SingleAddressBitcoinWallet extends BitcoinWallet {
+
+    readonly privKey?: Uint8Array;
+    readonly pubkey: Uint8Array;
+    readonly address: string;
+    readonly addressType: CoinselectAddressTypes;
+
+    constructor(
+        mempoolApi: BitcoinRpcWithAddressIndex<any>,
+        network: BTC_NETWORK,
+        addressDataOrWIF: string | {address: string, publicKey: string},
+        feeMultiplier: number = 1.25,
+        feeOverride?: number
+    ) {
+        super(mempoolApi, network, feeMultiplier, feeOverride);
+        if(typeof(addressDataOrWIF)==="string") {
+            try {
+                this.privKey = WIF(network).decode(addressDataOrWIF);
+            } catch(e) {
+                this.privKey = WIF().decode(addressDataOrWIF);
+            }
+            this.pubkey = pubECDSA(this.privKey);
+            const address = getAddress("wpkh", this.privKey, network);
+            if(address==null) throw new Error("Failed to generate p2wpkh address from the provided private key!");
+            this.address = address;
+        } else {
+            this.address = addressDataOrWIF.address;
+            this.pubkey = Buffer.from(addressDataOrWIF.publicKey, "hex");
+        }
+        this.addressType = identifyAddressType(this.address, network);
+    }
+
+    protected toBitcoinWalletAccounts(): {pubkey: string, address: string, addressType: CoinselectAddressTypes}[] {
+        return [{
+            pubkey: Buffer.from(this.pubkey).toString("hex"), address: this.address, addressType: this.addressType
+        }];
+    }
+
+    async sendTransaction(address: string, amount: bigint, feeRate?: number): Promise<string> {
+        if(!this.privKey) throw new Error("Not supported.");
+        const {psbt, fee} = await super._getPsbt(this.toBitcoinWalletAccounts(), address, Number(amount), feeRate);
+        if(psbt==null) throw new Error(`Not enough funds, required for fee: ${fee} sats!`);
+        psbt.sign(this.privKey);
+        psbt.finalize();
+        const txHex = Buffer.from(psbt.extract()).toString("hex");
+        return await super._sendTransaction(txHex);
+    }
+
+    async fundPsbt(inputPsbt: Transaction, feeRate?: number): Promise<Transaction> {
+        const {psbt} = await super._fundPsbt(this.toBitcoinWalletAccounts(), inputPsbt, feeRate);
+        if(psbt==null) {
+            throw new Error("Not enough balance!");
+        }
+        return psbt;
+    }
+
+    async signPsbt(psbt: Transaction, signInputs: number[]): Promise<Transaction> {
+        if(!this.privKey) throw new Error("Not supported.");
+        for(let signInput of signInputs) {
+            psbt.signIdx(this.privKey, signInput);
+        }
+        return psbt;
+    }
+
+    async getTransactionFee(address: string, amount: bigint, feeRate?: number): Promise<number> {
+        const {fee} = await super._getPsbt(this.toBitcoinWalletAccounts(), address, Number(amount), feeRate);
+        return fee;
+    }
+
+    async getFundedPsbtFee(basePsbt: Transaction, feeRate?: number): Promise<number> {
+        const {fee} = await super._fundPsbt(this.toBitcoinWalletAccounts(), basePsbt, feeRate);
+        return fee;
+    }
+
+    getReceiveAddress(): string {
+        return this.address;
+    }
+    getBalance(): Promise<{
+        confirmedBalance: bigint,
+        unconfirmedBalance: bigint
+    }> {
+        return this._getBalance(this.address);
+    }
+
+    getSpendableBalance(psbt?: Transaction, feeRate?: number): Promise<{
+        balance: bigint,
+        feeRate: number,
+        totalFee: number
+    }> {
+        return this._getSpendableBalance([{address: this.address, addressType: this.addressType}], psbt, feeRate);
+    }
+
+    static generateRandomPrivateKey(network?: BTC_NETWORK): string {
+         return WIF(network).encode(randomPrivateKeyBytes());
+    }
+
+}

package/src/enums/FeeType.ts

@@ -0,0 +1,9 @@
+
+/**
+ * Enum representing types of fees in a swap
+ * @category Pricing and LPs
+ */
+export enum FeeType {
+    SWAP = 0,
+    NETWORK_OUTPUT = 1
+}

package/src/enums/SwapAmountType.ts

@@ -0,0 +1,9 @@
+
+/**
+ * Enum representing whether the swap amount is exact input or exact output
+ * @category Core
+ */
+export enum SwapAmountType {
+    EXACT_IN = 1,
+    EXACT_OUT = 0
+}

package/src/enums/SwapDirection.ts

@@ -0,0 +1,9 @@
+
+/**
+ * Enum representing the direction of a swap (from or to Bitcoin)
+ * @category Core
+ */
+export enum SwapDirection {
+    FROM_BTC=0,
+    TO_BTC=1
+}

package/src/enums/SwapType.ts

@@ -0,0 +1,15 @@
+
+/**
+ * Enum representing different types of swaps
+ * @category Core
+ */
+export enum SwapType {
+    FROM_BTC=0,
+    FROM_BTCLN=1,
+    TO_BTC=2,
+    TO_BTCLN=3,
+    TRUSTED_FROM_BTC=4,
+    TRUSTED_FROM_BTCLN=5,
+    SPV_VAULT_FROM_BTC=6,
+    FROM_BTCLN_AUTO=7
+}

package/src/errors/IntermediaryError.ts

@@ -0,0 +1,24 @@
+/**
+ * An error or inconsistency in the intermediary's returned data, this will blacklist the intermediary
+ * @category Errors
+ */
+export class IntermediaryError extends Error {
+
+    recoverable: boolean;
+    originalStack?: string;
+
+    constructor(msg: string, originalError?: any, recoverable: boolean = false) {
+        if(originalError!=null) {
+            if(originalError.name!=null) msg += ": "+originalError.name;
+            if(originalError.message!=null) msg += ": "+originalError.message;
+            if(typeof(originalError)==="string") msg += ": "+originalError;
+        }
+        super(msg);
+
+        if(originalError?.stack!=null) this.originalStack = originalError.stack;
+        this.recoverable = recoverable;
+        // Set the prototype explicitly.
+        Object.setPrototypeOf(this, IntermediaryError.prototype);
+    }
+
+}

package/src/errors/PaymentAuthError.ts

@@ -0,0 +1,26 @@
+/**
+ * An error when the payment authorization returned by the intermediary is invalid
+ * @category Errors
+ */
+export class PaymentAuthError extends Error {
+
+    code?: number;
+    data: any;
+
+    constructor(msg: string, code?: number, data?: any) {
+        super(msg);
+        this.data = data;
+        this.code = code;
+        // Set the prototype explicitly.
+        Object.setPrototypeOf(this, PaymentAuthError.prototype);
+    }
+
+    getCode(): number | undefined {
+        return this.code;
+    }
+
+    getData(): any {
+        return this.data;
+    }
+
+}