@circle-fin/provider-cctp-v2 1.6.2 → 1.6.3

package/index.cjs

@@ -335,6 +335,57 @@ var BridgeChain;
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
 })(BridgeChain || (BridgeChain = {}));
 // -----------------------------------------------------------------------------
+// Unified Balance Chain Enum (Gateway V1 Supported Chains)
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support Gateway V1 operations
+ * (deposit, spend, balance, delegate, removeFund).
+ *
+ * Derived from the full {@link Blockchain} enum but filtered to only
+ * include chains with active Gateway V1 contract support. When new chains
+ * gain Gateway V1 support, they are added to this enum.
+ *
+ * @enum
+ * @category Enums
+ *
+ * @remarks
+ * - This enum is the **canonical source** of Gateway-supported chains.
+ * - Use this enum (or its string literals) in unified-balance-kit calls
+ *   for type safety.
+ *
+ * @see {@link Blockchain} for the complete list of all known blockchains.
+ * @see {@link UnifiedBalanceChainIdentifier} for the type that accepts these values.
+ */
+var UnifiedBalanceChain;
+(function (UnifiedBalanceChain) {
+    // Mainnet chains with Gateway V1 support
+    UnifiedBalanceChain["Arbitrum"] = "Arbitrum";
+    UnifiedBalanceChain["Avalanche"] = "Avalanche";
+    UnifiedBalanceChain["Base"] = "Base";
+    UnifiedBalanceChain["Ethereum"] = "Ethereum";
+    UnifiedBalanceChain["HyperEVM"] = "HyperEVM";
+    UnifiedBalanceChain["Optimism"] = "Optimism";
+    UnifiedBalanceChain["Polygon"] = "Polygon";
+    UnifiedBalanceChain["Sei"] = "Sei";
+    UnifiedBalanceChain["Solana"] = "Solana";
+    UnifiedBalanceChain["Sonic"] = "Sonic";
+    UnifiedBalanceChain["Unichain"] = "Unichain";
+    UnifiedBalanceChain["World_Chain"] = "World_Chain";
+    // Testnet chains with Gateway V1 support
+    UnifiedBalanceChain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
+    UnifiedBalanceChain["Arc_Testnet"] = "Arc_Testnet";
+    UnifiedBalanceChain["Avalanche_Fuji"] = "Avalanche_Fuji";
+    UnifiedBalanceChain["Base_Sepolia"] = "Base_Sepolia";
+    UnifiedBalanceChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
+    UnifiedBalanceChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    UnifiedBalanceChain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    UnifiedBalanceChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
+    UnifiedBalanceChain["Sei_Testnet"] = "Sei_Testnet";
+    UnifiedBalanceChain["Solana_Devnet"] = "Solana_Devnet";
+    UnifiedBalanceChain["Sonic_Testnet"] = "Sonic_Testnet";
+    UnifiedBalanceChain["Unichain_Sepolia"] = "Unichain_Sepolia";
+    UnifiedBalanceChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
+})(UnifiedBalanceChain || (UnifiedBalanceChain = {}));
 // Earn Chain Enum
 // -----------------------------------------------------------------------------
 /**
@@ -669,6 +720,62 @@ const ADAPTER_CONTRACT_EVM_MAINNET = '0x7FB8c7260b63934d8da38aF902f87ae6e284a845
  * integrations (e.g., Arc Testnet).
  */
 const ADAPTER_CONTRACT_EVM_TESTNET = '0xBBD70b01a1CAbc96d5b7b129Ae1AAabdf50dd40b';
+/**
+ * The GatewayWallet contract address for EVM mainnet networks.
+ *
+ * This contract manages wallet operations for Gateway transactions
+ * on mainnet environments across EVM-compatible chains.
+ */
+const GATEWAY_WALLET_EVM_MAINNET = '0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE';
+/**
+ * The GatewayMinter contract address for EVM mainnet networks.
+ *
+ * This contract handles minting operations for Gateway transactions
+ * on mainnet environments across EVM-compatible chains.
+ */
+const GATEWAY_MINTER_EVM_MAINNET = '0x2222222d7164433c4C09B0b0D809a9b52C04C205';
+/**
+ * The GatewayWallet contract address for EVM testnet networks.
+ *
+ * This contract manages wallet operations for Gateway transactions
+ * on testnet environments across EVM-compatible chains.
+ */
+const GATEWAY_WALLET_EVM_TESTNET = '0x0077777d7EBA4688BDeF3E311b846F25870A19B9';
+/**
+ * The GatewayMinter contract address for EVM testnet networks.
+ *
+ * This contract handles minting operations for Gateway transactions
+ * on testnet environments across EVM-compatible chains.
+ */
+const GATEWAY_MINTER_EVM_TESTNET = '0x0022222ABE238Cc2C7Bb1f21003F0a260052475B';
+/**
+ * The GatewayWallet program address for Solana mainnet.
+ *
+ * This program manages wallet operations for Gateway transactions
+ * on Solana mainnet.
+ */
+const GATEWAY_WALLET_SOLANA_MAINNET = 'GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ';
+/**
+ * The GatewayMinter program address for Solana mainnet.
+ *
+ * This program handles minting operations for Gateway transactions
+ * on Solana mainnet.
+ */
+const GATEWAY_MINTER_SOLANA_MAINNET = 'GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ';
+/**
+ * The GatewayWallet program address for Solana devnet.
+ *
+ * This program manages wallet operations for Gateway transactions
+ * on Solana devnet.
+ */
+const GATEWAY_WALLET_SOLANA_DEVNET = 'GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu';
+/**
+ * The GatewayMinter program address for Solana devnet.
+ *
+ * This program handles minting operations for Gateway transactions
+ * on Solana devnet.
+ */
+const GATEWAY_MINTER_SOLANA_DEVNET = 'GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr';
 
 /**
  * Arc Testnet chain definition
@@ -719,6 +826,19 @@ const ArcTestnet = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
         adapter: ADAPTER_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 26,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -769,6 +889,19 @@ const Arbitrum = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 3,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -818,6 +951,19 @@ const ArbitrumSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 3,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -868,6 +1014,19 @@ const Avalanche = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 1,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -917,6 +1076,19 @@ const AvalancheFuji = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 1,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -967,6 +1139,19 @@ const Base = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 6,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1016,6 +1201,19 @@ const BaseSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 6,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1260,7 +1458,10 @@ const Ethereum = defineChain({
     chainId: 1,
     isTestnet: false,
     explorerUrl: 'https://etherscan.io/tx/{hash}',
-    rpcEndpoints: ['https://eth.merkle.io', 'https://ethereum.publicnode.com'],
+    rpcEndpoints: [
+        'https://ethereum-rpc.publicnode.com',
+        'https://ethereum.publicnode.com',
+    ],
     eurcAddress: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
     usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
     usdtAddress: '0xdac17f958d2ee523a2206206994597c13d831ec7',
@@ -1290,6 +1491,19 @@ const Ethereum = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 0,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1310,7 +1524,7 @@ const EthereumSepolia = defineChain({
     chainId: 11155111,
     isTestnet: true,
     explorerUrl: 'https://sepolia.etherscan.io/tx/{hash}',
-    rpcEndpoints: ['https://sepolia.drpc.org'],
+    rpcEndpoints: ['https://ethereum-sepolia-rpc.publicnode.com'],
     eurcAddress: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4',
     usdcAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
     usdtAddress: null,
@@ -1339,6 +1553,19 @@ const EthereumSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 0,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1433,6 +1660,19 @@ const HyperEVM = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 19,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1477,6 +1717,19 @@ const HyperEVMTestnet = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 19,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2011,6 +2264,19 @@ const Optimism = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 2,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2060,6 +2326,19 @@ const OptimismSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 2,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2248,6 +2527,19 @@ const Polygon = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 7,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2297,6 +2589,19 @@ const PolygonAmoy = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 7,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2343,6 +2648,19 @@ const Sei = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 16,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2387,6 +2705,19 @@ const SeiTestnet = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 16,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2431,6 +2762,19 @@ const Sonic = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 13,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2474,6 +2818,19 @@ const SonicTestnet = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 13,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2522,6 +2879,19 @@ const Solana = defineChain({
     kitContracts: {
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
     },
+    gateway: {
+        domain: 5,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_SOLANA_MAINNET,
+                minter: GATEWAY_MINTER_SOLANA_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
+    },
 });
 
 /**
@@ -2570,6 +2940,19 @@ const SolanaDevnet = defineChain({
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
     },
     rpcEndpoints: ['https://api.devnet.solana.com'],
+    gateway: {
+        domain: 5,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_SOLANA_DEVNET,
+                minter: GATEWAY_MINTER_SOLANA_DEVNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
+    },
 });
 
 /**
@@ -2744,6 +3127,19 @@ const Unichain = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 10,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2793,6 +3189,19 @@ const UnichainSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 10,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2837,6 +3246,19 @@ const WorldChain = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 14,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2883,6 +3305,19 @@ const WorldChainSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 14,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -3162,6 +3597,87 @@ function hasCustomContractSupport(chain, contractType) {
     return (typeof contractAddress === 'string' && contractAddress.trim().length > 0);
 }
 
+/**
+ * Zod schema for validating Gateway v1 contract addresses.
+ *
+ * @example
+ * ```typescript
+ * gatewayV1ContractsSchema.parse({
+ *   wallet: '0x1234567890abcdef1234567890abcdef12345678',
+ *   minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+ * })
+ * ```
+ */
+const gatewayV1ContractsSchema = zod.z
+    .object({
+    wallet: zod.z
+        .string({
+        required_error: 'Gateway wallet address is required. Please provide a valid contract address.',
+        invalid_type_error: 'Gateway wallet address must be a string.',
+    })
+        .min(1, 'Gateway wallet address cannot be empty.'),
+    minter: zod.z
+        .string({
+        required_error: 'Gateway minter address is required. Please provide a valid contract address.',
+        invalid_type_error: 'Gateway minter address must be a string.',
+    })
+        .min(1, 'Gateway minter address cannot be empty.'),
+})
+    .strict(); // Reject any additional properties not defined in the schema
+/**
+ * Zod schema for validating the versioned Gateway contracts map.
+ *
+ * @description Mirrors the {@link GatewayContracts} type: a partial map of
+ * protocol versions to their contract addresses, following the same pattern
+ * as {@link CCTPContracts}.
+ *
+ * @example
+ * ```typescript
+ * gatewayContractsSchema.parse({
+ *   v1: {
+ *     wallet: '0x1234567890abcdef1234567890abcdef12345678',
+ *     minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+ *   }
+ * })
+ * ```
+ */
+const gatewayContractsSchema = zod.z
+    .object({
+    v1: gatewayV1ContractsSchema.optional(),
+})
+    .strict(); // Reject any additional properties not defined in the schema
+/**
+ * Zod schema for validating the full Gateway configuration.
+ *
+ * @description Mirrors the {@link GatewayConfig} type: a domain number plus
+ * a versioned contracts map, following the same pattern as {@link CCTPConfig}.
+ *
+ * @example
+ * ```typescript
+ * gatewayConfigSchema.parse({
+ *   domain: 6,
+ *   contracts: {
+ *     v1: {
+ *       wallet: '0x1234567890abcdef1234567890abcdef12345678',
+ *       minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+ *     }
+ *   }
+ * })
+ * ```
+ */
+const gatewayConfigSchema = zod.z
+    .object({
+    domain: zod.z.number({
+        required_error: 'Gateway domain is required. Please provide a valid domain number.',
+        invalid_type_error: 'Gateway domain must be a number.',
+    }),
+    contracts: gatewayContractsSchema,
+    forwarderSupported: zod.z.object({
+        source: zod.z.boolean(),
+        destination: zod.z.boolean(),
+    }),
+})
+    .strict(); // Reject any additional properties not defined in the schema
 /**
  * Base schema for common chain definition properties.
  * This contains all properties shared between EVM and non-EVM chains.
@@ -3200,6 +3716,7 @@ const baseChainDefinitionSchema = zod.z.object({
         adapter: zod.z.string().optional(),
     })
         .optional(),
+    gateway: gatewayConfigSchema.optional(),
 });
 /**
  * Zod schema for validating EVM chain definitions specifically.
@@ -3408,6 +3925,42 @@ zod.z.union([
             `Supported chains: ${Object.values(EarnChain).join(', ')}`,
     })),
 ]);
+/**
+ * Zod schema for validating unified balance chain identifiers.
+ *
+ * This schema validates that the provided chain is supported for unified balance operations.
+ * It accepts either a UnifiedBalanceChain enum value, a string matching a UnifiedBalanceChain value,
+ * or a ChainDefinition for a supported chain.
+ *
+ * Use this schema when validating chain parameters for unified balance operations to ensure
+ * only Gateway V1-supported chains are accepted at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { unifiedBalanceChainIdentifierSchema } from '@core/chains/validation'
+ * import { UnifiedBalanceChain, Chains } from '@core/chains'
+ *
+ * // Valid - UnifiedBalanceChain enum value
+ * unifiedBalanceChainIdentifierSchema.parse(UnifiedBalanceChain.Ethereum)
+ *
+ * // Valid - string literal
+ * unifiedBalanceChainIdentifierSchema.parse('Ethereum')
+ *
+ * // Invalid - Algorand is not in UnifiedBalanceChain (throws ZodError)
+ * unifiedBalanceChainIdentifierSchema.parse('Algorand')
+ * ```
+ *
+ * @see {@link UnifiedBalanceChain} for the enum of supported chains.
+ */
+const supportedUnifiedBalanceChains = Object.keys(UnifiedBalanceChain).join(', ');
+zod.z.union([
+    zod.z.string().refine((val) => val in UnifiedBalanceChain, (val) => ({
+        message: `Chain "${val}" is not supported for unified balance operations. Supported chains: ${supportedUnifiedBalanceChains}.`,
+    })),
+    chainDefinitionSchema$2.refine((chainDef) => chainDef.chain in UnifiedBalanceChain, (chainDef) => ({
+        message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for unified balance operations. Supported chains: ${supportedUnifiedBalanceChains}.`,
+    })),
+]);
 
 /**
  * @packageDocumentation
@@ -3716,6 +4269,23 @@ class BridgingProvider {
     }
 }
 
+/**
+ * Check whether the current runtime is Node.js.
+ *
+ * @returns `true` when running in Node.js, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { isNodeEnvironment } from '@core/utils'
+ *
+ * if (isNodeEnvironment()) {
+ *   console.log('Running in Node.js')
+ * }
+ * ```
+ */
+const isNodeEnvironment = () => typeof process !== 'undefined' &&
+    typeof process.versions === 'object' &&
+    typeof process.versions.node === 'string';
 /**
  * Detect the runtime environment and return a shortened identifier.
  *
@@ -3723,9 +4293,7 @@ class BridgingProvider {
  */
 const getRuntime = () => {
     // Node.js environment
-    if (typeof process !== 'undefined' &&
-        typeof process.versions === 'object' &&
-        typeof process.versions.node === 'string') {
+    if (isNodeEnvironment()) {
         // Shorten to major version only
         const majorVersion = process.versions.node.split('.')[0] ?? 'unknown';
         return `node/${majorVersion}`;
@@ -4714,6 +5282,7 @@ function createInsufficientTokenBalanceError(chain, token, trace) {
  * as it requires user intervention to add gas funds.
  *
  * @param chain - The blockchain network where the gas check failed
+ * @param nativeToken - Native token symbol (e.g. 'ETH', 'SOL', 'AVAX') for a specific message, defaults to 'native token'
  * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with insufficient gas details
  *
@@ -4722,25 +5291,25 @@ function createInsufficientTokenBalanceError(chain, token, trace) {
  * import { createInsufficientGasError } from '@core/errors'
  *
  * throw createInsufficientGasError('Ethereum')
- * // Message: "Insufficient gas funds on Ethereum"
+ * // Message: "Insufficient native token on Ethereum to cover gas fees"
+ *
+ * throw createInsufficientGasError('Ethereum', 'ETH')
+ * // Message: "Insufficient ETH on Ethereum to cover gas fees"
  * ```
  *
  * @example
  * ```typescript
- * // With trace context for debugging
- * throw createInsufficientGasError('Ethereum', {
+ * throw createInsufficientGasError('Ethereum', 'ETH', {
  *   rawError: error,
- *   gasRequired: '21000',
- *   gasAvailable: '10000',
  *   walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  * })
  * ```
  */
-function createInsufficientGasError(chain, trace) {
+function createInsufficientGasError(chain, nativeToken = 'native token', trace) {
     return new KitError({
         ...BalanceError.INSUFFICIENT_GAS,
         recoverability: 'FATAL',
-        message: `Insufficient gas funds on ${chain}`,
+        message: `Insufficient ${nativeToken} on ${chain} to cover gas fees`,
         cause: {
             trace: {
                 ...trace,
@@ -5106,7 +5675,7 @@ const SLIPPAGE_REVERT_PATTERN = /slippage|lower than the minimum required|less t
  *
  * @internal
  */
-function handleRevertError(msg, error, context) {
+function parseRevertError(msg, error, context) {
     const reason = extractRevertReason(msg, error) ?? 'Transaction reverted';
     if (SLIPPAGE_REVERT_PATTERN.test(reason)) {
         return new KitError({
@@ -5195,17 +5764,34 @@ function handleRevertError(msg, error, context) {
 function parseBlockchainError(error, context) {
     const msg = extractMessage(error);
     const token = context.token ?? 'token';
-    // Pattern 1: Insufficient balance errors
+    // Pattern 0: Insufficient native gas token errors
+    // Must run BEFORE the generic balance pattern because RPC messages like
+    // "insufficient funds for gas * price + value" and "insufficient funds
+    // for intrinsic transaction cost" contain "insufficient funds" which
+    // would otherwise match the token balance pattern below.
+    if (/insufficient funds for (gas|intrinsic transaction cost)|sender doesn't have enough funds to send tx/i.test(msg)) {
+        return createInsufficientGasError(context.chain, undefined, {
+            rawError: error,
+        });
+    }
+    // Pattern 1: Insufficient token balance errors
     // Matches balance-related errors from ERC20 contracts, native transfers, and Solana programs
     if (/transfer amount exceeds balance|insufficient (balance|funds)|burn amount exceeded/i.test(msg)) {
         return createInsufficientTokenBalanceError(context.chain, token, {
             rawError: error,
         });
     }
+    // Pattern 1b: Gateway-specific contract reverts
+    // Matched before the generic simulation/revert pattern so the error
+    // messages are actionable rather than opaque hex selectors.
+    const gatewayError = parseGatewayContractError(msg, context, error);
+    if (gatewayError !== null) {
+        return gatewayError;
+    }
     // Pattern 2: Simulation and execution reverts
     // Matches contract revert errors and simulation failures
     if (/execution reverted|simulation failed|transaction reverted|transaction failed/i.test(msg)) {
-        return handleRevertError(msg, error, context);
+        return parseRevertError(msg, error, context);
     }
     // Pattern 3: Gas-related errors
     // Matches gas estimation failures and gas exhaustion
@@ -5220,10 +5806,6 @@ function parseBlockchainError(error, context) {
         const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
         return createOutOfGasError(context.chain, { rawError: error }, txHash, explorerUrl);
     }
-    // Insufficient funds for gas
-    if (/insufficient funds for gas/i.test(msg)) {
-        return createInsufficientGasError(context.chain, { rawError: error });
-    }
     // Pattern 4: Network connectivity errors
     // Matches connection failures, DNS errors, and timeouts
     if (/connection (refused|failed)|network|timeout|ENOTFOUND|ECONNREFUSED/i.test(msg)) {
@@ -5475,6 +6057,59 @@ function extractRevertReason(msg, error) {
     }
     return null;
 }
+/**
+ * Parses Gateway smart-contract revert selectors into specific KitError types.
+ *
+ * Returns `null` when the message does not match any known Gateway revert,
+ * allowing the caller to fall through to generic patterns.
+ *
+ * @param msg - The extracted error message string.
+ * @param context - Parse error context (chain, token, operation).
+ * @param error - The original raw error for the trace payload.
+ * @returns A KitError if a Gateway pattern matched, otherwise `null`.
+ *
+ * @internal Called by {@link parseBlockchainError} — not re-exported from
+ *   the `@core/errors` barrel.
+ *
+ * @example
+ * ```typescript
+ * // Internal usage within parseBlockchainError:
+ * import { parseGatewayContractError } from './parseBlockchainError'
+ *
+ * const gatewayError = parseGatewayContractError(
+ *   'execution reverted: WithdrawalValueExceedsAvailableBalance',
+ *   { chain: 'Ethereum', token: 'USDC', operation: 'withdraw' },
+ *   new Error('execution reverted'),
+ * )
+ * if (gatewayError !== null) {
+ *   // KitError with INSUFFICIENT_TOKEN balance details
+ *   console.log(gatewayError.message)
+ * }
+ *
+ * // Returns null for unrecognised reverts (caller falls through to generic parsing)
+ * const unknown = parseGatewayContractError(
+ *   'execution reverted: SomeUnknownError()',
+ *   { chain: 'Base', token: 'USDC', operation: 'deposit' },
+ *   new Error('execution reverted'),
+ * )
+ * console.log(unknown) // null
+ * ```
+ */
+function parseGatewayContractError(msg, context, error) {
+    const token = context.token ?? 'token';
+    if (/WithdrawalValueExceedsAvailableBalance|InsufficientDepositBalance/i.test(msg)) {
+        return createInsufficientTokenBalanceError(context.chain, token, {
+            rawError: error,
+        });
+    }
+    if (/WithdrawalNotYetAvailable|WithdrawalDelayNotElapsed/i.test(msg)) {
+        return createTransactionRevertedError(context.chain, 'Withdrawal is not yet available — the withdrawal delay has not elapsed', { rawError: error });
+    }
+    if (/NoWithdrawingBalance/i.test(msg)) {
+        return createTransactionRevertedError(context.chain, 'No pending withdrawal balance — call initiateWithdrawal() first', { rawError: error });
+    }
+    return null;
+}
 
 /**
  * Type guard to check if an error is a KitError instance.
@@ -6089,12 +6724,12 @@ function validate(value, schema, context) {
 }
 
 /**
- * Symbol used to track validation state on objects.
- * This allows us to attach metadata to objects without interfering with their structure,
- * enabling optimized validation by skipping already validated objects.
+ * Module-level WeakMap for tracking which (schema, validator) combinations
+ * have already processed a given object. This avoids mutating user-supplied
+ * input objects while ensuring re-validation occurs when schemas change.
  * @internal
  */
-const VALIDATION_STATE = Symbol('validationState');
+const validationStateMap = new WeakMap();
 /**
  * Validates data against a Zod schema with state tracking and enhanced error reporting.
  *
@@ -6111,11 +6746,12 @@ const VALIDATION_STATE = Symbol('validationState');
  *
  * @example
  * ```typescript
- * const result = validateWithStateTracking(BridgeParamsSchema, params, 'bridge parameters')
+ * const VALIDATOR = Symbol('bridgeValidator')
+ * validateWithStateTracking(params, BridgeParamsSchema, 'bridge parameters', VALIDATOR)
+ * // params is now narrowed to the schema's output type
  * ```
  */
 function validateWithStateTracking(value, schema, context, validatorName) {
-    // Skip validation for null or undefined values
     if (value === null) {
         throw new KitError({
             ...InputError.VALIDATION_FAILED,
@@ -6140,7 +6776,6 @@ function validateWithStateTracking(value, schema, context, validatorName) {
             },
         });
     }
-    // Ensure value is an object that can hold validation state
     if (typeof value !== 'object') {
         throw new KitError({
             ...InputError.VALIDATION_FAILED,
@@ -6153,18 +6788,28 @@ function validateWithStateTracking(value, schema, context, validatorName) {
             },
         });
     }
-    // Get or initialize validation state
-    const valueWithState = value;
-    const state = valueWithState[VALIDATION_STATE] ?? { validatedBy: [] };
-    // Skip validation if already validated by this validator
-    if (state.validatedBy.includes(validatorName)) {
+    const state = validationStateMap.get(value) ?? {
+        validatedSchemasByValidator: new Map(),
+    };
+    // Get the set of schemas that have already validated this object
+    // for the given validator. Create a new WeakSet if this is first time.
+    const validatedSchemas = state.validatedSchemasByValidator.get(validatorName) ?? new WeakSet();
+    if (!(validatedSchemas instanceof WeakSet)) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Invalid validation state: expected WeakSet',
+        });
+    }
+    // Check if this exact schema instance has already validated this object
+    if (validatedSchemas.has(schema)) {
         return;
     }
-    // Delegate to the validate function for actual validation (now throws KitError)
     validate(value, schema, context);
-    // Update validation state
-    state.validatedBy.push(validatorName);
-    valueWithState[VALIDATION_STATE] = state;
+    // Record that this schema has validated the object for this validator
+    validatedSchemas.add(schema);
+    state.validatedSchemasByValidator.set(validatorName, validatedSchemas);
+    validationStateMap.set(value, state);
 }
 
 /**
@@ -9013,123 +9658,723 @@ async function assertCCTPv2AttestationParams(attestation, params) {
 }
 
 /**
- * Executes a prepared chain request and returns the result as a bridge step.
- *
- * This function takes a prepared chain request (containing transaction data) and executes
- * it using the appropriate adapter. It handles the execution details and formats
- * the result as a standardized bridge step with transaction details and explorer URLs.
- *
- * @param params - The execution parameters containing:
- *   - `name`: The name of the step
- *   - `request`: The prepared chain request containing transaction data
- *   - `adapter`: The adapter that will execute the transaction
- *   - `confirmations`: The number of confirmations to wait for (defaults to 1)
- *   - `timeout`: The timeout for the request in milliseconds
- * @returns The bridge step with the transaction details and explorer URL
- * @throws If the transaction execution fails
+ * CCTP bridge step names that can occur in the bridging flow.
  *
- * @example
- * ```typescript
- * const step = await executePreparedChainRequest({
- *   name: 'approve',
- *   request: preparedRequest,
- *   adapter: adapter,
- *   confirmations: 2,
- *   timeout: 30000
- * })
- * console.log('Transaction hash:', step.txHash)
- * ```
+ * This object provides type safety for step names and represents all possible
+ * steps that can be executed during a CCTP bridge operation. Using const assertions
+ * makes this tree-shakable and follows modern TypeScript best practices.
  */
-async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, }) {
-    const step = { name, state: 'pending' };
-    try {
-        /**
-         * No-op requests are not executed.
-         * We return a noop step instead.
-         */
-        if (request.type === 'noop') {
-            step.state = 'noop';
-            return step;
-        }
-        const txHash = await request.execute();
-        step.txHash = txHash;
-        const retryOptions = {
-            isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, { chain: chain.name, txHash })),
-        };
-        if (timeout !== undefined) {
-            retryOptions.deadlineMs = Date.now() + timeout;
-        }
-        const transaction = await retryAsync(async () => adapter.waitForTransaction(txHash, { confirmations, timeout }, chain), retryOptions);
-        step.state = transaction.blockNumber ? 'success' : 'error';
-        step.data = transaction;
-        // Generate explorer URL for the step
-        step.explorerUrl = buildExplorerUrl(chain, txHash);
-        if (!transaction.blockNumber) {
-            step.errorMessage = 'Transaction was not confirmed on-chain.';
-        }
-    }
-    catch (err) {
-        step.state = 'error';
-        step.error = err;
-        // Optionally parse for common blockchain error formats
-        if (err instanceof Error) {
-            step.errorMessage = err.message;
-        }
-        else if (typeof err === 'object' && err != null && 'message' in err) {
-            step.errorMessage = String(err.message);
-        }
-        else {
-            step.errorMessage = 'Unknown error occurred during approval step.';
-        }
-    }
-    return step;
-}
-
+const CCTPv2StepName = {
+    approve: 'approve',
+    burn: 'burn',
+    fetchAttestation: 'fetchAttestation',
+    mint: 'mint',
+    reAttest: 'reAttest',
+};
 /**
- * Approves the TokenMessenger contract to spend USDC tokens for a bridge operation.
- *
- * This function handles the approval step of the CCTP v2 bridge process, allowing
- * the TokenMessenger contract to spend the specified amount of USDC tokens on behalf
- * of the user. This is a prerequisite for the subsequent burn operation.
- *
- * @param params - The bridge parameters containing source, destination, amount and optional config
- * @param sourceChain - The source chain definition where the approval will occur
- * @returns Promise resolving to the bridge step with transaction details
- * @throws {KitError} If the parameters are invalid
- * @throws {BridgeError} If the approval transaction fails
+ * Conditional step transition rules for CCTP bridge flow.
  *
- * @example
- * ```typescript
- * const approveStep = await approve(params, sourceChain)
- * console.log('Approval tx:', approveStep.transactionHash)
- * ```
+ * Rules are evaluated in order - the first matching condition determines the next step.
+ * This approach supports flexible flow logic and makes it easy to extend with new patterns.
  */
-async function bridgeApproval({ params, provider, }) {
-    // Calculate the approval amount
-    const customFee = BigInt(params.config?.customFee?.value ?? '0');
-    const amountBigInt = BigInt(params.amount);
-    const approvalAmount = (amountBigInt + customFee).toString();
-    return await executePreparedChainRequest({
-        name: 'approve',
-        adapter: params.source.adapter,
-        chain: params.source.chain,
-        request: await provider.approve(params.source, approvalAmount),
-    });
-}
-
-/**
- * Executes a deposit-for-burn operation on the source chain to initiate a bridge.
- *
- * This function handles the burning step of the CCTP v2 bridge process, where USDC tokens
- * are burned on the source chain to create a message that can be used to mint equivalent
- * tokens on the destination chain.
- *
- * @param params - The bridge parameters containing source, destination, amount and optional config
- * @param sourceChain - The source chain definition where the burn will occur
- * @returns Promise resolving to the bridge step with transaction details
- * @throws {KitError} If the parameters are invalid
- * @throws \{BridgeError\} If the burn transaction fails
- *
+const STEP_TRANSITION_RULES = {
+    // Starting state - no steps executed yet
+    '': [
+        {
+            condition: () => true,
+            nextStep: CCTPv2StepName.approve,
+            reason: 'Start with approval step',
+            isActionable: true,
+        },
+    ],
+    // After Approve step
+    [CCTPv2StepName.approve]: [
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'success',
+            nextStep: CCTPv2StepName.burn,
+            reason: 'Approval successful, proceed to burn',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.approve,
+            reason: 'Retry failed approval',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'noop',
+            nextStep: CCTPv2StepName.burn,
+            reason: 'No approval needed, proceed to burn',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.approve,
+            reason: 'Continue pending approval',
+            isActionable: false, // Waiting for pending transaction
+        },
+    ],
+    // After Burn step
+    [CCTPv2StepName.burn]: [
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'success',
+            nextStep: CCTPv2StepName.fetchAttestation,
+            reason: 'Burn successful, fetch attestation',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.burn,
+            reason: 'Retry failed burn',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.burn,
+            reason: 'Continue pending burn',
+            isActionable: false, // Waiting for pending transaction
+        },
+    ],
+    // After FetchAttestation step
+    [CCTPv2StepName.fetchAttestation]: [
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'success',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Attestation fetched, proceed to mint',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.fetchAttestation,
+            reason: 'Retry fetching attestation',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.fetchAttestation,
+            reason: 'Continue pending attestation fetch',
+            isActionable: false, // Waiting for attestation to be ready
+        },
+    ],
+    // After Mint step
+    [CCTPv2StepName.mint]: [
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'success',
+            nextStep: null,
+            reason: 'Bridge completed successfully',
+            isActionable: false, // Nothing more to do
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Retry failed mint',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Continue pending mint',
+            isActionable: false, // Waiting for pending transaction
+        },
+    ],
+    // After ReAttest step
+    [CCTPv2StepName.reAttest]: [
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'success',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Re-attestation successful, proceed to mint',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Re-attestation failed, retry mint to re-initiate recovery',
+            isActionable: true,
+        },
+        {
+            condition: (ctx) => ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Re-attestation pending, retry mint to re-initiate recovery',
+            isActionable: true,
+        },
+    ],
+};
+/**
+ * Analyze bridge steps to determine retry feasibility and continuation point.
+ *
+ * This function examines the current state of bridge steps to determine the optimal
+ * continuation strategy. It uses a rule-based approach that makes it easy to extend
+ * with new flow patterns and step types in the future.
+ *
+ * The current analysis supports the standard CCTP flow:
+ * **Traditional flow**: Approve → Burn → FetchAttestation → Mint
+ *
+ * Key features:
+ * - Rule-based transitions: Easy to extend with new step types and logic
+ * - Context-aware decisions: Considers execution history and step states
+ * - Actionable logic: Distinguishes between steps requiring user action vs waiting
+ * - Terminal states: Properly handles completion and non-actionable states
+ *
+ * @param bridgeResult - The bridge result containing step execution history.
+ * @returns Analysis result with continuation step and actionability information.
+ * @throws Error when bridgeResult is invalid or contains no steps array.
+ *
+ * @example
+ * ```typescript
+ * import { analyzeSteps } from './analyzeSteps'
+ *
+ * // Failed approval step (requires user action)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'error', errorMessage: 'User rejected' }
+ *   ]
+ * }
+ *
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: 'Approve', isRetryable: true,
+ * //          reason: 'Retry failed approval' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Pending transaction (requires waiting, not actionable)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'pending' }
+ *   ]
+ * }
+ *
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: 'Approve', isRetryable: false,
+ * //          reason: 'Continue pending approval' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Completed bridge (nothing to do)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'success' },
+ *     { name: 'Burn', state: 'success' },
+ *     { name: 'FetchAttestation', state: 'success' },
+ *     { name: 'Mint', state: 'success' }
+ *   ]
+ * }
+ *
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: null, isRetryable: false,
+ * //          reason: 'Bridge completed successfully' }
+ * ```
+ */
+const analyzeSteps = (bridgeResult) => {
+    // Input validation
+    if (!bridgeResult || !Array.isArray(bridgeResult.steps)) {
+        throw new Error('Invalid bridgeResult: must contain a steps array');
+    }
+    const { steps } = bridgeResult;
+    // Build execution context from step history
+    const context = buildFlowContext(steps);
+    // Determine continuation logic using rule engine
+    const continuation = determineContinuationFromRules(context);
+    return {
+        continuationStep: continuation.nextStep,
+        isActionable: continuation.isActionable,
+        completedSteps: Array.from(context.completedSteps),
+        failedSteps: Array.from(context.failedSteps),
+        reason: continuation.reason,
+    };
+};
+/**
+ * Build flow context from the execution history.
+ *
+ * @param steps - Array of executed bridge steps.
+ * @returns Flow context with execution state and history.
+ */
+function buildFlowContext(steps) {
+    const completedSteps = new Set();
+    const failedSteps = new Set();
+    let lastStep;
+    // Process step history to build context
+    for (const step of steps) {
+        if (step.state === 'success' || step.state === 'noop') {
+            completedSteps.add(step.name);
+        }
+        else if (step.state === 'error') {
+            failedSteps.add(step.name);
+        }
+        // Track the last step for continuation logic
+        lastStep = {
+            name: step.name,
+            state: step.state,
+        };
+    }
+    return {
+        completedSteps,
+        failedSteps,
+        ...(lastStep && { lastStep }),
+    };
+}
+/**
+ * Determine continuation step using the rule engine.
+ *
+ * @param context - The flow context with execution history.
+ * @returns Continuation decision with next step and actionability information.
+ */
+function determineContinuationFromRules(context) {
+    const lastStepName = context.lastStep?.name;
+    // Handle initial state when no steps have been executed
+    if (lastStepName === undefined) {
+        const rules = STEP_TRANSITION_RULES[''];
+        const matchingRule = rules?.find((rule) => rule.condition(context));
+        if (!matchingRule) {
+            return {
+                nextStep: null,
+                isActionable: false,
+                reason: 'No initial state rule found',
+            };
+        }
+        return {
+            nextStep: matchingRule.nextStep,
+            isActionable: matchingRule.isActionable,
+            reason: matchingRule.reason,
+        };
+    }
+    // A step with an empty name is ambiguous and should be treated as an unrecoverable state.
+    if (lastStepName === '') {
+        return {
+            nextStep: null,
+            isActionable: false,
+            reason: 'No transition rules defined for step with empty name',
+        };
+    }
+    const rules = STEP_TRANSITION_RULES[lastStepName];
+    if (!rules) {
+        return {
+            nextStep: null,
+            isActionable: false,
+            reason: `No transition rules defined for step: ${lastStepName}`,
+        };
+    }
+    // Find the first matching rule
+    const matchingRule = rules.find((rule) => rule.condition(context));
+    if (!matchingRule) {
+        return {
+            nextStep: null,
+            isActionable: false,
+            reason: `No matching transition rule for current context`,
+        };
+    }
+    return {
+        nextStep: matchingRule.nextStep,
+        isActionable: matchingRule.isActionable,
+        reason: matchingRule.reason,
+    };
+}
+
+/**
+ * Find a step by name in the bridge result.
+ *
+ * @param result - The bridge result to search.
+ * @param stepName - The name of the step to find.
+ * @returns The step if found, undefined otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { findStepByName } from './findStep'
+ *
+ * const burnStep = findStepByName(result, 'burn')
+ * if (burnStep) {
+ *   console.log('Burn tx:', burnStep.txHash)
+ * }
+ * ```
+ */
+function findStepByName(result, stepName) {
+    return result.steps.find((step) => step.name === stepName);
+}
+/**
+ * Find a pending step by name and return it with its index.
+ *
+ * Searches for a step that matches both the step name and has a pending state.
+ *
+ * @param result - The bridge result containing steps to search through.
+ * @param stepName - The step name to find (e.g., 'burn', 'mint', 'fetchAttestation').
+ * @returns An object containing the step and its index in the steps array.
+ * @throws KitError if the specified pending step is not found.
+ *
+ * @example
+ * ```typescript
+ * import { findPendingStep } from './findStep'
+ *
+ * const { step, index } = findPendingStep(result, 'burn')
+ * console.log('Pending step:', step.name, 'at index:', index)
+ * ```
+ */
+function findPendingStep(result, stepName) {
+    const index = result.steps.findIndex((step) => step.name === stepName && step.state === 'pending');
+    if (index === -1) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Pending step "${stepName}" not found in result`,
+        });
+    }
+    const step = result.steps[index];
+    if (!step) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Pending step is undefined',
+        });
+    }
+    return { step, index };
+}
+/**
+ * Get the burn transaction hash from bridge result.
+ *
+ * @param result - The bridge result.
+ * @returns The burn transaction hash, or undefined if not found.
+ *
+ * @example
+ * ```typescript
+ * import { getBurnTxHash } from './findStep'
+ *
+ * const burnTxHash = getBurnTxHash(result)
+ * if (burnTxHash) {
+ *   console.log('Burn tx hash:', burnTxHash)
+ * }
+ * ```
+ */
+function getBurnTxHash(result) {
+    return findStepByName(result, CCTPv2StepName.burn)?.txHash;
+}
+/**
+ * Get the attestation data from bridge result.
+ *
+ * @param result - The bridge result.
+ * @returns The attestation data, or undefined if not found.
+ *
+ * @example
+ * ```typescript
+ * import { getAttestationData } from './findStep'
+ *
+ * const attestation = getAttestationData(result)
+ * if (attestation) {
+ *   console.log('Attestation:', attestation.message)
+ * }
+ * ```
+ */
+function getAttestationData(result) {
+    // Prefer reAttest data (most recent attestation after expiry)
+    const reAttestStep = findStepByName(result, CCTPv2StepName.reAttest);
+    if (reAttestStep?.state === 'success' && reAttestStep.data) {
+        return reAttestStep.data;
+    }
+    // Fall back to fetchAttestation step
+    const fetchStep = findStepByName(result, CCTPv2StepName.fetchAttestation);
+    return fetchStep?.data;
+}
+
+/**
+ * Check if the analysis indicates a non-actionable pending state.
+ *
+ * A pending state is non-actionable when there's a continuation step but
+ * the analysis marks it as not actionable, typically because we need to
+ * wait for an ongoing operation to complete.
+ *
+ * @param analysis - The step analysis result from analyzeSteps.
+ * @param result - The bridge result to check for pending steps.
+ * @returns True if there is a pending step that we should wait for.
+ *
+ * @example
+ * ```typescript
+ * import { hasPendingState } from './stepUtils'
+ * import { analyzeSteps } from '../analyzeSteps'
+ *
+ * const analysis = analyzeSteps(bridgeResult)
+ * if (hasPendingState(analysis, bridgeResult)) {
+ *   // Wait for the pending operation to complete
+ * }
+ * ```
+ */
+/**
+ * Evaluate a transaction receipt and return the corresponding step state
+ * and error message. Centralises the success/revert/unconfirmed logic so
+ * every call-site behaves identically.
+ *
+ * @param receipt - The transaction receipt containing status and block info.
+ * @param txHash - The transaction hash used in error messages.
+ * @returns An object with `state` and an optional `errorMessage`.
+ *
+ * @example
+ * ```typescript
+ * const outcome = evaluateTransactionOutcome(receipt, '0xabc...')
+ * step.state = outcome.state
+ * if (outcome.errorMessage) step.errorMessage = outcome.errorMessage
+ * ```
+ */
+function evaluateTransactionOutcome(receipt, txHash) {
+    if (receipt.status === 'success' && receipt.blockNumber) {
+        return { state: 'success' };
+    }
+    return {
+        state: 'error',
+        errorMessage: receipt.status === 'reverted'
+            ? `Transaction ${txHash} was reverted`
+            : 'Transaction was not confirmed on-chain',
+    };
+}
+function hasPendingState(analysis, result) {
+    // Check if there's a continuation step that's marked as non-actionable
+    if (analysis.continuationStep === null || analysis.isActionable) {
+        return false;
+    }
+    // Verify that the continuation step actually exists and is in pending state
+    const pendingStep = result.steps.find((step) => step.name === analysis.continuationStep && step.state === 'pending');
+    return pendingStep !== undefined;
+}
+/**
+ * Check if the step is the last one in the execution flow.
+ *
+ * @param step - The step object to check.
+ * @param stepNames - The ordered list of step names in the execution flow.
+ * @returns True if this is the last step in the flow.
+ *
+ * @example
+ * ```typescript
+ * import { isLastStep } from './stepUtils'
+ *
+ * const stepNames = ['approve', 'burn', 'fetchAttestation', 'mint']
+ * isLastStep({ name: 'mint' }, stepNames) // true
+ * isLastStep({ name: 'burn' }, stepNames) // false
+ * ```
+ */
+function isLastStep(step, stepNames) {
+    const stepIndex = stepNames.indexOf(step.name);
+    return stepIndex === -1 || stepIndex >= stepNames.length - 1;
+}
+/**
+ * Wait for a pending transaction to complete.
+ *
+ * Poll the adapter until the transaction is confirmed on-chain and return
+ * the updated step with success or error state based on the receipt.
+ *
+ * @param pendingStep - The full step object containing the transaction hash.
+ * @param adapter - The adapter to use for waiting.
+ * @param chain - The chain where the transaction was submitted.
+ * @returns The updated step object with success or error state.
+ *
+ * @throws KitError when the pending step has no transaction hash.
+ *
+ * @example
+ * ```typescript
+ * import { waitForPendingTransaction } from './bridgeStepUtils'
+ *
+ * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
+ * const updatedStep = await waitForPendingTransaction(pendingStep, adapter, chain)
+ * // updatedStep.state is now 'success' or 'error'
+ * ```
+ */
+async function waitForPendingTransaction(pendingStep, adapter, chain) {
+    if (!pendingStep.txHash) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Cannot wait for pending ${pendingStep.name}: no transaction hash available`,
+        });
+    }
+    const txHash = pendingStep.txHash;
+    const txReceipt = await retryAsync(async () => adapter.waitForTransaction(txHash, undefined, chain), {
+        isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, { chain: chain.name, txHash })),
+    });
+    const outcome = evaluateTransactionOutcome(txReceipt, txHash);
+    return {
+        ...pendingStep,
+        state: outcome.state,
+        data: txReceipt,
+        explorerUrl: buildExplorerUrl(chain, txHash),
+        ...(outcome.errorMessage ? { errorMessage: outcome.errorMessage } : {}),
+    };
+}
+/**
+ * Wait for a pending step to complete.
+ *
+ * For transaction steps: waits for the transaction to be confirmed.
+ * For attestation: re-executes the attestation fetch.
+ *
+ * @typeParam TFromAdapterCapabilities - The capabilities of the source adapter.
+ * @typeParam TToAdapterCapabilities - The capabilities of the destination adapter.
+ * @param pendingStep - The full step object (with name, state, txHash, data, etc.) to resolve.
+ * @param adapter - The adapter to use.
+ * @param chain - The chain where the step is executing.
+ * @param context - The retry context.
+ * @param result - The bridge result.
+ * @param provider - The CCTP v2 bridging provider.
+ * @returns The resolved step object with updated state.
+ *
+ * @throws KitError when fetching attestation but burn transaction hash is not found.
+ *
+ * @example
+ * ```typescript
+ * import { waitForStepToComplete } from './bridgeStepUtils'
+ *
+ * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
+ * const updatedStep = await waitForStepToComplete(
+ *   pendingStep,
+ *   adapter,
+ *   chain,
+ *   context,
+ *   result,
+ *   provider,
+ * )
+ * // updatedStep.state is now 'success' or 'error'
+ * ```
+ */
+async function waitForStepToComplete(pendingStep, adapter, chain, context, result, provider) {
+    if (pendingStep.name === CCTPv2StepName.fetchAttestation) {
+        // For attestation, re-run the fetch (it has built-in polling)
+        const burnTxHash = getBurnTxHash(result);
+        if (!burnTxHash) {
+            throw new KitError({
+                ...InputError.VALIDATION_FAILED,
+                recoverability: 'FATAL',
+                message: 'Cannot fetch attestation: burn transaction hash not found',
+            });
+        }
+        const sourceAddress = result.source.address;
+        const attestation = await provider.fetchAttestation({
+            chain: result.source.chain,
+            adapter: context.from,
+            address: sourceAddress,
+        }, burnTxHash);
+        return {
+            ...pendingStep,
+            state: 'success',
+            data: attestation,
+        };
+    }
+    // For transaction steps, wait for the transaction to complete
+    return waitForPendingTransaction(pendingStep, adapter, chain);
+}
+
+/**
+ * Executes a prepared chain request and returns the result as a bridge step.
+ *
+ * This function takes a prepared chain request (containing transaction data) and executes
+ * it using the appropriate adapter. It handles the execution details and formats
+ * the result as a standardized bridge step with transaction details and explorer URLs.
+ *
+ * @param params - The execution parameters containing:
+ *   - `name`: The name of the step
+ *   - `request`: The prepared chain request containing transaction data
+ *   - `adapter`: The adapter that will execute the transaction
+ *   - `confirmations`: The number of confirmations to wait for (defaults to 1)
+ *   - `timeout`: The timeout for the request in milliseconds
+ * @returns The bridge step with the transaction details and explorer URL
+ * @throws If the transaction execution fails
+ *
+ * @example
+ * ```typescript
+ * const step = await executePreparedChainRequest({
+ *   name: 'approve',
+ *   request: preparedRequest,
+ *   adapter: adapter,
+ *   confirmations: 2,
+ *   timeout: 30000
+ * })
+ * console.log('Transaction hash:', step.txHash)
+ * ```
+ */
+async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, }) {
+    const step = { name, state: 'pending' };
+    try {
+        /**
+         * No-op requests are not executed.
+         * We return a noop step instead.
+         */
+        if (request.type === 'noop') {
+            step.state = 'noop';
+            return step;
+        }
+        const txHash = await request.execute();
+        step.txHash = txHash;
+        const retryOptions = {
+            isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, { chain: chain.name, txHash })),
+        };
+        if (timeout !== undefined) {
+            retryOptions.deadlineMs = Date.now() + timeout;
+        }
+        const transaction = await retryAsync(async () => adapter.waitForTransaction(txHash, { confirmations, timeout }, chain), retryOptions);
+        const outcome = evaluateTransactionOutcome(transaction, txHash);
+        step.state = outcome.state;
+        step.data = transaction;
+        // Generate explorer URL for the step
+        step.explorerUrl = buildExplorerUrl(chain, txHash);
+        if (outcome.errorMessage) {
+            step.errorMessage = outcome.errorMessage;
+        }
+    }
+    catch (err) {
+        step.state = 'error';
+        step.error = err;
+        // Optionally parse for common blockchain error formats
+        if (err instanceof Error) {
+            step.errorMessage = err.message;
+        }
+        else if (typeof err === 'object' && err != null && 'message' in err) {
+            step.errorMessage = String(err.message);
+        }
+        else {
+            step.errorMessage = `Unknown error occurred during ${name} step.`;
+        }
+    }
+    return step;
+}
+
+/**
+ * Approves the TokenMessenger contract to spend USDC tokens for a bridge operation.
+ *
+ * This function handles the approval step of the CCTP v2 bridge process, allowing
+ * the TokenMessenger contract to spend the specified amount of USDC tokens on behalf
+ * of the user. This is a prerequisite for the subsequent burn operation.
+ *
+ * @param params - The bridge parameters containing source, destination, amount and optional config
+ * @param sourceChain - The source chain definition where the approval will occur
+ * @returns Promise resolving to the bridge step with transaction details
+ * @throws {KitError} If the parameters are invalid
+ * @throws {BridgeError} If the approval transaction fails
+ *
+ * @example
+ * ```typescript
+ * const approveStep = await approve(params, sourceChain)
+ * console.log('Approval tx:', approveStep.transactionHash)
+ * ```
+ */
+async function bridgeApproval({ params, provider, }) {
+    // Calculate the approval amount
+    const customFee = BigInt(params.config?.customFee?.value ?? '0');
+    const amountBigInt = BigInt(params.amount);
+    const approvalAmount = (amountBigInt + customFee).toString();
+    return await executePreparedChainRequest({
+        name: 'approve',
+        adapter: params.source.adapter,
+        chain: params.source.chain,
+        request: await provider.approve(params.source, approvalAmount),
+    });
+}
+
+/**
+ * Executes a deposit-for-burn operation on the source chain to initiate a bridge.
+ *
+ * This function handles the burning step of the CCTP v2 bridge process, where USDC tokens
+ * are burned on the source chain to create a message that can be used to mint equivalent
+ * tokens on the destination chain.
+ *
+ * @param params - The bridge parameters containing source, destination, amount and optional config
+ * @param sourceChain - The source chain definition where the burn will occur
+ * @returns Promise resolving to the bridge step with transaction details
+ * @throws {KitError} If the parameters are invalid
+ * @throws \{BridgeError\} If the burn transaction fails
+ *
  * @example
  * ```typescript
  * const burnStep = await burn(params, sourceChain)
@@ -10680,10 +11925,11 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
                 txHash: receipt.txHash,
             })),
         });
-        step.state = transaction.blockNumber === undefined ? 'error' : 'success';
+        const outcome = evaluateTransactionOutcome(transaction, receipt.txHash);
+        step.state = outcome.state;
         step.data = transaction;
-        if (transaction.blockNumber === undefined) {
-            step.errorMessage = 'Transaction was not confirmed on-chain.';
+        if (outcome.errorMessage) {
+            step.errorMessage = outcome.errorMessage;
         }
     }
     catch (err) {
@@ -10695,7 +11941,7 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
     return step;
 }
 
-var version = "1.6.2";
+var version = "1.6.3";
 var pkg = {
 	version: version};
 
@@ -11003,681 +12249,266 @@ const hexStringSchema = zod.z
     .refine((value) => value.trim().length > 0, 'Hex string cannot be empty')
     .refine((value) => value.startsWith('0x'), 'Hex string must start with 0x prefix')
     .refine((value) => {
-    const hexPattern = /^0x[0-9a-fA-F]+$/;
-    return hexPattern.test(value);
-}, 'Hex string contains invalid characters. Only hexadecimal characters (0-9, a-f, A-F) are allowed after 0x');
-/**
- * Schema for validating EVM addresses.
- *
- * This schema validates that a string is a properly formatted EVM address:
- * - Must be a valid hex string with '0x' prefix
- * - Must be exactly 42 characters long (0x + 40 hex characters)
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { evmAddressSchema } from '@core/adapter'
- *
- * const validAddress = '0x1234567890123456789012345678901234567890'
- *
- * const result = evmAddressSchema.safeParse(validAddress)
- * console.log(result.success) // true
- * ```
- */
-hexStringSchema.refine((value) => value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)');
-/**
- * Schema for validating transaction hashes.
- *
- * This schema validates that a string is a properly formatted transaction hash:
- * - Must be a valid hex string with '0x' prefix
- * - Must be exactly 66 characters long (0x + 64 hex characters)
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { evmTransactionHashSchema } from '@core/adapter'
- *
- * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
- *
- * const result = evmTransactionHashSchema.safeParse(validTxHash)
- * console.log(result.success) // true
- * ```
- */
-hexStringSchema.refine((value) => value.length === 66, 'Transaction hash must be exactly 66 characters long (0x + 64 hex characters)');
-/**
- * Schema for validating base58-encoded strings.
- *
- * This schema validates that a string:
- * - Is a string type
- * - Is not empty after trimming
- * - Contains only valid base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z)
- * - Does not contain commonly confused characters (0, O, I, l)
- *
- * @remarks
- * This schema does not validate length, making it suitable for various base58-encoded data
- * like Solana addresses, transaction signatures, and other base58-encoded data.
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { base58StringSchema } from '@core/adapter'
- *
- * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
- * const validTxHash = '3Jf8k2L5mN9pQ7rS1tV4wX6yZ8aB2cD4eF5gH7iJ9kL1mN3oP5qR7sT9uV1wX3yZ5'
- *
- * const addressResult = base58StringSchema.safeParse(validAddress)
- * const txHashResult = base58StringSchema.safeParse(validTxHash)
- * console.log(addressResult.success) // true
- * console.log(txHashResult.success) // true
- * ```
- */
-const base58StringSchema = zod.z
-    .string()
-    .min(1, 'Base58 string is required')
-    .refine((value) => value.trim().length > 0, 'Base58 string cannot be empty')
-    .refine((value) => {
-    // Base58 alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
-    // Excludes: 0, O, I, l to avoid confusion
-    const base58Pattern = /^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/;
-    return base58Pattern.test(value);
-}, 'Base58 string contains invalid characters. Only base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z) are allowed');
-/**
- * Schema for validating Solana addresses.
- *
- * This schema validates that a string is a properly formatted Solana address:
- * - Must be a valid base58-encoded string
- * - Must be between 32-44 characters long (typical length for base58-encoded 32-byte addresses)
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { solanaAddressSchema } from '@core/adapter'
- *
- * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
- *
- * const result = solanaAddressSchema.safeParse(validAddress)
- * console.log(result.success) // true
- * ```
- */
-base58StringSchema.refine((value) => value.length >= 32 && value.length <= 44, 'Solana address must be between 32-44 characters long (base58-encoded 32-byte address)');
-/**
- * Schema for validating Solana transaction hashes.
- *
- * This schema validates that a string is a properly formatted Solana transaction hash:
- * - Must be a valid base58-encoded string
- * - Must be between 86-88 characters long (typical length for base58-encoded 64-byte signatures)
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { solanaTransactionHashSchema } from '@core/adapter'
- *
- * const validTxHash = '5VfYmGBjvQKe3xgLtTQPSMEUdpEVHrJwLK7pKBJWKzYpNBE2g3kJrq7RSe9M8DqzQJ5J2aZPTjHLvd4WgxPpJKS'
- *
- * const result = solanaTransactionHashSchema.safeParse(validTxHash)
- * console.log(result.success) // true
- * ```
- */
-base58StringSchema.refine((value) => value.length >= 86 && value.length <= 88, 'Solana transaction hash must be between 86-88 characters long (base58-encoded 64-byte signature)');
-/**
- * Schema for validating Adapter objects.
- * Checks for the required methods that define an Adapter.
- */
-zod.z.object({
-    prepare: zod.z.function(),
-    waitForTransaction: zod.z.function(),
-    getAddress: zod.z.function(),
-});
-
-/**
- * Validate that the adapter has sufficient token balance for a transaction.
- *
- * This function checks if the adapter's current token balance is greater than or equal
- * to the requested transaction amount. It throws a KitError with code 9001
- * (BALANCE_INSUFFICIENT_TOKEN) if the balance is insufficient, providing detailed
- * information about the shortfall.
- *
- * @param params - The validation parameters containing adapter, amount, token, and token address.
- * @returns A promise that resolves to void if validation passes.
- * @throws {KitError} When the adapter's balance is less than the required amount (code: 9001).
- *
- * @example
- * ```typescript
- * import { validateBalanceForTransaction } from '@core/adapter'
- * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
- * import { isKitError, ERROR_TYPES } from '@core/errors'
- *
- * const adapter = createViemAdapterFromPrivateKey({
- *   privateKey: '0x...',
- *   chain: 'Ethereum',
- * })
- *
- * try {
- *   await validateBalanceForTransaction({
- *     adapter,
- *     amount: '1000000', // 1 USDC (6 decimals)
- *     token: 'USDC',
- *     tokenAddress: '0xA0b86a33E6441c8C1c7C16e4c5e3e5b5e4c5e3e5b5e4c5e',
- *     operationContext: { chain: 'Ethereum' },
- *   })
- *   console.log('Balance validation passed')
- * } catch (error) {
- *   if (isKitError(error) && error.type === ERROR_TYPES.BALANCE) {
- *     console.error('Insufficient funds:', error.message)
- *   }
- * }
- * ```
- */
-const validateBalanceForTransaction = async (params) => {
-    const { amount, adapter, token, tokenAddress, operationContext } = params;
-    const balancePrepared = await adapter.prepareAction('usdc.balanceOf', {
-        walletAddress: operationContext.address,
-    }, operationContext);
-    const balance = await balancePrepared.execute();
-    if (BigInt(balance) < BigInt(amount)) {
-        // Extract chain name from operationContext
-        const chainName = extractChainInfo(operationContext.chain).name;
-        // Create KitError with rich context in trace
-        throw createInsufficientTokenBalanceError(chainName, token, {
-            balance: balance.toString(),
-            amount,
-            tokenAddress,
-            walletAddress: operationContext.address,
-        });
-    }
-};
-
+    const hexPattern = /^0x[0-9a-fA-F]+$/;
+    return hexPattern.test(value);
+}, 'Hex string contains invalid characters. Only hexadecimal characters (0-9, a-f, A-F) are allowed after 0x');
 /**
- * Validate that the adapter has sufficient native token balance for transaction fees.
+ * Schema for validating EVM addresses.
  *
- * This function checks if the adapter's current native token balance (ETH, SOL, etc.)
- * is greater than zero. It throws a KitError with code 9002 (BALANCE_INSUFFICIENT_GAS)
- * if the balance is zero, indicating the wallet cannot pay for transaction fees.
+ * This schema validates that a string is a properly formatted EVM address:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 42 characters long (0x + 40 hex characters)
  *
- * @param params - The validation parameters containing adapter and operation context.
- * @returns A promise that resolves to void if validation passes.
- * @throws {KitError} When the adapter's native balance is zero (code: 9002).
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * import { validateNativeBalanceForTransaction } from '@core/adapter'
- * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
- * import { isKitError, ERROR_TYPES } from '@core/errors'
+ * import { evmAddressSchema } from '@core/adapter'
  *
- * const adapter = createViemAdapterFromPrivateKey({
- *   privateKey: '0x...',
- *   chain: 'Ethereum',
- * })
+ * const validAddress = '0x1234567890123456789012345678901234567890'
  *
- * try {
- *   await validateNativeBalanceForTransaction({
- *     adapter,
- *     operationContext: { chain: 'Ethereum' },
- *   })
- *   console.log('Native balance validation passed')
- * } catch (error) {
- *   if (isKitError(error) && error.type === ERROR_TYPES.BALANCE) {
- *     console.error('Insufficient gas funds:', error.message)
- *   }
- * }
+ * const result = evmAddressSchema.safeParse(validAddress)
+ * console.log(result.success) // true
  * ```
  */
-const validateNativeBalanceForTransaction = async (params) => {
-    const { adapter, operationContext } = params;
-    const balancePrepared = await adapter.prepareAction('native.balanceOf', {
-        walletAddress: operationContext.address,
-    }, operationContext);
-    const balance = await balancePrepared.execute();
-    if (BigInt(balance) === 0n) {
-        // Extract chain name from operationContext
-        const chainName = extractChainInfo(operationContext.chain).name;
-        // Create KitError with rich context in trace
-        throw createInsufficientGasError(chainName, {
-            balance: '0',
-            walletAddress: operationContext.address,
-        });
-    }
-};
-
+hexStringSchema.refine((value) => value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)');
 /**
- * Permit signature standards for gasless token approvals.
+ * Schema for validating transaction hashes.
  *
- * Defines the permit types that can be used to approve token spending
- * without requiring a separate approval transaction.
+ * This schema validates that a string is a properly formatted transaction hash:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 66 characters long (0x + 64 hex characters)
  *
- * @remarks
- * - NONE: No permit, tokens must be pre-approved via separate transaction
- * - EIP2612: Standard ERC-20 permit (USDC, DAI v2, and most modern tokens)
- */
-var PermitType;
-(function (PermitType) {
-    /** No permit required - tokens must be pre-approved */
-    PermitType[PermitType["NONE"] = 0] = "NONE";
-    /** EIP-2612 standard permit */
-    PermitType[PermitType["EIP2612"] = 1] = "EIP2612";
-})(PermitType || (PermitType = {}));
-
-/**
- * CCTP bridge step names that can occur in the bridging flow.
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
- * This object provides type safety for step names and represents all possible
- * steps that can be executed during a CCTP bridge operation. Using const assertions
- * makes this tree-shakable and follows modern TypeScript best practices.
- */
-const CCTPv2StepName = {
-    approve: 'approve',
-    burn: 'burn',
-    fetchAttestation: 'fetchAttestation',
-    mint: 'mint',
-    reAttest: 'reAttest',
-};
-/**
- * Conditional step transition rules for CCTP bridge flow.
+ * @example
+ * ```typescript
+ * import { evmTransactionHashSchema } from '@core/adapter'
  *
- * Rules are evaluated in order - the first matching condition determines the next step.
- * This approach supports flexible flow logic and makes it easy to extend with new patterns.
+ * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ *
+ * const result = evmTransactionHashSchema.safeParse(validTxHash)
+ * console.log(result.success) // true
+ * ```
  */
-const STEP_TRANSITION_RULES = {
-    // Starting state - no steps executed yet
-    '': [
-        {
-            condition: () => true,
-            nextStep: CCTPv2StepName.approve,
-            reason: 'Start with approval step',
-            isActionable: true,
-        },
-    ],
-    // After Approve step
-    [CCTPv2StepName.approve]: [
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'success',
-            nextStep: CCTPv2StepName.burn,
-            reason: 'Approval successful, proceed to burn',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.approve,
-            reason: 'Retry failed approval',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'noop',
-            nextStep: CCTPv2StepName.burn,
-            reason: 'No approval needed, proceed to burn',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.approve,
-            reason: 'Continue pending approval',
-            isActionable: false, // Waiting for pending transaction
-        },
-    ],
-    // After Burn step
-    [CCTPv2StepName.burn]: [
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'success',
-            nextStep: CCTPv2StepName.fetchAttestation,
-            reason: 'Burn successful, fetch attestation',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.burn,
-            reason: 'Retry failed burn',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.burn,
-            reason: 'Continue pending burn',
-            isActionable: false, // Waiting for pending transaction
-        },
-    ],
-    // After FetchAttestation step
-    [CCTPv2StepName.fetchAttestation]: [
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'success',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Attestation fetched, proceed to mint',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.fetchAttestation,
-            reason: 'Retry fetching attestation',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.fetchAttestation,
-            reason: 'Continue pending attestation fetch',
-            isActionable: false, // Waiting for attestation to be ready
-        },
-    ],
-    // After Mint step
-    [CCTPv2StepName.mint]: [
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'success',
-            nextStep: null,
-            reason: 'Bridge completed successfully',
-            isActionable: false, // Nothing more to do
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Retry failed mint',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Continue pending mint',
-            isActionable: false, // Waiting for pending transaction
-        },
-    ],
-    // After ReAttest step
-    [CCTPv2StepName.reAttest]: [
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'success',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Re-attestation successful, proceed to mint',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Re-attestation failed, retry mint to re-initiate recovery',
-            isActionable: true,
-        },
-        {
-            condition: (ctx) => ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Re-attestation pending, retry mint to re-initiate recovery',
-            isActionable: true,
-        },
-    ],
-};
+hexStringSchema.refine((value) => value.length === 66, 'Transaction hash must be exactly 66 characters long (0x + 64 hex characters)');
 /**
- * Analyze bridge steps to determine retry feasibility and continuation point.
- *
- * This function examines the current state of bridge steps to determine the optimal
- * continuation strategy. It uses a rule-based approach that makes it easy to extend
- * with new flow patterns and step types in the future.
- *
- * The current analysis supports the standard CCTP flow:
- * **Traditional flow**: Approve → Burn → FetchAttestation → Mint
- *
- * Key features:
- * - Rule-based transitions: Easy to extend with new step types and logic
- * - Context-aware decisions: Considers execution history and step states
- * - Actionable logic: Distinguishes between steps requiring user action vs waiting
- * - Terminal states: Properly handles completion and non-actionable states
- *
- * @param bridgeResult - The bridge result containing step execution history.
- * @returns Analysis result with continuation step and actionability information.
- * @throws Error when bridgeResult is invalid or contains no steps array.
+ * Schema for validating base58-encoded strings.
  *
- * @example
- * ```typescript
- * import { analyzeSteps } from './analyzeSteps'
+ * This schema validates that a string:
+ * - Is a string type
+ * - Is not empty after trimming
+ * - Contains only valid base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z)
+ * - Does not contain commonly confused characters (0, O, I, l)
  *
- * // Failed approval step (requires user action)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'error', errorMessage: 'User rejected' }
- *   ]
- * }
+ * @remarks
+ * This schema does not validate length, making it suitable for various base58-encoded data
+ * like Solana addresses, transaction signatures, and other base58-encoded data.
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: 'Approve', isRetryable: true,
- * //          reason: 'Retry failed approval' }
- * ```
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * // Pending transaction (requires waiting, not actionable)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'pending' }
- *   ]
- * }
+ * import { base58StringSchema } from '@core/adapter'
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: 'Approve', isRetryable: false,
- * //          reason: 'Continue pending approval' }
+ * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
+ * const validTxHash = '3Jf8k2L5mN9pQ7rS1tV4wX6yZ8aB2cD4eF5gH7iJ9kL1mN3oP5qR7sT9uV1wX3yZ5'
+ *
+ * const addressResult = base58StringSchema.safeParse(validAddress)
+ * const txHashResult = base58StringSchema.safeParse(validTxHash)
+ * console.log(addressResult.success) // true
+ * console.log(txHashResult.success) // true
  * ```
+ */
+const base58StringSchema = zod.z
+    .string()
+    .min(1, 'Base58 string is required')
+    .refine((value) => value.trim().length > 0, 'Base58 string cannot be empty')
+    .refine((value) => {
+    // Base58 alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
+    // Excludes: 0, O, I, l to avoid confusion
+    const base58Pattern = /^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/;
+    return base58Pattern.test(value);
+}, 'Base58 string contains invalid characters. Only base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z) are allowed');
+/**
+ * Schema for validating Solana addresses.
+ *
+ * This schema validates that a string is a properly formatted Solana address:
+ * - Must be a valid base58-encoded string
+ * - Must be between 32-44 characters long (typical length for base58-encoded 32-byte addresses)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * // Completed bridge (nothing to do)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'success' },
- *     { name: 'Burn', state: 'success' },
- *     { name: 'FetchAttestation', state: 'success' },
- *     { name: 'Mint', state: 'success' }
- *   ]
- * }
+ * import { solanaAddressSchema } from '@core/adapter'
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: null, isRetryable: false,
- * //          reason: 'Bridge completed successfully' }
- * ```
- */
-const analyzeSteps = (bridgeResult) => {
-    // Input validation
-    if (!bridgeResult || !Array.isArray(bridgeResult.steps)) {
-        throw new Error('Invalid bridgeResult: must contain a steps array');
-    }
-    const { steps } = bridgeResult;
-    // Build execution context from step history
-    const context = buildFlowContext(steps);
-    // Determine continuation logic using rule engine
-    const continuation = determineContinuationFromRules(context);
-    return {
-        continuationStep: continuation.nextStep,
-        isActionable: continuation.isActionable,
-        completedSteps: Array.from(context.completedSteps),
-        failedSteps: Array.from(context.failedSteps),
-        reason: continuation.reason,
-    };
-};
-/**
- * Build flow context from the execution history.
+ * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
  *
- * @param steps - Array of executed bridge steps.
- * @returns Flow context with execution state and history.
+ * const result = solanaAddressSchema.safeParse(validAddress)
+ * console.log(result.success) // true
+ * ```
  */
-function buildFlowContext(steps) {
-    const completedSteps = new Set();
-    const failedSteps = new Set();
-    let lastStep;
-    // Process step history to build context
-    for (const step of steps) {
-        if (step.state === 'success' || step.state === 'noop') {
-            completedSteps.add(step.name);
-        }
-        else if (step.state === 'error') {
-            failedSteps.add(step.name);
-        }
-        // Track the last step for continuation logic
-        lastStep = {
-            name: step.name,
-            state: step.state,
-        };
-    }
-    return {
-        completedSteps,
-        failedSteps,
-        ...(lastStep && { lastStep }),
-    };
-}
+base58StringSchema.refine((value) => value.length >= 32 && value.length <= 44, 'Solana address must be between 32-44 characters long (base58-encoded 32-byte address)');
 /**
- * Determine continuation step using the rule engine.
+ * Schema for validating Solana transaction hashes.
  *
- * @param context - The flow context with execution history.
- * @returns Continuation decision with next step and actionability information.
- */
-function determineContinuationFromRules(context) {
-    const lastStepName = context.lastStep?.name;
-    // Handle initial state when no steps have been executed
-    if (lastStepName === undefined) {
-        const rules = STEP_TRANSITION_RULES[''];
-        const matchingRule = rules?.find((rule) => rule.condition(context));
-        if (!matchingRule) {
-            return {
-                nextStep: null,
-                isActionable: false,
-                reason: 'No initial state rule found',
-            };
-        }
-        return {
-            nextStep: matchingRule.nextStep,
-            isActionable: matchingRule.isActionable,
-            reason: matchingRule.reason,
-        };
-    }
-    // A step with an empty name is ambiguous and should be treated as an unrecoverable state.
-    if (lastStepName === '') {
-        return {
-            nextStep: null,
-            isActionable: false,
-            reason: 'No transition rules defined for step with empty name',
-        };
-    }
-    const rules = STEP_TRANSITION_RULES[lastStepName];
-    if (!rules) {
-        return {
-            nextStep: null,
-            isActionable: false,
-            reason: `No transition rules defined for step: ${lastStepName}`,
-        };
-    }
-    // Find the first matching rule
-    const matchingRule = rules.find((rule) => rule.condition(context));
-    if (!matchingRule) {
-        return {
-            nextStep: null,
-            isActionable: false,
-            reason: `No matching transition rule for current context`,
-        };
-    }
-    return {
-        nextStep: matchingRule.nextStep,
-        isActionable: matchingRule.isActionable,
-        reason: matchingRule.reason,
-    };
-}
-
-/**
- * Find a step by name in the bridge result.
+ * This schema validates that a string is a properly formatted Solana transaction hash:
+ * - Must be a valid base58-encoded string
+ * - Must be between 86-88 characters long (typical length for base58-encoded 64-byte signatures)
  *
- * @param result - The bridge result to search.
- * @param stepName - The name of the step to find.
- * @returns The step if found, undefined otherwise.
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * import { findStepByName } from './findStep'
+ * import { solanaTransactionHashSchema } from '@core/adapter'
  *
- * const burnStep = findStepByName(result, 'burn')
- * if (burnStep) {
- *   console.log('Burn tx:', burnStep.txHash)
- * }
+ * const validTxHash = '5VfYmGBjvQKe3xgLtTQPSMEUdpEVHrJwLK7pKBJWKzYpNBE2g3kJrq7RSe9M8DqzQJ5J2aZPTjHLvd4WgxPpJKS'
+ *
+ * const result = solanaTransactionHashSchema.safeParse(validTxHash)
+ * console.log(result.success) // true
  * ```
  */
-function findStepByName(result, stepName) {
-    return result.steps.find((step) => step.name === stepName);
-}
+base58StringSchema.refine((value) => value.length >= 86 && value.length <= 88, 'Solana transaction hash must be between 86-88 characters long (base58-encoded 64-byte signature)');
 /**
- * Find a pending step by name and return it with its index.
+ * Schema for validating Adapter objects.
+ * Checks for the required methods that define an Adapter.
+ */
+zod.z.object({
+    prepare: zod.z.function(),
+    waitForTransaction: zod.z.function(),
+    getAddress: zod.z.function(),
+});
+
+/**
+ * Validate that the adapter has sufficient token balance for a transaction.
  *
- * Searches for a step that matches both the step name and has a pending state.
+ * This function checks if the adapter's current token balance is greater than or equal
+ * to the requested transaction amount. It throws a KitError with code 9001
+ * (BALANCE_INSUFFICIENT_TOKEN) if the balance is insufficient, providing detailed
+ * information about the shortfall.
  *
- * @param result - The bridge result containing steps to search through.
- * @param stepName - The step name to find (e.g., 'burn', 'mint', 'fetchAttestation').
- * @returns An object containing the step and its index in the steps array.
- * @throws KitError if the specified pending step is not found.
+ * @param params - The validation parameters containing adapter, amount, token, and token address.
+ * @returns A promise that resolves to void if validation passes.
+ * @throws {KitError} When the adapter's balance is less than the required amount (code: 9001).
  *
  * @example
  * ```typescript
- * import { findPendingStep } from './findStep'
+ * import { validateBalanceForTransaction } from '@core/adapter'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ * import { isKitError, ERROR_TYPES } from '@core/errors'
  *
- * const { step, index } = findPendingStep(result, 'burn')
- * console.log('Pending step:', step.name, 'at index:', index)
+ * const adapter = createViemAdapterFromPrivateKey({
+ *   privateKey: '0x...',
+ *   chain: 'Ethereum',
+ * })
+ *
+ * try {
+ *   await validateBalanceForTransaction({
+ *     adapter,
+ *     amount: '1000000', // 1 USDC (6 decimals)
+ *     token: 'USDC',
+ *     tokenAddress: '0xA0b86a33E6441c8C1c7C16e4c5e3e5b5e4c5e3e5b5e4c5e',
+ *     operationContext: { chain: 'Ethereum' },
+ *   })
+ *   console.log('Balance validation passed')
+ * } catch (error) {
+ *   if (isKitError(error) && error.type === ERROR_TYPES.BALANCE) {
+ *     console.error('Insufficient funds:', error.message)
+ *   }
+ * }
  * ```
  */
-function findPendingStep(result, stepName) {
-    const index = result.steps.findIndex((step) => step.name === stepName && step.state === 'pending');
-    if (index === -1) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: `Pending step "${stepName}" not found in result`,
-        });
-    }
-    const step = result.steps[index];
-    if (!step) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'Pending step is undefined',
+const validateBalanceForTransaction = async (params) => {
+    const { amount, adapter, token, tokenAddress, operationContext } = params;
+    const balancePrepared = await adapter.prepareAction('usdc.balanceOf', {
+        walletAddress: operationContext.address,
+    }, operationContext);
+    const balance = await balancePrepared.execute();
+    if (BigInt(balance) < BigInt(amount)) {
+        // Extract chain name from operationContext
+        const chainName = extractChainInfo(operationContext.chain).name;
+        // Create KitError with rich context in trace
+        throw createInsufficientTokenBalanceError(chainName, token, {
+            balance: balance.toString(),
+            amount,
+            tokenAddress,
+            walletAddress: operationContext.address,
         });
     }
-    return { step, index };
-}
+};
+
 /**
- * Get the burn transaction hash from bridge result.
+ * Validate that the adapter has sufficient native token balance for transaction fees.
  *
- * @param result - The bridge result.
- * @returns The burn transaction hash, or undefined if not found.
+ * This function checks if the adapter's current native token balance (ETH, SOL, etc.)
+ * is greater than zero. It throws a KitError with code 9002 (BALANCE_INSUFFICIENT_GAS)
+ * if the balance is zero, indicating the wallet cannot pay for transaction fees.
+ *
+ * @param params - The validation parameters containing adapter and operation context.
+ * @returns A promise that resolves to void if validation passes.
+ * @throws {KitError} When the adapter's native balance is zero (code: 9002).
  *
  * @example
  * ```typescript
- * import { getBurnTxHash } from './findStep'
+ * import { validateNativeBalanceForTransaction } from '@core/adapter'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ * import { isKitError, ERROR_TYPES } from '@core/errors'
  *
- * const burnTxHash = getBurnTxHash(result)
- * if (burnTxHash) {
- *   console.log('Burn tx hash:', burnTxHash)
+ * const adapter = createViemAdapterFromPrivateKey({
+ *   privateKey: '0x...',
+ *   chain: 'Ethereum',
+ * })
+ *
+ * try {
+ *   await validateNativeBalanceForTransaction({
+ *     adapter,
+ *     operationContext: { chain: 'Ethereum' },
+ *   })
+ *   console.log('Native balance validation passed')
+ * } catch (error) {
+ *   if (isKitError(error) && error.type === ERROR_TYPES.BALANCE) {
+ *     console.error('Insufficient gas funds:', error.message)
+ *   }
  * }
  * ```
  */
-function getBurnTxHash(result) {
-    return findStepByName(result, CCTPv2StepName.burn)?.txHash;
-}
+const validateNativeBalanceForTransaction = async (params) => {
+    const { adapter, operationContext } = params;
+    const balancePrepared = await adapter.prepareAction('native.balanceOf', {
+        walletAddress: operationContext.address,
+    }, operationContext);
+    const balance = await balancePrepared.execute();
+    if (BigInt(balance) === 0n) {
+        const { chain } = operationContext;
+        const chainName = extractChainInfo(chain).name;
+        const nativeSymbol = typeof chain === 'object' && chain !== null && 'nativeCurrency' in chain
+            ? chain.nativeCurrency.symbol
+            : undefined;
+        throw createInsufficientGasError(chainName, nativeSymbol, {
+            balance: '0',
+            walletAddress: operationContext.address,
+        });
+    }
+};
+
 /**
- * Get the attestation data from bridge result.
- *
- * @param result - The bridge result.
- * @returns The attestation data, or undefined if not found.
+ * Permit signature standards for gasless token approvals.
  *
- * @example
- * ```typescript
- * import { getAttestationData } from './findStep'
+ * Defines the permit types that can be used to approve token spending
+ * without requiring a separate approval transaction.
  *
- * const attestation = getAttestationData(result)
- * if (attestation) {
- *   console.log('Attestation:', attestation.message)
- * }
- * ```
+ * @remarks
+ * - NONE: No permit, tokens must be pre-approved via separate transaction
+ * - EIP2612: Standard ERC-20 permit (USDC, DAI v2, and most modern tokens)
  */
-function getAttestationData(result) {
-    // Prefer reAttest data (most recent attestation after expiry)
-    const reAttestStep = findStepByName(result, CCTPv2StepName.reAttest);
-    if (reAttestStep?.state === 'success' && reAttestStep.data) {
-        return reAttestStep.data;
-    }
-    // Fall back to fetchAttestation step
-    const fetchStep = findStepByName(result, CCTPv2StepName.fetchAttestation);
-    return fetchStep?.data;
-}
+var PermitType;
+(function (PermitType) {
+    /** No permit required - tokens must be pre-approved */
+    PermitType[PermitType["NONE"] = 0] = "NONE";
+    /** EIP-2612 standard permit */
+    PermitType[PermitType["EIP2612"] = 1] = "EIP2612";
+})(PermitType || (PermitType = {}));
 
 /**
  * Determine if a step executes on the source chain.
@@ -11730,169 +12561,6 @@ function getStepAdapterAndChain(step, context, result) {
     };
 }
 
-/**
- * Check if the analysis indicates a non-actionable pending state.
- *
- * A pending state is non-actionable when there's a continuation step but
- * the analysis marks it as not actionable, typically because we need to
- * wait for an ongoing operation to complete.
- *
- * @param analysis - The step analysis result from analyzeSteps.
- * @param result - The bridge result to check for pending steps.
- * @returns True if there is a pending step that we should wait for.
- *
- * @example
- * ```typescript
- * import { hasPendingState } from './stepUtils'
- * import { analyzeSteps } from '../analyzeSteps'
- *
- * const analysis = analyzeSteps(bridgeResult)
- * if (hasPendingState(analysis, bridgeResult)) {
- *   // Wait for the pending operation to complete
- * }
- * ```
- */
-function hasPendingState(analysis, result) {
-    // Check if there's a continuation step that's marked as non-actionable
-    if (analysis.continuationStep === null || analysis.isActionable) {
-        return false;
-    }
-    // Verify that the continuation step actually exists and is in pending state
-    const pendingStep = result.steps.find((step) => step.name === analysis.continuationStep && step.state === 'pending');
-    return pendingStep !== undefined;
-}
-/**
- * Check if the step is the last one in the execution flow.
- *
- * @param step - The step object to check.
- * @param stepNames - The ordered list of step names in the execution flow.
- * @returns True if this is the last step in the flow.
- *
- * @example
- * ```typescript
- * import { isLastStep } from './stepUtils'
- *
- * const stepNames = ['approve', 'burn', 'fetchAttestation', 'mint']
- * isLastStep({ name: 'mint' }, stepNames) // true
- * isLastStep({ name: 'burn' }, stepNames) // false
- * ```
- */
-function isLastStep(step, stepNames) {
-    const stepIndex = stepNames.indexOf(step.name);
-    return stepIndex === -1 || stepIndex >= stepNames.length - 1;
-}
-/**
- * Wait for a pending transaction to complete.
- *
- * Poll the adapter until the transaction is confirmed on-chain and return
- * the updated step with success or error state based on the receipt.
- *
- * @param pendingStep - The full step object containing the transaction hash.
- * @param adapter - The adapter to use for waiting.
- * @param chain - The chain where the transaction was submitted.
- * @returns The updated step object with success or error state.
- *
- * @throws KitError when the pending step has no transaction hash.
- *
- * @example
- * ```typescript
- * import { waitForPendingTransaction } from './bridgeStepUtils'
- *
- * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
- * const updatedStep = await waitForPendingTransaction(pendingStep, adapter, chain)
- * // updatedStep.state is now 'success' or 'error'
- * ```
- */
-async function waitForPendingTransaction(pendingStep, adapter, chain) {
-    if (!pendingStep.txHash) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: `Cannot wait for pending ${pendingStep.name}: no transaction hash available`,
-        });
-    }
-    const txHash = pendingStep.txHash;
-    const txReceipt = await retryAsync(async () => adapter.waitForTransaction(txHash, undefined, chain), {
-        isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, { chain: chain.name, txHash })),
-    });
-    // Check if transaction was confirmed on-chain
-    if (!txReceipt.blockNumber) {
-        return {
-            ...pendingStep,
-            state: 'error',
-            errorMessage: txReceipt.status === 'reverted'
-                ? `Transaction ${pendingStep.txHash} was reverted`
-                : 'Transaction was not confirmed on-chain',
-            data: txReceipt,
-        };
-    }
-    return {
-        ...pendingStep,
-        state: 'success',
-        data: txReceipt,
-    };
-}
-/**
- * Wait for a pending step to complete.
- *
- * For transaction steps: waits for the transaction to be confirmed.
- * For attestation: re-executes the attestation fetch.
- *
- * @typeParam TFromAdapterCapabilities - The capabilities of the source adapter.
- * @typeParam TToAdapterCapabilities - The capabilities of the destination adapter.
- * @param pendingStep - The full step object (with name, state, txHash, data, etc.) to resolve.
- * @param adapter - The adapter to use.
- * @param chain - The chain where the step is executing.
- * @param context - The retry context.
- * @param result - The bridge result.
- * @param provider - The CCTP v2 bridging provider.
- * @returns The resolved step object with updated state.
- *
- * @throws KitError when fetching attestation but burn transaction hash is not found.
- *
- * @example
- * ```typescript
- * import { waitForStepToComplete } from './bridgeStepUtils'
- *
- * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
- * const updatedStep = await waitForStepToComplete(
- *   pendingStep,
- *   adapter,
- *   chain,
- *   context,
- *   result,
- *   provider,
- * )
- * // updatedStep.state is now 'success' or 'error'
- * ```
- */
-async function waitForStepToComplete(pendingStep, adapter, chain, context, result, provider) {
-    if (pendingStep.name === CCTPv2StepName.fetchAttestation) {
-        // For attestation, re-run the fetch (it has built-in polling)
-        const burnTxHash = getBurnTxHash(result);
-        if (!burnTxHash) {
-            throw new KitError({
-                ...InputError.VALIDATION_FAILED,
-                recoverability: 'FATAL',
-                message: 'Cannot fetch attestation: burn transaction hash not found',
-            });
-        }
-        const sourceAddress = result.source.address;
-        const attestation = await provider.fetchAttestation({
-            chain: result.source.chain,
-            adapter: context.from,
-            address: sourceAddress,
-        }, burnTxHash);
-        return {
-            ...pendingStep,
-            state: 'success',
-            data: attestation,
-        };
-    }
-    // For transaction steps, wait for the transaction to complete
-    return waitForPendingTransaction(pendingStep, adapter, chain);
-}
-
 /**
  * Executes a re-attestation operation to obtain a fresh attestation for an expired message.
  *