@omnity/ree-client-ts-sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,565 @@
+import { ActorSubclass } from '@dfinity/agent';
+import * as bitcoin from 'bitcoinjs-lib';
+import { IDL } from '@dfinity/candid';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+export declare const AddressType: {
+    P2PKH: {
+        P2PKH: null;
+    };
+    P2SH_P2WPKH: {
+        P2SH_P2WPKH: null;
+    };
+    P2WPKH: {
+        P2WPKH: null;
+    };
+    P2WSH: {
+        P2WSH: null;
+    };
+    P2SH: {
+        P2SH: null;
+    };
+    P2TR: {
+        P2TR: null;
+    };
+    UNKNOWN: {
+        UNKNOWN: null;
+    };
+};
+
+export declare type AddressType = (typeof AddressType)[keyof typeof AddressType] | {
+    OpReturn: bigint;
+};
+
+declare function bytesToHex(bytes: Uint8Array): string;
+
+declare type CoinBalance = {
+    id: string;
+    value: bigint;
+};
+
+export declare type Config = {
+    network: Network;
+    maestroApiKey: string;
+    exchangeIdlFactory: IDL.InterfaceFactory;
+    exchangeId: string;
+    exchangeCanisterId: string;
+};
+
+declare function getAddressType(address: string): AddressType;
+
+declare function getScriptByAddress(address: string, network?: Network): Buffer<ArrayBufferLike>;
+
+declare function hexToBytes(hex: string): Uint8Array;
+
+declare type InputCoin = {
+    coin: CoinBalance;
+    from: string;
+};
+
+export declare type Intention = {
+    input_coins: InputCoin[];
+    output_coins: OutputCoin[];
+    action: string;
+    exchange_id: string;
+    action_params: string;
+    pool_utxo_spent: string[];
+    nonce: bigint;
+    pool_utxo_received: string[];
+    pool_address: string;
+};
+
+export declare type IntentionSet = {
+    tx_fee_in_sats: bigint;
+    initiator_address: string;
+    intentions: Intention[];
+};
+
+declare class Maestro {
+    private axios;
+    constructor(params: {
+        baseUrl: string;
+        apiKey: string;
+    });
+    utxosByAddress(address: string, cursor?: string | null): Promise<{
+        next_cursor: string | null;
+        last_updated: {
+            block_hash: string;
+            block_height: bigint;
+        };
+        data: RawBtcUtxo[];
+    }>;
+    inscriptionsByAddress(address: string, cursor?: string | null): Promise<{
+        next_cursor: string | null;
+        last_updated: {
+            block_hash: string;
+            block_height: bigint;
+        };
+        data: RawInscription[];
+    }>;
+    inscriptionIdsByCollectionSymbol(collection: string, cursor?: string | null): Promise<{
+        next_cursor: string | null;
+        last_updated: {
+            block_hash: string;
+            block_height: bigint;
+        };
+        data: string[];
+    }>;
+    runeUtxosByAddress(address: string, rune: string, cursor?: string | null): Promise<{
+        next_cursor: string | null;
+        last_updated: {
+            block_hash: string;
+            block_height: bigint;
+        };
+        data: RawRuneUtxo[];
+    }>;
+}
+
+export declare const Network: {
+    readonly Mainnet: "mainnet";
+    readonly Testnet: "testnet";
+};
+
+export declare type Network = (typeof Network)[keyof typeof Network];
+
+declare type OutputCoin = {
+    coin: CoinBalance;
+    to: string;
+};
+
+export declare type Pool = {
+    name: string;
+    address: string;
+};
+
+export declare type PoolInfo = {
+    address: string;
+    attributes: string;
+    btc_reserved: bigint;
+    coin_reserved: {
+        id: string;
+        value: bigint;
+    }[];
+    key: string;
+    name: string;
+    nonce: bigint;
+    utxos: {
+        coins: {
+            id: string;
+            value: bigint;
+        }[];
+        sats: bigint;
+        txid: string;
+        vout: number;
+    }[];
+};
+
+declare type RawBtcUtxo = {
+    txid: string;
+    vout: number;
+    script_pubkey: string;
+    satoshis: string;
+    confirmations: bigint;
+    height: bigint;
+    runes: {
+        rune_id: string;
+        amount: string;
+    }[];
+    inscriptions: {
+        offset: bigint;
+        inscription_id: string;
+    }[];
+    address: string;
+};
+
+declare type RawInscription = {
+    inscription_id: string;
+    satoshis: string;
+    utxo_sat_offset: bigint;
+    utxo_txid: string;
+    utxo_vout: number;
+    utxo_block_height: number;
+    utxo_confirmations: string;
+};
+
+declare type RawRuneUtxo = {
+    txid: string;
+    vout: number;
+    satoshis: string;
+    confirmations: bigint;
+    height: bigint;
+    runes: {
+        rune_id: string;
+        amount: string;
+    }[];
+};
+
+/**
+ * Main client for interacting with the Ree protocol
+ * Provides methods for Bitcoin UTXO management, Rune operations, and transaction creation
+ */
+export declare class ReeClient {
+    /** Maestro API client for Bitcoin data */
+    readonly maestro: Maestro;
+    /** Configuration object */
+    readonly config: Config;
+    /** Exchange canister actor for pool operations */
+    readonly exchange: ActorSubclass;
+    /** Orchestrator canister actor for transaction processing */
+    readonly orchestrator: ActorSubclass;
+    /**
+     * Initialize ReeClient with wallet addresses and configuration
+     * @param config - Client configuration including network and API keys
+     */
+    constructor(config: Config);
+    /**
+     * Filter out UTXOs that have already been spent or are being used in pending transactions
+     * Queries the orchestrator to get a list of used outpoints and removes them from the UTXO set
+     * @param address - The Bitcoin (or Ordinals) address to check used outpoints for
+     * @param utxos - Array of UTXOs to filter
+     * @returns Filtered array of UTXOs excluding spent/used ones
+     */
+    private filterSpentUtxos;
+    /**
+     * Get all Bitcoin UTXOs for the payment address
+     * Handles pagination automatically to fetch all available UTXOs
+     * @returns Array of Bitcoin UTXOs
+     */
+    getBtcUtxos(paymentAddress: string): Promise<Utxo[]>;
+    /**
+     * Get UTXOs containing a specific rune for the user's address
+     * @param runeId - The rune ID to filter UTXOs by
+     * @returns Array of UTXOs containing the specified rune
+     */
+    getRuneUtxos(address: string, runeId: string): Promise<Utxo[]>;
+    /**
+     * Search for runes by keyword or rune ID
+     * Supports both exact rune ID matches and fuzzy name matching
+     * @param keyword - Search term (rune ID or partial name)
+     * @returns Array of matching rune information
+     */
+    searchRunes(keyword: string): Promise<RuneInfo[]>;
+    /**
+     * Get detailed information for a specific rune by ID
+     * @param runeId - The rune ID to look up
+     * @returns Rune information or undefined if not found
+     */
+    getRuneInfo(runeId: string): Promise<RuneInfo | undefined>;
+    /**
+     * Get total Bitcoin balance from all UTXOs
+     * @returns Total balance in satoshis
+     */
+    getBtcBalance(paymentAddress: string): Promise<number>;
+    /**
+     * Get the balance of a specific rune for the user's address
+     * Calculates total rune amount across all UTXOs and applies divisibility
+     * @param runeId - The rune ID to get balance for (format: "block:index")
+     * @returns Rune balance as a number, or undefined if rune not found
+     */
+    getRuneBalance(address: string, runeId: string): Promise<number | undefined>;
+    /**
+     * Get list of all available liquidity pools
+     * @returns Array of pool information
+     */
+    getPoolList(): Promise<Pool[]>;
+    /**
+     * Get detailed information about a specific liquidity pool
+     * @param poolAddress - The pool's Bitcoin address
+     * @returns Pool information including UTXOs and balances
+     * @throws Error if pool is not found
+     */
+    getPoolInfo(poolAddress: string): Promise<PoolInfo>;
+    /**
+     * Create a transaction for trading with a liquidity pool
+     * Supports both BTC-only and BTC-Rune swaps
+     * @param params - Transaction parameters
+     * @param params.runeId - Optional rune ID for rune swaps
+     * @param params.poolAddress - Target pool address
+     * @param params.sendBtcAmount - BTC amount to send
+     * @param params.sendRuneAmount - Rune amount to send (0 for BTC-only)
+     * @param params.receiveBtcAmount - Expected BTC to receive
+     * @param params.receiveRuneAmount - Expected rune amount to receive
+     * @returns Transaction builder instance
+     */
+    createTransaction({ address, paymentAddress, runeId, poolAddress, sendBtcAmount, sendRuneAmount, receiveBtcAmount, receiveRuneAmount, }: {
+        runeId?: string;
+        address: string;
+        paymentAddress: string;
+        poolAddress: string;
+        sendBtcAmount: bigint;
+        sendRuneAmount: bigint;
+        receiveBtcAmount: bigint;
+        receiveRuneAmount: bigint;
+    }): Promise<Transaction>;
+}
+
+declare interface ReeContextValue {
+    client: ReeClient;
+    exchange: ActorSubclass;
+    address: string;
+    paymentAddress: string;
+    updateWallet: (wallet: {
+        address?: string;
+        paymentAddress?: string;
+    }) => void;
+    createTransaction: (params: {
+        runeId?: string;
+        poolAddress: string;
+        sendBtcAmount: bigint;
+        sendRuneAmount: bigint;
+        receiveBtcAmount: bigint;
+        receiveRuneAmount: bigint;
+    }) => Promise<Transaction>;
+}
+
+export declare function ReeProvider({ children, config }: ReeProviderProps): JSX_2.Element;
+
+declare interface ReeProviderProps {
+    children: ReactNode;
+    config: Config;
+}
+
+export declare interface RuneInfo {
+    runeId: string;
+    spacedRune: string;
+    symbol: string;
+    divisibility: number;
+    etching: string;
+}
+
+declare function toBitcoinNetwork(network: Network): bitcoin.networks.Network;
+
+/**
+ * Transaction builder for Bitcoin and Rune transactions
+ * Handles PSBT creation, UTXO selection, and fee calculation
+ */
+export declare class Transaction {
+    private psbt;
+    private inputAddressTypes;
+    private outputAddressTypes;
+    private config;
+    /** Track dust amounts from user input UTXOs for fee calculation */
+    private userInputUtxoDusts;
+    /** Orchestrator actor for fee estimation */
+    readonly orchestrator: ActorSubclass;
+    private intentionSet;
+    constructor(config: TransactionConfig, orchestrator: ActorSubclass);
+    /**
+     * Add a UTXO as transaction input
+     * @param utxo - The UTXO to add as input
+     */
+    private addInput;
+    /**
+     * Add a standard output to the transaction
+     * @param address - Recipient address
+     * @param amount - Amount in satoshis
+     */
+    private addOutput;
+    /**
+     * Add an OP_RETURN script output (for Runestone)
+     * @param script - The script buffer to include
+     */
+    private addScriptOutput;
+    /**
+     * Select UTXOs containing specific runes for the transaction
+     * @param runeUtxos - Available rune UTXOs
+     * @param runeId - Target rune ID
+     * @param runeAmount - Required rune amount
+     * @returns Selected UTXOs that contain the required runes
+     */
+    private selectRuneUtxos;
+    /**
+     * Select BTC UTXOs for the transaction
+     * @param btcUtxos - Available BTC UTXOs
+     * @param btcAmount - Required BTC amount in satoshis
+     * @returns Selected UTXOs that contain enough BTC
+     */
+    private selectBtcUtxos;
+    /**
+     * Calculate rune change amount and determine if change is needed
+     * @param runeId - The rune ID to calculate change for
+     * @param runeUtxos - UTXOs containing the runes
+     * @param runeAmount - Amount being sent
+     * @returns Change calculation result
+     */
+    private caclulateRuneChangeAmount;
+    /**
+     * Add rune-related outputs to the transaction
+     * @param runeIdStr - Rune ID string (block:index format)
+     * @param runeUtxos - UTXOs containing the runes
+     * @param runeAmount - Amount of runes to transfer
+     * @param receiveAddress - Address to receive the runes
+     * @returns Information about whether change output is needed
+     */
+    private addRuneOutputs;
+    /**
+     * Add BTC outputs and calculate transaction fees
+     * @param btcUtxos - Available BTC UTXOs
+     * @param btcAmount - Required BTC amount
+     * @param paymentAddress - Address for change output
+     * @param additionalDustNeeded - Additional dust needed for rune outputs
+     * @returns Fee calculation result
+     */
+    private addBtcAndFees;
+    /**
+     * Build the complete transaction
+     * Handles both BTC-only and Rune transactions
+     * @returns Built PSBT and total fee
+     */
+    build(action: string, nonce: bigint, actionParams?: string): Promise<bitcoin.Psbt>;
+    /**
+     * Submit the signed transaction to the orchestrator for execution
+     * This method sends the signed PSBT along with the intention set to the orchestrator canister
+     *
+     * @param signedPsbtHex - The signed PSBT in hexadecimal format from the user's wallet
+     * @returns Promise that resolves to the orchestrator's response on success
+     * @throws Error if intention set is not available or if the orchestrator returns an error
+     *
+     * @example
+     * ```typescript
+     * // After building and signing the transaction
+     * const signedPsbt = await wallet.signPsbt(psbt);
+     * const result = await transaction.send(signedPsbt.toHex());
+     * ```
+     */
+    send(signedPsbtHex: string): Promise<any>;
+}
+
+export declare interface TransactionConfig {
+    network: Network;
+    exchangeId: string;
+    address: string;
+    paymentAddress: string;
+    poolAddress: string;
+    runeId?: string;
+    runeUtxos?: Utxo[];
+    btcUtxos: Utxo[];
+    poolUtxos: Utxo[];
+    sendBtcAmount: bigint;
+    sendRuneAmount: bigint;
+    receiveBtcAmount: bigint;
+    receiveRuneAmount: bigint;
+}
+
+declare interface UseBalanceOptions {
+    /** Auto-refresh interval in milliseconds (0 to disable) */
+    refreshInterval?: number;
+    /** Enable automatic refresh when wallet changes */
+    autoRefresh?: boolean;
+}
+
+/**
+ * Hook to get and manage Bitcoin balance
+ * @returns Object with balance, loading state, error, and refresh function
+ */
+export declare function useBtcBalance(options?: UseBalanceOptions): {
+    balance: number | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook to get and manage Bitcoin UTXOs
+ * @returns Object with UTXOs, loading state, error, and refresh function
+ */
+export declare function useBtcUtxos(options?: UseBalanceOptions): {
+    utxos: Utxo[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook to get pool information by address
+ * @param poolAddress - The pool address to get info for
+ * @returns Object with pool info, loading state, error, and refetch function
+ */
+export declare function usePoolInfo(poolAddress?: string): {
+    poolInfo: PoolInfo | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook to get list of all pools
+ * @returns Object with pools, loading state, error, and refetch function
+ */
+export declare function usePoolList(): {
+    pools: Pool[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
+export declare function useRee(): ReeContextValue;
+
+/**
+ * Hook to get and manage Rune balance for a specific rune
+ * @param runeId - The rune ID to get balance for
+ * @returns Object with balance, loading state, error, and refresh function
+ */
+export declare function useRuneBalance(runeId: string | undefined, options?: UseBalanceOptions): {
+    balance: number | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook to get rune information by ID
+ * @param runeId - The rune ID to get info for
+ * @returns Object with rune info, loading state, error, and refetch function
+ */
+export declare function useRuneInfo(runeId?: string): {
+    runeInfo: RuneInfo | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook to get and manage Rune UTXOs for a specific rune
+ * @param runeId - The rune ID to get UTXOs for
+ * @returns Object with UTXOs, loading state, error, and refresh function
+ */
+export declare function useRuneUtxos(runeId: string, options?: UseBalanceOptions): {
+    utxos: Utxo[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook to search for runes by keyword
+ * @param keyword - Search term (rune ID or partial name)
+ * @returns Object with runes, loading state, error, and search function
+ */
+export declare function useSearchRunes(): (searchKeyword?: string) => Promise<RuneInfo[]>;
+
+export declare namespace utils {
+    export {
+        hexToBytes,
+        bytesToHex,
+        toBitcoinNetwork,
+        getScriptByAddress,
+        getAddressType
+    }
+}
+
+export declare type Utxo = {
+    txid: string;
+    vout: number;
+    satoshis: string;
+    height?: number;
+    runes: {
+        id: string;
+        amount: string;
+    }[];
+    address: string;
+    scriptPk: string;
+};
+
+export { }