@omnity/ree-client-ts-sdk 0.3.0 → 0.3.3

package/README.md

@@ -68,20 +68,31 @@ const poolInfo = await client.getPoolInfo("pool-address");
 ```typescript
 // Create a transaction for a single pool operation
 const transaction = await client.createTransaction({
-  address: "bc1q...", // Bitcoin address for runes
+  address: "bc1p...", // Bitcoin address for runes
   paymentAddress: "bc1q...", // Payment address for BTC
-  involvedPoolAddresses: ["bc1q..."], // Pool addresses involved
-  involvedRuneIds: ["840000:3"], // Optional: rune IDs if trading runes
 });
 
 // Add a single intention (e.g., swap BTC for runes)
 transaction.addIntention({
-  poolAddress: "bc1q...",
+  poolAddress: "bc1p...",
+  poolUtxos: [],
   inputCoins: [
-    { id: "0:0", value: BigInt(100000) }, // Send 0.001 BTC
+    {
+      coin: {
+        id: "0:0",
+        value: BigInt(100000),
+      }, // Send 0.001 BTC,
+      from: paymentAddress,
+    },
   ],
   outputCoins: [
-    { id: "840000:3", value: BigInt(1000) }, // Receive 1000 runes
+    {
+      coin: {
+        id: "840000:3",
+        value: BigInt(1000),
+      }, // Receive 1000 runes,
+      to: address,
+    },
   ],
   action: "swap",
   nonce: BigInt(1234),
@@ -98,18 +109,23 @@ const result = await transaction.send(signedPsbt.toHex());
 ```typescript
 // Create a complex transaction with multiple operations
 const transaction = await client.createTransaction({
-  address: "bc1q...",
+  address: "bc1p...",
   paymentAddress: "bc1q...",
-  involvedPoolAddresses: ["bc1q...pool1", "bc1q...pool2"],
-  involvedRuneIds: ["840000:3", "840000:5"],
 });
 
 // Add multiple intentions in a single transaction
 // Intention 1: Deposit BTC to Pool 1
 transaction.addIntention({
-  poolAddress: "bc1q...pool1",
+  poolAddress: "bc1p...pool1",
   inputCoins: [
-    { id: "0:0", value: BigInt(50000) }, // Deposit 0.0005 BTC
+    {
+      // Deposit 0.0005 BTC
+      coin: {
+        id: "0:0",
+        value: BigInt(50000),
+      },
+      from: paymentAddress,
+    },
   ],
   outputCoins: [],
   action: "deposit",
@@ -120,10 +136,24 @@ transaction.addIntention({
 transaction.addIntention({
   poolAddress: "bc1q...pool2",
   inputCoins: [
-    { id: "840000:3", value: BigInt(500) }, // Send 500 of rune A
+    {
+      // Send 500 of rune A,
+      coin: {
+        id: "840000:3",
+        value: BigInt(500),
+      },
+      from: address,
+    },
   ],
   outputCoins: [
-    { id: "840000:5", value: BigInt(250) }, // Receive 250 of rune B
+    {
+      // Receive 250 of rune B,
+      coin: {
+        id: "840000:5",
+        value: BigInt(250),
+      },
+      to: address,
+    },
   ],
   action: "swap",
   nonce: BigInt(Date.now() + 1),
@@ -149,7 +179,7 @@ function App() {
 }
 
 function WalletComponent() {
-  const { client, address, updateWallet, createTransaction } = useRee();
+  const { client, address, paymentAddress, updateWallet, createTransaction } = useRee();
   const { balance: btcBalance } = useBtcBalance();
 
   const connectWallet = () => {
@@ -161,24 +191,45 @@ function WalletComponent() {
 
   const executeComplexTransaction = async () => {
     // Create transaction with multiple pools
-    const tx = await createTransaction({
-      involvedPoolAddresses: ["pool1", "pool2"],
-      involvedRuneIds: ["840000:3"],
-    });
+    const tx = await createTransaction();
 
     // Add multiple intentions
     tx.addIntention({
       poolAddress: "pool1",
-      inputCoins: [{ id: "0:0", value: BigInt(100000) }],
-      outputCoins: [{ id: "840000:3", value: BigInt(1000) }],
+      inputCoins: [{
+        coin: {
+          id: "0:0",
+          value: BigInt(100000)
+        },
+        from: paymentAddress
+      }],
+      outputCoins: [
+        coint: {
+          id: "840000:3",
+          value: BigInt(1000)
+        },
+        to: address
+      ],
       action: "swap",
       nonce: BigInt(Date.now()),
     });
 
     tx.addIntention({
       poolAddress: "pool2",
-      inputCoins: [{ id: "840000:3", value: BigInt(500) }],
-      outputCoins: [{ id: "0:0", value: BigInt(50000) }],
+      inputCoins: [{
+        coin: {
+          id: "840000:3",
+          value: BigInt(500)
+        },
+        from: address
+      }],
+      outputCoins: [{
+        coin: {
+          id: "0:0",
+          value: BigInt(50000)
+        },
+        to: paymentAddress
+      }],
       action: "swap",
       nonce: BigInt(Date.now() + 1),
     });
@@ -228,13 +279,19 @@ function MyComponent({ children }) {
       value: depositBtcAmount,
     });
 
-    const tx = await createTransaction({
-      involvedPoolAddresses: ["bc1q..."],
-    });
+    const tx = await createTransaction();
 
     tx.addIntention({
       poolAddress: "bc1q...",
-      inputCoins: [{ id: "0:0", value: depositBtcAmount }],
+      inputCoins: [
+        {
+          coin: {
+            id: "0:0",
+            value: depositBtcAmount,
+          },
+          from: paymentAddress,
+        },
+      ],
       outputCoins: [],
       action: "deposit",
       nonce: depositOffer.nonce,
@@ -307,7 +364,7 @@ new ReeClient(config: Config)
 
 ##### Transaction Methods
 
-- `createTransaction(params): Promise<Transaction>` - Create a transaction for trading with a liquidity pool
+- `createTransaction(): Promise<Transaction>` - Create a transaction
 
 ### Transaction
 
@@ -323,18 +380,37 @@ Transaction builder for Bitcoin and Rune transactions with multi-intention suppo
 
 ```typescript
 interface Intention {
-  poolAddress: string; // Target pool address
-  inputCoins: CoinBalance[]; // Coins being sent to the pool
-  outputCoins: CoinBalance[]; // Coins expected from the pool
-  action: string; // Action type (swap, deposit, withdraw, etc.)
-  actionParams?: string; // Optional action parameters
-  nonce: bigint; // Unique nonce for the intention
+  // Target pool address
+  poolAddress: string;
+  // the UTXOs obtained through the pool’s pre methods
+  // if not provided, will be fetched via the maestro API.
+  poolUtxos?: [];
+  // Coins being sent to the pool
+  inputCoins: InputCoin[];
+  // Coins expected from the pool
+  outputCoins: InputCoin[];
+  // Action type (swap, deposit, withdraw, etc.)
+  action: string;
+  // Optional action parameters
+  actionParams?: string;
+  // Unique nonce for the intention
+  nonce: bigint;
 }
 
-interface CoinBalance {
+type CoinBalance = {
   id: string; // Coin ID ("0:0" for BTC, "840000:3" for runes)
   value: bigint; // Amount in smallest unit
-}
+};
+
+type InputCoin = {
+  coin: CoinBalance;
+  from: string;
+};
+
+type OutputCoin = {
+  coin: CoinBalance;
+  to: string;
+};
 ```
 
 ### Multi-Intention Transaction Benefits
@@ -494,35 +570,3 @@ enum Network {
   Testnet = "testnet",
 }
 ```
-
-## Error Handling
-
-```typescript
-try {
-  const transaction = await client.createTransaction({
-    address: "bc1q...",
-    paymentAddress: "bc1q...",
-    involvedPoolAddresses: ["bc1q..."],
-  });
-
-  transaction.addIntention({
-    poolAddress: "bc1q...",
-    inputCoins: [{ id: "0:0", value: BigInt(100000) }],
-    outputCoins: [{ id: "840000:3", value: BigInt(1000) }],
-    action: "swap",
-    nonce: BigInt(Date.now()),
-  });
-
-  const psbt = await transaction.build();
-  const signedPsbt = await wallet.signPsbt(psbt);
-  const result = await transaction.send(signedPsbt.toHex());
-} catch (error) {
-  if (error.message.includes("INSUFFICIENT")) {
-    console.error("Insufficient funds:", error);
-  } else if (error.message.includes("Pool")) {
-    console.error("Pool error:", error);
-  } else {
-    console.error("Transaction failed:", error);
-  }
-}
-```

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export declare type AddressType = (typeof AddressType)[keyof typeof AddressType]
 
 declare function bytesToHex(bytes: Uint8Array): string;
 
-export declare type CoinBalance = {
+declare type CoinBalance = {
     id: string;
     value: bigint;
 };
@@ -47,13 +47,23 @@ export declare type Config = {
     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 hexToBytes(hex: string): Uint8Array;
 
-declare type InputCoin = {
+export declare type InputCoin = {
     coin: CoinBalance;
     from: string;
 };
@@ -64,6 +74,7 @@ export declare type Intention = {
     action: string;
     actionParams?: string;
     poolAddress: string;
+    poolUtxos?: Utxo[];
     nonce: bigint;
 };
 
@@ -73,7 +84,7 @@ declare class Maestro {
         baseUrl: string;
         apiKey: string;
     });
-    utxosByAddress(address: string, cursor?: string | null): Promise<{
+    utxosByAddress(address: string, cursor?: string | null, excludeMetaprotocols?: boolean): Promise<{
         next_cursor: string | null;
         last_updated: {
             block_hash: string;
@@ -81,29 +92,28 @@ declare class Maestro {
         };
         data: RawBtcUtxo[];
     }>;
-    inscriptionsByAddress(address: string, cursor?: string | null): Promise<{
+    inscriptionIdsByCollectionSymbol(collection: string, cursor?: string | null): Promise<{
         next_cursor: string | null;
         last_updated: {
             block_hash: string;
             block_height: bigint;
         };
-        data: RawInscription[];
+        data: string[];
     }>;
-    inscriptionIdsByCollectionSymbol(collection: string, cursor?: string | null): Promise<{
+    runeUtxosByAddress(address: string, rune: string, cursor?: string | null): Promise<{
         next_cursor: string | null;
         last_updated: {
             block_hash: string;
             block_height: bigint;
         };
-        data: string[];
+        data: RawRuneUtxo[];
     }>;
-    runeUtxosByAddress(address: string, rune: string, cursor?: string | null): Promise<{
-        next_cursor: string | null;
+    runeInfo(runeId: string): Promise<{
         last_updated: {
             block_hash: string;
             block_height: bigint;
         };
-        data: RawRuneUtxo[];
+        data: RawRuneInfo;
     }>;
 }
 
@@ -114,7 +124,7 @@ export declare const Network: {
 
 export declare type Network = (typeof Network)[keyof typeof Network];
 
-declare type OutputCoin = {
+export declare type OutputCoin = {
     coin: CoinBalance;
     to: string;
 };
@@ -164,14 +174,11 @@ declare type RawBtcUtxo = {
     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 RawRuneInfo = {
+    id: string;
+    symbol: string;
+    spaced_name: string;
+    divisibility: number;
 };
 
 declare type RawRuneUtxo = {
@@ -217,7 +224,7 @@ export declare class ReeClient {
      * Handles pagination automatically to fetch all available UTXOs
      * @returns Array of Bitcoin UTXOs
      */
-    getBtcUtxos(paymentAddress: string): Promise<Utxo[]>;
+    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
@@ -284,10 +291,7 @@ declare interface ReeContextValue {
         address?: string;
         paymentAddress?: string;
     }) => void;
-    createTransaction: (params: {
-        involvedRuneIds?: string[];
-        involvedPoolAddresses: string[];
-    }) => Promise<Transaction>;
+    createTransaction: () => Promise<Transaction>;
 }
 
 export declare function ReeProvider({ children, config }: ReeProviderProps): JSX_2.Element;
@@ -313,23 +317,17 @@ declare function toBitcoinNetwork(network: Network): bitcoin.networks.Network;
  */
 export 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;
-    /** Orchestrator actor for fee estimation */
-    readonly orchestrator: ActorSubclass;
     private intentions;
     private txFee;
     private additionalDustNeeded;
     private inputUtxos;
-    private getBtcUtxos;
-    private getRuneUtxos;
-    constructor(config: TransactionConfig, orchestrator: ActorSubclass, utxoFetchers: {
-        btc: (address: string) => Promise<Utxo[]>;
-        rune: (address: string, runeId: string) => Promise<Utxo[]>;
-    });
+    constructor(config: TransactionConfig, client: ReeClient);
     /**
      * Add a UTXO as transaction input
      * @param utxo - The UTXO to add as input
@@ -370,8 +368,70 @@ export declare class Transaction {
      * @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
@@ -544,7 +604,8 @@ export declare namespace utils {
         bytesToHex,
         toBitcoinNetwork,
         getScriptByAddress,
-        getAddressType
+        getAddressType,
+        formatPoolUtxo
     }
 }