@aboutcircles/sdk-transfers 0.1.5 → 0.1.7

package/dist/TransferBuilder.d.ts

@@ -1,13 +1,33 @@
-import type { Address, AdvancedTransferOptions } from '@aboutcircles/sdk-types';
-import type { Core } from '@aboutcircles/sdk-core';
+import type { Address, AdvancedTransferOptions, PathfindingResult, CirclesConfig } from '@aboutcircles/sdk-types';
 /**
  * TransferBuilder constructs transfer transactions without executing them
  * Handles pathfinding, wrapped token unwrapping/wrapping, and flow matrix construction
  */
 export declare class TransferBuilder {
-    private core;
-    private rpc;
-    constructor(core: Core);
+    private config;
+    private hubV2;
+    private liftERC20;
+    private rpcClient;
+    private pathfinder;
+    private balance;
+    private group;
+    constructor(config: CirclesConfig);
+    /**
+     * Build flow matrix transaction from a pre-computed path
+     * This is a lower-level function useful when you already have a path and want to build transactions
+     *
+     * @param from Sender address
+     * @param to Recipient address
+     * @param path Pathfinding result with transfers
+     * @param options Advanced transfer options
+     * @param aggregate Whether to aggregate tokens at destination
+     * @returns Array of transactions to execute in order
+     */
+    buildFlowMatrixTx(from: Address, to: Address, path: PathfindingResult, options?: AdvancedTransferOptions, aggregate?: boolean): Promise<Array<{
+        to: Address;
+        data: `0x${string}`;
+        value: bigint;
+    }>>;
     /**
      * Construct an advanced transfer transaction
      * Returns the list of transactions to execute without executing them
@@ -18,21 +38,47 @@ export declare class TransferBuilder {
      * @param options Advanced transfer options
      * @returns Array of transactions to execute in order
      */
-    constructAdvancedTransfer(from: Address, to: Address, amount: number | bigint, options?: AdvancedTransferOptions): Promise<Array<{
+    constructAdvancedTransfer(from: Address, to: Address, amount: number | bigint, options?: AdvancedTransferOptions, aggregate?: boolean): Promise<Array<{
         to: Address;
         data: `0x${string}`;
         value: bigint;
     }>>;
     /**
-     * Construct a replenish transaction to convert wrapped/other tokens into unwrapped personal CRC
-     * This uses pathfinder to find the best way to convert available tokens (including wrapped tokens)
-     * into the sender's own unwrapped ERC1155 personal CRC tokens
+     * Construct a replenish transaction to acquire a specific token in unwrapped form
+     *
+     * This function tops up your unwrapped balance to reach the target amount (not adding on top).
+     *
+     * Process:
+     * 1. Checks current balance of the target token (unwrapped and wrapped)
+     * 2. If sufficient wrapped tokens exist, unwraps only what's needed
+     * 3. If insufficient, uses pathfinding with trust simulation to acquire tokens
+     * 4. Temporarily trusts the token owner if needed for the transfer
+     * 5. Untrusts after the transfer completes
+     *
+     * Note on Precision:
+     * - Pathfinding uses 6-decimal precision (last 12 decimals are truncated)
+     * - The function rounds UP to the next 6-decimal boundary to ensure you get at least the target
+     * - Final balance will be AT or SLIGHTLY ABOVE target (e.g., 1900.000001 instead of exactly 1900.000000)
+     * - The excess is always less than 0.000001 CRC and ensures you never fall short of the target
+     *
+     * @param from The account address that needs tokens
+     * @param tokenId The token ID to replenish (avatar address whose tokens we want)
+     * @param amount Target unwrapped balance in atto-circles (will top up to this amount)
+     * @param receiver Optional receiver address (defaults to 'from')
+     * @returns Array of transactions to execute in order
      *
-     * @param avatarAddress The avatar address to replenish (convert tokens to their personal CRC)
-     * @param options Optional pathfinding options
-     * @returns Array of transactions to execute in order to perform the replenish
+     * @example
+     * ```typescript
+     * // If you have 100 CRC unwrapped and call replenish(1000 CRC),
+     * // it will acquire 900 CRC to reach a total of 1000 CRC
+     * const txs = await transferBuilder.constructReplenish(
+     *   myAddress,
+     *   tokenAddress,
+     *   1000n * 10n**18n // 1000 CRC
+     * );
+     * ```
      */
-    constructReplenish(avatarAddress: Address, options?: Omit<AdvancedTransferOptions, 'txData'>): Promise<Array<{
+    constructReplenish(from: Address, tokenId: Address, amount: bigint, receiver?: Address): Promise<Array<{
         to: Address;
         data: `0x${string}`;
         value: bigint;

package/dist/TransferBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TransferBuilder.d.ts","sourceRoot":"","sources":["../src/TransferBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAqB,MAAM,yBAAyB,CAAC;AACnG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAYnD;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,GAAG,CAAa;gBAEZ,IAAI,EAAE,IAAI;IAKtB;;;;;;;;;OASG;IACG,yBAAyB,CAC7B,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAgLtE;;;;;;;;OAQG;IACG,kBAAkB,CACtB,aAAa,EAAE,OAAO,EACtB,OAAO,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,QAAQ,CAAC,GAChD,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAetE;;;;;OAKG;YACW,mBAAmB;IAUjC;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IAkCpC;;;;;;;;OAQG;IACH,OAAO,CAAC,qCAAqC;IAmE7C;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAM9B;;;;;;;OAOG;YACW,2BAA2B;CAoC1C"}
+{"version":3,"file":"TransferBuilder.d.ts","sourceRoot":"","sources":["../src/TransferBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAoBlH;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,KAAK,CAAe;gBAEhB,MAAM,EAAE,aAAa;IAgBjC;;;;;;;;;;OAUG;IACG,iBAAiB,CACrB,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,OAAO,EACX,IAAI,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE,uBAAuB,EACjC,SAAS,GAAE,OAAe,GACzB,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAkGtE;;;;;;;;;OASG;IACG,yBAAyB,CAC7B,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,OAAO,CAAC,EAAE,uBAAuB,EACjC,SAAS,GAAE,OAAe,GACzB,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IA+FtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IAEG,kBAAkB,CACtB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IA0TtE;;;;;OAKG;YACW,mBAAmB;IAUjC;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IA4BpC;;;;;;;;OAQG;IACH,OAAO,CAAC,qCAAqC;IA6D7C;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAM9B;;;;;;;OAOG;YACW,2BAA2B;CAoC1C"}