MetaMask 扩展添加非 EVM 桥接/交换网络完整指南从常量配置到 LaunchDarkly 门控发布【免费下载链接】metamask-extension:globe_with_meridians: :electric_plug: The MetaMask browser extension enables browsing Ethereum blockchain enabled websites项目地址: https://gitcode.com/GitHub_Trending/me/metamask-extension导读本指南面向需要在 MetaMask 浏览器扩展metamask-extension中新增一个非 EVMnon-EVM网络用于 Swap 与 Bridge 功能的开发者与 AI Agent。文章以仓库中的 SSOTSingle Source of Truth标准文档 docs/add-non-evm-swaps-bridge-network.md 为骨架逐层拆解从 chain ID 白名单、桥接常量、账户检测、目标账户校验、发送类型解析到代码门控 LaunchDarkly 双保险的完整落地流程。读完你将掌握为什么必须双门控发布、shared/constants/bridge.ts中每个常量改什么、ui/ducks/bridge/selectors.ts中getFromChains如何按账户类型过滤网络以及如何用验证清单和测试保障新增网络不破坏现有 EVM/多链桥接路径。什么时候使用该标准该标准适用于以下任一情形任务要求为 Bridge 或 Swap 新增一个非 EVM网络如 Bitcoin、Solana、Tron、Stellar 这类由 Snap 账户体系管理的多链网络需求中明确涉及 chain ID 白名单chain ID allowlists、桥接常量bridge constants、账户检测account detection、目标账户检查destination account checks或发送类型解析send type resolution发布要求同时具备代码门控code-gated与LaunchDarkly 控制的LaunchDarkly-controlled行为。从仓库现状可以确认目前受支持的非 EVM 桥接网络定义在 shared/constants/bridge.ts 的ALLOWED_MULTICHAIN_BRIDGE_CHAIN_IDS中包含 Solana、Bitcoin、Tron、Stellar 四条链BRIDGE_ONLY_CHAINSshared/constants/bridge.ts则标注了仅用于桥接、不参与交换的链目前为 Bitcoin。新增网络的过程本质上是把这条链以相同模式加入整个链路。前置条件必须全部满足在动手之前先确认以下四项全部为真只要有一项缺失就应该停下来上报阻塞项blocker而不是部分接线partially wiring该功能前置条件含义仓库中的印证钱包 Snap 存在目标网络已有对应的钱包 Snap能创建/管理该网络账户多链账户类型来自metamask/keyring-api的BtcAccountType、SolAccountType、TrxAccountType、XlmAccountType等见 shared/constants/multichain/networks.tsmetamask/bridge-controller支持Bridge 控制器层面已能对该网络报价、取原生资产getNativeAssetForChainId、ChainId、formatChainIdToCaip均从metamask/bridge-controller导入见 shared/constants/bridge.tsmetamask/keyring-api有账户类型网络对应的账户类型枚举已存在于 keyring-apiMultichainNetworks枚举直接映射到BtcScope/SolScope/TrxScope/XlmScope见 shared/constants/multichain/networks.ts基础网络支持已就绪该网络在扩展其他部分如账户体系、网络切换已具备基础能力例如ui/selectors/multichain.ts中getMultichainIsTronui/selectors/multichain.ts与多链 testnet 判断getMultichainIsTestnetui/selectors/multichain.ts参考实现先看 Tron 与 Bitcoin 两个 PR官方标准明确要求在写任何代码之前先审查 TronPR #37683与 BitcoinPR #35597两个参考 PR镜像其既有模式与命名。这是因为非 EVM 桥接涉及大量每链专属逻辑地址校验格式、账户类型判断、代币命名空间等只有跟随既有实现才能保持一致。仓库中现成的落地代码就是最好的活参考Tron 的桥接常量与资产对已完整存在于 shared/constants/bridge.tsTRX → USDTtrc20:命名空间与 shared/constants/multichain/networks.ts含 Tron Nile/Shasta testnetStellar 的 USDC 资产对asset:命名空间也已在 shared/constants/bridge.ts 中。新增网络时保持同样的枚举命名与注释风格如// TRX - USDT on Tron即可。Agent 技能入口点该标准为不同 AI 编码工具harness提供了统一的入口约定全部指向同一份 SSOTOpenAI/Codex skill 入口.agents/skills/add-non-evm-swaps-bridge-network/SKILL.md$add-non-evm-swaps-bridge-networkCursor skill 入口.cursor/skills/add-non-evm-swaps-bridge-network/SKILL.mdClaude skill 入口.claude/skills/add-non-evm-swaps-bridge-network/SKILL.mdClaude command 入口.claude/commands/add-non-evm-swaps-bridge-network.mdCursor command 入口.cursor/commands/add-non-evm-swaps-bridge-network.mdWindsurf 及其他 harness以Follow docs/add-non-evm-swaps-bridge-network.md section Agent Execution Standard (SSOT).开头引导Agent 执行标准SSOT7 步工作流无论是 Agent 自主实现还是代码审查都必须严格按以下工作流执行确认前置条件满足不满足则停下并上报阻塞项编辑前先审查 Tron 与 Bitcoin 参考 PR更新 shared/constants/bridge.ts 中的代码门控桥接常量更新相关 UI 与状态文件覆盖账户检测、账户兼容性、地址校验、发送类型、代币过滤同时应用两种发布控制构建期代码门控 LaunchDarklybridge-config定向验证代码门控关闭时网络不可见代码门控开启时仅出现在 LaunchDarkly 允许的环境中运行受影响的定向测试记录剩余缺口remaining gaps。第 1 步代码门控常量更新必做核心文件shared/constants/bridge.ts新增网络需要更新四组相关条目且命名与排序必须与文件中现有网络保持一致ALLOWED_MULTICHAIN_BRIDGE_CHAIN_IDSL21-L26export const ALLOWED_MULTICHAIN_BRIDGE_CHAIN_IDS [ MultichainNetworks.SOLANA, MultichainNetworks.BITCOIN, MultichainNetworks.TRON, MultichainNetworks.STELLAR, ];这是非 EVM 网络的总入口新增网络在此加入MultichainNetworks.新网络值来自 shared/constants/multichain/networks.ts 的 CAIP-2 scope 枚举。ALLOWED_BRIDGE_CHAIN_IDSL46-L54export const ALLOWED_BRIDGE_CHAIN_IDS [ ...ALLOWED_MULTICHAIN_BRIDGE_CHAIN_IDS, ...ALLOWED_EVM_BRIDGE_CHAIN_IDS, CHAIN_IDS.LINEA_MAINNET, CHAIN_IDS.BASE, MultichainNetworks.SOLANA, MultichainNetworks.BITCOIN, MultichainNetworks.TRON, ] as const;该数组合并了多链与 EVM 两条白名单并显式补充个别链。它是AllowedBridgeChainIds联合类型L72-L74的组成部分直接影响NETWORK_TO_SHORT_NETWORK_NAME_MAP的类型约束——未加入白名单的链 ID 在类型层面就无法被映射表接受这是编译期强制的一致性保障。由它派生的ALLOWED_BRIDGE_CHAIN_IDS_IN_CAIPL56-L59用toEvmCaipChainId将 EVM 链转为 CAIP 格式并拼上多链 ID桥接 UI 的网络图标映射BRIDGE_CHAIN_ID_TO_NETWORK_IMAGE_MAPL117-L127正是基于它构建的。NETWORK_TO_SHORT_NETWORK_NAME_MAPL129-L173以RecordAllowedBridgeChainIds, string为类型为每个链 ID 提供显示用的短名例如[MultichainNetworks.TRON]: Tron, [MultichainNetworks.STELLAR]: Stellar,注意非 EVM 网络的 testnet 也会出现在这里如SOLANA_TESTNET: Solana Testnet、BITCOIN_SIGNET: Bitcoin Mutinynet。新增网络时主网与 testnet 的短名都要补齐。BRIDGE_CHAINID_COMMON_TOKEN_PAIRL203-L350定义打开 Bridge 视图时默认的目标代币toToken类型为BridgeChainTokenMapL177-L188每条链一个{ address, symbol, decimals, name, assetId }。非 EVM 的现有写法如下[MultichainNetworks.TRON]: { // TRX - USDT on Tron address: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, symbol: USDT, decimals: 6, name: Tether USD, assetId: ${MultichainNetworks.TRON}/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, },这里体现了非 EVM 与 EVM 的关键差异assetId采用 CAIP-21 风格的命名空间如trc20:Tron、token:Solana、asset:Stellar而 EVM 链使用erc20: checksum 地址由toChecksumHexAddress生成。Bitcoin 是特例直接复用getNativeAssetForChainId(CHAIN_IDS.MAINNET)L333。相关但非必改的辅助常量BRIDGE_CHAINID_TO_DEFAULT_FROM_TOKENL191-L200当某链默认from 代币不是原生资产时需要覆盖如 Arc 链默认 USDCBRIDGE_ASSET_PICKER_HIDDEN_ASSETSL352-L359在资产选择器中隐藏的资产集合用于处理同链同名代币冲突如 Arc 的原生 USDC 与 ERC20 USDC。这些常量的运行时消费者值得关注ui/ducks/bridge/utils.ts中的getDefaultToTokenui/ducks/bridge/utils.ts读取BRIDGE_CHAINID_COMMON_TOKEN_PAIR作为默认目标代币isSupportedBridgeChainui/ducks/bridge/utils.ts通过ALL_ALLOWED_BRIDGE_CHAIN_IDS判断链是否可桥接。因此常量更新会同步传导到 UI 的选择器逻辑。第 2 步非门控ungatedUI 与状态更新在常量之外还需更新下列 UI/状态文件让新网络正确参与账户检测、地址校验与发送流程。以下文件路径与职责均来自 SSOT 文档并结合仓库现状说明每处的现有实现模式文件需要做的改动仓库现状参照ui/ducks/bridge/selectors.ts新增hasNetworkAccountsselector更新getFromChains的过滤逻辑正确包含/排除新网络现有getFromChainsui/ducks/bridge/selectors.ts已用hasSolanaAccount/hasBitcoinAccount/hasTronAccount/hasStellarAccount分别控制四条非 EVM 链的显隐ui/ducks/bridge/utils.ts若无共享 helper导出isNetworkChainId工具函数现有isTronChainId从确认流程工具重导出ui/ducks/bridge/utils.tsisNonEvmChainId亦从 bridge-controller 重导出ui/ducks/bridge/utils.tsui/pages/bridge/prepare/components/destination-account-picker-modal.tsx为目标网络增加目标账户兼容性检查需要结合metamask/keyring-api的账户类型如BtcAccountType.P2pkh、TrxAccountType.Eoa、SolAccountType.DataAccount、XlmAccountType.Account见 shared/constants/multichain/networks.ts阻止不兼容账户类型被选为目标ui/pages/bridge/hooks/useExternalAccountResolution.ts增加网络专属地址校验地址校验能力集中在 shared/lib/multichain/accountsisBtcMainnetAddress/isBtcTestnetAddress/isSolanaAddress/isStellarAddress/isTronAddress被 shared/constants/multichain/networks.ts 导入应复用这些工具ui/pages/confirmations/hooks/send/useSendType.ts增加该网络的发送类型处理确保发送确认路径能解析到正确的 send typeui/selectors/multichain.ts将相关 testnet chain ID 加入多链检测逻辑getMultichainIsTestnetui/selectors/multichain.ts目前只检测 Bitcoin/Solana/Tron 的 testnet注释明确写着后续需要扩展到更多网络Tron 的 Nile/Shasta testnet 已纳入MULTICHAIN_TESTNET_NETWORKSshared/constants/multichain/networks.tsui/hooks/bridge/useTokensWithFiltering.ts适当时过滤该网络的不可交易资源与BRIDGE_ASSET_PICKER_HIDDEN_ASSETS的隐藏资产思路一致其中getFromChains是账户驱动的网络显隐核心逻辑值得细看其现有模式ui/ducks/bridge/selectors.tsconst shouldAddSolana isSolanaChainId(chainId) ? hasSolanaAccount : true; const shouldAddBitcoin isBitcoinChainId(chainId) ? hasBitcoinAccount : true; const shouldAddTron isTronChainId(chainId) ? hasTronAccount : true; const shouldAddStellar isStellarChainId(chainId) ? hasStellarAccount : true;它对每条链执行先按链 ID 判断是否属于该网络、再按账户存在性决定是否展示的短路逻辑四个条件连同matchedNetwork全部为真时才把链加入 from-chain 列表。新增网络时需要同样增加shouldAddNetwork与hasNetworkAccount组合并把它加进 L376-L382 的every(Boolean)数组中。第 3 步门控与发布模型双保险缺一不可新网络必须同时应用两种发布控制不能只依赖其中一个代码门控Code gate构建期门控例如通过 builds 配置builds.yml或 webpack 构建配置控制是否把该网络编译进产物LaunchDarkly 标志Flag通过bridge-config特性标志做环境定向environment targeting。两者分工明确LaunchDarkly 提供细粒度的环境定向能力可以精确控制哪些环境/用户组先看到而代码门控防止功能在未全局发布时意外暴露——即使 LaunchDarkly 配置失误构建期代码门控也能兜底。仓库中桥接功能的 API 环境路由本身就是可配置的getBridgeApiBaseUrlForMetaMaskEnvshared/constants/bridge.ts依据METAMASK_ENVIRONMENT在 UAT/Dev/Prod 三套 Bridge API 间切换且允许用BRIDGE_USE_CUSTOM_BASE_URL覆盖这正是不同环境不同行为的基础设施。对应测试在 shared/constants/bridge.test.ts 中验证了各环境映射。验证清单Validation Checklist实现完成后逐项确认SSOT 文档原样要求门控关闭时网络不可见代码门控 off 时该网络不应出现在任何入口门控开启时仅限定向环境代码门控 on 时该网络只出现在 LaunchDarklybridge-config定向的环境From 链列表按账户过滤from-chain 列表仅在存在所需账户时包含该网络对应getFromChains的hasNetworkAccount逻辑目标账户选择器拦截不兼容账户类型destination account picker 必须阻止不兼容账户类型对应destination-account-picker-modal.tsx的兼容性检查外部地址校验执行网络格式规则external address validation 强制网络专属的地址格式复用 shared/lib/multichain/accounts.ts 的isXxxAddress工具发送确认路径解析正确send confirmation path 解析到正确的 send type对应useSendType.ts代币/资源过滤排除不可交易资产token/resource filtering 排除不可交易资产对应useTokensWithFiltering.ts与BRIDGE_ASSET_PICKER_HIDDEN_ASSETS。测试指导SSOT 标准要求运行受影响区域的定向测试再跑更广泛的 bridge/swaps 覆盖选择器、Hooks、Utils 的单测例如getFromChains的账户过滤逻辑、isNetworkChainId工具函数。仓库中常量层的既有测试模式可参考 shared/constants/bridge.test.ts该文件目前覆盖getBridgeApiBaseUrlForMetaMaskEnv的环境路由新增常量后可在此补充白名单/映射完整性断言桥接账户选择器与发送类型的单测或集成测试验证不兼容账户被拦截、发送类型解析正确新网络路径与既有网络回归的 E2E 测试仓库的 E2E 套件位于 test/e2eswap/bridge 相关流程均在其中需同时覆盖新网络正路径与既有 EVM/非 EVM 网络的回归。若行为发生变化应在最贴近的既有测试套件中新增或更新测试而不是另起炉灶。使用该标准时 Agent 必须返回的响应结构当 Agent 依据本标准执行任务时最终交付必须包含以下六个部分便于人工复核与追责Prerequisites Check前置条件检查结果逐项列出Implementation Checklist实现清单对应 7 步工作流Files Changed变更文件列表Gating Behavior Verified门控行为已验证off/on 两种状态下的可见性结论Tests Run已运行的测试Remaining Gaps剩余缺口如未覆盖的 testnet、未接入的 LaunchDarkly 环境等这套结构同时适用于Agent 自主实现与Agent 审查他人实现两种场景是保证非 EVM 桥接网络新增工作可审计、可回滚、不泄漏的关键约定。小结一条新非 EVM 链上线的完整路径综合全文新增一条非 EVM 桥接/交换网络的核心路径可以浓缩为验证前置条件 → 对照 Tron/Bitcoin 参考实现 → 更新shared/constants/bridge.ts四组常量白名单、短名、默认资产对→ 更新选择器/工具/账户选择器/发送类型/多链 testnet 检测等 UI 状态 → 同时挂上构建期代码门控与 LaunchDarklybridge-config定向 → 按验证清单逐项确认 → 跑单测、集成测试与 E2E 回归 → 按六段式结构输出交付报告。其中双门控与账户驱动显隐是两条贯穿始终的主线前者保证发布安全后者保证非 EVM 网络只对持有对应账户的用户可见——这正是 MetaMask 多链桥接在 Tron、Bitcoin、Solana、Stellar 上已验证的成熟模式。【免费下载链接】metamask-extension:globe_with_meridians: :electric_plug: The MetaMask browser extension enables browsing Ethereum blockchain enabled websites项目地址: https://gitcode.com/GitHub_Trending/me/metamask-extension创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考