feat: port multicollateral sdk/cli + warp monitor metrics (public split)

.changeset/multicollateral-sdk-cli-monitor.md

@@ -0,0 +1,13 @@
+---
+'@hyperlane-xyz/sdk': minor
+'@hyperlane-xyz/cli': minor
+'@hyperlane-xyz/warp-monitor': minor
+---
+
+MultiCollateral warp route support was added across the SDK, CLI, and warp monitor.
+
+SDK: WarpCore gained `transferRemoteTo` flows for multicollateral tokens, including fee quoting, ERC-20 approval, and destination token resolution. EvmWarpModule now handles multicollateral router enrollment/unenrollment with canonical router ID normalization. EvmWarpRouteReader derives multicollateral token config including on-chain scale. A new `EvmMultiCollateralAdapter` provides quote, approve, and transfer operations.
+
+CLI: `warp deploy` and `warp extend` support multicollateral token types. A new `warp combine` command merges independent warp route configs into a single multicollateral route. `warp send` and `warp check` work with multicollateral routes.
+
+Warp monitor: Pending-transfer and inventory metrics were added for multicollateral routes, with projected deficit scoped to collateralized routes only.

.changeset/rebalancer-sim-exporter.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/rebalancer-sim': minor
+---
+
+Scenario loading was extracted to a shared `ScenarioLoader` API with `SCENARIOS_DIR` env override support. A new `ResultsExporter` API was added for saving simulation results as JSON and HTML. Path traversal guards were added to both scenario loading and result export paths.

solidity/eslint.config.mjs

@@ -9,8 +9,8 @@ export default [
       '**/dist/**/*',
       '**/lib/**/*',
       '**/typechain/**/*',
-      '**/dependencies/**/*',
       '**/multicollateral/**/*',
+      '**/dependencies/**/*',
       '.solcover.js',
       'generate-artifact-exports.mjs',
     ],

typescript/Dockerfile.node-service

@@ -52,6 +52,7 @@ COPY typescript/tron-sdk/package.json ./typescript/tron-sdk/
 COPY typescript/tsconfig/package.json ./typescript/tsconfig/
 COPY typescript/eslint-config/package.json ./typescript/eslint-config/
 COPY solidity/package.json ./solidity/
+COPY solidity/multicollateral/package.json ./solidity/multicollateral/
 COPY solhint-plugin/package.json ./solhint-plugin/
 COPY starknet/package.json ./starknet/
 
@@ -138,4 +139,4 @@ ENV SERVER_PORT=${SERVICE_PORT}
 EXPOSE 9090
 
 # Run the service from the bundle
-CMD ["node", "bundle/index.js"]
+CMD ["node", "bundle/index.js"]

typescript/cli/src/commands/warp.ts

@@ -27,7 +27,11 @@ import {
   type CommandModuleWithWarpDeployContext,
   type CommandModuleWithWriteContext,
 } from '../context/types.js';
-import { runWarpRouteApply, runWarpRouteDeploy } from '../deploy/warp.js';
+import {
+  runWarpRouteApply,
+  runWarpRouteCombine,
+  runWarpRouteDeploy,
+} from '../deploy/warp.js';
 import { runWarpRouteFees } from '../fees/warp.js';
 import { runForkCommand } from '../fork/fork.js';
 import {
@@ -77,6 +81,7 @@ export const warpCommand: CommandModule = {
     yargs
       .command(apply)
       .command(check)
+      .command(combine)
       .command(deploy)
       .command(fork)
       .command(getFees)
@@ -182,6 +187,51 @@ export const deploy: CommandModuleWithWarpDeployContext<SelectWarpRouteBuilder>
     },
   };
 
+const combine: CommandModuleWithWriteContext<{
+  routes: string;
+  'output-warp-route-id': string;
+}> = {
+  command: 'combine',
+  describe:
+    'Combine multiple MultiCollateral warp routes, updating deploy configs with cross-route enrolledRouters',
+  builder: {
+    routes: {
+      type: 'string',
+      description:
+        'Comma-separated warp route IDs to combine (e.g., "USDC/eth-arb,USDT/eth-arb")',
+      demandOption: true,
+    },
+    'output-warp-route-id': {
+      type: 'string',
+      description:
+        'Warp route ID for the merged WarpCoreConfig (e.g., MULTI/stableswap)',
+      demandOption: true,
+    },
+  },
+  handler: async ({ context, routes, 'output-warp-route-id': outputId }) => {
+    logCommandHeader('Hyperlane Warp Combine');
+
+    const routeIds = routes
+      .split(',')
+      .map((r) => r.trim())
+      .filter((r) => r.length > 0);
+    assert(
+      routeIds.length >= 2,
+      'At least 2 route IDs are required to combine',
+    );
+    assert(
+      outputId.trim().length > 0,
+      'Output warp route ID must be non-empty',
+    );
+    await runWarpRouteCombine({
+      context,
+      routeIds,
+      outputWarpRouteId: outputId,
+    });
+    process.exit(0);
+  },
+};
+
 export const init: CommandModuleWithContext<{
   advanced: boolean;
   out: string;
@@ -296,6 +346,8 @@ const send: CommandModuleWithWriteContext<
       recipient?: string;
       chains?: string[];
       skipValidation?: boolean;
+      sourceToken?: string;
+      destinationToken?: string;
     }
 > = {
   command: 'send',
@@ -322,6 +374,15 @@ const send: CommandModuleWithWriteContext<
       description: 'Skip transfer validation (e.g., collateral checks)',
       default: false,
     },
+    'source-token': {
+      type: 'string',
+      description: 'Source token router address (for MultiCollateral routes)',
+    },
+    'destination-token': {
+      type: 'string',
+      description:
+        'Destination token router address (for MultiCollateral cross-stablecoin transfers)',
+    },
   },
   handler: async ({
     context,
@@ -337,6 +398,8 @@ const send: CommandModuleWithWriteContext<
     roundTrip,
     chains: chainsArg,
     skipValidation,
+    sourceToken,
+    destinationToken,
   }) => {
     const warpCoreConfig = await getWarpCoreConfigOrExit({
       symbol,
@@ -366,10 +429,17 @@ const send: CommandModuleWithWriteContext<
       `Chain(s) ${[...unsupportedChains].join(', ')} are not part of the warp route.`,
     );
 
-    chains =
-      chains.length === 0
-        ? [...supportedChains]
-        : [...intersection(new Set(chains), supportedChains)];
+    // When origin & destination are explicitly provided, preserve duplicates
+    // for same-chain transfers (e.g., origin=anvil2, destination=anvil2).
+    // Only deduplicate when using --chains or auto-selecting from config.
+    if (origin && destination) {
+      chains = [origin, destination];
+    } else {
+      chains =
+        chains.length === 0
+          ? [...supportedChains]
+          : [...intersection(new Set(chains), supportedChains)];
+    }
 
     if (roundTrip) {
       // Appends the reverse of the array, excluding the 1st (e.g. [1,2,3] becomes [1,2,3,2,1])
@@ -388,6 +458,8 @@ const send: CommandModuleWithWriteContext<
       skipWaitForDelivery: quick,
       selfRelay: relay,
       skipValidation,
+      sourceToken,
+      destinationToken,
     });
     logGreen(
       `✅ Successfully sent messages for chains: ${chains.join(' ➡️ ')}`,

typescript/cli/src/config/warp.ts

@@ -75,6 +75,8 @@ const TYPE_DESCRIPTIONS: Record<DeployableTokenType, string> = {
   [TokenType.syntheticUri]: '',
   [TokenType.collateralUri]: '',
   [TokenType.nativeScaled]: '',
+  [TokenType.multiCollateral]:
+    'A collateral token that can route to multiple routers across chains',
 };
 
 const TYPE_CHOICES = Object.values(TokenType)
@@ -248,6 +250,7 @@ export async function createWarpRouteDeployConfig({
       case TokenType.XERC20:
       case TokenType.XERC20Lockbox:
       case TokenType.collateralFiat:
+      case TokenType.multiCollateral:
         result[chain] = {
           type,
           owner,