test: added fallback routing tests

Author: troykessler

rust/sealevel/Cargo.lock

@@ -63,7 +63,7 @@ hyperlane-sealevel-client composite-ism transfer-ownership \
 
 ### Config File Format
 
-The config file is a JSON file representing the root `IsmNode`. The `"type"` field selects the ISM variant; all field names are camelCase.
+The config file is a JSON file representing the root `IsmNode`. The `"type"` field selects the ISM variant. Variant names are camelCase; field names within variants are snake_case (matching the Rust struct fields exactly).
 
 #### Leaf nodes
 
@@ -75,17 +75,12 @@ The config file is a JSON file representing the root `IsmNode`. The `"type"` fie
 }
 ```
 
-**`multisigMessageId`** — ECDSA threshold multisig over `CheckpointWithMessageId`, one validator set per origin domain.
+**`multisigMessageId`** — ECDSA threshold multisig over `CheckpointWithMessageId`. Flat validators/threshold for a single validator set; use a `routing` or `fallbackRouting` parent to select different sets per origin domain.
 ```json
 {
   "type": "multisigMessageId",
-  "domainConfigs": [
-    {
-      "origin": 1000,
-      "validators": ["0xabc123...", "0xdef456..."],
-      "threshold": 2
-    }
-  ]
+  "validators": ["0xabc123...", "0xdef456..."],
+  "threshold": 2
 }
 ```
 
@@ -99,70 +94,107 @@ The config file is a JSON file representing the root `IsmNode`. The `"type"` fie
 { "type": "pausable", "paused": false }
 ```
 
+**`rateLimited`** — token-bucket rate limiter. Rejects messages once the bucket is empty; the bucket refills over time up to `max_capacity`. `recipient` is an optional H256 address used to restrict which message recipient this node applies to.
+```json
+{
+  "type": "rateLimited",
+  "max_capacity": 10000,
+  "recipient": "0x000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
+}
+```
+
+> `recipient` is optional and may be omitted.  Mutable state (`filled_level`, `last_updated`) is managed on-chain and is never part of the config file.
+
 #### Compound nodes
 
 **`aggregation`** — m-of-n: requires metadata from at least `threshold` sub-ISMs, and all sub-ISMs with provided metadata must verify.
 ```json
 {
   "type": "aggregation",
   "threshold": 2,
-  "subIsms": [
+  "sub_isms": [
     { "type": "trustedRelayer", "relayer": "<Pubkey>" },
     { "type": "test", "accept": true },
-    { "type": "multisigMessageId", "domainConfigs": [...] }
+    { "type": "multisigMessageId", "validators": ["0x..."], "threshold": 1 }
   ]
 }
 ```
 
-**`routing`** — routes to a sub-ISM based on the message's origin domain. Falls back to `defaultIsm` if the origin has no explicit route.
+**`routing`** — routes to a per-domain sub-ISM based on the message's origin domain. Returns an error if no ISM is configured for the incoming origin. Use `fallbackRouting` if you need a catch-all.
+
+The `domains` object maps decimal domain ID strings to ISM configs. During `deploy`/`update` each entry is submitted as a separate `SetDomainIsm` transaction.
 ```json
 {
   "type": "routing",
-  "routes": [
-    { "domain": 1000, "ism": { "type": "trustedRelayer", "relayer": "<Pubkey>" } },
-    { "domain": 2000, "ism": { "type": "test", "accept": false } }
-  ],
-  "defaultIsm": { "type": "pausable", "paused": false }
+  "domains": {
+    "1000": { "type": "trustedRelayer", "relayer": "<Pubkey>" },
+    "2000": {
+      "type": "multisigMessageId",
+      "validators": ["0xabc..."],
+      "threshold": 1
+    }
+  }
 }
 ```
 
-**`amountRouting`** — routes based on the token amount in `body[32..64]` (big-endian u256, TokenMessage format). Routes to `upper` if `amount >= threshold`, else `lower`.
+**`fallbackRouting`** — like `routing`, but falls back to a statically-configured ISM program (`fallback_ism`) when the message's origin domain has no explicit override. The fallback ISM must be another deployed composite ISM program.
+```json
+{
+  "type": "fallbackRouting",
+  "fallback_ism": "<base58 Pubkey of fallback composite ISM program>",
+  "domains": {
+    "1000": { "type": "trustedRelayer", "relayer": "<Pubkey>" }
+  }
+}
+```
+
+> `domains` is optional (omitted when empty). When no per-domain ISM matches, the fallback ISM's `VerifyMetadataSpec` / `VerifyAccountMetas` / `Verify` are called via CPI.
+
+**`amountRouting`** — routes based on the token transfer amount in `body[32..64]` (big-endian u256, TokenMessage format). Routes to `upper` if `amount >= threshold`, else `lower`. `threshold` is a decimal string representing the u256.
 ```json
 {
   "type": "amountRouting",
-  "threshold": "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000",
+  "threshold": "20000000000000000",
   "lower": { "type": "trustedRelayer", "relayer": "<Pubkey>" },
-  "upper": { "type": "multisigMessageId", "domainConfigs": [...] }
+  "upper": {
+    "type": "multisigMessageId",
+    "validators": ["0xabc..."],
+    "threshold": 1
+  }
 }
 ```
 
-> The `threshold` is a `"0x"`-prefixed 64-character hex string representing a 32-byte big-endian u256 (e.g. `1e18` = `0x0000...000de0b6b3a7640000`).
+> `threshold` is a plain decimal integer string (e.g. `"20000000000000000"` for 0.02 ETH in wei units). The value is a big-endian u256.
 
 #### Full example
 
+A `fallbackRouting` ISM that uses a per-domain multisig for origin 1000 and falls back to a trusted-relayer composite ISM for all other origins:
+
+```json
+{
+  "type": "fallbackRouting",
+  "fallback_ism": "4Nd1mBQtrMJVYVfKf2PX98YCKvsyfDXxsY7E3D4siqYb",
+  "domains": {
+    "1000": {
+      "type": "multisigMessageId",
+      "validators": ["0xabcdef1234567890abcdef1234567890abcdef12"],
+      "threshold": 1
+    }
+  }
+}
+```
+
+A 1-of-2 aggregation where one branch is a multisig and the other is a trusted relayer:
+
 ```json
 {
   "type": "aggregation",
   "threshold": 1,
-  "subIsms": [
+  "sub_isms": [
     {
-      "type": "routing",
-      "routes": [
-        {
-          "domain": 1000,
-          "ism": {
-            "type": "multisigMessageId",
-            "domainConfigs": [
-              {
-                "origin": 1000,
-                "validators": ["0xabcdef1234567890abcdef1234567890abcdef12"],
-                "threshold": 1
-              }
-            ]
-          }
-        }
-      ],
-      "defaultIsm": { "type": "test", "accept": false }
+      "type": "multisigMessageId",
+      "validators": ["0xabcdef1234567890abcdef1234567890abcdef12"],
+      "threshold": 1
     },
     {
       "type": "trustedRelayer",

rust/sealevel/client/README.md

@@ -28,10 +28,16 @@ serializable-account-meta = { path = "../../../libraries/serializable-account-me
 
 [dev-dependencies]
 hyperlane-test-utils = { path = "../../../libraries/test-utils" }
+hyperlane-sealevel-test-ism = { path = "../test-ism" }
+hyperlane-sealevel-multisig-ism-message-id = { path = "../multisig-ism-message-id", features = ["no-entrypoint"] }
+hyperlane-sealevel-test-send-receiver = { path = "../../test-send-receiver", features = ["test-client"] }
+ecdsa-signature = { path = "../../../libraries/ecdsa-signature" }
+multisig-ism = { path = "../../../libraries/multisig-ism" }
 solana-banks-interface.workspace = true
 tokio = { workspace = true, features = ["macros", "rt"] }
 solana-program-test.workspace = true
 solana-sdk.workspace = true
+spl-noop.workspace = true
 hex.workspace = true
 rand = "0.8.5"