@circle-fin/bridge-kit 1.5.0 → 1.6.0

package/index.mjs

@@ -21,6 +21,7 @@ import '@ethersproject/bytes';
 import '@ethersproject/address';
 import 'bs58';
 import { formatUnits as formatUnits$1, parseUnits as parseUnits$1 } from '@ethersproject/units';
+import pino from 'pino';
 import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2';
 
 /**
@@ -653,6 +654,18 @@ const NetworkError = {
         name: 'NETWORK_TIMEOUT',
         type: 'NETWORK',
     },
+    /** Circle relayer failed to process the forwarding/mint transaction */
+    RELAYER_FORWARD_FAILED: {
+        code: 3003,
+        name: 'NETWORK_RELAYER_FORWARD_FAILED',
+        type: 'NETWORK',
+    },
+    /** Relayer mint is pending - waiting for confirmation */
+    RELAYER_PENDING: {
+        code: 3004,
+        name: 'NETWORK_RELAYER_PENDING',
+        type: 'NETWORK',
+    },
 };
 
 /**
@@ -1213,6 +1226,10 @@ const Aptos = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -1246,6 +1263,10 @@ const AptosTestnet = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -1305,6 +1326,10 @@ const ArcTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1349,6 +1374,10 @@ const Arbitrum = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1393,6 +1422,10 @@ const ArbitrumSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1437,6 +1470,10 @@ const Avalanche = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1480,6 +1517,10 @@ const AvalancheFuji = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     rpcEndpoints: ['https://api.avax-test.network/ext/bc/C/rpc'],
     kitContracts: {
@@ -1525,6 +1566,10 @@ const Base = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1569,6 +1614,10 @@ const BaseSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1655,6 +1704,10 @@ const Codex = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1693,6 +1746,10 @@ const CodexTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1737,6 +1794,10 @@ const Ethereum = defineChain({
                 fastConfirmations: 2,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1781,6 +1842,10 @@ const EthereumSepolia = defineChain({
                 fastConfirmations: 2,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1867,6 +1932,10 @@ const HyperEVM = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1906,6 +1975,10 @@ const HyperEVMTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1949,6 +2022,10 @@ const Ink = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1991,6 +2068,10 @@ const InkTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2029,6 +2110,10 @@ const Linea = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2067,6 +2152,10 @@ const LineaSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2107,6 +2196,10 @@ const Monad = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2147,6 +2240,10 @@ const MonadTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2228,6 +2325,10 @@ const Noble = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -2260,6 +2361,10 @@ const NobleTestnet = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -2301,6 +2406,10 @@ const Optimism = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2345,6 +2454,10 @@ const OptimismSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2385,6 +2498,10 @@ const Plume = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2424,6 +2541,10 @@ const PlumeTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2514,6 +2635,10 @@ const Polygon = defineChain({
                 fastConfirmations: 13,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2558,6 +2683,10 @@ const PolygonAmoy = defineChain({
                 fastConfirmations: 13,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2598,6 +2727,10 @@ const Sei = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2637,6 +2770,10 @@ const SeiTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2675,6 +2812,10 @@ const Sonic = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2713,6 +2854,10 @@ const SonicTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2756,6 +2901,10 @@ const Solana = defineChain({
                 fastConfirmations: 3,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
@@ -2798,6 +2947,10 @@ const SolanaDevnet = defineChain({
                 fastConfirmations: 3,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
@@ -2881,6 +3034,10 @@ const Sui = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -2914,6 +3071,10 @@ const SuiTestnet = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -2935,7 +3096,7 @@ const Unichain = defineChain({
     chainId: 130,
     isTestnet: false,
     explorerUrl: 'https://unichain.blockscout.com/tx/{hash}',
-    rpcEndpoints: ['https://rpc.unichain.org', 'https://mainnet.unichain.org'],
+    rpcEndpoints: ['https://mainnet.unichain.org'],
     eurcAddress: null,
     usdcAddress: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
     cctp: {
@@ -2955,6 +3116,10 @@ const Unichain = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2999,6 +3164,10 @@ const UnichainSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -3025,7 +3194,7 @@ const WorldChain = defineChain({
     explorerUrl: 'https://worldscan.org/tx/{hash}',
     rpcEndpoints: ['https://worldchain-mainnet.g.alchemy.com/public'],
     eurcAddress: null,
-    usdcAddress: '0x79A02482A880bCe3F13E09da970dC34dB4cD24D1',
+    usdcAddress: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
     cctp: {
         domain: 14,
         contracts: {
@@ -3037,6 +3206,10 @@ const WorldChain = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -3078,6 +3251,10 @@ const WorldChainSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -3104,7 +3281,7 @@ const XDC = defineChain({
     chainId: 50,
     isTestnet: false,
     explorerUrl: 'https://xdcscan.io/tx/{hash}',
-    rpcEndpoints: ['https://erpc.xinfin.network'],
+    rpcEndpoints: ['https://erpc.xdcrpc.com', 'https://erpc.xinfin.network'],
     eurcAddress: null,
     usdcAddress: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
     cctp: {
@@ -3118,6 +3295,10 @@ const XDC = defineChain({
                 fastConfirmations: 3,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -3156,6 +3337,10 @@ const XDCApothem = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -3392,7 +3577,7 @@ const nonEvmChainDefinitionSchema = baseChainDefinitionSchema
  * })
  * ```
  */
-const chainDefinitionSchema$1 = z.discriminatedUnion('type', [
+const chainDefinitionSchema$2 = z.discriminatedUnion('type', [
     evmChainDefinitionSchema,
     nonEvmChainDefinitionSchema,
 ]);
@@ -3417,7 +3602,7 @@ z.union([
         .string()
         .refine((val) => val in Blockchain, 'Must be a valid Blockchain enum value as string'),
     z.nativeEnum(Blockchain),
-    chainDefinitionSchema$1,
+    chainDefinitionSchema$2,
 ]);
 /**
  * Zod schema for validating bridge chain identifiers.
@@ -3453,7 +3638,7 @@ const bridgeChainIdentifierSchema = z.union([
     z.string().refine((val) => val in BridgeChain, (val) => ({
         message: `Chain "${val}" is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
     })),
-    chainDefinitionSchema$1.refine((chainDef) => chainDef.chain in BridgeChain, (chainDef) => ({
+    chainDefinitionSchema$2.refine((chainDef) => chainDef.chain in BridgeChain, (chainDef) => ({
         message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
     })),
 ]);
@@ -3940,6 +4125,62 @@ function getErrorMessage(error) {
 function getErrorCode(error) {
     return isKitError(error) ? error.code : null;
 }
+/**
+ * Extract structured error information for logging and events.
+ *
+ * @remarks
+ * Safely extracts error information from any thrown value, handling:
+ * - KitError objects (message preserved - safe to log)
+ * - Standard Error objects (message redacted for security)
+ * - Plain objects with name/message/code (message redacted)
+ * - Primitive values (logged as-is since they contain no structured data)
+ *
+ * For security, only KitError messages are included. Other error messages are
+ * redacted to prevent logging sensitive data like tokens or PII.
+ *
+ * @param error - The error to extract info from.
+ * @returns Structured error information.
+ *
+ * @example
+ * ```typescript
+ * import { extractErrorInfo } from '@core/errors'
+ *
+ * // Standard Error - message is redacted for security
+ * const info1 = extractErrorInfo(new Error('Something went wrong'))
+ * // { name: 'Error', message: 'An error occurred. See error name and code for details.' }
+ *
+ * // KitError - message is preserved (safe type)
+ * const error = createNetworkConnectionError('Ethereum')
+ * const info2 = extractErrorInfo(error)
+ * // { name: 'NETWORK_CONNECTION_FAILED', message: 'Network connection failed for Ethereum', code: 3001 }
+ *
+ * // Primitive value - logged as-is
+ * const info3 = extractErrorInfo('string error')
+ * // { name: 'UnknownError', message: 'string error' }
+ * ```
+ */
+function extractErrorInfo(error) {
+    if (error === null || typeof error !== 'object') {
+        return {
+            name: 'UnknownError',
+            message: String(error),
+        };
+    }
+    const err = error;
+    // Only preserve messages for KitError instances (safe type)
+    // For other errors, redact message for security
+    const errorMessage = isKitError(error)
+        ? getErrorMessage(error)
+        : 'An error occurred. See error name and code for details.';
+    const info = {
+        name: err.name ?? 'UnknownError',
+        message: errorMessage,
+    };
+    if (typeof err.code === 'number') {
+        info.code = err.code;
+    }
+    return info;
+}
 
 /**
  * Validates if an address format is correct for the specified chain.
@@ -4484,7 +4725,7 @@ function validateWithStateTracking(value, schema, context, validatorName) {
  * Zod schema for validating chain definition objects used in buildExplorerUrl.
  * This schema ensures the chain definition has the required properties for URL generation.
  */
-const chainDefinitionSchema = z.object({
+const chainDefinitionSchema$1 = z.object({
     name: z
         .string({
         required_error: 'Chain name is required',
@@ -4508,15 +4749,14 @@ const transactionHashSchema = z
     required_error: 'Transaction hash is required',
     invalid_type_error: 'Transaction hash must be a string',
 })
-    .min(1, 'Transaction hash cannot be empty')
-    .transform((hash) => hash.trim()) // Automatically trim whitespace
-    .refine((hash) => hash.length > 0, 'Transaction hash must not be empty or whitespace-only');
+    .transform((hash) => hash.trim())
+    .refine((hash) => hash.length > 0, 'Transaction hash cannot be empty');
 /**
  * Zod schema for validating buildExplorerUrl function parameters.
  * This schema validates both the chain definition and transaction hash together.
  */
 z.object({
-    chainDef: chainDefinitionSchema,
+    chainDef: chainDefinitionSchema$1,
     txHash: transactionHashSchema,
 });
 /**
@@ -4527,6 +4767,69 @@ z
     .string()
     .url('Generated explorer URL is invalid');
 
+/**
+ * Parses and validates data against a Zod schema, returning the transformed result.
+ *
+ * Unlike `validate` and `validateOrThrow` which use type assertions (`asserts value is T`),
+ * this function **returns the parsed data** from Zod. This is important when your schema
+ * includes transformations like defaults, coercion, or custom transforms.
+ *
+ * @typeParam T - The expected output type (caller must specify).
+ * @param value - The value to parse and validate.
+ * @param schema - The Zod schema to validate against.
+ * @param context - Context string to include in error messages (e.g., 'user input', 'config').
+ * @returns The parsed and transformed data of type T.
+ * @throws KitError with INPUT_VALIDATION_FAILED code (1098) if validation fails.
+ *
+ * @remarks
+ * This function uses `ZodTypeAny` for the schema parameter to avoid TypeScript's
+ * "excessively deep type instantiation" error in generic contexts. The caller
+ * must provide the expected type `T` explicitly.
+ *
+ * Use this instead of `validate`/`validateOrThrow` when:
+ * - Your schema has `.default()` values
+ * - Your schema uses `.coerce` (e.g., `z.coerce.number()`)
+ * - Your schema has `.transform()` functions
+ * - You need the actual parsed output, not just type narrowing
+ *
+ * @example
+ * ```typescript
+ * import { parseOrThrow } from '@core/utils'
+ * import { z } from 'zod'
+ *
+ * const userSchema = z.object({
+ *   name: z.string().default('Anonymous'),
+ *   age: z.coerce.number(),  // Transforms "25" → 25
+ * })
+ *
+ * type User = z.infer<typeof userSchema>
+ *
+ * // Explicit type parameter
+ * const user = parseOrThrow<User>({ age: '25' }, userSchema, 'user data')
+ * console.log(user)  // { name: 'Anonymous', age: 25 }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage in generic adapter functions (no deep type instantiation)
+ * function validateInput<TInput>(
+ *   input: unknown,
+ *   schema: z.ZodTypeAny,
+ *   name: string,
+ * ): TInput {
+ *   return parseOrThrow<TInput>(input, schema, `${name} input`)
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- Intentional: T is caller-provided to avoid deep type instantiation from schema inference
+function parseOrThrow(value, schema, context) {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        throw createValidationErrorFromZod(result.error, context);
+    }
+    return result.data;
+}
+
 /**
  * A type-safe event emitter for managing action-based event subscriptions.
  *
@@ -4801,7 +5104,7 @@ const parseAmount = (params) => {
 };
 
 var name = "@circle-fin/bridge-kit";
-var version = "1.5.0";
+var version = "1.6.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -5227,7 +5530,7 @@ const createDecimalStringValidator = (options) => (schema) => {
  * console.log(result.success) // true
  * ```
  */
-z.object({
+const chainDefinitionSchema = z.object({
     name: z.string().min(1, 'Chain name is required'),
     type: z.string().min(1, 'Chain type is required'),
 });
@@ -5274,6 +5577,53 @@ const walletContextSchema = z.object({
         isTestnet: z.boolean(),
     }),
 });
+/**
+ * Schema for validating destination wallet contexts.
+ * Extends walletContextSchema with optional useForwarder flag.
+ *
+ * @throws KitError if validation fails
+ */
+const destinationContextSchema = walletContextSchema.extend({
+    useForwarder: z.boolean().optional(),
+    recipientAddress: z.string().optional(),
+});
+/**
+ * Schema for validating forwarder-only destination contexts.
+ * Used when useForwarder is true and no adapter is provided.
+ * Requires chain definition and recipientAddress.
+ *
+ * Validates that recipientAddress format is correct for the destination chain
+ * (EVM hex address or Solana base58 address).
+ *
+ * @throws KitError if validation fails
+ */
+const forwarderOnlyDestinationSchema = z
+    .object({
+    chain: chainDefinitionSchema.extend({
+        isTestnet: z.boolean(),
+    }),
+    recipientAddress: z
+        .string()
+        .min(1, 'Recipient address is required for forwarder-only destination'),
+    useForwarder: z.literal(true),
+})
+    .superRefine((data, ctx) => {
+    // Pass chain name as string - isValidAddressForChain will use name-based matching
+    if (!isValidAddressForChain(data.recipientAddress, data.chain.name)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Invalid recipient address format for chain ${data.chain.name}`,
+            path: ['recipientAddress'],
+        });
+    }
+});
+/**
+ * Schema for validating any destination - either with adapter or forwarder-only.
+ */
+const bridgeDestinationSchema$1 = z.union([
+    destinationContextSchema,
+    forwarderOnlyDestinationSchema,
+]);
 /**
  * Schema for validating a custom fee configuration.
  * Validates the simplified CustomFee interface which includes:
@@ -5371,7 +5721,7 @@ z.object({
         maxDecimals: 6,
     })(z.string())),
     source: walletContextSchema,
-    destination: walletContextSchema,
+    destination: bridgeDestinationSchema$1,
     token: z.literal('USDC'),
     config: z.object({
         transferSpeed: z.nativeEnum(TransferSpeed).optional(),
@@ -5388,6 +5738,28 @@ z.object({
     }),
 });
 
+/**
+ * Creates a Zod superRefine validator for recipient address format validation.
+ * Validates that the address format matches the expected format for the chain type.
+ *
+ * @returns A superRefine function that validates recipientAddress against chain type
+ */
+function createRecipientAddressValidator() {
+    return (data, ctx) => {
+        const chain = data.chain;
+        if (chain === null) {
+            return;
+        }
+        if (!isValidAddressForChain(data.recipientAddress, chain)) {
+            const chainInfo = extractChainInfo(chain);
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['recipientAddress'],
+                message: `Invalid address format for ${String(chainInfo.name)}. Expected ${chainInfo.expectedAddressFormat}, but received: ${data.recipientAddress}`,
+            });
+        }
+    };
+}
 /**
  * Schema for validating AdapterContext for bridge operations.
  * Must always contain both adapter and chain explicitly.
@@ -5407,32 +5779,52 @@ const adapterContextSchema = z.object({
 const bridgeDestinationWithAddressSchema = adapterContextSchema
     .extend({
     recipientAddress: z.string().min(1, 'Recipient address is required'),
+    useForwarder: z.boolean().optional(),
 })
-    .superRefine((data, ctx) => {
-    const chain = data.chain;
-    if (chain === null) {
-        return;
-    }
-    if (!isValidAddressForChain(data.recipientAddress, chain)) {
-        const chainInfo = extractChainInfo(chain);
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ['recipientAddress'],
-            message: `Invalid address format for ${String(chainInfo.name)}. Expected ${chainInfo.expectedAddressFormat}, but received: ${data.recipientAddress}`,
-        });
-    }
+    .superRefine(createRecipientAddressValidator());
+/**
+ * Schema for validating AdapterContext with optional useForwarder.
+ * Extends adapterContextSchema with the useForwarder flag.
+ */
+const adapterContextWithForwarderSchema = adapterContextSchema.extend({
+    useForwarder: z.boolean().optional(),
 });
+/**
+ * Schema for validating ForwarderDestination objects.
+ * Used when useForwarder is true and no adapter is provided.
+ * Requires chain, recipientAddress, and useForwarder: true.
+ *
+ * When using this destination type:
+ * - The mint step completes when the IRIS API confirms forwardState === 'CONFIRMED'
+ * - No on-chain transaction confirmation is performed (no adapter available)
+ * - The mint step's data field will be undefined (no transaction receipt)
+ */
+const forwarderDestinationSchema = z
+    .object({
+    chain: bridgeChainIdentifierSchema,
+    recipientAddress: z.string().min(1, 'Recipient address is required'),
+    useForwarder: z.literal(true),
+})
+    .strict()
+    .superRefine(createRecipientAddressValidator());
 /**
  * Schema for validating BridgeDestination union type.
- * Can be an AdapterContext or BridgeDestinationWithAddress.
+ * Supports three destination configurations:
+ * - BridgeDestinationWithAddress (adapter with explicit recipient)
+ * - ForwarderDestination (no adapter, requires useForwarder: true and recipientAddress)
+ * - AdapterContext with optional useForwarder (adapter for default recipient)
+ *
+ * When using ForwarderDestination (no adapter):
+ * - The mint step completes when the IRIS API confirms forwardState === 'CONFIRMED'
+ * - No on-chain transaction confirmation is performed
  *
- * The order matters: we check the more specific schema (with recipientAddress) first.
- * This ensures that objects with an empty recipientAddress field are rejected rather
- * than silently treated as AdapterContext with the field ignored.
+ * The order matters: we check the more specific schemas first.
+ * This ensures that objects with specific fields are matched correctly.
  */
 const bridgeDestinationSchema = z.union([
     bridgeDestinationWithAddressSchema,
-    adapterContextSchema.strict(),
+    forwarderDestinationSchema,
+    adapterContextWithForwarderSchema.strict(),
 ]);
 /**
  * Schema for validating bridge parameters with chain identifiers.
@@ -5506,121 +5898,1413 @@ const bridgeParamsWithChainIdentifierSchema = z.object({
 });
 
 /**
- * Resolves a chain identifier to a chain definition.
- *
- * Both AdapterContext and BridgeDestinationWithAddress have the chain property
- * at the top level, so we can directly access it from either type.
+ * Default clock implementation using `Date.now()`.
  *
- * @param ctx - The bridge destination containing the chain identifier
- * @returns The resolved chain definition
- * @throws If the chain definition cannot be resolved
+ * @remarks
+ * Use this in production code. For testing, inject a mock clock
+ * that returns controlled timestamps.
  *
  * @example
  * ```typescript
- * import { Blockchain } from '@core/chains'
- *
- * // AdapterContext
- * const chain1 = resolveChainDefinition({
- *   adapter: mockAdapter,
- *   chain: 'Ethereum'
- * })
+ * import { defaultClock } from '@core/runtime'
  *
- * // BridgeDestinationWithAddress
- * const chain2 = resolveChainDefinition({
- *   adapter: mockAdapter,
- *   chain: 'Base',
- *   recipientAddress: '0x123...'
- * })
+ * const start = defaultClock.now()
+ * // ... do work ...
+ * const elapsed = defaultClock.since(start)
  * ```
  */
-function resolveChainDefinition(ctx) {
-    return resolveChainIdentifier(ctx.chain);
-}
+const defaultClock = {
+    now: () => Date.now(),
+    since: (start) => Date.now() - start,
+};
+
 /**
- * Resolves the signer's address from a bridge destination.
+ * ID generation utilities for distributed tracing.
  *
- * This function resolves the address that will be used for transaction signing,
- * ignoring any `recipientAddress` field which is handled separately.
+ * @remarks
+ * | Function | Format | Use Case |
+ * |----------|--------|----------|
+ * | {@link createTraceId} | 32-char hex | Standard traceId (OpenTelemetry) |
+ * | {@link createShortOpId} | 8-char hex | Standard opId |
+ * | {@link createOpId} | `op-{ts}-{rand}` | Timestamped operation IDs |
+ * | {@link createUuidV4} | RFC 4122 UUID | External system compatibility |
+ * | {@link createId} | `{prefix}-{ts}-{rand}` | Custom prefixed IDs |
  *
- * It handles two cases:
- * - Developer-controlled adapters - returns the explicit address from context
- * - User-controlled adapters - calls getAddress() on the adapter
+ * @packageDocumentation
+ */
+// ============================================================================
+// Crypto Utilities (Internal)
+// ============================================================================
+/** @internal */
+function hasGetRandomValues() {
+    return (typeof crypto !== 'undefined' &&
+        typeof crypto.getRandomValues === 'function');
+}
+/**
+ * Create a W3C/OpenTelemetry-compatible trace ID.
  *
- * @param ctx - The bridge destination to resolve the address from
- * @returns The resolved signer address string
+ * @returns 32-character lowercase hex string (128-bit).
+ *
+ * @remarks
+ * **Standard function for generating `traceId` values.** Compatible with
+ * OpenTelemetry, Jaeger, Zipkin, and AWS X-Ray.
  *
  * @example
  * ```typescript
- * // Developer-controlled adapter
- * const addr1 = await resolveAddress({
- *   adapter: devAdapter,
- *   chain: 'Ethereum',
- *   address: '0x1234567890123456789012345678901234567890'
- * }) // Returns: '0x1234567890123456789012345678901234567890'
- *
- * // User-controlled adapter
- * const addr2 = await resolveAddress({
- *   adapter: userAdapter,
- *   chain: 'Ethereum'
- * }) // Returns adapter's connected address
+ * const traceId = createTraceId() // "a1b2c3d4e5f6789012345678abcdef00"
  * ```
  */
-async function resolveAddress(ctx) {
-    // Handle based on adapter's addressContext
-    if (ctx.adapter.capabilities?.addressContext === 'developer-controlled') {
-        // Developer-controlled: address must be provided explicitly
-        if ('address' in ctx && ctx.address) {
-            return ctx.address;
-        }
-        throw new Error('Address is required in context for developer-controlled adapters. ' +
-            'Please provide: { adapter, chain, address: "0x..." }');
+function createTraceId() {
+    const bytes = new Uint8Array(16);
+    if (hasGetRandomValues()) {
+        crypto.getRandomValues(bytes);
     }
     else {
-        // User-controlled: address should not be provided (auto-resolved from adapter)
-        if ('address' in ctx && ctx.address) {
-            throw new Error('Address should not be provided for user-controlled adapters. ' +
-                'The address is automatically resolved from the connected wallet.');
+        for (let i = 0; i < 16; i++) {
+            bytes[i] = Math.floor(Math.random() * 256); // NOSONAR:
         }
-        // Derive address from adapter
-        const chain = resolveChainDefinition(ctx);
-        return await ctx.adapter.getAddress(chain);
     }
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
 }
+
 /**
- * Resolves the amount of a transfer by formatting it according to the token's decimal places.
+ * Clean tags by removing keys with undefined values.
  *
- * This function takes the raw amount from the transfer parameters and formats it
- * using the appropriate decimal places for the specified token. Currently supports
- * USDC (6 decimals) and falls back to the raw amount for other tokens.
+ * @param tags - Tags object, may contain undefined values. Accepts `undefined` or `null`.
+ * @returns A new object with undefined values removed, or empty object if input is nullish.
  *
- * @param params - The bridge parameters containing the amount, token type, and from context
- * @returns The formatted amount string with proper decimal places
+ * @remarks
+ * This helper ensures tags are safe for serialization and logging.
+ * Similar to the internal `cleanUndefined` in the logger module, but
+ * typed specifically for {@link Tags}.
  *
  * @example
  * ```typescript
- * import { Adapter } from '@core/adapter'
+ * import { cleanTags } from '@core/runtime'
  *
- * const params = {
- *   amount: '1000000',
- *   token: 'USDC',
- *   from: { adapter: mockAdapter, chain: Ethereum },
- *   to: { adapter: mockAdapter, chain: Base }
- * }
- * const formattedAmount = resolveAmount(params) // Returns '1000000000000'
+ * const tags = { chain: 'Ethereum', amount: 100, extra: undefined }
+ * const cleaned = cleanTags(tags)
+ * // { chain: 'Ethereum', amount: 100 }
+ *
+ * const empty = cleanTags(undefined)
+ * // {}
  * ```
  */
-function resolveAmount(params) {
-    if (params.token === 'USDC') {
-        return parseUnits(params.amount, 6).toString();
+function cleanTags(tags) {
+    if (tags == null)
+        return {};
+    return Object.fromEntries(Object.entries(tags).filter(([, value]) => value !== undefined));
+}
+
+/**
+ * Check if a pattern is valid.
+ *
+ * @remarks
+ * Invalid patterns:
+ * - Empty segments (e.g., `a..b`, `.a`, `a.`)
+ * - `**` not at end (e.g., `a.**.b`)
+ *
+ * @param pattern - The pattern to validate.
+ * @returns True if valid, false otherwise.
+ */
+function isValidPattern(pattern) {
+    // Empty pattern is valid (matches empty topic)
+    if (pattern === '')
+        return true;
+    const segments = pattern.split('.');
+    // Check for empty segments
+    if (segments.includes(''))
+        return false;
+    // Check that ** only appears at the end
+    const doubleStarIndex = segments.indexOf('**');
+    if (doubleStarIndex !== -1 && doubleStarIndex !== segments.length - 1) {
+        return false;
     }
-    return params.amount;
+    return true;
 }
 /**
- * Resolves and normalizes bridge configuration for the provider.
+ * Convert a pattern to a regular expression.
+ *
+ * @param pattern - The pattern to convert.
+ * @returns A RegExp that matches topics according to the pattern.
+ */
+function patternToRegex(pattern) {
+    const segments = pattern.split('.');
+    // Handle ** at end specially to match zero or more segments
+    const lastSegment = segments.at(-1);
+    if (lastSegment === '**') {
+        // Everything before ** must match, then optionally more segments
+        const prefix = segments
+            .slice(0, -1)
+            .map((seg) => {
+            if (seg === '*')
+                return '[^.]+';
+            return seg.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
+        })
+            .join(String.raw `\.`);
+        // ** matches zero or more segments:
+        // - If prefix is empty (**), match anything
+        // - Otherwise, match prefix, then optionally (dot + more content)
+        if (prefix === '') {
+            return /^.*$/;
+        }
+        return new RegExp(String.raw `^${prefix}(?:\..*)?$`);
+    }
+    // No ** - just convert segments normally
+    const escaped = segments
+        .map((segment) => {
+        if (segment === '*')
+            return '[^.]+';
+        return segment.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
+    })
+        .join(String.raw `\.`);
+    return new RegExp(String.raw `^${escaped}$`);
+}
+/**
+ * Execute an event handler with error isolation.
  *
- * This function takes the optional configuration from bridge parameters and returns
- * a normalized BridgeConfig with:
- * - Default transfer speed set to FAST if not provided
+ * @param handler - The handler function to execute.
+ * @param event - The event to pass to the handler.
+ * @param logger - Optional logger for error reporting.
+ *
+ * @remarks
+ * - Synchronous errors are caught and logged
+ * - Promise rejections are caught without awaiting
+ * - Handler errors never propagate to caller
+ */
+function executeHandler(handler, event, logger) {
+    try {
+        const result = handler(event);
+        // Handle promise rejection without awaiting
+        if (result instanceof Promise) {
+            result.catch((err) => {
+                logger?.error('Event handler promise rejected', {
+                    event: event.name,
+                    error: extractErrorInfo(err),
+                });
+            });
+        }
+    }
+    catch (err) {
+        // Isolate handler errors
+        logger?.error('Event handler threw', {
+            event: event.name,
+            error: extractErrorInfo(err),
+        });
+    }
+}
+/**
+ * Create an event bus.
+ *
+ * @param opts - Options for the event bus.
+ * @returns An EventBus instance.
+ *
+ * @example
+ * ```typescript
+ * import { createEventBus } from '@core/runtime'
+ *
+ * const bus = createEventBus({ logger })
+ *
+ * // Subscribe to events
+ * const unsubscribe = bus.on('tx.*', (event) => {
+ *   console.log('Transaction event:', event.name)
+ * })
+ *
+ * // Emit events
+ * bus.emit({ name: 'tx.sent', data: { txHash: '0x123' } })
+ *
+ * // Unsubscribe
+ * unsubscribe()
+ * ```
+ */
+function createEventBus(opts) {
+    const logger = opts?.logger;
+    const subscriptions = new Set();
+    function createBus(baseTags) {
+        return {
+            emit(event) {
+                // Invalid topic names silently don't match any subscriptions
+                if (!isValidPattern(event.name))
+                    return;
+                const mergedTags = Object.keys(baseTags).length > 0 || event.tags
+                    ? { ...baseTags, ...cleanTags(event.tags) }
+                    : undefined;
+                const finalEvent = mergedTags === undefined ? event : { ...event, tags: mergedTags };
+                // Notify all matching subscribers
+                for (const sub of subscriptions) {
+                    // Match-all subscription
+                    if (sub.pattern === null) {
+                        executeHandler(sub.handler, finalEvent, logger);
+                        continue;
+                    }
+                    // Patterned subscription: invalid pattern => regex=null => never match
+                    if (sub.regex === null)
+                        continue;
+                    if (!sub.regex.test(event.name))
+                        continue;
+                    executeHandler(sub.handler, finalEvent, logger);
+                }
+            },
+            child(tags) {
+                // Merge and clean tags, don't mutate parent
+                const childTags = { ...baseTags, ...cleanTags(tags) };
+                return createBus(childTags);
+            },
+            on(patternOrHandler, handler) {
+                let sub;
+                if (typeof patternOrHandler === 'function') {
+                    // on(handler) - subscribe to all
+                    sub = { pattern: null, handler: patternOrHandler, regex: null };
+                }
+                else {
+                    // on(pattern, handler)
+                    if (typeof handler !== 'function') {
+                        throw new TypeError(`EventBus.on("${patternOrHandler}") expected a function handler`);
+                    }
+                    const regex = isValidPattern(patternOrHandler)
+                        ? patternToRegex(patternOrHandler)
+                        : null;
+                    sub = {
+                        pattern: patternOrHandler,
+                        handler,
+                        regex,
+                    };
+                }
+                subscriptions.add(sub);
+                // Return unsubscribe function (idempotent)
+                let unsubscribed = false;
+                return () => {
+                    if (!unsubscribed) {
+                        subscriptions.delete(sub);
+                        unsubscribed = true;
+                    }
+                };
+            },
+        };
+    }
+    return createBus({});
+}
+
+/** No-op counter that discards all increments. */
+const noopCounter = {
+    inc: () => {
+        // Intentionally empty - discards increment
+    },
+};
+/** No-op histogram that discards all observations. */
+const noopHistogram = {
+    observe: () => {
+        // Intentionally empty - discards observation
+    },
+};
+/** No-op timer that returns an empty stop function. */
+const noopTimer = {
+    start: () => () => {
+        // Intentionally empty - discards timing
+    },
+};
+/**
+ * Create a no-op metrics instance.
+ *
+ * @returns A Metrics instance that discards all operations.
+ */
+function createNoopMetrics() {
+    // Self-referential instance - child() returns same object to avoid allocations
+    const instance = {
+        counter: () => noopCounter,
+        histogram: () => noopHistogram,
+        timer: () => noopTimer,
+        child: () => instance,
+    };
+    return instance;
+}
+/**
+ * A no-op metrics implementation that discards all operations.
+ *
+ * @remarks
+ * Use this when metrics collection is disabled or not configured.
+ * All metric operations are safe to call and return immediately.
+ * The `child()` method returns the same instance to avoid allocations.
+ *
+ * @example
+ * ```typescript
+ * import { noopMetrics } from '@core/runtime'
+ *
+ * // Use when metrics are disabled
+ * const metrics = config.metricsEnabled
+ *   ? createDatadogMetrics(config)
+ *   : noopMetrics
+ *
+ * // All operations are safe to call
+ * metrics.counter('requests').inc()
+ * const stop = metrics.timer('query').start()
+ * stop()
+ * ```
+ */
+const noopMetrics = createNoopMetrics();
+
+/**
+ * Define a schema for runtime logger interfaces.
+ *
+ * @remarks
+ * Validate that a runtime logger provides the minimal methods expected by the SDK.
+ *
+ * @example
+ * ```typescript
+ * import { loggerSchema } from '@core/runtime'
+ *
+ * const logger = {
+ *   debug: () => undefined,
+ *   info: () => undefined,
+ *   warn: () => undefined,
+ *   error: () => undefined,
+ *   child: () => logger,
+ * }
+ *
+ * loggerSchema.parse(logger)
+ * ```
+ */
+const loggerSchema = z.custom((value) => {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return (typeof record['debug'] === 'function' &&
+        typeof record['info'] === 'function' &&
+        typeof record['warn'] === 'function' &&
+        typeof record['error'] === 'function' &&
+        typeof record['child'] === 'function');
+}, {
+    message: 'Invalid logger',
+});
+
+/**
+ * Define a schema for runtime metrics interfaces.
+ *
+ * @remarks
+ * Validate that a metrics implementation exposes the minimal API expected by the runtime.
+ *
+ * @example
+ * ```typescript
+ * import { metricsSchema } from '@core/runtime'
+ *
+ * const metrics = {
+ *   counter: () => ({ inc: () => undefined }),
+ *   histogram: () => ({ observe: () => undefined }),
+ *   timer: () => ({ start: () => () => undefined }),
+ *   child: () => metrics,
+ * }
+ *
+ * metricsSchema.parse(metrics)
+ * ```
+ */
+const metricsSchema = z.custom((value) => {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return (typeof record['counter'] === 'function' &&
+        typeof record['histogram'] === 'function' &&
+        typeof record['timer'] === 'function' &&
+        typeof record['child'] === 'function');
+}, {
+    message: 'Invalid metrics',
+});
+
+/**
+ * Omit undefined values from an object.
+ *
+ * @param obj - The object to process.
+ * @returns A new object with undefined values removed.
+ *
+ * @internal
+ * @remarks
+ * Used by both production and mock loggers to ensure consistent behavior.
+ * This prevents undefined values from being serialized in log output,
+ * which can cause issues with some log transports.
+ */
+function omitUndefined(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+
+/**
+ * Default redaction paths for web3/blockchain SDKs.
+ *
+ * @remarks
+ * These paths target common sensitive fields in blockchain applications.
+ * All user fields are nested under `context`, so paths start with `context.`.
+ * Wildcard `*` matches any key at that level.
+ */
+const DEFAULT_REDACT_PATHS = [
+    // Generic Credentials
+    'context.password',
+    'context.passphrase',
+    'context.secret',
+    'context.token',
+    'context.*.password',
+    'context.*.passphrase',
+    'context.*.secret',
+    'context.*.token',
+    // API Keys & Auth Tokens
+    'context.apiKey',
+    'context.apiSecret',
+    'context.accessToken',
+    'context.refreshToken',
+    'context.jwt',
+    'context.bearerToken',
+    'context.sessionId',
+    'context.authorization',
+    'context.cookie',
+    'context.*.apiKey',
+    'context.*.apiSecret',
+    'context.*.accessToken',
+    'context.*.refreshToken',
+    'context.*.jwt',
+    'context.*.bearerToken',
+    'context.*.sessionId',
+    'context.*.authorization',
+    'context.*.cookie',
+    // Web3 / Crypto Keys
+    'context.privateKey',
+    'context.secretKey',
+    'context.signingKey',
+    'context.encryptionKey',
+    'context.*.privateKey',
+    'context.*.secretKey',
+    'context.*.signingKey',
+    'context.*.encryptionKey',
+    // Web3 / Crypto Mnemonics and Seeds
+    'context.mnemonic',
+    'context.seed',
+    'context.seedPhrase',
+    'context.*.mnemonic',
+    'context.*.seed',
+    'context.*.seedPhrase',
+    // OTP / Verification Codes
+    'context.otp',
+    'context.verificationCode',
+    'context.*.otp',
+    'context.*.verificationCode',
+    // Payment Information
+    'context.cardNumber',
+    'context.cvv',
+    'context.accountNumber',
+    'context.*.cardNumber',
+    'context.*.cvv',
+    'context.*.accountNumber',
+];
+/**
+ * Wrap user fields under `context` to prevent collision with pino internals.
+ *
+ * @param fields - User-provided log fields.
+ * @returns Object with fields nested under `context`, or undefined if empty.
+ *
+ * @remarks
+ * This function handles edge cases by returning undefined for null, undefined,
+ * or empty objects to avoid unnecessary wrapping in log output.
+ * Undefined values are cleaned before wrapping.
+ */
+function wrapInContext(fields) {
+    if (!fields)
+        return undefined;
+    // Clean undefined values for consistency and transport compatibility
+    const cleaned = omitUndefined(fields);
+    // Handle edge case: all values were undefined, resulting in empty object
+    const keys = Object.keys(cleaned);
+    if (keys.length === 0)
+        return undefined;
+    return { context: cleaned };
+}
+/**
+ * Wrap a pino instance to conform to our Logger interface.
+ *
+ * @param pinoInstance - The pino logger instance to wrap.
+ * @returns A Logger instance conforming to our stable interface.
+ */
+function wrapPino(pinoInstance) {
+    return {
+        debug(message, fields) {
+            const wrapped = wrapInContext(fields);
+            if (wrapped) {
+                pinoInstance.debug(wrapped, message);
+            }
+            else {
+                pinoInstance.debug(message);
+            }
+        },
+        info(message, fields) {
+            const wrapped = wrapInContext(fields);
+            if (wrapped) {
+                pinoInstance.info(wrapped, message);
+            }
+            else {
+                pinoInstance.info(message);
+            }
+        },
+        warn(message, fields) {
+            const wrapped = wrapInContext(fields);
+            if (wrapped) {
+                pinoInstance.warn(wrapped, message);
+            }
+            else {
+                pinoInstance.warn(message);
+            }
+        },
+        error(message, fields) {
+            const wrapped = wrapInContext(fields);
+            if (wrapped) {
+                pinoInstance.error(wrapped, message);
+            }
+            else {
+                pinoInstance.error(message);
+            }
+        },
+        child(tags) {
+            // Child bindings stay flat (not wrapped) - they're part of logger's base context
+            const cleaned = omitUndefined(tags);
+            return wrapPino(pinoInstance.child(cleaned));
+        },
+    };
+}
+/**
+ * Build pino redact configuration from our simplified options.
+ *
+ * @param redact - The redact configuration option.
+ * @returns Pino-compatible redact configuration or undefined.
+ */
+function buildRedactConfig(redact) {
+    // Explicitly disabled
+    if (redact === false) {
+        return undefined;
+    }
+    // Custom paths provided
+    if (Array.isArray(redact)) {
+        return redact.length > 0
+            ? { paths: redact, censor: '[REDACTED]' }
+            : undefined;
+    }
+    // Default: use web3 sensible defaults
+    return {
+        paths: [...DEFAULT_REDACT_PATHS],
+        censor: '[REDACTED]',
+    };
+}
+/**
+ * Create a logger backed by pino.
+ *
+ * @param options - Logger options (optional).
+ * @param stream - Destination stream (optional).
+ * @returns A Logger instance.
+ * @throws Error if invalid pino options are provided.
+ *
+ * @remarks
+ * This is a thin wrapper around pino that exposes our stable Logger interface.
+ * Pino handles all transport concerns: JSON, pretty printing, file, remote, browser, etc.
+ *
+ * **Security**: By default, sensitive web3 fields (privateKey, mnemonic, apiKey, etc.)
+ * are automatically redacted from log output. Use `redact: false` to disable.
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from '@core/runtime'
+ *
+ * // Default: web3 sensitive fields are redacted
+ * const logger = createLogger({ level: 'info' })
+ * logger.info('Signing', { privateKey: '0x123...' })
+ * // Output: { context: { privateKey: '[REDACTED]' }, msg: 'Signing' }
+ *
+ * // Disable redaction (use with caution)
+ * const unsafeLogger = createLogger({ level: 'debug', redact: false })
+ *
+ * // Custom redaction paths
+ * const customLogger = createLogger({
+ *   level: 'info',
+ *   redact: ['context.mySecret', 'context.*.credentials']
+ * })
+ *
+ * // Pretty output for development
+ * const devLogger = createLogger({
+ *   level: 'debug',
+ *   transport: { target: 'pino-pretty' }
+ * })
+ *
+ * // Browser logger
+ * const browserLogger = createLogger({
+ *   browser: { asObject: true }
+ * })
+ * ```
+ */
+function createLogger(options, stream) {
+    const { redact, ...pinoOptions } = {};
+    // Build redaction config
+    const redactConfig = buildRedactConfig(redact);
+    // Build final pino options, only include redact if defined
+    const finalOptions = redactConfig
+        ? { ...pinoOptions, redact: redactConfig }
+        : pinoOptions;
+    const pinoInstance = pino(finalOptions);
+    return wrapPino(pinoInstance);
+}
+
+/**
+ * Factory for creating Runtime instances with defaults.
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// Validation Schema
+// ============================================================================
+/**
+ * Schema for validating {@link RuntimeOptions}.
+ *
+ * @remarks
+ * Used internally by {@link createRuntime} to validate options from JS consumers.
+ * Exported for advanced use cases where manual validation is needed.
+ */
+const runtimeOptionsSchema = z
+    .object({
+    logger: loggerSchema.optional(),
+    metrics: metricsSchema.optional(),
+})
+    .passthrough();
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a complete Runtime with sensible defaults.
+ *
+ * @param options - Optional configuration to override logger and metrics.
+ * @returns A frozen, immutable Runtime with all services guaranteed present.
+ * @throws KitError (INPUT_VALIDATION_FAILED) if options contain invalid services.
+ *
+ * @remarks
+ * Creates a fully-configured runtime by merging provided options with defaults.
+ * The returned runtime is frozen to enforce immutability.
+ *
+ * | Service | Default | Configurable |
+ * |---------|---------|--------------|
+ * | `logger` | pino logger (info level) | Yes |
+ * | `metrics` | No-op metrics | Yes |
+ * | `events` | Internal event bus | No |
+ * | `clock` | `Date.now()` | No |
+ *
+ * **Why only logger and metrics?**
+ *
+ * - **Logger/Metrics**: Integration points with your infrastructure
+ * - **Events**: Internal pub/sub mechanism - subscribe via `runtime.events.on()`
+ * - **Clock**: Testing concern - use mock factories for tests
+ *
+ * @example
+ * ```typescript
+ * import { createRuntime, createLogger } from '@core/runtime'
+ *
+ * // Use all defaults
+ * const runtime = createRuntime()
+ *
+ * // Custom logger
+ * const runtime = createRuntime({
+ *   logger: createLogger({ level: 'debug' }),
+ * })
+ *
+ * // Custom metrics (e.g., Prometheus)
+ * const runtime = createRuntime({
+ *   metrics: myPrometheusMetrics,
+ * })
+ *
+ * // Subscribe to events (don't replace the bus)
+ * runtime.events.on('operation.*', (event) => {
+ *   console.log('Event:', event.name)
+ * })
+ * ```
+ */
+function createRuntime(options) {
+    // Validate options for JS consumers
+    if (options != null) {
+        parseOrThrow(options, runtimeOptionsSchema, 'runtime options');
+    }
+    // Resolve logger first (events may need it)
+    const logger = options?.logger ?? createLogger();
+    // Internal services - not configurable
+    const events = createEventBus({ logger });
+    const clock = defaultClock;
+    // Resolve metrics
+    const metrics = options?.metrics ?? noopMetrics;
+    return Object.freeze({ logger, events, metrics, clock });
+}
+
+/**
+ * Invocation context resolution - resolves the **WHO/HOW** of an operation.
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// Validation Schemas
+// ============================================================================
+/**
+ * Schema for validating Caller.
+ */
+const callerSchema = z.object({
+    type: z.string(),
+    name: z.string(),
+    version: z.string().optional(),
+});
+/**
+ * Schema for validating InvocationMeta input.
+ */
+const invocationMetaSchema = z
+    .object({
+    traceId: z.string().optional(),
+    runtime: z.object({}).passthrough().optional(),
+    tokens: z.object({}).passthrough().optional(),
+    callers: z.array(callerSchema).optional(),
+})
+    .strict();
+// ============================================================================
+// Invocation Context Resolution
+// ============================================================================
+/**
+ * Resolve invocation metadata to invocation context.
+ *
+ * @param meta - User-provided invocation metadata (**WHO/HOW**), optional.
+ * @param defaults - Default runtime and tokens to use if not overridden.
+ * @returns Frozen, immutable invocation context with guaranteed values.
+ * @throws KitError when meta contains invalid properties.
+ *
+ * @remarks
+ * Resolves the **WHO** called and **HOW** to observe:
+ * - TraceId: Uses provided value or generates new one
+ * - Runtime: Uses meta.runtime if provided, otherwise defaults.runtime
+ * - Tokens: Uses meta.tokens if provided, otherwise defaults.tokens
+ * - Callers: Uses provided array or empty array
+ *
+ * The returned context is frozen to enforce immutability.
+ *
+ * @example
+ * ```typescript
+ * import { resolveInvocationContext, createRuntime } from '@core/runtime'
+ * import { createTokenRegistry } from '@core/tokens'
+ *
+ * const defaults = {
+ *   runtime: createRuntime(),
+ *   tokens: createTokenRegistry(),
+ * }
+ *
+ * // Minimal - just using defaults
+ * const ctx = resolveInvocationContext(undefined, defaults)
+ *
+ * // With trace ID and caller info
+ * const ctx = resolveInvocationContext(
+ *   {
+ *     traceId: 'abc-123',
+ *     callers: [{ type: 'kit', name: 'BridgeKit', version: '1.0.0' }],
+ *   },
+ *   defaults
+ * )
+ *
+ * // With runtime override (complete replacement)
+ * const ctx = resolveInvocationContext(
+ *   { runtime: createRuntime({ logger: myLogger }) },
+ *   defaults
+ * )
+ * ```
+ */
+function resolveInvocationContext(meta, defaults) {
+    // Validate meta input if provided
+    if (meta !== undefined) {
+        const result = invocationMetaSchema.safeParse(meta);
+        if (!result.success) {
+            throw createValidationFailedError$1('invocationMeta', meta, result.error.errors.map((e) => e.message).join(', '));
+        }
+    }
+    // Generate trace ID if not provided
+    const traceId = meta?.traceId ?? createTraceId();
+    // Use meta overrides or fall back to defaults
+    const runtime = meta?.runtime ?? defaults.runtime;
+    const tokens = meta?.tokens ?? defaults.tokens;
+    const callers = meta?.callers ?? [];
+    return Object.freeze({ traceId, runtime, tokens, callers });
+}
+
+/**
+ * Extend an invocation context by appending a caller to its call chain.
+ *
+ * @param context - The existing invocation context to extend.
+ * @param caller - The caller to append to the call chain.
+ * @returns A new frozen invocation context with the caller appended.
+ *
+ * @remarks
+ * This function creates a new immutable context with the caller appended
+ * to the `callers` array while preserving all other context properties
+ * (traceId, runtime, tokens).
+ *
+ * The returned context is frozen to enforce immutability.
+ *
+ * @example
+ * ```typescript
+ * import { extendInvocationContext } from '@core/runtime'
+ *
+ * const caller = { type: 'provider', name: 'CCTPV2', version: '1.0.0' }
+ * const extended = extendInvocationContext(existingContext, caller)
+ * // extended.callers === [...existingContext.callers, caller]
+ * ```
+ */
+function extendInvocationContext(context, caller) {
+    return Object.freeze({
+        traceId: context.traceId,
+        runtime: context.runtime,
+        tokens: context.tokens,
+        callers: [...context.callers, caller],
+    });
+}
+
+// Clock - expose defaultClock for backward compatibility
+/** Clock validation schema (backward compatibility). */
+z.custom((val) => val !== null &&
+    typeof val === 'object' &&
+    'now' in val &&
+    typeof val['now'] === 'function');
+/** EventBus validation schema (backward compatibility). */
+z.custom((val) => val !== null &&
+    typeof val === 'object' &&
+    'emit' in val &&
+    typeof val['emit'] === 'function');
+/** Runtime validation schema (backward compatibility). */
+z
+    .object({
+    logger: z.any().optional(),
+    events: z.any().optional(),
+    metrics: z.any().optional(),
+    clock: z.any().optional(),
+})
+    .passthrough();
+
+/**
+ * Create a structured error for token resolution failures.
+ *
+ * @remarks
+ * Returns a `KitError` with `INPUT_INVALID_TOKEN` code (1006).
+ * The error trace contains the selector and chain context for debugging.
+ *
+ * @param message - Human-readable error description.
+ * @param selector - The token selector that failed to resolve.
+ * @param chainId - The chain being resolved for (optional).
+ * @param cause - The underlying error, if any (optional).
+ * @returns A KitError with INPUT type and FATAL recoverability.
+ *
+ * @example
+ * ```typescript
+ * throw createTokenResolutionError(
+ *   'Unknown token symbol: FAKE',
+ *   'FAKE',
+ *   'Ethereum'
+ * )
+ * ```
+ */
+function createTokenResolutionError(message, selector, chainId, cause) {
+    const trace = {
+        selector,
+        ...(chainId === undefined ? {} : { chainId }),
+        ...({} ),
+    };
+    return new KitError({
+        ...InputError.INVALID_TOKEN,
+        recoverability: 'FATAL',
+        message,
+        cause: { trace },
+    });
+}
+
+/**
+ * USDC token definition with addresses and metadata.
+ *
+ * @remarks
+ * This is the built-in USDC definition used by the TokenRegistry.
+ * Includes all known USDC addresses across supported chains.
+ *
+ * Keys use the `Blockchain` enum for type safety. Both enum values
+ * and string literals are supported:
+ * - `Blockchain.Ethereum` or `'Ethereum'`
+ *
+ * @example
+ * ```typescript
+ * import { USDC } from '@core/tokens'
+ * import { Blockchain } from '@core/chains'
+ *
+ * console.log(USDC.symbol)   // 'USDC'
+ * console.log(USDC.decimals) // 6
+ * console.log(USDC.locators[Blockchain.Ethereum])
+ * // '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
+ * ```
+ */
+const USDC = {
+    symbol: 'USDC',
+    decimals: 6,
+    locators: {
+        // =========================================================================
+        // Mainnets (alphabetically sorted)
+        // =========================================================================
+        [Blockchain.Arbitrum]: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+        [Blockchain.Avalanche]: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E',
+        [Blockchain.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        [Blockchain.Celo]: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
+        [Blockchain.Codex]: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
+        [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+        [Blockchain.Hedera]: '0.0.456858',
+        [Blockchain.HyperEVM]: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
+        [Blockchain.Ink]: '0x2D270e6886d130D724215A266106e6832161EAEd',
+        [Blockchain.Linea]: '0x176211869ca2b568f2a7d4ee941e073a821ee1ff',
+        [Blockchain.NEAR]: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
+        [Blockchain.Noble]: 'uusdc',
+        [Blockchain.Optimism]: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
+        [Blockchain.Plume]: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
+        [Blockchain.Polkadot_Asset_Hub]: '1337',
+        [Blockchain.Polygon]: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
+        [Blockchain.Sei]: '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392',
+        [Blockchain.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        [Blockchain.Sonic]: '0x29219dd400f2Bf60E5a23d13Be72B486D4038894',
+        [Blockchain.Stellar]: 'USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
+        [Blockchain.Sui]: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+        [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
+        [Blockchain.World_Chain]: '0x79A02482A880bCe3F13E09da970dC34dB4cD24D1',
+        [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
+        // =========================================================================
+        // Testnets (alphabetically sorted)
+        // =========================================================================
+        [Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
+        [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
+        [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+        [Blockchain.Codex_Testnet]: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
+        [Blockchain.Ethereum_Sepolia]: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+        [Blockchain.Hedera_Testnet]: '0.0.429274',
+        [Blockchain.HyperEVM_Testnet]: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
+        [Blockchain.Ink_Testnet]: '0xFabab97dCE620294D2B0b0e46C68964e326300Ac',
+        [Blockchain.Linea_Sepolia]: '0xfece4462d57bd51a6a552365a011b95f0e16d9b7',
+        [Blockchain.NEAR_Testnet]: '3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af',
+        [Blockchain.Noble_Testnet]: 'uusdc',
+        [Blockchain.Optimism_Sepolia]: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
+        [Blockchain.Plume_Testnet]: '0xcB5f30e335672893c7eb944B374c196392C19D18',
+        [Blockchain.Polkadot_Westmint]: '31337',
+        [Blockchain.Polygon_Amoy_Testnet]: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
+        [Blockchain.Sei_Testnet]: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED',
+        [Blockchain.Solana_Devnet]: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
+        [Blockchain.Sonic_Testnet]: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
+        [Blockchain.Stellar_Testnet]: 'USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
+        [Blockchain.Sui_Testnet]: '0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC',
+        [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
+        [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
+        [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853',
+    },
+};
+
+// Re-export for consumers
+/**
+ * All default token definitions.
+ *
+ * @remarks
+ * These tokens are automatically included in the TokenRegistry when created
+ * without explicit defaults. Extensions can override these definitions.
+ *
+ * @example
+ * ```typescript
+ * import { createTokenRegistry } from '@core/tokens'
+ *
+ * // Registry uses these by default
+ * const registry = createTokenRegistry()
+ *
+ * // Add custom tokens (built-ins are still included)
+ * const customRegistry = createTokenRegistry({
+ *   tokens: [myCustomToken],
+ * })
+ * ```
+ */
+const DEFAULT_TOKENS = [USDC];
+
+/**
+ * Check if a selector is a raw token selector (object form).
+ *
+ * @param selector - The token selector to check.
+ * @returns True if the selector is a raw token selector.
+ */
+function isRawSelector(selector) {
+    return typeof selector === 'object' && 'locator' in selector;
+}
+/**
+ * Normalize a symbol to uppercase for case-insensitive lookup.
+ *
+ * @param symbol - The symbol to normalize.
+ * @returns The normalized (uppercase) symbol.
+ */
+function normalizeSymbol(symbol) {
+    return symbol.toUpperCase();
+}
+/**
+ * Create a token registry with built-in tokens and optional extensions.
+ *
+ * @remarks
+ * The registry always includes built-in tokens (DEFAULT_TOKENS) like USDC.
+ * Custom tokens are merged on top - use this to add new tokens or override
+ * built-in definitions.
+ *
+ * @param options - Configuration options for the registry.
+ * @returns A token registry instance.
+ *
+ * @example
+ * ```typescript
+ * import { createTokenRegistry } from '@core/tokens'
+ *
+ * // Create registry with built-in tokens (USDC, etc.)
+ * const registry = createTokenRegistry()
+ *
+ * // Resolve USDC on Ethereum
+ * const usdc = registry.resolve('USDC', 'Ethereum')
+ * console.log(usdc.locator) // '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
+ * console.log(usdc.decimals) // 6
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Add custom tokens (built-ins are still included)
+ * const myToken: TokenDefinition = {
+ *   symbol: 'MY',
+ *   decimals: 18,
+ *   locators: { Ethereum: '0x...' },
+ * }
+ *
+ * const registry = createTokenRegistry({ tokens: [myToken] })
+ * registry.resolve('USDC', 'Ethereum') // Still works!
+ * registry.resolve('MY', 'Ethereum')   // Also works
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Override a built-in token
+ * const customUsdc: TokenDefinition = {
+ *   symbol: 'USDC',
+ *   decimals: 6,
+ *   locators: { MyChain: '0xCustomAddress' },
+ * }
+ *
+ * const registry = createTokenRegistry({ tokens: [customUsdc] })
+ * // Now USDC resolves to customUsdc definition
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Resolve arbitrary tokens by raw locator
+ * const registry = createTokenRegistry()
+ * const token = registry.resolve(
+ *   { locator: '0x1234...', decimals: 18 },
+ *   'Ethereum'
+ * )
+ * ```
+ */
+function createTokenRegistry(options = {}) {
+    const { tokens = [], requireDecimals = false } = options;
+    // Build the token map: always start with DEFAULT_TOKENS, then add custom tokens
+    const tokenMap = new Map();
+    // Add built-in tokens first
+    for (const def of DEFAULT_TOKENS) {
+        tokenMap.set(normalizeSymbol(def.symbol), def);
+    }
+    // Custom tokens override built-ins
+    for (const def of tokens) {
+        tokenMap.set(normalizeSymbol(def.symbol), def);
+    }
+    /**
+     * Resolve a symbol selector to token information.
+     */
+    function resolveSymbol(symbol, chainId) {
+        const normalizedSymbol = normalizeSymbol(symbol);
+        const definition = tokenMap.get(normalizedSymbol);
+        if (definition === undefined) {
+            throw createTokenResolutionError(`Unknown token symbol: ${symbol}. Register it via createTokenRegistry({ tokens: [...] }) or use a raw selector.`, symbol, chainId);
+        }
+        const locator = definition.locators[chainId];
+        if (locator === undefined || locator.trim() === '') {
+            throw createTokenResolutionError(`Token ${symbol} has no locator for chain ${chainId}`, symbol, chainId);
+        }
+        return {
+            symbol: definition.symbol,
+            decimals: definition.decimals,
+            locator,
+        };
+    }
+    /**
+     * Resolve a raw selector to token information.
+     */
+    function resolveRaw(selector, chainId) {
+        const { locator, decimals } = selector;
+        // Validate locator
+        if (!locator || typeof locator !== 'string') {
+            throw createTokenResolutionError('Raw selector must have a valid locator string', selector, chainId);
+        }
+        // Decimals are always required for raw selectors
+        if (decimals === undefined) {
+            const message = requireDecimals
+                ? 'Decimals required for raw token selector (requireDecimals: true)'
+                : 'Decimals required for raw token selector. Provide { locator, decimals }.';
+            throw createTokenResolutionError(message, selector, chainId);
+        }
+        // Validate decimals
+        if (typeof decimals !== 'number' ||
+            decimals < 0 ||
+            !Number.isInteger(decimals)) {
+            throw createTokenResolutionError(`Invalid decimals: ${String(decimals)}. Must be a non-negative integer.`, selector, chainId);
+        }
+        return {
+            decimals,
+            locator,
+        };
+    }
+    return {
+        resolve(selector, chainId) {
+            // Runtime validation of inputs - these checks are for JS consumers
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (selector === null || selector === undefined) {
+                throw createTokenResolutionError('Token selector cannot be null or undefined', selector, chainId);
+            }
+            if (chainId === '' || typeof chainId !== 'string') {
+                throw createTokenResolutionError('Chain ID is required for token resolution', selector, chainId);
+            }
+            // Dispatch based on selector type
+            if (isRawSelector(selector)) {
+                return resolveRaw(selector, chainId);
+            }
+            if (typeof selector === 'string') {
+                return resolveSymbol(selector, chainId);
+            }
+            throw createTokenResolutionError(`Invalid selector type: ${typeof selector}. Expected string or object with locator.`, selector, chainId);
+        },
+        get(symbol) {
+            if (!symbol || typeof symbol !== 'string') {
+                return undefined;
+            }
+            return tokenMap.get(normalizeSymbol(symbol));
+        },
+        has(symbol) {
+            if (!symbol || typeof symbol !== 'string') {
+                return false;
+            }
+            return tokenMap.has(normalizeSymbol(symbol));
+        },
+        symbols() {
+            return Array.from(tokenMap.values()).map((def) => def.symbol);
+        },
+        entries() {
+            return Array.from(tokenMap.values());
+        },
+    };
+}
+
+/**
+ * Define a schema for token registry interfaces.
+ *
+ * @remarks
+ * Validate that a registry exposes the `resolve()` API used by adapters.
+ *
+ * @example
+ * ```typescript
+ * import { tokenRegistrySchema } from '@core/tokens'
+ *
+ * const registry = {
+ *   resolve: () => ({ locator: '0x0', decimals: 6 }),
+ * }
+ *
+ * tokenRegistrySchema.parse(registry)
+ * ```
+ */
+z.custom((value) => {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return (typeof record['resolve'] === 'function' &&
+        typeof record['get'] === 'function' &&
+        typeof record['has'] === 'function' &&
+        typeof record['symbols'] === 'function' &&
+        typeof record['entries'] === 'function');
+}, {
+    message: 'Invalid token registry',
+});
+
+/**
+ * Type guard to check if the destination is a forwarder-only destination.
+ *
+ * Forwarder-only destinations have `useForwarder: true` and no adapter.
+ * They require a `recipientAddress` to be specified.
+ *
+ * @param dest - The bridge destination to check
+ * @returns True if this is a forwarder-only destination without adapter
+ */
+function isForwarderOnlyDestination(dest) {
+    return (dest.useForwarder === true &&
+        !('adapter' in dest) &&
+        'recipientAddress' in dest);
+}
+/**
+ * Resolves a chain identifier to a chain definition.
+ *
+ * Both AdapterContext and BridgeDestinationWithAddress have the chain property
+ * at the top level, so we can directly access it from either type.
+ *
+ * @param ctx - The bridge destination containing the chain identifier
+ * @returns The resolved chain definition
+ * @throws If the chain definition cannot be resolved
+ *
+ * @example
+ * ```typescript
+ * import { Blockchain } from '@core/chains'
+ *
+ * // AdapterContext
+ * const chain1 = resolveChainDefinition({
+ *   adapter: mockAdapter,
+ *   chain: 'Ethereum'
+ * })
+ *
+ * // BridgeDestinationWithAddress
+ * const chain2 = resolveChainDefinition({
+ *   adapter: mockAdapter,
+ *   chain: 'Base',
+ *   recipientAddress: '0x123...'
+ * })
+ * ```
+ */
+function resolveChainDefinition(ctx) {
+    return resolveChainIdentifier(ctx.chain);
+}
+/**
+ * Resolves the signer's address from a bridge destination.
+ *
+ * This function resolves the address that will be used for transaction signing,
+ * ignoring any `recipientAddress` field which is handled separately.
+ *
+ * It handles two cases:
+ * - Developer-controlled adapters - returns the explicit address from context
+ * - User-controlled adapters - calls getAddress() on the adapter
+ *
+ * @param ctx - The bridge destination to resolve the address from
+ * @returns The resolved signer address string
+ *
+ * @example
+ * ```typescript
+ * // Developer-controlled adapter
+ * const addr1 = await resolveAddress({
+ *   adapter: devAdapter,
+ *   chain: 'Ethereum',
+ *   address: '0x1234567890123456789012345678901234567890'
+ * }) // Returns: '0x1234567890123456789012345678901234567890'
+ *
+ * // User-controlled adapter
+ * const addr2 = await resolveAddress({
+ *   adapter: userAdapter,
+ *   chain: 'Ethereum'
+ * }) // Returns adapter's connected address
+ * ```
+ */
+async function resolveAddress(ctx) {
+    // Handle based on adapter's addressContext
+    if (ctx.adapter.capabilities?.addressContext === 'developer-controlled') {
+        // Developer-controlled: address must be provided explicitly
+        if ('address' in ctx && ctx.address) {
+            return ctx.address;
+        }
+        throw new Error('Address is required in context for developer-controlled adapters. ' +
+            'Please provide: { adapter, chain, address: "0x..." }');
+    }
+    else {
+        // User-controlled: address should not be provided (auto-resolved from adapter)
+        if ('address' in ctx && ctx.address) {
+            throw new Error('Address should not be provided for user-controlled adapters. ' +
+                'The address is automatically resolved from the connected wallet.');
+        }
+        // Derive address from adapter
+        const chain = resolveChainDefinition(ctx);
+        return await ctx.adapter.getAddress(chain);
+    }
+}
+/**
+ * Resolves the amount of a transfer by formatting it according to the token's decimal places.
+ *
+ * This function takes the raw amount from the transfer parameters and formats it
+ * using the appropriate decimal places for the specified token. Currently supports
+ * USDC (6 decimals) and falls back to the raw amount for other tokens.
+ *
+ * @param params - The bridge parameters containing the amount, token type, and from context
+ * @returns The formatted amount string with proper decimal places
+ *
+ * @example
+ * ```typescript
+ * import { Adapter } from '@core/adapter'
+ *
+ * const params = {
+ *   amount: '1000000',
+ *   token: 'USDC',
+ *   from: { adapter: mockAdapter, chain: Ethereum },
+ *   to: { adapter: mockAdapter, chain: Base }
+ * }
+ * const formattedAmount = resolveAmount(params) // Returns '1000000000000'
+ * ```
+ */
+function resolveAmount(params) {
+    if (params.token === 'USDC') {
+        return parseUnits(params.amount, 6).toString();
+    }
+    return params.amount;
+}
+/**
+ * Resolves the invocation context for a bridge operation.
+ *
+ * Takes optional invocation metadata and resolves it into a full
+ * InvocationContext with BridgeKit caller information appended.
+ *
+ * @param invocationMeta - Optional invocation metadata for tracing and correlation
+ * @returns An InvocationContext with traceId, runtime, tokens, and caller chain
+ *
+ * @example
+ * ```typescript
+ * // With user-provided invocation metadata
+ * const invocation = resolveBridgeInvocation({
+ *   traceId: 'my-custom-trace-id',
+ *   callers: [{ type: 'app', name: 'MyDApp' }],
+ * })
+ * // invocation.traceId === 'my-custom-trace-id'
+ * // invocation.callers === [{ type: 'app', name: 'MyDApp' }, { type: 'kit', name: 'BridgeKit' }]
+ *
+ * // Without invocation metadata (auto-generated traceId)
+ * const invocation2 = resolveBridgeInvocation()
+ * // invocation2.traceId === <auto-generated OpenTelemetry-compatible trace ID>
+ * // invocation2.callers === [{ type: 'kit', name: 'BridgeKit' }]
+ * ```
+ */
+function resolveBridgeInvocation(invocationMeta) {
+    const bridgeKitCaller = {
+        type: 'kit',
+        name: 'BridgeKit',
+        version: pkg.version,
+    };
+    // Create default runtime and tokens for invocation context resolution
+    const defaults = {
+        runtime: createRuntime(),
+        tokens: createTokenRegistry(),
+    };
+    // Resolve invocation metadata to full context, then extend with BridgeKit caller
+    const baseContext = resolveInvocationContext(invocationMeta, defaults);
+    return extendInvocationContext(baseContext, bridgeKitCaller);
+}
+/**
+ * Resolves and normalizes bridge configuration for the provider.
+ *
+ * This function takes the optional configuration from bridge parameters and returns
+ * a normalized BridgeConfig with:
+ * - Default transfer speed set to FAST if not provided
  * - Max fee values converted from human-readable to smallest units (6 decimals for USDC)
  * - Custom fee values converted from human-readable to smallest units (6 decimals for USDC)
  *
@@ -5683,6 +7367,7 @@ function resolveConfig(params) {
  * - Amount formatting
  *
  * @param params - The bridge parameters containing source/destination contexts, amount, and token
+ * @param invocationMeta - Optional invocation metadata for tracing and correlation
  * @returns Promise resolving to normalized bridge parameters for provider consumption
  * @throws \{Error\} If parameters cannot be resolved (invalid chains, etc.)
  *
@@ -5702,22 +7387,32 @@ function resolveConfig(params) {
  * ```
  */
 async function resolveBridgeParams(params) {
-    const fromChain = resolveChainDefinition(params.from);
-    const toChain = resolveChainDefinition(params.to);
+    // Resolve chains
+    const fromChain = resolveChainIdentifier(params.from.chain);
+    const toChain = resolveChainIdentifier(params.to.chain);
+    // Check if this is a forwarder-only destination (no adapter)
+    const isForwarderOnly = isForwarderOnlyDestination(params.to);
     // Validate adapter chain support after resolution
-    // This ensures adapters support the resolved chains before proceeding
     params.from.adapter.validateChainSupport(fromChain);
-    params.to.adapter.validateChainSupport(toChain);
+    // Only validate destination adapter if it exists
+    if (!isForwarderOnly && 'adapter' in params.to) {
+        params.to.adapter.validateChainSupport(toChain);
+    }
+    // For forwarder-only destinations, use recipientAddress directly
+    // For other destinations, resolve address from adapter
     const [fromAddress, toAddress] = await Promise.all([
         resolveAddress(params.from),
-        resolveAddress(params.to),
+        isForwarderOnly
+            ? Promise.resolve(params.to.recipientAddress)
+            : resolveAddress(params.to),
     ]);
     const token = params.token ?? 'USDC';
-    // Extract adapters - now always from explicit contexts
-    const fromAdapter = params.from.adapter;
-    const toAdapter = params.to.adapter;
     // Extract recipientAddress from params.to if it exists
     const recipientAddress = 'recipientAddress' in params.to ? params.to.recipientAddress : undefined;
+    // Extract useForwarder from params.to if it exists
+    const useForwarder = 'useForwarder' in params.to ? params.to.useForwarder : undefined;
+    // Resolve invocation metadata to full InvocationContext with BridgeKit caller
+    const resolvedInvocation = resolveBridgeInvocation(params.invocationMeta);
     return {
         amount: resolveAmount({
             ...params,
@@ -5727,16 +7422,21 @@ async function resolveBridgeParams(params) {
         config: resolveConfig({
             ...params}),
         source: {
-            adapter: fromAdapter,
+            adapter: params.from.adapter,
             chain: fromChain,
             address: fromAddress,
         },
         destination: {
-            adapter: toAdapter,
+            // Only include adapter if it exists (not forwarder-only)
+            ...(!isForwarderOnly &&
+                'adapter' in params.to && { adapter: params.to.adapter }),
             chain: toChain,
             address: toAddress,
             ...(recipientAddress !== undefined && { recipientAddress }),
+            ...(useForwarder !== undefined && { useForwarder }),
         },
+        // Pass resolved InvocationContext as invocationMeta (superset is compatible)
+        invocationMeta: resolvedInvocation,
     };
 }
 
@@ -5814,6 +7514,36 @@ const formatBridgeResult = (result, formatDirection) => {
     };
 };
 
+/**
+ * BridgeKit caller component for retry and estimate operations.
+ */
+const BRIDGE_KIT_CALLER = {
+    type: 'kit',
+    name: 'BridgeKit',
+    version: pkg.version,
+};
+/**
+ * Merge BridgeKit's caller into the invocation metadata for retry operations.
+ *
+ * Prepends the BridgeKit caller to the callers array.
+ *
+ * @param invocationMeta - Optional invocation metadata provided by caller.
+ * @returns Merged invocation metadata with BridgeKit caller prepended.
+ *
+ * @internal
+ */
+function mergeRetryInvocationMeta(invocationMeta) {
+    // Prepend BridgeKit caller to existing callers array
+    const existingCallers = invocationMeta?.callers ?? [];
+    return invocationMeta
+        ? {
+            ...invocationMeta,
+            callers: [BRIDGE_KIT_CALLER, ...existingCallers],
+        }
+        : {
+            callers: [BRIDGE_KIT_CALLER, ...existingCallers],
+        };
+}
 /**
  * Route cross-chain USDC bridging through Circle's Cross-Chain Transfer Protocol v2 (CCTPv2).
  *
@@ -5910,7 +7640,7 @@ class BridgeKit {
      * - CCTPv2 support for the chain pair
      * - Transfer configuration options
      *
-     * @param params - The transfer parameters containing source, destination, amount, and token
+     * @param params - The transfer parameters containing source, destination, amount, token, and optional invocation metadata
      * @returns Promise resolving to the transfer result with transaction details and steps
      * @throws {KitError} When any parameter validation fails.
      * @throws {Error} When CCTPv2 does not support the specified route.
@@ -5927,18 +7657,24 @@ class BridgeKit {
      *   privateKey: process.env.PRIVATE_KEY,
      * })
      *
+     * // Basic usage
      * const result = await kit.bridge({
-     *   from: {
-     *     adapter,
-     *     chain: 'Ethereum'
-     *   },
-     *   to: {
-     *     adapter,
-     *     chain: 'Base'
-     *   },
+     *   from: { adapter, chain: 'Ethereum' },
+     *   to: { adapter, chain: 'Base' },
      *   amount: '100.50'
      * })
      *
+     * // With custom invocation metadata
+     * const result = await kit.bridge({
+     *   from: { adapter, chain: 'Ethereum' },
+     *   to: { adapter, chain: 'Base' },
+     *   amount: '100.50',
+     *   invocationMeta: {
+     *     traceId: 'custom-trace-id',
+     *     callers: [{ type: 'app', name: 'MyDApp', version: '1.0.0' }],
+     *   },
+     * })
+     *
      * // Handle result
      * if (result.state === 'success') {
      *   console.log('Bridge completed!')
@@ -5984,6 +7720,8 @@ class BridgeKit {
      * @param context - The retry context containing fresh adapter instances for both
      *                  source and destination chains. These adapters should be properly
      *                  configured with current network connections and signing capabilities.
+     * @param invocationMeta - Optional invocation metadata for tracing and correlation.
+     *                         If not provided, uses the traceId from the original result.
      * @returns A promise that resolves to the updated bridge result after retry execution.
      *          The result will contain the complete step history including both original
      *          and retry attempts.
@@ -6015,31 +7753,35 @@ class BridgeKit {
      *   // ... other properties
      * }
      *
+     * // Basic retry (uses traceId from original result)
+     * const retryResult = await kit.retry(failedResult, {
+     *   from: sourceAdapter,
+     *   to: destAdapter
+     * })
      *
-     * try {
-     *   const retryResult = await kit.retry(failedResult, {
-     *     from: sourceAdapter,
-     *     to: destAdapter
-     *   })
-     *
-     *   console.log('Retry completed successfully:', retryResult.state)
-     *   console.log('Total steps executed:', retryResult.steps.length)
-     * } catch (error) {
-     *   console.error('Retry failed:', error.message)
-     *   // Handle retry failure (may require manual intervention)
-     * }
+     * // Retry with custom invocation metadata
+     * const retryResult = await kit.retry(
+     *   failedResult,
+     *   { from: sourceAdapter, to: destAdapter },
+     *   {
+     *     traceId: 'custom-trace-id',
+     *     callers: [{ type: 'app', name: 'MyApp' }],
+     *   }
+     * )
      * ```
      */
-    async retry(result, context) {
+    async retry(result, context, invocationMeta) {
         const provider = this.providers.find((p) => p.name === result.provider);
         if (!provider) {
             throw new Error(`Provider ${result.provider} not found`);
         }
+        // Merge BridgeKit caller into invocation metadata for retry operation
+        const mergedMeta = mergeRetryInvocationMeta(invocationMeta);
         // Format the bridge result into bigint string values for internal use
         const formattedBridgeResultInternal = formatBridgeResult(result, 'to-internal');
         // Execute the retry using the provider
         // Format the bridge result into human-readable string values for the user
-        return formatBridgeResult(await provider.retry(formattedBridgeResultInternal, context), 'to-human-readable');
+        return formatBridgeResult(await provider.retry(formattedBridgeResultInternal, context, mergedMeta), 'to-human-readable');
     }
     /**
      * Estimate the cost and fees for a cross-chain USDC bridge operation.
@@ -6047,13 +7789,15 @@ class BridgeKit {
      * This method calculates the expected gas fees and protocol costs for bridging
      * without actually executing the transaction. It performs the same validation
      * as the bridge method but stops before execution.
-     * @param params - The bridge parameters for cost estimation
+     *
+     * @param params - The bridge parameters for cost estimation, including optional invocation metadata
      * @returns Promise resolving to detailed cost breakdown including gas estimates
      * @throws {KitError} When the parameters are invalid.
      * @throws {UnsupportedRouteError} When the route is not supported.
      *
      * @example
      * ```typescript
+     * // Basic usage
      * const estimate = await kit.estimate({
      *   from: { adapter: adapter, chain: 'Ethereum' },
      *   to: { adapter: adapter, chain: 'Base' },
@@ -6061,6 +7805,18 @@ class BridgeKit {
      *   token: 'USDC'
      * })
      * console.log('Estimated cost:', estimate.totalCost)
+     *
+     * // With custom invocation metadata
+     * const estimate = await kit.estimate({
+     *   from: { adapter: adapter, chain: 'Ethereum' },
+     *   to: { adapter: adapter, chain: 'Base' },
+     *   amount: '10.50',
+     *   token: 'USDC',
+     *   invocationMeta: {
+     *     traceId: 'custom-trace-id',
+     *     callers: [{ type: 'app', name: 'MyDApp', version: '1.0.0' }],
+     *   },
+     * })
      * ```
      */
     async estimate(params) {
@@ -6112,6 +7868,9 @@ class BridgeKit {
      * // Get only EVM mainnet chains
      * const evmMainnets = kit.getSupportedChains({ chainType: 'evm', isTestnet: false })
      *
+     * // Get only chains that support forwarding
+     * const forwarderChains = kit.getSupportedChains({ forwarderSupported: true })
+     *
      * console.log('Supported chains:')
      * allChains.forEach(chain => {
      *   console.log(`- ${chain.name} (${chain.type})`)
@@ -6145,6 +7904,18 @@ class BridgeKit {
         if (options?.isTestnet !== undefined) {
             chains = chains.filter((chain) => chain.isTestnet === options.isTestnet);
         }
+        // Apply forwarder support filter if provided
+        if (options?.forwarderSupported !== undefined) {
+            chains = chains.filter((chain) => {
+                const fs = chain.cctp?.forwarderSupported;
+                if (!fs) {
+                    return !options.forwarderSupported;
+                }
+                return options.forwarderSupported
+                    ? fs.source || fs.destination
+                    : !fs.source && !fs.destination;
+            });
+        }
         return chains;
     }
     /**
@@ -6332,5 +8103,5 @@ class BridgeKit {
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg.name}/${pkg.version}`);
 
-export { BalanceError, Blockchain, BridgeChain, BridgeKit, InputError, KitError, NetworkError, OnchainError, RpcError, TransferSpeed, bridgeParamsWithChainIdentifierSchema, getErrorCode, getErrorMessage, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRetryableError, isRpcError, resolveChainIdentifier, setExternalPrefix };
+export { BalanceError, Blockchain, BridgeChain, BridgeKit, InputError, KitError, NetworkError, OnchainError, RpcError, TransferSpeed, bridgeParamsWithChainIdentifierSchema, createRuntime, createTokenRegistry, createTraceId, extendInvocationContext, getErrorCode, getErrorMessage, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRetryableError, isRpcError, resolveChainIdentifier, resolveInvocationContext, setExternalPrefix };
 //# sourceMappingURL=index.mjs.map