@aboutcircles/sdk-transfers 0.1.5 → 0.1.7

package/dist/TransferBuilder.js

@@ -1,18 +1,120 @@
-import { createFlowMatrix as createFlowMatrixUtil, getTokenInfoMapFromPath, getWrappedTokensFromPath, replaceWrappedTokensWithAvatars, } from '@aboutcircles/sdk-pathfinder';
-import { CirclesRpc } from '@aboutcircles/sdk-rpc';
-import { bytesToHex, CirclesConverter, encodeFunctionData, ZERO_ADDRESS } from '@aboutcircles/sdk-utils';
-import { InflationaryCirclesContract, DemurrageCirclesContract, CirclesType } from '@aboutcircles/sdk-core';
+import { createFlowMatrix as createFlowMatrixUtil, prepareFlowMatrixStreams, getTokenInfoMapFromPath, getWrappedTokensFromPath, replaceWrappedTokensWithAvatars, } from '@aboutcircles/sdk-pathfinder';
+import { RpcClient, PathfinderMethods, BalanceMethods, GroupMethods } from '@aboutcircles/sdk-rpc';
+import { CirclesConverter } from '@aboutcircles/sdk-utils/circlesConverter';
+import { ZERO_ADDRESS } from '@aboutcircles/sdk-utils/constants';
+import { HubV2ContractMinimal, LiftERC20ContractMinimal, DemurrageCirclesContractMinimal, InflationaryCirclesContractMinimal, } from '@aboutcircles/sdk-core/minimal';
+import { CirclesType } from '@aboutcircles/sdk-types';
 import { TransferError } from './errors';
 /**
  * TransferBuilder constructs transfer transactions without executing them
  * Handles pathfinding, wrapped token unwrapping/wrapping, and flow matrix construction
  */
 export class TransferBuilder {
-    core;
-    rpc;
-    constructor(core) {
-        this.core = core;
-        this.rpc = new CirclesRpc(core.config.circlesRpcUrl);
+    config;
+    hubV2;
+    liftERC20;
+    rpcClient;
+    pathfinder;
+    balance;
+    group;
+    constructor(config) {
+        this.config = config;
+        this.hubV2 = new HubV2ContractMinimal({
+            address: config.v2HubAddress,
+            rpcUrl: config.circlesRpcUrl,
+        });
+        this.liftERC20 = new LiftERC20ContractMinimal({
+            address: config.liftERC20Address,
+            rpcUrl: config.circlesRpcUrl,
+        });
+        this.rpcClient = new RpcClient(config.circlesRpcUrl);
+        this.pathfinder = new PathfinderMethods(this.rpcClient);
+        this.balance = new BalanceMethods(this.rpcClient);
+        this.group = new GroupMethods(this.rpcClient);
+    }
+    /**
+     * 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
+     */
+    async buildFlowMatrixTx(from, to, path, options, aggregate = false) {
+        const fromAddr = from.toLowerCase();
+        const toAddr = to.toLowerCase();
+        // Validate path
+        if (!path.transfers || path.transfers.length === 0) {
+            throw TransferError.noPathFound(fromAddr, toAddr);
+        }
+        let workingPath = { ...path };
+        // If aggregate flag is set and toTokens has exactly one element,
+        // add an aggregation transfer step from recipient to themselves.
+        if (aggregate && options?.toTokens?.length === 1) {
+            const aggregateToken = options.toTokens[0].toLowerCase();
+            if (path.maxFlow > 0n) {
+                // Add a self-transfer to aggregate all tokens into the single token type
+                workingPath.transfers.push({
+                    from: toAddr,
+                    to: toAddr,
+                    tokenOwner: aggregateToken,
+                    value: path.maxFlow
+                });
+            }
+        }
+        // Get token info for all tokens in the path using pathfinder utility
+        const tokenInfoMap = await getTokenInfoMapFromPath(fromAddr, this.config.circlesRpcUrl, workingPath);
+        // Get wrapped tokens found in the path with their amounts and types
+        const wrappedTokensInPath = getWrappedTokensFromPath(workingPath, tokenInfoMap);
+        const hasWrappedTokens = Object.keys(wrappedTokensInPath).length > 0;
+        // Validate that wrapped tokens are enabled if they're needed
+        if (hasWrappedTokens && !options?.useWrappedBalances) {
+            throw TransferError.wrappedTokensRequired();
+        }
+        let unwrapCalls = [];
+        let wrapCalls = [];
+        if (hasWrappedTokens) {
+            // Fetch token balances once for both unwrap and wrap operations
+            const balanceMap = await this._getTokenBalanceMap(fromAddr);
+            // Create unwrap calls for demurraged tokens (unwrap exact amount used in path)
+            const demurragedUnwrapCalls = this._createDemurragedUnwrapCalls(wrappedTokensInPath);
+            // Create unwrap and wrap calls for inflationary tokens
+            const { unwrapCalls: inflationaryUnwrapCalls, wrapCalls: inflationaryWrapCalls } = this._createInflationaryUnwrapAndWrapCalls(wrappedTokensInPath, tokenInfoMap, balanceMap);
+            // Combine all unwrap calls
+            unwrapCalls = [...demurragedUnwrapCalls, ...inflationaryUnwrapCalls];
+            wrapCalls = inflationaryWrapCalls;
+            // Replace wrapped token addresses with avatar addresses in the path
+            workingPath = replaceWrappedTokensWithAvatars(workingPath, tokenInfoMap);
+        }
+        // Create flow matrix from the (possibly rewritten) path
+        const flowMatrix = createFlowMatrixUtil(fromAddr, toAddr, workingPath.maxFlow, workingPath.transfers);
+        // Prepare streams with hex-encoded data and optional txData
+        const streamsWithHexData = prepareFlowMatrixStreams(flowMatrix, options?.txData);
+        // Create the operateFlowMatrix transaction
+        const operateFlowMatrixTx = this.hubV2.operateFlowMatrix(flowMatrix.flowVertices, flowMatrix.flowEdges, streamsWithHexData, flowMatrix.packedCoordinates);
+        // Check if self-approval is needed
+        let isApproved = false;
+        try {
+            isApproved = await this.hubV2.isApprovedForAll(fromAddr, fromAddr);
+        }
+        catch (error) {
+            console.warn('Failed to check approval status, including approval transaction:', error);
+        }
+        // Assemble all transactions in strict order:
+        // 1. Self-approval (only if not already approved)
+        // 2. All unwraps
+        // 3. operateFlowMatrix
+        // 4. All wraps (for leftover inflationary tokens)
+        const allTransactions = [
+            ...(isApproved ? [] : [this.hubV2.setApprovalForAll(fromAddr, true)]),
+            ...unwrapCalls,
+            operateFlowMatrixTx,
+            ...wrapCalls,
+        ];
+        return allTransactions;
     }
     /**
      * Construct an advanced transfer transaction
@@ -24,7 +126,7 @@ export class TransferBuilder {
      * @param options Advanced transfer options
      * @returns Array of transactions to execute in order
      */
-    async constructAdvancedTransfer(from, to, amount, options) {
+    async constructAdvancedTransfer(from, to, amount, options, aggregate = false) {
         // Normalize addresses
         const fromAddr = from.toLowerCase();
         const toAddr = to.toLowerCase();
@@ -40,16 +142,16 @@ export class TransferBuilder {
             const toTokenAddr = options.toTokens[0];
             // Use lift contract to check if fromToken is a wrapper and determine its type
             const [demurragedWrapper, inflationaryWrapper] = await Promise.all([
-                this.core.liftERC20.erc20Circles(CirclesType.Demurrage, toTokenAddr),
-                this.core.liftERC20.erc20Circles(CirclesType.Inflation, toTokenAddr)
+                this.liftERC20.erc20Circles(CirclesType.Demurrage, toTokenAddr),
+                this.liftERC20.erc20Circles(CirclesType.Inflation, toTokenAddr)
             ]);
             // Check if fromToken is a demurraged wrapper for the toToken avatar
             if (fromTokenAddr.toLowerCase() === demurragedWrapper.toLowerCase() &&
                 demurragedWrapper !== ZERO_ADDRESS) {
                 // Use demurraged wrapper contract to unwrap
-                const wrapper = new DemurrageCirclesContract({
+                const wrapper = new DemurrageCirclesContractMinimal({
                     address: fromTokenAddr,
-                    rpcUrl: this.core.config.circlesRpcUrl
+                    rpcUrl: this.config.circlesRpcUrl
                 });
                 const unwrapTx = wrapper.unwrap(amountBigInt);
                 return [{
@@ -62,9 +164,9 @@ export class TransferBuilder {
             if (fromTokenAddr.toLowerCase() === inflationaryWrapper.toLowerCase() &&
                 inflationaryWrapper !== ZERO_ADDRESS) {
                 // Use inflationary wrapper contract to unwrap
-                const wrapper = new InflationaryCirclesContract({
+                const wrapper = new InflationaryCirclesContractMinimal({
                     address: fromTokenAddr,
-                    rpcUrl: this.core.config.circlesRpcUrl
+                    rpcUrl: this.config.circlesRpcUrl
                 });
                 // Convert demurraged amount to static atto circles for inflationary unwrap
                 const unwrapAmount = CirclesConverter.attoCirclesToAttoStaticCircles(amountBigInt);
@@ -80,12 +182,14 @@ export class TransferBuilder {
         const truncatedAmount = this._truncateToSixDecimals(amountBigInt);
         // Get default token exclude list if sending to a group mint handler
         const completeExcludeFromTokens = await this._getDefaultTokenExcludeList(toAddr, options?.excludeFromTokens);
-        // Update options with complete exclude list
+        // Update options with complete exclude list, but exclude the 'aggregate' flag
+        // as it should only be used at the constructAdvancedTransfer level
+        const { ...pathfindingOptionsBase } = options || {};
         const pathfindingOptions = {
-            ...options,
+            ...pathfindingOptionsBase,
             ...(completeExcludeFromTokens ? { excludeFromTokens: completeExcludeFromTokens } : {}),
         };
-        let path = await this.rpc.pathfinder.findPath({
+        let path = await this.pathfinder.findPath({
             from: fromAddr,
             to: toAddr,
             targetFlow: truncatedAmount,
@@ -99,88 +203,281 @@ export class TransferBuilder {
         if (path.maxFlow < truncatedAmount) {
             throw TransferError.insufficientBalance(truncatedAmount, path.maxFlow, fromAddr, toAddr);
         }
-        // Get token info for all tokens in the path using pathfinder utility
-        // @dev returning a Map<string, TokenInfo>
-        const tokenInfoMap = await getTokenInfoMapFromPath(fromAddr, this.core.config.circlesRpcUrl, path);
-        // Get wrapped tokens found in the path with their amounts and types
-        // @dev returning a Record<string (wrapperAddress), [bigint (amount used in path), string (type)]>
+        // Use the buildFlowMatrixTx helper to construct transactions from the path
+        return this.buildFlowMatrixTx(fromAddr, toAddr, path, options, aggregate);
+    }
+    /**
+     * 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
+     *
+     * @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
+     * );
+     * ```
+     */
+    // @todo review the impleementation
+    async constructReplenish(from, tokenId, amount, receiver) {
+        const fromAddr = from.toLowerCase();
+        const tokenIdAddr = tokenId.toLowerCase();
+        const receiverAddr = (receiver || from).toLowerCase();
+        const amountBigInt = BigInt(amount);
+        // Step 1: Check current balances (unwrapped + wrapped)
+        const balances = await this.balance.getTokenBalances(fromAddr);
+        // Filter balances for the target token
+        const targetTokenBalances = balances.filter(b => b.tokenOwner.toLowerCase() === tokenIdAddr);
+        let unwrappedBalance = 0n;
+        let wrappedDemurrageBalance = 0n;
+        let wrappedInflationaryBalance = 0n;
+        let wrappedDemurrageAddress = null;
+        let wrappedInflationaryAddress = null;
+        for (const balance of targetTokenBalances) {
+            if (balance.isWrapped) {
+                const isDemurrage = balance.tokenType.includes('Demurrage');
+                if (isDemurrage) {
+                    wrappedDemurrageBalance = BigInt(balance.attoCircles);
+                    wrappedDemurrageAddress = balance.tokenAddress;
+                }
+                else {
+                    // For inflationary, use staticAttoCircles to get actual balance
+                    wrappedInflationaryBalance = BigInt(balance.staticAttoCircles);
+                    wrappedInflationaryAddress = balance.tokenAddress;
+                }
+            }
+            else {
+                unwrappedBalance = BigInt(balance.attoCircles);
+            }
+        }
+        const totalAvailable = unwrappedBalance + wrappedDemurrageBalance +
+            CirclesConverter.attoStaticCirclesToAttoCircles(wrappedInflationaryBalance);
+        const transactions = [];
+        // Step 2: If we already have enough in unwrapped form, we're done
+        if (unwrappedBalance >= amountBigInt) {
+            console.log(`✓ Already have ${Number(unwrappedBalance) / 1e18} CRC unwrapped (target: ${Number(amountBigInt) / 1e18} CRC). No replenish needed.`);
+            // If receiver is different from sender, create transfer transaction
+            if (receiverAddr !== fromAddr) {
+                const tokenIdBigInt = await this.hubV2.toTokenId(tokenIdAddr);
+                const transferTx = this.hubV2.safeTransferFrom(fromAddr, receiverAddr, tokenIdBigInt, amountBigInt);
+                transactions.push({
+                    to: transferTx.to,
+                    data: transferTx.data,
+                    value: transferTx.value ?? 0n
+                });
+            }
+            return transactions;
+        }
+        // Step 3: Calculate deficit (how much more we need to reach the target)
+        const deficit = amountBigInt - unwrappedBalance;
+        console.log(`Current unwrapped: ${Number(unwrappedBalance) / 1e18} CRC`);
+        console.log(`Target amount: ${Number(amountBigInt) / 1e18} CRC`);
+        console.log(`Need to acquire: ${Number(deficit) / 1e18} CRC`);
+        // Step 4: Try to unwrap if we have enough wrapped tokens
+        if (totalAvailable >= amountBigInt) {
+            let remainingToUnwrap = deficit;
+            // Unwrap demurrage first (exact amount)
+            if (wrappedDemurrageBalance > 0n && wrappedDemurrageAddress && remainingToUnwrap > 0n) {
+                const toUnwrap = remainingToUnwrap > wrappedDemurrageBalance
+                    ? wrappedDemurrageBalance
+                    : remainingToUnwrap;
+                const wrapper = new DemurrageCirclesContractMinimal({
+                    address: wrappedDemurrageAddress,
+                    rpcUrl: this.config.circlesRpcUrl
+                });
+                const unwrapTx = wrapper.unwrap(toUnwrap);
+                transactions.push({
+                    to: unwrapTx.to,
+                    data: unwrapTx.data,
+                    value: unwrapTx.value ?? 0n,
+                });
+                remainingToUnwrap -= toUnwrap;
+            }
+            // Unwrap inflationary if still needed
+            if (wrappedInflationaryBalance > 0n && wrappedInflationaryAddress && remainingToUnwrap > 0n) {
+                // For inflationary, we need to unwrap in static (inflationary) units
+                const staticToUnwrap = CirclesConverter.attoCirclesToAttoStaticCircles(remainingToUnwrap);
+                const actualUnwrap = staticToUnwrap > wrappedInflationaryBalance
+                    ? wrappedInflationaryBalance
+                    : staticToUnwrap;
+                const wrapper = new InflationaryCirclesContractMinimal({
+                    address: wrappedInflationaryAddress,
+                    rpcUrl: this.config.circlesRpcUrl
+                });
+                const unwrapTx = wrapper.unwrap(actualUnwrap);
+                transactions.push({
+                    to: unwrapTx.to,
+                    data: unwrapTx.data,
+                    value: unwrapTx.value ?? 0n,
+                });
+            }
+            // If receiver is different, add transfer
+            if (receiverAddr !== fromAddr) {
+                const tokenIdBigInt = await this.hubV2.toTokenId(tokenIdAddr);
+                const transferTx = this.hubV2.safeTransferFrom(fromAddr, receiverAddr, tokenIdBigInt, amountBigInt);
+                transactions.push({
+                    to: transferTx.to,
+                    data: transferTx.data,
+                    value: transferTx.value ?? 0n
+                });
+            }
+            return transactions;
+        }
+        // Step 5: Not enough tokens even with unwrapping, try pathfinding
+        // Check if we already trust the token owner
+        const alreadyTrusted = await this.hubV2.isTrusted(fromAddr, tokenIdAddr);
+        const needsTemporaryTrust = !alreadyTrusted;
+        // Calculate current time + 1 year for trust expiry
+        const trustExpiry = BigInt(Math.floor(Date.now() / 1000) + 365 * 24 * 60 * 60);
+        // Try pathfinding with trust simulation (only for the deficit)
+        // Round UP the deficit to the next 6-decimal boundary to ensure we get at least the target amount
+        // This compensates for the pathfinder's 6-decimal precision
+        const truncatedDeficit = CirclesConverter.truncateToInt64(deficit);
+        const hasRemainder = deficit % CirclesConverter.FACTOR_1E12 !== 0n;
+        const roundedUpDeficit = CirclesConverter.blowUpToBigInt(hasRemainder ? truncatedDeficit + 1n : truncatedDeficit);
+        let path;
+        try {
+            path = await this.pathfinder.findPath({
+                from: fromAddr,
+                to: receiverAddr,
+                targetFlow: roundedUpDeficit,
+                toTokens: [tokenIdAddr],
+                useWrappedBalances: true,
+                simulatedTrusts: needsTemporaryTrust ? [{
+                        truster: fromAddr,
+                        trustee: tokenIdAddr
+                    }] : undefined
+            });
+        }
+        catch (error) {
+            // Pathfinding failed
+            const availableCrc = Number(totalAvailable) / 1e18;
+            const targetCrc = Number(amountBigInt) / 1e18;
+            const deficitCrc = Number(deficit) / 1e18;
+            throw new TransferError(`Insufficient tokens to replenish. Target: ${targetCrc.toFixed(6)} CRC, ` +
+                `Current unwrapped: ${Number(unwrappedBalance) / 1e18} CRC, ` +
+                `Need: ${deficitCrc.toFixed(6)} CRC, ` +
+                `Available (including all paths): ${availableCrc.toFixed(6)} CRC. ` +
+                `Cannot acquire the remaining ${(Number(deficit - (totalAvailable - unwrappedBalance)) / 1e18).toFixed(6)} CRC.`, {
+                code: 'REPLENISH_INSUFFICIENT_TOKENS',
+                source: 'VALIDATION',
+                context: {
+                    from: fromAddr,
+                    tokenId: tokenIdAddr,
+                    target: amountBigInt.toString(),
+                    unwrapped: unwrappedBalance.toString(),
+                    deficit: deficit.toString(),
+                    available: totalAvailable.toString(),
+                    targetCrc,
+                    unwrappedCrc: Number(unwrappedBalance) / 1e18,
+                    deficitCrc,
+                    availableCrc
+                },
+            });
+        }
+        // Check if pathfinder found enough
+        if (!path.transfers || path.transfers.length === 0) {
+            throw TransferError.noPathFound(fromAddr, receiverAddr, `No path to acquire token ${tokenIdAddr}`);
+        }
+        // Check if we got enough flow
+        // We requested roundedUpDeficit, so we should get at least that much
+        if (path.maxFlow < roundedUpDeficit) {
+            const pathFlowCrc = Number(path.maxFlow) / 1e18;
+            const deficitCrc = Number(roundedUpDeficit) / 1e18;
+            throw new TransferError(`Pathfinder can only provide ${pathFlowCrc.toFixed(6)} CRC of the ${deficitCrc.toFixed(6)} CRC deficit needed for token ${tokenIdAddr}.`, {
+                code: 'REPLENISH_INSUFFICIENT_PATH_FLOW',
+                source: 'PATHFINDING',
+                context: {
+                    from: fromAddr,
+                    tokenId: tokenIdAddr,
+                    deficit: roundedUpDeficit.toString(),
+                    pathFlow: path.maxFlow.toString(),
+                    deficitCrc,
+                    pathFlowCrc
+                },
+            });
+        }
+        // Step 6: Add temporary trust if needed
+        if (needsTemporaryTrust) {
+            const trustTx = this.hubV2.trust(tokenIdAddr, trustExpiry);
+            transactions.push({
+                to: trustTx.to,
+                data: trustTx.data,
+                value: trustTx.value ?? 0n
+            });
+        }
+        // Step 7: Handle wrapped tokens in path (similar to constructAdvancedTransfer)
+        const tokenInfoMap = await getTokenInfoMapFromPath(fromAddr, this.config.circlesRpcUrl, path);
         const wrappedTokensInPath = getWrappedTokensFromPath(path, tokenInfoMap);
-        // @todo maybe there is an easier way to check if there are wrapped tokens
         const hasWrappedTokens = Object.keys(wrappedTokensInPath).length > 0;
-        // Validate that wrapped tokens are enabled if they're needed
-        if (hasWrappedTokens && !options?.useWrappedBalances) {
-            throw TransferError.wrappedTokensRequired();
-        }
         let unwrapCalls = [];
         let wrapCalls = [];
         if (hasWrappedTokens) {
-            // Fetch token balances once for both unwrap and wrap operations
             const balanceMap = await this._getTokenBalanceMap(fromAddr);
-            // Create unwrap calls for demurraged tokens (unwrap exact amount used in path)
             const demurragedUnwrapCalls = this._createDemurragedUnwrapCalls(wrappedTokensInPath);
-            // Create unwrap and wrap calls for inflationary tokens
-            // Unwrap entire balance, then wrap back leftovers after transfer
             const { unwrapCalls: inflationaryUnwrapCalls, wrapCalls: inflationaryWrapCalls } = this._createInflationaryUnwrapAndWrapCalls(wrappedTokensInPath, tokenInfoMap, balanceMap);
-            // Combine all unwrap calls
             unwrapCalls = [...demurragedUnwrapCalls, ...inflationaryUnwrapCalls];
             wrapCalls = inflationaryWrapCalls;
-            // Replace wrapped token addresses with avatar addresses in the path
             path = replaceWrappedTokensWithAvatars(path, tokenInfoMap);
         }
-        // Create flow matrix from the (possibly rewritten) path
-        const flowMatrix = createFlowMatrixUtil(fromAddr, toAddr, path.maxFlow, path.transfers);
-        // If txData is provided, attach it to the streams
-        if (options?.txData && flowMatrix.streams.length > 0) {
-            flowMatrix.streams[0].data = options.txData;
-        }
-        // Convert Uint8Array data to hex strings for ABI encoding
-        const streamsWithHexData = flowMatrix.streams.map((stream) => ({
-            sourceCoordinate: stream.sourceCoordinate,
-            flowEdgeIds: stream.flowEdgeIds,
-            data: stream.data instanceof Uint8Array ? bytesToHex(stream.data) : stream.data,
-        }));
-        // Create the operateFlowMatrix transaction
-        const operateFlowMatrixTx = this.core.hubV2.operateFlowMatrix(flowMatrix.flowVertices, flowMatrix.flowEdges, streamsWithHexData, flowMatrix.packedCoordinates);
-        // Check if self-approval is needed
-        // If the check fails (e.g., network error), we'll include the approval anyway to be safe
+        // Step 8: Create flow matrix
+        const flowMatrix = createFlowMatrixUtil(fromAddr, receiverAddr, path.maxFlow, path.transfers);
+        // Prepare streams with hex-encoded data
+        const streamsWithHexData = prepareFlowMatrixStreams(flowMatrix);
+        const operateFlowMatrixTxRaw = this.hubV2.operateFlowMatrix(flowMatrix.flowVertices, flowMatrix.flowEdges, streamsWithHexData, flowMatrix.packedCoordinates);
+        const operateFlowMatrixTx = {
+            to: operateFlowMatrixTxRaw.to,
+            data: operateFlowMatrixTxRaw.data,
+            value: operateFlowMatrixTxRaw.value ?? 0n
+        };
+        // Check self-approval
         let isApproved = false;
         try {
-            isApproved = await this.core.hubV2.isApprovedForAll(fromAddr, fromAddr);
+            isApproved = await this.hubV2.isApprovedForAll(fromAddr, fromAddr);
         }
         catch (error) {
-            // If checking approval fails, assume not approved and include the approval transaction
             console.warn('Failed to check approval status, including approval transaction:', error);
         }
-        // Assemble all transactions in strict order:
-        // 1. Self-approval (only if not already approved)
-        // 2. All unwraps
-        // 3. operateFlowMatrix
-        // 4. All wraps (for leftover inflationary tokens)
-        const allTransactions = [
-            ...(isApproved ? [] : [this.core.hubV2.setApprovalForAll(fromAddr, true)]),
-            ...unwrapCalls,
-            operateFlowMatrixTx,
-            ...wrapCalls,
-        ];
-        return allTransactions;
-    }
-    /**
-     * 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
-     *
-     * @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
-     */
-    async constructReplenish(avatarAddress, options) {
-        // @todo Implement replenish functionality
-        // This should:
-        // 1. Find maximum flow from avatar to itself targeting personal tokens
-        // 2. Handle wrapped token unwrapping similar to constructAdvancedTransfer
-        // 3. Create flow matrix for self-transfer
-        // 4. Handle wrap calls for leftover inflationary tokens
-        throw new Error('constructReplenish is not yet implemented. Please use constructAdvancedTransfer with same from/to address as a workaround.');
+        // Step 9: Add untrust if we added temporary trust
+        if (needsTemporaryTrust) {
+            const untrustTx = this.hubV2.trust(tokenIdAddr, 0n); // 0 expiry = untrust
+            wrapCalls.push({
+                to: untrustTx.to,
+                data: untrustTx.data,
+                value: untrustTx.value ?? 0n
+            });
+        }
+        // Assemble all transactions in order
+        const approvalTxs = isApproved ? [] : [{
+                to: this.hubV2.setApprovalForAll(fromAddr, true).to,
+                data: this.hubV2.setApprovalForAll(fromAddr, true).data,
+                value: 0n
+            }];
+        transactions.push(...approvalTxs, ...unwrapCalls, operateFlowMatrixTx, ...wrapCalls);
+        return transactions;
     }
     // ============================================================================
     // Private Helper Methods
@@ -192,7 +489,7 @@ export class TransferBuilder {
      * @returns Map of token address to balance (in static units)
      */
     async _getTokenBalanceMap(from) {
-        const allBalances = await this.rpc.balance.getTokenBalances(from);
+        const allBalances = await this.balance.getTokenBalances(from);
         const balanceMap = new Map();
         // @todo remove any
         allBalances.forEach((balance) => {
@@ -215,21 +512,15 @@ export class TransferBuilder {
                 continue;
             }
             // Create unwrap call for the exact amount used in path
-            const data = encodeFunctionData({
-                abi: [{
-                        type: 'function',
-                        name: 'unwrap',
-                        inputs: [{ name: '_amount', type: 'uint256' }],
-                        outputs: [],
-                        stateMutability: 'nonpayable',
-                    }],
-                functionName: 'unwrap',
-                args: [amountUsedInPath],
+            const wrapper = new DemurrageCirclesContractMinimal({
+                address: wrapperAddr,
+                rpcUrl: this.config.circlesRpcUrl
             });
+            const unwrapTx = wrapper.unwrap(amountUsedInPath);
             unwrapCalls.push({
-                to: wrapperAddr,
-                data,
-                value: 0n,
+                to: unwrapTx.to,
+                data: unwrapTx.data,
+                value: unwrapTx.value ?? 0n,
             });
         }
         return unwrapCalls;
@@ -257,21 +548,15 @@ export class TransferBuilder {
                 continue;
             }
             // Create unwrap call for the entire balance (in static units)
-            const unwrapData = encodeFunctionData({
-                abi: [{
-                        type: 'function',
-                        name: 'unwrap',
-                        inputs: [{ name: '_amount', type: 'uint256' }],
-                        outputs: [],
-                        stateMutability: 'nonpayable',
-                    }],
-                functionName: 'unwrap',
-                args: [currentBalance],
+            const wrapper = new InflationaryCirclesContractMinimal({
+                address: wrapperAddr,
+                rpcUrl: this.config.circlesRpcUrl
             });
+            const unwrapTx = wrapper.unwrap(currentBalance);
             unwrapCalls.push({
-                to: wrapperAddr,
-                data: unwrapData,
-                value: 0n,
+                to: unwrapTx.to,
+                data: unwrapTx.data,
+                value: unwrapTx.value ?? 0n,
             });
             // Calculate leftover amount: balance before unwrap (converted to demurraged) - amount used in path
             const tokenOwner = tokenInfo?.tokenOwner;
@@ -279,7 +564,7 @@ export class TransferBuilder {
             // Only create wrap call if there's leftover amount
             if (leftoverAmount > 0n) {
                 // Create wrap call using hubV2 contract
-                const wrapTx = this.core.hubV2.wrap(tokenOwner, leftoverAmount, CirclesType.Inflation // 1 = Inflationary
+                const wrapTx = this.hubV2.wrap(tokenOwner, leftoverAmount, CirclesType.Inflation // 1 = Inflationary
                 );
                 wrapCalls.push({
                     to: wrapTx.to,
@@ -308,7 +593,7 @@ export class TransferBuilder {
      */
     async _getDefaultTokenExcludeList(to, excludeFromTokens) {
         // Check if recipient is a group mint handler
-        const groups = await this.rpc.group.findGroups(1, {
+        const groups = await this.group.findGroups(1, {
             mintHandlerEquals: to,
         });
         const completeExcludeFromTokenList = new Set();

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import { CirclesError } from '@aboutcircles/sdk-utils';
+import { CirclesError } from '@aboutcircles/sdk-utils/errors';
 import type { Address } from '@aboutcircles/sdk-types';
 /**
  * Transfers package error source

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,aAAa,GAAG,aAAa,GAAG,YAAY,CAAC;AAE9F;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY,CAAC,oBAAoB,CAAC;gBAEjE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,oBAAoB,CAAC;QAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC/B;IAKH;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa;IAW9E;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,aAAa;IAqB3G;;OAEG;IACH,MAAM,CAAC,qBAAqB,IAAI,aAAa;IAU7C;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,aAAa;IAc/D;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa;IAc/E;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,aAAa;CAU5D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,aAAa,GAAG,aAAa,GAAG,YAAY,CAAC;AAE9F;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY,CAAC,oBAAoB,CAAC;gBAEjE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,oBAAoB,CAAC;QAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC/B;IAKH;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa;IAW9E;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,aAAa;IAqB3G;;OAEG;IACH,MAAM,CAAC,qBAAqB,IAAI,aAAa;IAU7C;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,aAAa;IAc/D;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa;IAc/E;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,aAAa;CAU5D"}

package/dist/errors.js

@@ -1,4 +1,4 @@
-import { CirclesError } from '@aboutcircles/sdk-utils';
+import { CirclesError } from '@aboutcircles/sdk-utils/errors';
 /**
  * Base error for transfers package
  */