@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2-humanode.1

package/dist/utils/gasEstimation.js

@@ -0,0 +1,206 @@
+import { BigNumber } from 'ethers';
+import { addBufferToGasLimit, isZeroishAddress, ProtocolType, } from '@humanode-hyperlane/utils';
+/**
+ * Fallback gas limit for transferRemote when eth_estimateGas fails.
+ * Conservative estimate for cross-chain token transfers.
+ */
+export const FALLBACK_TRANSFER_REMOTE_GAS_LIMIT = 300000n;
+/**
+ * Cost multiplier for minimum viable transfer.
+ * A transfer must be worth at least this multiple of its cost to be worthwhile.
+ */
+export const MIN_VIABLE_COST_MULTIPLIER = 2n;
+/**
+ * Estimate gas for a transferRemote transaction using eth_estimateGas.
+ * Falls back to conservative estimate if estimation fails.
+ *
+ * @param originChain - Chain where transferRemote will be called
+ * @param destinationChain - Chain where the Hyperlane message goes
+ * @param amount - Amount to transfer
+ * @param multiProvider - MultiProvider for chain access
+ * @param warpCoreMultiProvider - MultiProvider from WarpCore for adapter access
+ * @param getTokenForChain - Function to get token for a chain
+ * @param inventorySigner - Address of the inventory signer
+ * @param logger - Logger instance
+ * @returns Estimated gas limit for the transaction
+ */
+export async function estimateTransferRemoteGas(originChain, destinationChain, amount, multiProvider, warpCoreMultiProvider, getTokenForChain, inventorySigner, logger) {
+    const originToken = getTokenForChain(originChain);
+    if (!originToken) {
+        logger.warn({ originChain }, 'No token found for origin chain, using fallback gas limit');
+        return FALLBACK_TRANSFER_REMOTE_GAS_LIMIT;
+    }
+    try {
+        const destinationDomain = multiProvider.getDomainId(destinationChain);
+        const adapter = originToken.getHypAdapter(warpCoreMultiProvider);
+        // Quote the IGP gas first (needed for the full transaction)
+        const gasQuote = await adapter.quoteTransferRemoteGas({
+            destination: destinationDomain,
+            sender: inventorySigner,
+            recipient: inventorySigner,
+            amount,
+        });
+        // Populate with minimal amount for gas estimation
+        // Gas cost is independent of transfer size (just a require check in _transferFromSender),
+        // and using minimal amount prevents eth_estimateGas from failing when account balance < requested amount
+        // Note: getHypAdapter returns IHypTokenAdapter<unknown> for protocol-agnostic support.
+        // For EVM chains (which inventory rebalancing uses), the actual type is AnnotatedEV5Transaction.
+        const populatedTx = (await adapter.populateTransferRemoteTx({
+            destination: destinationDomain,
+            recipient: inventorySigner,
+            weiAmountOrId: 1n,
+            interchainGas: gasQuote,
+        }));
+        // Estimate gas using the provider
+        const provider = multiProvider.getProvider(originChain);
+        const gasEstimate = await provider.estimateGas({
+            to: populatedTx.to,
+            data: populatedTx.data,
+            value: populatedTx.value,
+            from: inventorySigner,
+        });
+        const estimatedGas = BigInt(gasEstimate.toString());
+        logger.debug({
+            originChain,
+            destinationChain,
+            amount: amount.toString(),
+            estimatedGas: estimatedGas.toString(),
+        }, 'Estimated transferRemote gas via eth_estimateGas');
+        return estimatedGas;
+    }
+    catch (error) {
+        logger.warn({
+            originChain,
+            destinationChain,
+            error: error.message,
+            fallbackGas: FALLBACK_TRANSFER_REMOTE_GAS_LIMIT.toString(),
+        }, 'Gas estimation failed, using fallback gas limit');
+        return FALLBACK_TRANSFER_REMOTE_GAS_LIMIT;
+    }
+}
+/**
+ * Calculate all transfer costs for a transferRemote operation.
+ * Consolidates IGP costs, gas costs, and derived values (max transferable, min viable).
+ *
+ * @param originChain - Chain to transfer from (where transferRemote is called)
+ * @param destinationChain - Chain to transfer to (Hyperlane message destination)
+ * @param availableInventory - Available token balance on origin chain
+ * @param requestedAmount - Requested transfer amount
+ * @param multiProvider - MultiProvider for chain access
+ * @param warpCoreMultiProvider - MultiProvider from WarpCore for adapter access
+ * @param getTokenForChain - Function to get token for a chain
+ * @param inventorySigner - Address of the inventory signer
+ * @param isNativeTokenStandard - Function to check if token standard is native
+ * @param logger - Logger instance
+ * @returns Cost estimate with all components and derived values
+ */
+export async function calculateTransferCosts(originChain, destinationChain, availableInventory, requestedAmount, multiProvider, warpCoreMultiProvider, getTokenForChain, inventorySigner, isNativeTokenStandard, logger) {
+    const originToken = getTokenForChain(originChain);
+    if (!originToken) {
+        throw new Error(`No token found for origin chain: ${originChain}`);
+    }
+    const destinationDomain = multiProvider.getDomainId(destinationChain);
+    const adapter = originToken.getHypAdapter(warpCoreMultiProvider);
+    // Always quote IGP for the gas quote (needed for populateTransferRemoteTx)
+    const gasQuote = await adapter.quoteTransferRemoteGas({
+        destination: destinationDomain,
+        sender: inventorySigner,
+        recipient: inventorySigner,
+        amount: requestedAmount,
+    });
+    // For non-native tokens, no cost reservation needed from token balance
+    if (!isNativeTokenStandard(originToken.standard)) {
+        return {
+            igpCost: 0n,
+            gasCost: 0n,
+            tokenFeeCost: 0n,
+            totalCost: 0n,
+            maxTransferable: availableInventory < requestedAmount
+                ? availableInventory
+                : requestedAmount,
+            minViableTransfer: 0n,
+            gasQuote,
+        };
+    }
+    // For native tokens, calculate costs
+    const igpCost = gasQuote.igpQuote.amount;
+    // Extract token fee cost (native denom only)
+    const tokenFeeCost = !gasQuote.tokenFeeQuote?.addressOrDenom ||
+        isZeroishAddress(gasQuote.tokenFeeQuote.addressOrDenom)
+        ? (gasQuote.tokenFeeQuote?.amount ?? 0n)
+        : 0n;
+    // Skip gas estimation for non-EVM chains (e.g., Solana).
+    // Non-EVM chains have negligible base fees (~5000 lamports ~$0.0001 on Solana)
+    // compared to EVM gas costs ($0.50-$50/tx). The IGP (Interchain Gas Paymaster)
+    // reservation dominates the cost, not chain-specific gas. Thus gasCost=0 is a
+    // safe approximation for non-EVM origin chains.
+    const originProtocol = multiProvider.getProtocol(originChain);
+    if (originProtocol !== ProtocolType.Ethereum) {
+        const totalCost = igpCost + tokenFeeCost;
+        let maxTransferable;
+        if (availableInventory <= totalCost) {
+            maxTransferable = 0n;
+        }
+        else {
+            const maxAfterReservation = availableInventory - totalCost;
+            maxTransferable =
+                maxAfterReservation < requestedAmount
+                    ? maxAfterReservation
+                    : requestedAmount;
+        }
+        const minViableTransfer = totalCost * MIN_VIABLE_COST_MULTIPLIER;
+        return {
+            igpCost,
+            gasCost: 0n,
+            tokenFeeCost,
+            totalCost,
+            maxTransferable,
+            minViableTransfer,
+            gasQuote,
+        };
+    }
+    // Estimate gas with buffer
+    const estimatedGasLimit = await estimateTransferRemoteGas(originChain, destinationChain, requestedAmount, multiProvider, warpCoreMultiProvider, getTokenForChain, inventorySigner, logger);
+    const bufferedGasLimit = addBufferToGasLimit(BigNumber.from(estimatedGasLimit.toString()));
+    // Get gas price and calculate cost
+    const provider = multiProvider.getProvider(originChain);
+    const feeData = await provider.getFeeData();
+    const gasPrice = feeData.maxFeePerGas ?? feeData.gasPrice ?? 0n;
+    const gasCost = bufferedGasLimit.toBigInt() * BigInt(gasPrice.toString());
+    const totalCost = igpCost + gasCost + tokenFeeCost;
+    // Calculate derived values
+    let maxTransferable;
+    if (availableInventory <= totalCost) {
+        maxTransferable = 0n;
+    }
+    else {
+        const maxAfterReservation = availableInventory - totalCost;
+        maxTransferable =
+            maxAfterReservation < requestedAmount
+                ? maxAfterReservation
+                : requestedAmount;
+    }
+    const minViableTransfer = totalCost * MIN_VIABLE_COST_MULTIPLIER;
+    logger.debug({
+        originChain,
+        destinationChain,
+        availableInventory: availableInventory.toString(),
+        requestedAmount: requestedAmount.toString(),
+        igpCost: igpCost.toString(),
+        gasCost: gasCost.toString(),
+        tokenFeeCost: tokenFeeCost.toString(),
+        totalCost: totalCost.toString(),
+        maxTransferable: maxTransferable.toString(),
+        minViableTransfer: minViableTransfer.toString(),
+    }, 'Calculated transfer costs for native token');
+    return {
+        igpCost,
+        gasCost,
+        tokenFeeCost,
+        totalCost,
+        maxTransferable,
+        minViableTransfer,
+        gasQuote,
+    };
+}
+//# sourceMappingURL=gasEstimation.js.map

package/dist/utils/gasEstimation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gasEstimation.js","sourceRoot":"","sources":["../../src/utils/gasEstimation.ts"],"names":[],"mappings":"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"}

package/dist/utils/solanaKeyParser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parses a Solana private key from various formats.
+ * Supports JSON array format, comma-separated byte values, and base58 values.
+ *
+ * @param rawKey - Raw private key string in JSON array, comma-separated, or base58 format
+ * @returns Uint8Array representation of the private key
+ * @throws Error if the key format is invalid
+ */
+export declare function parseSolanaPrivateKey(rawKey: string): Uint8Array;
+//# sourceMappingURL=solanaKeyParser.d.ts.map

package/dist/utils/solanaKeyParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solanaKeyParser.d.ts","sourceRoot":"","sources":["../../src/utils/solanaKeyParser.ts"],"names":[],"mappings":"AA0BA;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAkFhE"}

package/dist/utils/solanaKeyParser.js

@@ -0,0 +1,87 @@
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+const SOLANA_KEY_ERROR_MESSAGE = 'Invalid Solana private key format. Expected JSON byte array, comma-separated bytes, or base58 key (32 or 64 bytes). Set HYP_INVENTORY_KEY_SEALEVEL env var.';
+function throwInvalidSolanaKey(reason) {
+    throw new Error(`${SOLANA_KEY_ERROR_MESSAGE} ${reason}`);
+}
+function validateKeyLength(bytes) {
+    if (bytes.length !== 32 && bytes.length !== 64) {
+        throwInvalidSolanaKey(`Received ${bytes.length} bytes; expected exactly 32 or 64.`);
+    }
+}
+function toSecretKey(bytes) {
+    validateKeyLength(bytes);
+    if (bytes.length === 32) {
+        return Keypair.fromSeed(Uint8Array.from(bytes)).secretKey;
+    }
+    return Uint8Array.from(bytes);
+}
+/**
+ * Parses a Solana private key from various formats.
+ * Supports JSON array format, comma-separated byte values, and base58 values.
+ *
+ * @param rawKey - Raw private key string in JSON array, comma-separated, or base58 format
+ * @returns Uint8Array representation of the private key
+ * @throws Error if the key format is invalid
+ */
+export function parseSolanaPrivateKey(rawKey) {
+    const trimmed = rawKey.trim();
+    if (trimmed === '') {
+        throwInvalidSolanaKey('Input is empty.');
+    }
+    try {
+        if (trimmed.startsWith('[')) {
+            const parsed = JSON.parse(trimmed);
+            if (!Array.isArray(parsed)) {
+                throwInvalidSolanaKey('JSON input must be an array of bytes.');
+            }
+            const bytes = parsed.map((value, index) => {
+                if (!Number.isInteger(value)) {
+                    throwInvalidSolanaKey(`JSON byte at index ${index} must be an integer.`);
+                }
+                if (value < 0 || value > 255) {
+                    throwInvalidSolanaKey(`JSON byte at index ${index} must be in range 0..255.`);
+                }
+                return value;
+            });
+            return toSecretKey(bytes);
+        }
+        if (trimmed.includes(',')) {
+            const bytes = trimmed.split(',').map((segment, index) => {
+                const segmentTrimmed = segment.trim();
+                if (segmentTrimmed === '') {
+                    throwInvalidSolanaKey(`Comma-separated byte at index ${index} is empty.`);
+                }
+                const value = Number(segmentTrimmed);
+                if (!Number.isFinite(value)) {
+                    throwInvalidSolanaKey(`Comma-separated byte at index ${index} is not numeric.`);
+                }
+                if (!Number.isInteger(value)) {
+                    throwInvalidSolanaKey(`Comma-separated byte at index ${index} must be an integer.`);
+                }
+                if (value < 0 || value > 255) {
+                    throwInvalidSolanaKey(`Comma-separated byte at index ${index} must be in range 0..255.`);
+                }
+                return value;
+            });
+            return toSecretKey(bytes);
+        }
+        try {
+            const decoded = bs58.decode(trimmed);
+            const bytes = Array.from(decoded);
+            return toSecretKey(bytes);
+        }
+        catch {
+            // bs58 decode failed, fall through to outer catch
+        }
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.includes(SOLANA_KEY_ERROR_MESSAGE)) {
+            throw error;
+        }
+        throwInvalidSolanaKey('Failed to parse key input.');
+    }
+    throwInvalidSolanaKey('Failed to match supported format (JSON array, comma-separated bytes, or base58 key).');
+}
+//# sourceMappingURL=solanaKeyParser.js.map

package/dist/utils/solanaKeyParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solanaKeyParser.js","sourceRoot":"","sources":["../../src/utils/solanaKeyParser.ts"],"names":[],"mappings":"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"}

package/dist/utils/solanaKeyParser.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=solanaKeyParser.test.d.ts.map

package/dist/utils/solanaKeyParser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solanaKeyParser.test.d.ts","sourceRoot":"","sources":["../../src/utils/solanaKeyParser.test.ts"],"names":[],"mappings":""}

package/dist/utils/solanaKeyParser.test.js

@@ -0,0 +1,71 @@
+import { expect } from 'chai';
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+import { parseSolanaPrivateKey } from './solanaKeyParser.js';
+describe('parseSolanaPrivateKey', () => {
+    it('parses valid 64-byte JSON array', () => {
+        const bytes = Array.from({ length: 64 }, (_, i) => i);
+        const parsed = parseSolanaPrivateKey(JSON.stringify(bytes));
+        expect(parsed).to.be.instanceOf(Uint8Array);
+        expect(Array.from(parsed)).to.deep.equal(bytes);
+        expect(parsed).to.have.length(64);
+    });
+    it('parses valid 64-byte comma-separated', () => {
+        const bytes = Array.from({ length: 64 }, (_, i) => i);
+        const parsed = parseSolanaPrivateKey(bytes.join(','));
+        expect(Array.from(parsed)).to.deep.equal(bytes);
+        expect(parsed).to.have.length(64);
+    });
+    it('parses valid 32-byte seed JSON array and expands to 64 bytes', () => {
+        const seed = Array.from({ length: 32 }, (_, i) => i);
+        const parsed = parseSolanaPrivateKey(JSON.stringify(seed));
+        const expected = Keypair.fromSeed(Uint8Array.from(seed)).secretKey;
+        expect(parsed).to.have.length(64);
+        expect(Array.from(parsed)).to.deep.equal(Array.from(expected));
+    });
+    it('parses valid 32-byte seed comma-separated and expands to 64 bytes', () => {
+        const seed = Array.from({ length: 32 }, (_, i) => i + 1);
+        const parsed = parseSolanaPrivateKey(seed.join(','));
+        const expected = Keypair.fromSeed(Uint8Array.from(seed)).secretKey;
+        expect(parsed).to.have.length(64);
+        expect(Array.from(parsed)).to.deep.equal(Array.from(expected));
+    });
+    it('throws on "1,2,abc,4" (non-numeric)', () => {
+        expect(() => parseSolanaPrivateKey('1,2,abc,4')).to.throw('Comma-separated byte at index 2 is not numeric.');
+    });
+    it('throws on empty string', () => {
+        expect(() => parseSolanaPrivateKey('   ')).to.throw('Input is empty.');
+    });
+    it('throws on "256,1,2" (out of range)', () => {
+        expect(() => parseSolanaPrivateKey('256,1,2')).to.throw('Comma-separated byte at index 0 must be in range 0..255.');
+    });
+    it('throws on "-1,1,2" (negative)', () => {
+        expect(() => parseSolanaPrivateKey('-1,1,2')).to.throw('Comma-separated byte at index 0 must be in range 0..255.');
+    });
+    it('throws on "1.5,2,3" (non-integer)', () => {
+        expect(() => parseSolanaPrivateKey('1.5,2,3')).to.throw('Comma-separated byte at index 0 must be an integer.');
+    });
+    it('throws on 10-byte array (wrong length)', () => {
+        const tenBytes = JSON.stringify(Array.from({ length: 10 }, (_, i) => i));
+        expect(() => parseSolanaPrivateKey(tenBytes)).to.throw('Received 10 bytes; expected exactly 32 or 64.');
+    });
+    it('error message contains HYP_INVENTORY_KEY_SEALEVEL', () => {
+        expect(() => parseSolanaPrivateKey('not-a-key')).to.throw('HYP_INVENTORY_KEY_SEALEVEL');
+    });
+    it('parses valid base58-encoded 64-byte key', () => {
+        const bytes = Array.from({ length: 64 }, (_, i) => i);
+        const base58Key = bs58.encode(Uint8Array.from(bytes));
+        const parsed = parseSolanaPrivateKey(base58Key);
+        expect(Array.from(parsed)).to.deep.equal(bytes);
+        expect(parsed).to.have.length(64);
+    });
+    it('parses valid base58-encoded 32-byte seed and expands to 64 bytes', () => {
+        const seed = Array.from({ length: 32 }, (_, i) => i + 1);
+        const base58Seed = bs58.encode(Uint8Array.from(seed));
+        const parsed = parseSolanaPrivateKey(base58Seed);
+        const expected = Keypair.fromSeed(Uint8Array.from(seed)).secretKey;
+        expect(parsed).to.have.length(64);
+        expect(Array.from(parsed)).to.deep.equal(Array.from(expected));
+    });
+});
+//# sourceMappingURL=solanaKeyParser.test.js.map

package/dist/utils/solanaKeyParser.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solanaKeyParser.test.js","sourceRoot":"","sources":["../../src/utils/solanaKeyParser.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/tokenUtils.d.ts

@@ -0,0 +1,38 @@
+import type { ExternalBridgeType } from '../config/types.js';
+import { type Token, TokenStandard } from '@humanode-hyperlane/sdk';
+/**
+ * Check if a token's balance is the same as native gas balance.
+ * For these tokens, we must reserve funds for IGP when calculating max transferable.
+ *
+ * @param standard - The token standard to check.
+ * @returns `true` if the token is a native token standard, `false` otherwise.
+ */
+export declare function isNativeTokenStandard(standard: TokenStandard): boolean;
+/**
+ * @dev This function exists because the rebalancer currently only supports a subset of collateralized token standards
+ *   (see `REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS` vs. all possible `TOKEN_COLLATERALIZED_STANDARDS`).
+ *
+ * @deprecated This function is conditionally deprecated. It is intended for removal once the rebalancer
+ *   achieves full support for all collateralized token standards.
+ *   After this condition is met and this function is removed, please use `token.isCollateralized()` as the alternative.
+ *
+ * @param token - The token to be checked for rebalancing eligibility.
+ * @returns `true` if the token is of a collateralized standard currently supported by the rebalancer, `false` otherwise.
+ */
+export declare function isCollateralizedTokenEligibleForRebalancing(token: Token): boolean;
+/**
+ * Resolves the correct token address for external bridges (e.g. LiFi).
+ *
+ * For warp route tokens, `addressOrDenom` is the warp router contract address,
+ * NOT the underlying token. External bridges need the actual token address:
+ * - Native tokens (EvmHypNative, SealevelHypNative): Use the bridge's native token representation
+ * - Collateral tokens (EvmHypCollateral, SealevelHypCollateral): Use `collateralAddressOrDenom` (the underlying token)
+ * - Synthetic tokens: `collateralAddressOrDenom` is undefined, `addressOrDenom` IS the token
+ *
+ * @param token - The warp route token to resolve
+ * @param externalBridgeType - The type of external bridge (e.g. 'lifi')
+ * @param getNativeTokenAddress - Function to get the bridge's native token representation
+ * @returns The correct token address for the external bridge
+ */
+export declare function getExternalBridgeTokenAddress(token: Token, externalBridgeType: ExternalBridgeType, getNativeTokenAddress: (type: ExternalBridgeType) => string): string;
+//# sourceMappingURL=tokenUtils.d.ts.map

package/dist/utils/tokenUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenUtils.d.ts","sourceRoot":"","sources":["../../src/utils/tokenUtils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAEL,KAAK,KAAK,EACV,aAAa,EACd,MAAM,yBAAyB,CAAC;AAkBjC;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAEtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2CAA2C,CACzD,KAAK,EAAE,KAAK,GACX,OAAO,CAKT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,KAAK,EACZ,kBAAkB,EAAE,kBAAkB,EACtC,qBAAqB,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,MAAM,GAC1D,MAAM,CAaR"}

package/dist/utils/tokenUtils.js

@@ -0,0 +1,65 @@
+import { ProtocolType, assert } from '@humanode-hyperlane/utils';
+import { PROTOCOL_TO_HYP_NATIVE_STANDARD, TokenStandard, } from '@humanode-hyperlane/sdk';
+const REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS = new Set([
+    TokenStandard.EvmHypCollateral,
+    TokenStandard.EvmHypNative,
+    TokenStandard.SealevelHypCollateral,
+    TokenStandard.SealevelHypNative,
+]);
+// SDK-backed native token standard check scoped to EVM and Sealevel only (2-protocol scope).
+// NOTE: We intentionally do NOT use the full PROTOCOL_TO_HYP_NATIVE_STANDARD map (all 7 protocols)
+// because the rebalancer only supports EVM and Sealevel native token bridging.
+// Expanding this would change gas reservation behavior for other protocols.
+const REBALANCER_NATIVE_STANDARDS = new Set([
+    PROTOCOL_TO_HYP_NATIVE_STANDARD[ProtocolType.Ethereum],
+    PROTOCOL_TO_HYP_NATIVE_STANDARD[ProtocolType.Sealevel],
+]);
+/**
+ * Check if a token's balance is the same as native gas balance.
+ * For these tokens, we must reserve funds for IGP when calculating max transferable.
+ *
+ * @param standard - The token standard to check.
+ * @returns `true` if the token is a native token standard, `false` otherwise.
+ */
+export function isNativeTokenStandard(standard) {
+    return REBALANCER_NATIVE_STANDARDS.has(standard);
+}
+/**
+ * @dev This function exists because the rebalancer currently only supports a subset of collateralized token standards
+ *   (see `REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS` vs. all possible `TOKEN_COLLATERALIZED_STANDARDS`).
+ *
+ * @deprecated This function is conditionally deprecated. It is intended for removal once the rebalancer
+ *   achieves full support for all collateralized token standards.
+ *   After this condition is met and this function is removed, please use `token.isCollateralized()` as the alternative.
+ *
+ * @param token - The token to be checked for rebalancing eligibility.
+ * @returns `true` if the token is of a collateralized standard currently supported by the rebalancer, `false` otherwise.
+ */
+export function isCollateralizedTokenEligibleForRebalancing(token) {
+    return (token.isCollateralized() &&
+        REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS.has(token.standard));
+}
+/**
+ * Resolves the correct token address for external bridges (e.g. LiFi).
+ *
+ * For warp route tokens, `addressOrDenom` is the warp router contract address,
+ * NOT the underlying token. External bridges need the actual token address:
+ * - Native tokens (EvmHypNative, SealevelHypNative): Use the bridge's native token representation
+ * - Collateral tokens (EvmHypCollateral, SealevelHypCollateral): Use `collateralAddressOrDenom` (the underlying token)
+ * - Synthetic tokens: `collateralAddressOrDenom` is undefined, `addressOrDenom` IS the token
+ *
+ * @param token - The warp route token to resolve
+ * @param externalBridgeType - The type of external bridge (e.g. 'lifi')
+ * @param getNativeTokenAddress - Function to get the bridge's native token representation
+ * @returns The correct token address for the external bridge
+ */
+export function getExternalBridgeTokenAddress(token, externalBridgeType, getNativeTokenAddress) {
+    if (isNativeTokenStandard(token.standard)) {
+        return getNativeTokenAddress(externalBridgeType);
+    }
+    if (token.collateralAddressOrDenom)
+        return token.collateralAddressOrDenom;
+    assert(!REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS.has(token.standard), `Missing collateralAddressOrDenom for collateralized token on ${token.chainName} (${token.standard})`);
+    return token.addressOrDenom;
+}
+//# sourceMappingURL=tokenUtils.js.map

package/dist/utils/tokenUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenUtils.js","sourceRoot":"","sources":["../../src/utils/tokenUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAIjE,OAAO,EACL,+BAA+B,EAE/B,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,MAAM,4CAA4C,GAAG,IAAI,GAAG,CAAgB;IAC1E,aAAa,CAAC,gBAAgB;IAC9B,aAAa,CAAC,YAAY;IAC1B,aAAa,CAAC,qBAAqB;IACnC,aAAa,CAAC,iBAAiB;CAChC,CAAC,CAAC;AAEH,6FAA6F;AAC7F,mGAAmG;AACnG,+EAA+E;AAC/E,4EAA4E;AAC5E,MAAM,2BAA2B,GAAG,IAAI,GAAG,CAAC;IAC1C,+BAA+B,CAAC,YAAY,CAAC,QAAQ,CAAC;IACtD,+BAA+B,CAAC,YAAY,CAAC,QAAQ,CAAC;CACvD,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAuB;IAC3D,OAAO,2BAA2B,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2CAA2C,CACzD,KAAY;IAEZ,OAAO,CACL,KAAK,CAAC,gBAAgB,EAAE;QACxB,4CAA4C,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CACjE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,6BAA6B,CAC3C,KAAY,EACZ,kBAAsC,EACtC,qBAA2D;IAE3D,IAAI,qBAAqB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1C,OAAO,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,KAAK,CAAC,wBAAwB;QAAE,OAAO,KAAK,CAAC,wBAAwB,CAAC;IAE1E,MAAM,CACJ,CAAC,4CAA4C,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EACjE,gEAAgE,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,QAAQ,GAAG,CACtG,CAAC;IAEF,OAAO,KAAK,CAAC,cAAc,CAAC;AAC9B,CAAC"}

package/dist/utils/transactionUtils.d.ts

@@ -0,0 +1,22 @@
+import { type ProtocolType } from '@humanode-hyperlane/utils';
+import { type ProtocolTypedTransaction, type WarpTypedTransaction } from '@humanode-hyperlane/sdk';
+/**
+ * Runtime-validated cast from WarpTypedTransaction to ProtocolTypedTransaction.
+ * WarpTypedTransaction extends TypedTransaction but ProtocolTypedTransaction
+ * only covers known protocol types.
+ * Safe at runtime because WarpCore only produces default-provider transactions.
+ *
+ * The double-cast (as unknown as) is unavoidable due to TypeScript's type narrowing
+ * limitations: WarpTypedTransaction is a union of all protocol transaction types,
+ * and ProtocolTypedTransaction<P> is a conditional/mapped type. Even after the
+ * runtime assert() proves type safety, TypeScript cannot narrow the union across
+ * this structural boundary. The cast is safe because the assert validates the
+ * transaction type matches the expected protocol at runtime.
+ *
+ * @param tx - The transaction to cast
+ * @param expectedProtocol - The expected protocol type
+ * @returns The transaction cast to ProtocolTypedTransaction
+ * @throws Error if the transaction type doesn't match the expected protocol
+ */
+export declare function toProtocolTransaction(tx: WarpTypedTransaction, expectedProtocol: ProtocolType): ProtocolTypedTransaction<ProtocolType>;
+//# sourceMappingURL=transactionUtils.d.ts.map

package/dist/utils/transactionUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionUtils.d.ts","sourceRoot":"","sources":["../../src/utils/transactionUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EAC1B,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,oBAAoB,EACxB,gBAAgB,EAAE,YAAY,GAC7B,wBAAwB,CAAC,YAAY,CAAC,CAQxC"}

package/dist/utils/transactionUtils.js

@@ -0,0 +1,26 @@
+import { assert, } from '@humanode-hyperlane/utils';
+import { PROTOCOL_TO_DEFAULT_PROVIDER_TYPE, } from '@humanode-hyperlane/sdk';
+/**
+ * Runtime-validated cast from WarpTypedTransaction to ProtocolTypedTransaction.
+ * WarpTypedTransaction extends TypedTransaction but ProtocolTypedTransaction
+ * only covers known protocol types.
+ * Safe at runtime because WarpCore only produces default-provider transactions.
+ *
+ * The double-cast (as unknown as) is unavoidable due to TypeScript's type narrowing
+ * limitations: WarpTypedTransaction is a union of all protocol transaction types,
+ * and ProtocolTypedTransaction<P> is a conditional/mapped type. Even after the
+ * runtime assert() proves type safety, TypeScript cannot narrow the union across
+ * this structural boundary. The cast is safe because the assert validates the
+ * transaction type matches the expected protocol at runtime.
+ *
+ * @param tx - The transaction to cast
+ * @param expectedProtocol - The expected protocol type
+ * @returns The transaction cast to ProtocolTypedTransaction
+ * @throws Error if the transaction type doesn't match the expected protocol
+ */
+export function toProtocolTransaction(tx, expectedProtocol) {
+    const expectedType = PROTOCOL_TO_DEFAULT_PROVIDER_TYPE[expectedProtocol];
+    assert(expectedType && tx.type === expectedType, `Transaction type ${tx.type} doesn't match expected protocol ${expectedProtocol} (expected ${expectedType})`);
+    return tx;
+}
+//# sourceMappingURL=transactionUtils.js.map

package/dist/utils/transactionUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionUtils.js","sourceRoot":"","sources":["../../src/utils/transactionUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,GAGP,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,iCAAiC,GAGlC,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CACnC,EAAwB,EACxB,gBAA8B;IAE9B,MAAM,YAAY,GAChB,iCAAiC,CAAC,gBAAqC,CAAC,CAAC;IAC3E,MAAM,CACJ,YAAY,IAAI,EAAE,CAAC,IAAI,KAAK,YAAY,EACxC,oBAAoB,EAAE,CAAC,IAAI,oCAAoC,gBAAgB,cAAc,YAAY,GAAG,CAC7G,CAAC;IACF,OAAO,EAAuD,CAAC;AACjE,CAAC"}