@omnity/ree-client-ts-sdk 0.5.2 → 0.5.3

package/dist/react.d.ts

@@ -0,0 +1,691 @@
+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 formatPoolUtxo(poolAddress: string, input: {
+    coins: [{
+        id: string;
+        value: bigint;
+    }];
+    sats: bigint;
+    txid: string;
+    vout: number;
+}, network: Network): Utxo;
+
+declare function getAddressType(address: string): AddressType;
+
+declare function getScriptByAddress(address: string, network?: Network): Uint8Array<ArrayBufferLike>;
+
+declare function getUtxoProof(utxos: Utxo[], network: Network): Promise<number[] | null>;
+
+declare function hexToBytes(hex: string): Uint8Array;
+
+declare type InputCoin = {
+    coin: CoinBalance;
+    from: string;
+};
+
+declare type Intention = {
+    exchangeId?: string;
+    inputCoins: InputCoin[];
+    outputCoins: OutputCoin[];
+    action: string;
+    actionParams?: string;
+    poolAddress: string;
+    poolUtxos?: Utxo[];
+    nonce: bigint;
+};
+
+declare class Maestro {
+    private axios;
+    constructor(params: {
+        baseUrl: string;
+        apiKey: string;
+    });
+    utxosByAddress(address: string, cursor?: string | null, excludeMetaprotocols?: boolean): Promise<{
+        next_cursor: string | null;
+        last_updated: {
+            block_hash: string;
+            block_height: bigint;
+        };
+        data: RawBtcUtxo[];
+    }>;
+    utxosByAddressMempoolAware(address: string, cursor?: string | null, excludeMetaprotocols?: boolean): Promise<{
+        next_cursor: string | null;
+        last_updated: {
+            block_hash: string;
+            block_height: bigint;
+        };
+        data: RawBtcUtxo[];
+    }>;
+    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[];
+    }>;
+    runeInfo(runeId: string): Promise<{
+        last_updated: {
+            block_hash: string;
+            block_height: bigint;
+        };
+        data: RawRuneInfo;
+    }>;
+}
+
+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 RawRuneInfo = {
+    id: string;
+    symbol: string;
+    spaced_name: string;
+    divisibility: number;
+};
+
+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
+ */
+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 pending (zero-confirmation) Bitcoin UTXOs for a payment address
+     * These are UTXOs from Ree protocol transactions that have been broadcast but not yet confirmed
+     * Filters out UTXOs that contain runes to get pure Bitcoin UTXOs only
+     * @param paymentAddress - The Bitcoin payment address to check for pending UTXOs
+     * @returns Array of pending Bitcoin UTXOs without runes from Ree transactions
+     */
+    private getPendingBtcUtxos;
+    /**
+     * Get pending (zero-confirmation) Rune UTXOs for an ordinals address
+     * These are UTXOs from Ree protocol transactions that have been broadcast but not yet confirmed
+     * Filters to include only UTXOs that contain runes
+     * @param address - The ordinals address to check for pending rune UTXOs
+     * @returns Array of pending UTXOs containing runes from Ree transactions
+     */
+    private getPendingRuneUtxos;
+    /**
+     * Get all Bitcoin UTXOs for the payment address
+     * Handles pagination automatically to fetch all available UTXOs
+     * @returns Array of Bitcoin UTXOs
+     */
+    getBtcUtxos(paymentAddress: string, excludeMetaprotocols?: boolean): 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
+     * @param params - Transaction parameters
+     * @param params.address - Bitcoin address
+     * @param params.paymentAddress - Ordinals address
+     * @param params.involvedRuneId - Optional rune ID for rune swaps
+     * @returns Transaction instance
+     */
+    createTransaction({ address, paymentAddress, feeRate, mergeSelfRuneBtcOutputs, }: {
+        address: string;
+        paymentAddress: string;
+        feeRate?: number;
+        mergeSelfRuneBtcOutputs?: boolean;
+    }): Promise<Transaction>;
+    getRecommendedFeeRate(): Promise<{
+        min: number;
+        max: number;
+    }>;
+}
+
+declare interface ReeContextValue {
+    client: ReeClient;
+    exchange: ActorSubclass;
+    address: string;
+    paymentAddress: string;
+    updateWallet: (wallet: {
+        address?: string;
+        paymentAddress?: string;
+    }) => void;
+    createTransaction: (params?: {
+        feeRate?: number;
+        mergeSelfRuneBtcOutputs?: boolean;
+    }) => 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
+ */
+declare class Transaction {
+    private psbt;
+    private client;
+    private inputAddressTypes;
+    private outputAddressTypes;
+    private config;
+    /** Track dust amounts from user input UTXOs for fee calculation */
+    private userInputUtxoDusts;
+    private intentions;
+    private txFee;
+    private additionalDustNeeded;
+    private inputUtxos;
+    constructor(config: TransactionConfig, client: ReeClient);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Resolve and fetch all UTXOs required by the current intention set, grouped by address.
+     *
+     * How it works:
+     * - Scans every intention to determine, per address, whether BTC UTXOs are needed and which rune IDs are needed.
+     *   • For inputCoins, uses their `from` address.
+     *   • For outputCoins, uses their `to` address.
+     *   • Pool address is always considered “involved” for any coin that appears in the intention.
+     *   • The user's payment address is always flagged as needing BTC (to pay fees/change).
+     * - Deduplicates addresses and rune IDs, then fetches UTXOs in parallel via the client:
+     *   • BTC UTXOs: client.getBtcUtxos(address)
+     *   • Rune UTXOs: client.getRuneUtxos(address, runeId)
+     * - Any fetch error is treated as an empty list for robustness.
+     *
+     * Returns:
+     * - An object with two maps:
+     *   • btc: Record<address, Utxo[]>
+     *   • rune: Record<address, Record<runeId, Utxo[]>>
+     */
+    private getInvolvedAddressUtxos;
+    /**
+     * Select inputs (UTXOs) according to the intentions and compute the coin outputs per address.
+     *
+     * Inputs:
+     * - addressUtxos: UTXOs grouped as returned by getInvolvedAddressUtxos().
+     *
+     * Algorithm (high level):
+     * 1) Validate there is at least one intention.
+     * 2) For each intention, ensure symmetry between inputCoins and outputCoins around the pool:
+     *    - If a coin is sent from an address to the pool but not listed as output to the pool, add an output-to-pool entry.
+     *    - If a coin is received from the pool by an address but not listed as input-from-pool, add an input-from-pool entry.
+     * 3) Aggregate per-address input and output coin amounts (addressInputCoinAmounts, addressOutputCoinAmounts).
+     * 4) For each [address, coinId] in the input amounts:
+     *    - BTC (coinId === BITCOIN_ID):
+     *      • If address is the user's payment address, we treat it specially by decrementing its BTC in addressOutputCoinAmounts
+     *        (the actual funding and fee handling will be done later in addBtcAndFees).
+     *      • Otherwise, select BTC UTXOs (preferring rune-free for non-pool addresses), add them as inputs, compute change and
+     *        add that change to addressOutputCoinAmounts[address]. If the address is a pool, also credit any rune balances
+     *        contained in selected pool BTC UTXOs to addressOutputCoinAmounts for later distribution.
+     *    - Rune (coinId !== BITCOIN_ID): select rune UTXOs for the required runeId, add as inputs, compute rune change and add
+     *      to addressOutputCoinAmounts[address].
+     * 5) Ensure all pool UTXOs are included: for pool addresses that only appear on the receiving side, add all their BTC/rune
+     *    UTXOs as inputs and credit their total balances into addressOutputCoinAmounts accordingly.
+     *
+     * Returns:
+     * - addressOutputCoinAmounts: Record<address, Record<coinId, bigint>> — the final coin amounts to be sent to each address.
+     */
+    private addInputsAndCalculateOutputs;
+    /**
+     * Materialize outputs from the computed addressReceiveCoinAmounts.
+     *
+     * Steps:
+     * 1) Collect all rune IDs present across recipients. If any runes are to be transferred, first build a Runestone (edicts)
+     *    and add an OP_RETURN output (at index 0). Edicts reference subsequent output indices.
+     * 2) For each address that receives runes, also ensure a BTC output exists at that index:
+     *    - If an explicit BTC amount is provided for the address and the address is not the user's own rune address, use it.
+     *    - Otherwise, add a dust-sized BTC output (UTXO_DUST) to carry the runes, and track additionalDustNeeded for fees.
+     *    After using an explicit BTC amount for a rune recipient, remove it from the remaining BTC-only outputs map.
+     * 3) Finally, add any remaining BTC-only outputs where amount > 0.
+     *
+     * Notes:
+     * - Output values are bigint; scripts use Uint8Array, compatible with bitcoinjs-lib v7.
+     * - Output ordering: OP_RETURN (if any) first, then rune recipients in the order we build edicts, then remaining BTC outputs.
+     */
+    private addOutputs;
+    /**
+     * Add an intention to the transaction
+     * Multiple intentions can be added to create complex, atomic transactions
+     *
+     * @param intention - The intention object containing:
+     *   - poolAddress: Target pool address
+     *   - inputCoins: Coins being sent to the pool
+     *   - outputCoins: Coins expected from the pool
+     *   - action: Action type (swap, deposit, withdraw, etc.)
+     *   - nonce: Unique identifier for this intention
+     *
+     * @example
+     * ```typescript
+     * // Add a swap intention
+     * transaction.addIntention({
+     *   poolAddress: "bc1q...",
+     *   inputCoins: [{ id: "0:0", value: BigInt(100000) }], // Send BTC
+     *   outputCoins: [{ id: "840000:3", value: BigInt(1000) }], // Receive runes
+     *   action: "swap",
+     *   nonce: BigInt(Date.now()),
+     * });
+     * ```
+     */
+    addIntention(intention: Intention): void;
+    /**
+     * Build the complete PSBT with all added intentions
+     * This method processes all intentions atomically and calculates:
+     * - Required inputs from user and pools
+     * - Output distributions to user and pools
+     * - Transaction fees and change outputs
+     * - Runestone for rune transfers
+     *
+     * @returns Promise resolving to the built PSBT ready for signing
+     * @throws Error if insufficient funds or invalid intentions
+     *
+     * @example
+     * ```typescript
+     * // After adding intentions
+     * const { psbt, txid } = await transaction.build();
+     * const signedPsbt = await wallet.signPsbt(psbt);
+     * ```
+     */
+    build(): Promise<{
+        psbt: bitcoin.Psbt;
+        txid: string;
+        fee: bigint;
+    }>;
+    private static estimateTxVirtualSize;
+    private static parseAddressType;
+    private static varIntSize;
+    /**
+     * 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>;
+}
+
+declare interface TransactionConfig {
+    network: Network;
+    exchangeId: string;
+    address: string;
+    paymentAddress: string;
+    clientInfo?: string;
+    /** Optional manual fee rate in satoshis per virtual byte */
+    feeRate?: number;
+    /**
+     * When true, rune outputs to the local rune address reuse existing BTC value
+     * instead of emitting a separate dust output. Defaults to false.
+     */
+    mergeSelfRuneBtcOutputs?: boolean;
+}
+
+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>;
+};
+
+/**
+ * Hook to retrieve the recommended fee rate range
+ * @returns Object with minimum/maximum fee rates, loading state, error, and refetch function
+ */
+export declare function useRecommendedFeeRate(options?: UseBalanceOptions): {
+    feeRate: {
+        min: number;
+        max: number;
+    } | null;
+    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,
+        formatPoolUtxo,
+        getUtxoProof
+    }
+}
+
+export declare type Utxo = {
+    txid: string;
+    vout: number;
+    satoshis: string;
+    height?: number;
+    runes: {
+        id: string;
+        amount: string;
+    }[];
+    address: string;
+    scriptPk: string;
+};
+
+export { }