Merge pull request #23 from etherspot/spec/complete-compliance

spec: complete Generic Relayer Architecture compliance

Author: ch4r10t33r

README.md

@@ -75,6 +75,8 @@ cargo build --release
 | `--db-path` | — | `./relayx_db` | RocksDB path |
 | `--config` | `RELAYX_CONFIG` | — | JSON config file path |
 | `--relayer-private-key` | `RELAYX_PRIVATE_KEY` | — | Hex-encoded signer key |
+| `--disable-simulation` | `RELAYX_DISABLE_SIMULATION` | `false` | Skip pre-flight simulation (use default gas limit) |
+| `--disable-multichain` | `RELAYX_DISABLE_MULTICHAIN` | `false` | Return `4212` for `relayer_sendTransactionMultichain` calls |
 
 Additional environment variables:
 
@@ -94,7 +96,12 @@ Additional environment variables:
   "log_level": "info",
   "relayerPrivateKey": "0x...",
   "feeCollector": "0x55f3a93f544e01ce4378d25e927d7c493b863bd6",
+  "feeCollectors": {
+    "1":   "0x55f3a93f544e01ce4378d25e927d7c493b863bd6",
+    "137": "0x66f3a93f544e01ce4378d25e927d7c493b863bd7"
+  },
   "defaultToken": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+  "disableMultichain": false,
   "rpcs": {
     "1":   "https://ethereum.publicnode.com",
     "137": "https://polygon-rpc.com"
@@ -116,6 +123,8 @@ Additional environment variables:
 }
 ```
 
+> **`feeCollectors`** (optional) — per-chain overrides for the fee collector address. Takes precedence over the global `feeCollector` value for the specified chain.
+
 ## JSON-RPC Methods
 
 All methods use JSON-RPC 2.0. The server listens on `POST /`.
@@ -134,7 +143,7 @@ Submit a single transaction for relay.
 | `payment` | `Payment` | ✅ | How the relayer fee is paid |
 | `to` | `string` | ✅ | Smart account (wallet) address |
 | `data` | `string` | ✅ | ABI-encoded `executeWithRelayer(...)` calldata |
-| `context` | `object` | — | Arbitrary metadata; `callbackUrl` is read from here |
+| `context` | `object` | — | Arbitrary metadata; `callbackUrl` and `expiry` are read from here |
 | `authorizationList` | `AuthorizationItem[]` | — | EIP-7702 authorization entries |
 | `taskId` | `string` | — | Client-provided 32-byte hex task ID (`0x`-prefixed, 66 chars) |
 
@@ -275,8 +284,8 @@ Query the status of a submitted transaction.
     "hash": "0x9b7bb827...",
     "receipt": {
       "blockHash":        "0xf19bbafd...",
-      "blockNumber":      "0xabcd",
-      "gasUsed":          "0xdef",
+      "blockNumber":      "43981",
+      "gasUsed":          "3567",
       "transactionHash":  "0x9b7bb827...",
       "logs": [
         {
@@ -361,7 +370,10 @@ Get current fee pricing for a token on a chain.
 | `chainId` | Chain the fee data applies to |
 | `token` | Token descriptor (`address`, `decimals`) |
 | `rate` | Tokens per 1 unit of native currency (e.g. USDC/ETH ≈ 2000.5); always `1.0` for native |
-| `gasPrice` | Current gas price in wei (hex string) |
+| `gasPrice` | Current gas price in wei (decimal string) |
+| `maxFeePerGas` | EIP-1559 max fee per gas in wei (decimal string, omitted on pre-EIP-1559 chains) |
+| `maxPriorityFeePerGas` | EIP-1559 max priority fee per gas in wei (decimal string, omitted on pre-EIP-1559 chains) |
+| `feeCollector` | Address clients should send payment tokens to (mirrors `relayer_getCapabilities`) |
 | `expiry` | Unix timestamp when this quote expires |
 | `minFee` | Minimum fee in token units (optional) |
 | `context` | Opaque signed quote context (optional) |
@@ -386,7 +398,10 @@ curl -X POST http://localhost:4937 \
     "chainId": "1",
     "token": { "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "decimals": 6 },
     "rate": 2000.5,
-    "gasPrice": "0x4a817c800",
+    "gasPrice": "20000000000",
+    "maxFeePerGas": "40000000000",
+    "maxPriorityFeePerGas": "1000000000",
+    "feeCollector": "0x55f3a93f544e01ce4378d25e927d7c493b863bd6",
     "expiry": 1741234867
   },
   "id": 1
@@ -434,7 +449,8 @@ Pass a `callbackUrl` inside `context` to receive a `POST` when the transaction s
   "to": "0x...",
   "data": "0x...",
   "context": {
-    "callbackUrl": "https://yourapp.com/webhook/relay-status"
+    "callbackUrl": "https://yourapp.com/webhook/relay-status",
+    "expiry": 1741234867
   }
 }
 ```
@@ -466,17 +482,28 @@ Callback failures are logged and silently dropped; they never affect the relay f
 
 ## Error Codes
 
-| Code | Name | Description |
+Full set of spec-defined error codes (per the [Generic Relayer Architecture spec](https://hackmd.io/T4TkZYFQQnCupiuW231DYw)):
+
+| Code | Name | Where raised |
 |------|------|-------------|
-| 4200 | Invalid Params | Missing or malformed request fields |
-| 4201 | Unsupported Chain | Chain ID not in relayer's config |
-| 4202 | Simulation Failed | `eth_call` reverted during pre-flight check |
-| 4203 | Insufficient Balance | Wallet balance too low to cover gas |
-| 4204 | Invalid Authorization List | Malformed EIP-7702 authorization entries |
-| 4205 | Unsupported Payment Token | ERC-20 token not in configured token list |
-| 4206 | Unsupported Capability | Payment type not supported |
-| 4207 | Task Not Found | No request found for given task ID |
-| 4214 | Duplicate Task ID | Client-provided task ID already in use |
+| `-32602` | Invalid Params | Missing or malformed request fields |
+| `4200` | Insufficient Payment | Fee-verification middleware: payment below required minimum |
+| `4201` | Invalid Signature | Signature-validation middleware: signer mismatch |
+| `4202` | Unsupported Payment Token | ERC-20 token not in configured token list |
+| `4203` | Rate Limit Exceeded | Rate-limiting middleware: per-address or per-key quota exceeded |
+| `4204` | Quote Expired | `context.expiry` is in the past at submission time |
+| `4205` | Insufficient Balance | Wallet native balance too low to cover gas cost |
+| `4206` | Unsupported Chain | Chain ID not in relayer's config |
+| `4207` | Transaction Too Large | Calldata exceeds 128 KB |
+| `4208` | Unknown Transaction ID | No request found for the given task ID |
+| `4209` | Unsupported Capability | Payment type not supported |
+| `4210` | Invalid Authorization List | Malformed EIP-7702 authorization entries |
+| `4211` | Simulation Failed | `eth_call` reverted during pre-flight check |
+| `4212` | Multichain Not Supported | `--disable-multichain` is set on this instance |
+| `4213` | Invalid Task ID | Client-provided `taskId` is not a valid 32-byte hex string |
+| `4214` | Duplicate Task ID | Client-provided `taskId` already has an associated job |
+
+> Codes `4200`, `4201`, and `4203` are available as `pub(crate)` helpers for operators adding auth or rate-limiting middleware; they are not raised by the core relay path itself.
 
 ---
 
@@ -533,7 +560,7 @@ Background Monitor (tokio::spawn)
 # Build
 cargo build --release
 
-# Run all tests (28 tests, ~20ms)
+# Run all tests (40 tests: 12 unit + 28 integration, ~20ms)
 cargo test
 
 # Lint

src/config.rs

@@ -67,6 +67,10 @@ pub struct Config {
     /// Sentry DSN for error tracking (optional)
     #[arg(long = "sentry-dsn", env = "SENTRY_DSN")]
     pub sentry_dsn: Option<String>,
+
+    /// Disable multichain transaction support (relayer_sendTransactionMultichain returns 4212)
+    #[arg(long = "disable-multichain", env = "RELAYX_DISABLE_MULTICHAIN")]
+    pub disable_multichain: bool,
 }
 
 impl Config {
@@ -138,6 +142,22 @@ impl Config {
             .map(|s| s.to_string())
     }
 
+    /// Returns the fee collector address for a specific chain.
+    /// Checks `{ "feeCollectors": { chainId: "0x..." } }` first, then falls back to the global
+    /// `feeCollector` value.
+    pub fn fee_collector_for_chain(&self, chain_id: &str) -> Option<String> {
+        if let Some(root) = self.get_json_config() {
+            if let Some(addr) = root
+                .get("feeCollectors")
+                .and_then(|m| m.get(chain_id))
+                .and_then(|v| v.as_str())
+            {
+                return Some(addr.to_string());
+            }
+        }
+        self.fee_collector()
+    }
+
     /// Returns Chainlink native token/USD aggregator address for a chain
     /// Expects JSON structure: { "chainlink": { "nativeUsd": { "1": "0x..." } } }
     pub fn chainlink_native_usd(&self, chain_id: &str) -> Option<String> {
@@ -306,6 +326,18 @@ impl Config {
             .unwrap_or(false)
     }
 
+    /// Returns true when multichain transactions are administratively disabled.
+    /// Operators can set `--disable-multichain`, `RELAYX_DISABLE_MULTICHAIN=true`, or
+    /// `{ "disableMultichain": true }` in the JSON config.
+    pub fn is_multichain_disabled(&self) -> bool {
+        if self.disable_multichain {
+            return true;
+        }
+        self.get_json_config()
+            .and_then(|v| v.get("disableMultichain").and_then(|s| s.as_bool()))
+            .unwrap_or(false)
+    }
+
     /// Get Sentry DSN from config.json or CLI/env
     pub fn get_sentry_dsn(&self) -> Option<String> {
         if let Some(cli_dsn) = self.sentry_dsn.as_ref().filter(|s| !s.is_empty()) {