S3-E.3: hedera dual-protocol adapter (Mirror REST + JSON-RPC Relay)

Hedera 是天然双协议链 — Mirror REST 提供账户/balance/transaction 查询,
JSON-RPC Relay (Hashio) 提供 EVM-compat eth_* 方法。原 `rest` family adapter
不支持单 chain 内 per-method 协议路由,所以 mixed mode 跑 eth_getBalance/
eth_call 时会 ValueError(method not in _meta.rest_paths)。

## 改动

(1) 新建 `tools/chain_adapters/hedera_dual.py` — 第 7 个 adapter family。
    - per-method 路由:eth_*/net_*/web3_*/debug_*/trace_* → JSON-RPC POST
      到 _meta.json_rpc_url;其他 path-style key → REST GET/POST
    - delegate to RestAdapter + JsonRpcAdapter,不重复 logic
    - health_check 复用 REST 侧;parse_block_height 两侧 best-effort

(2) `tools/chain_adapters/base.py` — import chain 加 hedera_dual

(3) `config/chains/hedera.json`:
    - adapter_family: rest → hedera_dual(留 adapter_family_upgraded_at 审计)
    - 加 _meta.json_rpc_url = https://mainnet.hashio.io/api
    - 保留全 5 mixed method(3 Mirror REST + eth_getBalance + eth_call)

(4) `tests/test_chain_adapters.py`:
    - test_factory_registers_six → seven_families;expected set 含 hedera_dual
    - KNOWN_BROKEN_CLI 移除 hedera 条目,assert len 14 → 13
    - _sample_address_for 加 hedera_dual → "0.0.2"(原生 3-part ID)

## 验证

L1:python3 tests/test_chain_adapters.py → 10/10 PASS
    - healthy 22 → 23(hedera 进集合)
    - broken 14 → 13
    - 7 families registered

L3 替代:bash tools/target_generator.sh BLOCKCHAIN_NODE=hedera RPC_MODE=mixed
    - 4 个 account × 5 method 全成功,exit=0
    - 实际生成 vegeta target:
      * Mirror REST GET → mainnet-public.mirrornode.hedera.com/api/v1/accounts/0.0.2
      * Mirror REST GET → mainnet-public.mirrornode.hedera.com/api/v1/balances?account.id=0.0.98
      * Mirror REST GET → mainnet-public.mirrornode.hedera.com/api/v1/transactions/0.0.800
      * JSON-RPC POST  → mainnet.hashio.io/api  body={"method":"eth_getBalance","params":["0.0.801"]}
    - 真双协议路由生效

L3 single mode:4 account × 1 method (GET /api/v1/accounts/{addr}) 全成功

## 自审 E1-E5

E1 (调研先行):基于 docs/zh/chains/14-hedera.md 调研(E1-E15 实测过 Mirror + Hashio),
              endpoint URL 现场 curl HTTP 200 复验。
E2 (无降级/未 defer):5 method 全保留,不砍 mixed,无 KNOWN_BROKEN_MIXED ledger。
E3 (实证):L1 10/10 + L3 真路径 vegeta target 文件生成 + body base64 decode 验证。
E4 (parallel-entry-trap):无新平行入口,新 adapter 用 composition (RestAdapter +
                          JsonRpcAdapter delegation),不复制 logic。
E5 (broken set 单调递减):14 → 13,hedera 进 audit healthy 集合。

## 显式 defer(非降级,新 wave 处理)

(a) cli.py L40 读 `params` 字段应该是 `param_formats` — 全链 bug,影响所有
    JSON-RPC chain 的 param shape(eth_getBalance 应为 [addr, "latest"]
    现 [addr])。本 PR scope = hedera_dual adapter,不污染 commit。
(b) hedera eth_* 实际生产需把 3-part ID (0.0.N) 转 EVM 地址 (0x...0N),
    fetch_active_accounts 端处理,留 S4。

ledger: KNOWN_BROKEN_CLI baseline 16 → S3-E.1 aptos -1 → S3-E.2 algorand -1
        → S3-E.3 hedera -1 → 13 剩

Author: StayHungryStayFoolish

config/chains/hedera.json

@@ -17,8 +17,8 @@
     "tx_batch_size": "ACCOUNT_TX_BATCH_SIZE"
   },
   "rpc_methods": {
-    "single": "mirror_account_query",
-    "mixed": "mirror_account_query,mirror_balance_query,mirror_tx_lookup,eth_getBalance,eth_call"
+    "single": "GET /api/v1/accounts/{addr}",
+    "mixed": "GET /api/v1/accounts/{addr},GET /api/v1/balances?account.id={addr},GET /api/v1/transactions/{addr},eth_getBalance,eth_call"
   },
   "rpc_url": "LOCAL_RPC_URL",
   "system_addresses": [
@@ -54,7 +54,18 @@
     ],
     "original_notes": "双协议 Mirror REST + JSON-RPC; 3-part account ID (shard.realm.num); tinybar vs weibar 单位换算; gRPC 不测",
     "adapter_required": true,
-    "adapter_family": "rest",
-    "adapter_family_assigned_at": "2026-05-24T05:24:00.591042Z"
+    "adapter_family": "hedera_dual",
+    "adapter_family_assigned_at": "2026-05-24T05:24:00.591042Z",
+    "adapter_family_upgraded_at": "2026-05-24T18:00:00Z",
+    "adapter_family_upgrade_note": "S3-E.3: was 'rest' (broken — couldn't route eth_*); upgraded to dual-protocol adapter that routes per-method between Mirror REST and JSON-RPC Relay.",
+    "json_rpc_url": "https://mainnet.hashio.io/api",
+    "rest_paths": {
+      "GET /api/v1/accounts/{addr}": {"method": "GET", "path": "/api/v1/accounts/{address}"},
+      "GET /api/v1/balances?account.id={addr}": {"method": "GET", "path": "/api/v1/balances?account.id={address}"},
+      "GET /api/v1/transactions/{addr}": {"method": "GET", "path": "/api/v1/transactions/{address}"},
+      "GET /api/v1/blocks?limit=1&order=desc": {"method": "GET", "path": "/api/v1/blocks?limit=1&order=desc"},
+      "GET /api/v1/network/supply": {"method": "GET", "path": "/api/v1/network/supply"}
+    },
+    "health_probe": {"method": "GET", "path": "/api/v1/network/supply", "parse_jq": ".timestamp"}
   }
 }

tests/test_chain_adapters.py

@@ -33,12 +33,12 @@ def _fail(msg: str):
 # ─────────────────────────────────────────────────────────────────────────────
 # Test 1: Factory registration — 6 families
 # ─────────────────────────────────────────────────────────────────────────────
-def test_factory_registers_six_families():
+def test_factory_registers_seven_families():
     print("\n[1] Factory registration")
     fams = list_adapters()
-    expected = {"jsonrpc", "rest", "tendermint", "bitcoin_jsonrpc", "substrate", "ogmios"}
+    expected = {"jsonrpc", "rest", "tendermint", "bitcoin_jsonrpc", "substrate", "ogmios", "hedera_dual"}
     assert set(fams) == expected, f"expected {expected}, got {fams}"
-    _ok(f"6 families registered: {sorted(fams)}")
+    _ok(f"7 families registered: {sorted(fams)}")
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -343,7 +343,6 @@ def test_evm_compat_5chains_standard_enum():
     # F1: rpc_methods.single picked a health-probe (no address) instead of
     #     a real benchmark method. Fix = pick a method from param_formats
     #     that takes an address. Pure chain-template edit, no adapter work.
-    "hedera":    ("F1", "S3-E", "single='mirror_account_query' is logical name, no real path; use 'mirror_balance_query' or 'eth_getBalance'"),
     "tezos":     ("F1", "S3-E", "single='GET /chains/main/blocks/head/header' has no address; use '/contracts/{addr}/balance'"),
     "ton":       ("F1", "S3-E", "single='getMasterchainInfo' is health-probe; use 'getAddressBalance'"),
     "kusama":    ("F1", "S3-C", "single='chain_getHeader' has no address; use 'system_account' or similar"),
@@ -368,7 +367,7 @@ def test_evm_compat_5chains_standard_enum():
     "acala":     ("F3", "S3-C", "family=substrate; single='system_chain' has no address; pick eth_getBalance from param_formats"),
 }
 
-assert len(KNOWN_BROKEN_CLI) == 14, f"KNOWN_BROKEN_CLI must have exactly 14 entries (baseline 16 minus aptos S3-E.1 minus algorand S3-E.2), got {len(KNOWN_BROKEN_CLI)}"
+assert len(KNOWN_BROKEN_CLI) == 13, f"KNOWN_BROKEN_CLI must have exactly 13 entries (baseline 16 minus aptos S3-E.1 minus algorand S3-E.2 minus hedera S3-E.3), got {len(KNOWN_BROKEN_CLI)}"
 
 
 def _sample_address_for(family: str) -> str:
@@ -385,6 +384,11 @@ def _sample_address_for(family: str) -> str:
         "tendermint":      "cosmos1abc",
         "ogmios":          "addr1q9adlx6mh0dr8xs0gpcm9nz5pqe5w2hzfx5l8qj5",
         "rest":            "TESTADDR123",
+        # hedera_dual: native 3-part account ID; L1 only asserts the address
+        # string appears in url-or-body, not EVM semantics. Production
+        # fetch_active_accounts must convert 0.0.N → EVM 0x...0N for eth_*
+        # routes — out of scope for L1.
+        "hedera_dual":     "0.0.2",
     }.get(family, "TESTADDR123")
 
 
@@ -478,7 +482,7 @@ def test_cli_build_target_all_36_chains():
 # ─────────────────────────────────────────────────────────────────────────────
 def main():
     tests = [
-        test_factory_registers_six_families,
+        test_factory_registers_seven_families,
         test_all_36_chains_resolve,
         test_baseline_8_vegeta_byte_equality,
         test_parse_block_height_per_family,

tools/chain_adapters/base.py

@@ -141,4 +141,4 @@ def list_adapters() -> list[str]:
 
 
 # Trigger registration of all subclasses
-from . import jsonrpc, rest, tendermint, bitcoin_jsonrpc, substrate, ogmios  # noqa: E402, F401
+from . import jsonrpc, rest, tendermint, bitcoin_jsonrpc, substrate, ogmios, hedera_dual  # noqa: E402, F401

tools/chain_adapters/hedera_dual.py

@@ -0,0 +1,119 @@
+"""HederaDualAdapter — Hedera 双协议 adapter (Mirror REST + JSON-RPC Relay).
+
+Hedera 是天然双协议链:
+  - Mirror REST  https://mainnet-public.mirrornode.hedera.com  (账户/balance/tx)
+  - JSON-RPC Relay https://mainnet.hashio.io/api               (EVM-compat eth_*)
+
+method 路由规则 (per-request):
+  - method 以 'eth_' 开头 或 等于已知 JSON-RPC 方法名 → 走 JSON-RPC POST + json body
+    rpc_url 取 _meta.json_rpc_url (chain template 显式声明)
+  - 否则按 REST 路径处理 (method key 必须在 _meta.rest_paths 里)
+    rpc_url 取 build_vegeta_target 传入的 rpc_url (即 LOCAL_RPC_URL = Mirror REST)
+
+为什么不直接复用 RestAdapter+JsonRpcAdapter?
+  ChainAdapter ABC + factory 是 chain→family 1:1 映射。同一 chain 单 request 内
+  按 method 分协议路由,必须新 family。
+
+测试 invariant (L1-CLI):address 必须出现在生成的 vegeta target 的 url 或 body 里。
+  REST 侧 → address 进 path → 进 url
+  JSON-RPC 侧 → address 进 params[0] → 进 body
+"""
+from __future__ import annotations
+import json
+import os
+import re
+from typing import Optional
+
+from .base import ChainAdapter, register, _vegeta_get, _vegeta_post_json, _try_int
+from .rest import RestAdapter, _CHAINS_DIR
+from .jsonrpc import JsonRpcAdapter
+
+
+_JSONRPC_METHOD_RE = re.compile(r"^(eth_|net_|web3_|debug_|trace_)")
+
+
+def _is_jsonrpc_method(method: str) -> bool:
+    """Decide if a method name should be routed to the JSON-RPC Relay.
+
+    True for eth_* / net_* / web3_* / debug_* / trace_* (standard EVM
+    JSON-RPC namespaces). False for REST path-style keys like
+    'GET /api/v1/accounts/{addr}'.
+    """
+    return bool(_JSONRPC_METHOD_RE.match(method))
+
+
+@register("hedera_dual")
+class HederaDualAdapter(ChainAdapter):
+    """Per-request protocol routing for Hedera Mirror REST + JSON-RPC Relay."""
+
+    def __init__(self):
+        # Delegate the two protocol concerns to the existing single-protocol
+        # adapters — no logic duplication, only routing.
+        self._rest = RestAdapter()
+        self._jsonrpc = JsonRpcAdapter()
+        self._chain_cache: dict[str, dict] = {}
+
+    def _load_chain(self, chain_name: str) -> dict:
+        if chain_name not in self._chain_cache:
+            with open(_CHAINS_DIR / f"{chain_name}.json") as f:
+                self._chain_cache[chain_name] = json.load(f)
+        return self._chain_cache[chain_name]
+
+    def _get_chain_name(self) -> str:
+        chain_name = os.environ.get("BLOCKCHAIN_NODE", "").lower()
+        if not chain_name:
+            raise RuntimeError("HederaDualAdapter requires BLOCKCHAIN_NODE env var")
+        return chain_name
+
+    def _get_jsonrpc_url(self, chain_name: str) -> str:
+        """JSON-RPC url comes from chain template _meta.json_rpc_url.
+
+        Required because LOCAL_RPC_URL (the single env var used as rpc_url
+        for this run) points at Mirror REST; JSON-RPC traffic needs a
+        separate endpoint (Hashio relay for hedera).
+        """
+        tpl = self._load_chain(chain_name)
+        url = tpl.get("_meta", {}).get("json_rpc_url")
+        if not url:
+            raise ValueError(
+                f"hedera_dual chain {chain_name}: _meta.json_rpc_url not set; "
+                f"required for routing eth_*/net_*/web3_* methods."
+            )
+        return url
+
+    # ─── ABC contract ──────────────────────────────────────────────────────
+
+    def build_vegeta_target(
+        self, method: str, address: str, rpc_url: str, param_format: str = "",
+    ) -> dict:
+        chain_name = self._get_chain_name()
+        if _is_jsonrpc_method(method):
+            jsonrpc_url = self._get_jsonrpc_url(chain_name)
+            return self._jsonrpc.build_vegeta_target(
+                method=method, address=address,
+                rpc_url=jsonrpc_url, param_format=param_format,
+            )
+        # REST path-style: delegate to RestAdapter (uses BLOCKCHAIN_NODE +
+        # _meta.rest_paths from chain template, same as before)
+        return self._rest.build_vegeta_target(
+            method=method, address=address,
+            rpc_url=rpc_url, param_format=param_format,
+        )
+
+    def health_check_request(self, rpc_url: str) -> dict:
+        """Health probe uses REST side (_meta.health_probe).
+
+        Mirror REST is the primary observability surface; JSON-RPC liveness
+        is an orthogonal concern. If both must be probed, run two probes
+        externally (eth_blockNumber against json_rpc_url).
+        """
+        return self._rest.health_check_request(rpc_url)
+
+    def parse_block_height(self, response_text: str) -> Optional[int]:
+        """Best-effort: try REST shape first (.block_height / .blocks[0].number),
+        then JSON-RPC shape (.result as hex or int).
+        """
+        h = self._rest.parse_block_height(response_text)
+        if h is not None:
+            return h
+        return self._jsonrpc.parse_block_height(response_text)