Token bridging architecture

The technical companion to Token bridging on Elysium: the full contract-level map of how tokens move between Elysium, HyperEVM, and HyperCore. It covers the system architecture, per-leg sequence diagrams, the address-derivation mechanics behind the 1:1 mirror guarantee, and the invariants and trust model.

The practical flow guides show how to call each leg: Bridging HyperEVM tokens to Elysium, Bridging Elysium tokens to HyperEVM, and HyperCore bridging via deposit wallets.

Elysium is pre-launch: all contract addresses — Elysium-side and the deposit-wallet family alike — arrive at launch, and details may be refined before mainnet. HyperCore's native linkage mechanism (spot deploy, EVM linking, sendAsset) is live Hyperliquid protocol behavior today.

1. Design principles

• Adapters implement only the surface their bridge calls. The deposit wallet emits the one Transfer log HyperCore parses; the bridge wallet implements the three-member surface the bridge gateway calls. Neither is an ERC-20.
• Native tokens need zero bridge code. No interface conformance, no mint authority granted to anything, no wrapping. Holders always hold the original asset on its home chain.
• Per-token isolation. Every wallet and mirror serves exactly one token; a misconfigured or malicious pair can only affect its own users.
• Deposits fail closed, exits fail open. Entry paths re-validate everything and revert before funds move; payout paths never depend on an oracle or precompile.
• Retryables mean delay, not loss. A reverting finalization leaves the message re-executable.

2. Contract inventory

The deployment posture matches the production bridge deployments of the Arbitrum Orbit rollup stack Elysium runs on: the factories run behind transparent upgradeable proxies, and every wallet and mirror is a clone behind a per-chain beacon — the same shape the canonical bridge uses for its standard child tokens (one beacon upgrade re-points a chain's fleet; for the deposit wallets that is also the compatibility lever for HyperCore's precompile surface). Address derivation does not depend on byte-identical builds: the clone creation code is constant and argless, each factory is configured at initialization with the other chain's clone creation-code hash read off its deployed proxy factory, and both factories expose the hashes (l2WalletInitCodeHash() / l1MirrorInitCodeHash()) as publicly checkable views — agreement holds by construction (section 5).

3. System architecture

The diagram shows all three legs side by side:

• the Core linkage: a HyperEVM token escrowed in its deposit wallet, credited and debited by HyperCore itself;
• the mirror bridge for Elysium-native T: locked in ElysiumBridgeWallet, minted as T′ on HyperEVM;
• the canonical bridge for HyperEVM-native U: locked in the standard L1ERC20Gateway, minted as a 1:1 StandardArbERC20 representation on Elysium (entirely upstream code).

The mirror bridge is the canonical bridge run in the opposite direction.

4. The Core linkage (HyperEVM ↔ HyperCore)

The wallet, not the token, is the HyperCore-linked EVM contract (the Circle/USDC pattern). It escrows the real underlying 1:1 and exposes only the surface HyperCore's log parsing requires. Invariant: wallet escrow == Core circulating supply outside the system address, scaled by evmExtraWeiDecimals (see Amounts & decimals).

Every deposit re-validates the linkage live before funds move: the wallet must be the token's linked EVM contract, the scaled credit must fit HyperCore's u64 and alignment bounds, the per-block credit total must fit the system address's live balance, and the escrow delta must be exact. Entries therefore fail closed. Revert-level detail lives in HyperCore bridging via deposit wallets.

Deposit (HyperEVM → HyperCore)

Exit (HyperCore → HyperEVM)

This is not an EVM transaction from the user: they sign a sendAsset action to the token's system address (0x20‖index), and HyperCore drives the payout.

Funds arrive at the signer's own address. There is no third-party recipient in this direction (unlike depositFor on the way in).

Factory and beacon structure

predictWallet enables the deploy-first ceremony (request the Core link against a predicted address, deploy later). WalletDeployed events + walletFor are the on-chain registry, and a wallet is canonical iff tokenInfo(index).evmContract == wallet. createWallet rejects HYPE's token index, because its system address is special-cased to 0x2222…2222 rather than following the derivation wallets assume. The EVM link, once finalized, is permanent.

5. The mirror bridge (Elysium ↔ HyperEVM)

The exact mirror of the canonical bridge: canonical tokens lock on the parent and mint a representation on the child, while Elysium-native tokens lock on Elysium and mint T′ on HyperEVM. The gateways and router are unmodified upstream token-bridge code from the rollup stack; the parent-side L1ReverseCustomGateway is the same contract family the stack's flagship governance token runs in production. Retryable funding rides plain msg.value HYPE on every call, and there are no fee-token approvals anywhere. The bespoke pieces are the two per-token contracts and the factory pair that deploys them:

• ElysiumBridgeWallet (Elysium): registered as the "child token" under a dedicated stock L2CustomGateway. bridgeBurn pulls the native token into escrow (this requires the user's approval, the one bridge-specific step in the product), bridgeMint releases it, and l1Address() returns T′. It deliberately has no ERC-20 surface, so a misregistration to an escrow-type gateway fails closed.
• ElysiumMirrorToken (HyperEVM): T′, a plain ERC-20 to everyone except the reverse gateway, which alone may mint and burn. Uncapped at the contract level; supply is bounded by what the bridge finalizes against locked escrow. bridgeBurn is unilateral (no allowance), the same authority every canonical gateway token grants its gateway.

Invariant: T locked in ElysiumBridgeWallet == totalSupply(T′).

Derivation mechanics: How 1:1 is enforced

Both per-token contracts deploy at CREATE2 addresses derived from identity, not chosen by callers:

The two factories pin each other's identity — the counterpart factory, its beacon-proxy factory, and that factory's constant clone creation-code hash — at initialization, so each chain can compute the other chain's addresses with no cross-chain call: a child's address commits to the clone creation code and the deploying factory's identity, never to an implementation build. ElysiumBridgeFactory.expectedL1Mirror(token) reads the token's live name()/symbol()/decimals() on Elysium, where the metadata is authoritative, and derives the one mirror those values produce on HyperEVM. ElysiumMirrorFactory.expectedL2Wallet(mirror) derives the Elysium wallet the same way. Registration never accepts a caller-supplied counterpart address.

The 1:1 guarantee follows from three facts composing:

1. Mirror supply requires wallet escrow. The bridge mints T′ only when the child gateway has locked the native token in the wallet, and a withdrawal against a wallet address with no code fails closed (TOKEN_NOT_DEPLOYED).
2. A CREATE2 address commits to its deployer. The clone factory keys every deployment salt by its caller, so only ElysiumBridgeFactory can ever place code at any wallet address the derivation produces.
3. The factory only deploys the live-metadata pair. createL2Wallet(token) derives the mirror from the token's current on-chain metadata and deploys the wallet bound to that mirror alone.

A mirror created with any other metadata tuple is a different mirror at a different address whose wallet is underivable from any real token state. It can exist and even complete registration, but its supply remains zero permanently. Canonical resolution is therefore on-chain: expectedL1Mirror(token) on Elysium, and factory provenance (elysiumTokenOf(mirror) set) plus totalSupply() > 0 on HyperEVM. Tokens with owner-mutable metadata produce one pair per metadata snapshot (the live-metadata pair is canonical). Derivation integrity across the two factory deployments is publicly checkable by comparing l2WalletInitCodeHash() / l1MirrorInitCodeHash() across both chains — each value is either the local proxy factory's live constant or a configured snapshot of the remote one, so a mismatch cannot arise from rebuilds.

Withdraw (Elysium → HyperEVM): Lock T, mint T′

Deposit back (HyperEVM → Elysium): Burn T′, release T

Registration

Registration is keyed on the caller upstream (NOT_ARB_ENABLED guard): a token can only register itself, and the binding is permanent (NO_UPDATE_TO_DIFFERENT_ADDR: a repeat call must name the same wallet and merely re-sends the retryables). The mirror's registerTokenOnL2 is callable only by its registrar, the factory, and the factory passes its derived expectedL2Wallet, so no party can bind a mirror to a foreign wallet. The mirror answers the gateway/router isArbitrumEnabled callbacks with 0xb1 only during its own registration call, closing enablement at all other times.

Fallback (gateway-owner only): forceRegisterTokenToL2 + setGateways, which skip the token callbacks entirely.

Timing model. The HyperEVM-side state (gateway binding + router route) is written synchronously in the registration transaction; the two Elysium-side writes arrive as independent retryables that normally auto-execute within a minute but can individually be delayed (claimable, re-executable by anyone) or expire. Every in-between state fails safe — deposits against an unregistered wallet bounce back automatically, and routed withdrawals revert until the Elysium route lands — with one exception worth engineering around: a mirror with no route on a router yet falls through to that chain's default standard gateway, where a deposit silently escrows and mints an unrelated standard representation instead of reverting (recoverable by withdrawing it back, but a look-alike-token hazard). The recovery for any lost retryable is an identical-argument re-registration, which re-sends both messages. Hence the integration rule in section 8: confirm getGateway resolves to the dedicated gateway on both routers before treating a pair as open.

6. The canonical bridge (HyperEVM → Elysium)

The standard lock-and-mint leg for HyperEVM-native tokens: entirely upstream contracts, permissionless for any ERC-20. The token locks in the standard L1ERC20Gateway on HyperEVM and a 1:1 StandardArbERC20 representation is minted on Elysium by L2ERC20Gateway; burning the representation releases the escrow. The first-ever deposit of a token auto-deploys its child counterpart at the deterministic address L2GatewayRouter.calculateL2TokenAddress reports. This is the template the mirror bridge runs in the opposite direction.

The one issuer-relevant rule: gateway assignment is permanent after first use. A token that wants custom bridge behavior must register a custom gateway before its first standard-gateway deposit; a token that has used the standard gateway can never be re-pointed. For plain bridging there is nothing to do at all.

Both directions follow the mirror-bridge sequences in section 5 with the roles reversed (parent escrow instead of parent mint), and the flow-level call detail is in Bridging HyperEVM tokens to Elysium.

Invariant (upstream-enforced): U locked in L1ERC20Gateway ≥ totalSupply(rep).

7. Composed lifecycle

T′ is an ordinary HyperEVM ERC-20 to the deposit-wallet machinery, so the mirror bridge composes into the Core linkage with no special casing. For a graduating T′, the HIP-1 genesis parks the chosen max supply at the system address, and the deposit wallet's per-block supply guard is the capacity backstop. The full issuer ceremony (ticker auction → genesis → link → listing) is HyperCore spot deployment. HyperEVM-native tokens compose the other way with the same building blocks: Core linkage onto an order book directly, canonical bridge onto Elysium.

8. Resolving a token's leg

Integrations (wallets, frontends, indexers) can classify any token and derive its route entirely on one chain — no cross-chain queries. The routers key every route by the HyperEVM-side token address (l1Key below); the Elysium router keeps its own synchronized copy of the mapping, and each chain's bridge factory registers the tokens native to it. So resolution on Elysium is always the same two steps: resolve the token's L1 address, then drive the router with it — identically for both asset classes.

On Elysium, given any token:

// Step 1 — resolve the token's L1 (HyperEVM-side) address, the route key for
// every router call. Exactly one of these two answers:
address l1Key;
try IArbToken(token).l1Address() returns (address l1) {
    // Canonical representation? The rep carries a back-pointer — validate it
    // with the LOCAL router round trip (never trust the pointer alone).
    if (IGatewayRouter(ELYSIUM_ROUTER).calculateL2TokenAddress(l1) == token) l1Key = l1;
} catch {} // no back-pointer: not a rep
if (l1Key == address(0)) {
    // Elysium-native — the bridge factory derives its one L1 mirror:
    l1Key = IElysiumBridgeFactory(BRIDGE_FACTORY).expectedL1Mirror(token);
    // reverts: token lacks IERC20Metadata — not bridgeable.
    address wallet = IElysiumBridgeFactory(BRIDGE_FACTORY).l2WalletFor(token);
    // wallet == 0: unpaired — run the one-time setup first.
    // wallet != 0: paired — approve the token to `wallet` before withdrawing.
}

// Step 2 — the same router calls for both classes, keyed by l1Key:
address gateway = IGatewayRouter(ELYSIUM_ROUTER).getGateway(l1Key);
IGatewayRouter(ELYSIUM_ROUTER).outboundTransfer(l1Key, to, amount, "");

The only per-class difference is the approval target (rep: none; native: the escrow wallet). Before using the routed path for a mirror pair, confirm the registration has propagated: getGateway(l1Key) must equal the bridge's dedicated gateway (the published address) rather than the default gateway — on both routers, since the two registration retryables land independently. A default-gateway answer means the route hasn't landed there yet; proceeding anyway does not revert but routes the mirror through the standard bridge, minting an unrelated look-alike representation (registration timing has the full model).

On HyperEVM, given any token:

// 1. Mirror of an Elysium-native token? The mirror factory is the registry:
address native = IElysiumMirrorFactory(MIRROR_FACTORY).elysiumTokenOf(token);
// native != 0: mirror — route key = the token itself, no approval to deposit
// back (canonical iff it also has nonzero totalSupply — the live-metadata pair).

// 2. Otherwise a native HyperEVM token on the canonical bridge:
address gateway = IGatewayRouter(HYPEREVM_ROUTER).getGateway(token);   // escrow gateway
address rep = IGatewayRouter(HYPEREVM_ROUTER).calculateL2TokenAddress(token);
// route key = the token itself; approve the token to `gateway` before depositing.

Classification must key on the factory registries and their events — never on implementation or beacon identity, which anyone can imitate. The registries are the only canonicality source.

9. Invariants & trust model

Failure semantics everywhere: reverting deposits move no funds, and reverting finalizations leave retryables and outbox executions re-executable. The result is delay, not loss.

Elysium-side contract addresses and example transactions will be added at launch.