KeeperHub / KeeperHub/keeperhub

feat(chains): add HyperEVM mainnet (chain 999) as a supported chain

Open
#2,473 1 comment 0 reactions 0 assignees View on GitHub
accepted confirmed enhancement
Dominant language
TypeScript
Stars
24
Forks
93
Avg merge
1d 4h
Merged PRs (30d)
253

Description

### Before filing

- [x] I searched open and closed issues for this proposal.
- [x] I checked the docs and the current behaviour on `staging`.
- [x] This is one change, not several. (Several means several issues.)

### Reason: what you cannot do today

KeeperHub has no HyperEVM support. Chain 999 is not in `CHAIN_CONFIG`, the chain seed, the explorer configs or the token seed, so a workflow cannot select HyperEVM as a network. The same gap blocks reading a contract, running an event or block trigger, and holding a stablecoin balance there.

The product already tells users HyperEVM is coming:

- The Hyperliquid protocol entry (`protocols/hyperliquid.ts`) is `hubOnly` with no contracts or actions. Its description says "On-chain HyperEVM read/write actions are coming soon", and its comment says to add real contracts and actions "once HyperEVM on-chain support lands".
- The Hyperliquid plugin covers HyperCore through the Info REST API, but nothing on-chain.

That on-chain support starts with the chain. This issue adds the chain itself; it does not add Hyperliquid protocol actions.

Checked on `staging` at `d963a59`: no reference to HyperEVM or chain 999 in `lib/rpc/rpc-config.ts`, `scripts/seed/seed-chains.ts` or `scripts/seed/seed-tokens.ts`, and no open issue or PR for it.

### Reason: what the workaround costs

There is no workaround inside KeeperHub. `getChainIdFromNetwork` rejects an unknown network and there is no chain row to route to, so the only option is running HyperEVM automation somewhere else.

### Scope: what this touches, and what it does not

Touches, following the shape of the Hoodi chain PR (#2443) and `.claude/commands/add-chain.md`:

- **`lib/rpc/rpc-config.ts`:** public defaults and a `CHAIN_CONFIG[999]` entry with jsonKey `hyperevm-mainnet`.
- **`scripts/seed/seed-chains.ts`:** the chain row (name "HyperEVM", symbol HYPE, aliases), an Etherscan V2 explorer template for hyperevmscan.io, and the `chainToDefaultIdMap` entry.
- **`scripts/seed/seed-tokens.ts`:** USDC and USDT0, each verified on-chain.
- **Wallet token list:** HyperEVM in the independent-token-list sets (`components/overlays/wallet/chain-utils.ts`, `app/api/supported-tokens/route.ts`). Its stablecoin lineup does not mirror Ethereum's (no USDS), which is the case those sets exist for.
- **Network aliases:** `hyperevm` and `hyperevm-mainnet` resolve to 999, documented in `docs/api/chains.md`. Deliberately not `hyperliquid`: that name also covers HyperCore, the non-EVM L1 the Hyperliquid plugin reads.
- **Unit tests:** config, aliases and seed coverage.

Does not touch:

- **HyperEVM testnet (998).** Its RPC works (`https://rpc.hyperliquid-testnet.xyz/evm` answers `0x3e6`), but I found no explorer API for it: Etherscan V2's chain list has 999 and not 998, and Routescan and purrsec did not serve it. Adding it without explorer config would leave ABI auto-fetch and links broken, so it is a follow-up question below.
- **Hyperliquid protocol actions** (lifting `hubOnly`). A separate issue, once the chain exists.
- **Gas strategy overrides.** Measurements below show the defaults fit.
- **Safe support, sponsorship and big blocks.** Out of scope.

One change: the chain row, its RPC config, explorer and tokens are only useful together, which is why the add-chain command treats them as one unit.

### Plan: what you propose

Every value below was verified live on 2026-09-15.

**RPC (HTTP).**
- Primary `https://rpc.hyperliquid.xyz/evm`, the official public endpoint: `eth_chainId` returns `0x3e7` (999) and blocks advance.
- Fallback `https://hyperliquid.drpc.org`, which also answers 999. Two more endpoints answered 999 too (`rpc.hypurrscan.io`, `hyperliquid-json-rpc.stakely.io`), as alternatives if you prefer a different fallback.

**RPC (WebSocket).** Event and block triggers need a WSS endpoint.
- The official endpoint does not serve WebSocket (HTTP 405).
- `wss://hyperliquid.drpc.org` does, and I checked it beyond the handshake:
- `eth_subscribe newHeads` delivered 17 new-head notifications in 25 s;
- `eth_getLogs` over the socket returned three real USDC `Transfer` logs from the last 25 blocks;
- a Multicall3 `eth_call` over the socket succeeded.
- I note this because `rpc-config.ts` records dRPC's free tier rejecting `eth_subscribe` for Robinhood; on HyperEVM it does not.
- Proposed as `publicWssDefault`. Deployed environments would still normally set WSS through `CHAIN_RPC_CONFIG`.

**Explorer.** Etherscan V2 lists chain 999 ("HyperEVM Mainnet", `https://hyperevmscan.io/`, `apiurl https://api.etherscan.io/v2/api?chainid=999`, status 1), so the template uses `explorerApiType: "etherscan"` like the other V2 chains.

**Stablecoins** (`symbol()`, `name()`, `decimals()` and `totalSupply()` read over the official RPC):

| Token | Address | symbol / decimals | Supply |
|-------|---------|-------------------|--------|
| USDC | `0xb88339CB7199b77E23DB6E890353E22632Ba630f` | USDC / 6 | about 6.36B |
| USDT0 | `0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb` | USD₮0 / 6 | about 85.6M |

USDe, USDHL and feUSD also resolve on-chain. I would track the two above, as the chain's two largest dollar stablecoins, and leave the others for later.

**Multicall3** is deployed at the canonical `0xcA11bde05977b3631167028862bE2a173976CA11`, so the batched state-threshold sampling works as on other chains.

**Gas.**
- Latest block: gas limit 3,000,000, base fee 0.1 gwei.
- `eth_maxPriorityFeePerGas` returns 0.
- `eth_feeHistory` rewards ranged from 0 to 0.55 gwei at p25 to p99, with blocks at most about 31% full.
- The default strategy covers this, so I am not adding a gas override.

**Known limit, for the docs.** HyperEVM's regular blocks cap at 3M gas, and larger transactions go into separate "big blocks". An automation transaction above 3M gas (for example a large deployment) will not land in a regular block; ordinary reads, transfers and contract calls are far below it.

**Status.** Seed the chain as `experimental`, as 0G and Robinhood Chain are, until it has run in a deployed environment.

**Verification plan.**
- Unit tests for the config, aliases and seed entries.
- Run both seeds locally, and check that `/api/supported-tokens?chainId=999` returns USDC and USDT0.
- Screenshot the wallet modal and the network selector showing HyperEVM.
- Run a read-contract workflow against HyperEVM in a local instance.

**Questions for triage:**

1. Is `wss://hyperliquid.drpc.org` acceptable as the public WSS default, or would you rather leave WSS to `CHAIN_RPC_CONFIG` only?
2. Should the testnet (998) wait for an explorer API, or go in with RPC only?
3. Any objection to `experimental` status for the first release?

### Plan: alternatives you considered

- **Adding Hyperliquid protocol actions first.** Not possible without the chain row.
- **Using a third-party RPC as primary.** Rejected: the official endpoint is up and is the natural default; third parties serve as fallback.
- **No WSS default.** This would leave event and block triggers unavailable on any install without a configured WSS URL, which is the Robinhood situation. It was avoidable here because a working public socket exists.

### Scope: compatibility

- [ ] Changes an existing response shape, status code, CLI flag, or default.
- [ ] Adds, removes, or upgrades a dependency.
- [ ] Changes database schema or requires a migration.
- [ ] Touches authentication, permissions, validation, or spend limits.
- [ ] Changes pricing, plan limits, or anything a user is charged.

Contributor guide

Open the contributing guide

Research direction

Start with .claude/commands/add-chain.md and the shape of Hoodi chain PR #2443. Review lib/rpc/rpc-config.ts, scripts/seed/seed-chains.ts, scripts/seed/seed-tokens.ts, components/overlays/wallet/chain-utils.ts, app/api/supported-tokens/route.ts, and docs/api/chains.md, then locate the existing config, alias, and seed tests. Done means HyperEVM is selectable, seeded with its explorer and tokens, supported by the wallet and API, and both seeds and the local read-contract workflow pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design, blockchain, frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.