Integrate Citrea chain (Bitcoin L2 zk-rollup, chain ID 4114)

[swdiscordia]

Overview

Add support for Citrea — the first Bitcoin L2 ZK-rollup (EVM-equivalent Type-2) — as a second-class EVM chain in ShapeShift. Users would be able to hold and view their cBTC and Citrea-bridged tokens (USDC.e, USDT.e, WBTC.e, etc.) directly in the wallet.

Citrea mainnet launched in early 2026. Chain ID 4114, native gas token is cBTC (BTC-pegged via the Clementine BitVM bridge, 18 decimals).

This issue is scoped strictly to chain integration. Bridge (BTC L1 ↔ Citrea L2 via Clementine system contract) and swapper routes are out of scope and would be tracked in separate issues.

References and additional details

• Citrea docs: https://docs.citrea.xyz/
• Bridge (system contract, out of scope here): https://docs.citrea.xyz/developer-documentation/system-contracts/bridge
• Block explorer: https://explorer.mainnet.citrea.xyz (verified HTTP 200)
• Public RPC: https://rpc.mainnet.citrea.xyz (verified live, eth_chainId → 0x1012)
• Wrapped cBTC (WcBTC, ERC-20 system contract): 0x3100000000000000000000000000000000000006 (deployed, verified via eth_getCode)
• Native asset (slip44:60): cBTC (18 decimals, BTC-pegged)
• Convention contract followed: .claude/contracts/second-class-evm-chain.md

Notes on related-asset mapping:

• WBTC.e (Citrea Bridged WBTC at 0xdf240dc...) was being mis-mapped by Zerion's algo to ETH USDT (price ~$1) instead of ETH WBTC (price ~$77k). A manual override in manualRelatedAssetIndex corrects this in both generateRelatedAssetIndex.ts and generateChainRelatedAssetIndex.ts.
• cBTC is treated as its own primary asset (relatedAssetKey: null, no group) — matches BTC/AVAX/MNT/BERA convention and Citrea team guidance ("cBTC is the main token of Citrea").

Phase 3 swapper / data-provider research (verified 2026-05-21):

• Garden Finance — has Citrea pre-integrated in /v2/chains (evm:4114, native citrea:cbtc, HTLC contract 0xE413743B51f3cC8b3ac24addf50D18fa138cB0Bb, is_active: true) but no order_pair activated server-side. 8 representative pairs tested via /v2/quote (bitcoin↔cbtc, cbtc↔arbitrum:wbtc, starknet:strkbtc/base:cbbtc/ethereum:wbtc → cbtc), all return No order pair found. Routes can activate at any time via Garden backend.
• Relay — /chains returns 73 chains; chainId 4114 not in list. ❌ Not supported.
• Portals — /v2/networks does not list Citrea. ❌ Not supported.
• Across, Zerion, WalletConnect V2, Yield.xyz — inconclusive or untested from public endpoints (need API auth / project ID); follow-up.

Acceptance Criteria

• Citrea appears in chain selector when VITE_FEATURE_CITREA=true
• cBTC native balance loads from the RPC
• Citrea ERC-20 tokens discoverable via token search
• Tx history works (handled generically by SecondClassEvmAdapter.getTransactionStatus)
• "Popular Assets" in trade modal shows Citrea natives without searching
• All 10 HDWallet packages expose supportsCitrea()
• WBTC.e asset detail shows Wrapped Bitcoin (mainnet) as related asset (NOT USDT)
• cBTC stands as its own primary (no related-asset group)
• All Phase 4.5 additions are append-only (verified in audit)

Need By Date

N/A

Estimate

S