Skip to content

feat: add swaps core controller content for adding a new network #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
infiniteflower wants to merge 5 commits into from
Closed

feat: add swaps core controller content for adding a new network #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c09a505
feat: add swaps core controller content for adding a new network
infiniteflower Jul 9, 2026
2c1812a
feat: add extension and mobile, clean up core, reference robinhood im…
infiniteflower Jul 10, 2026
8a65f67
chore: clean up
infiniteflower Jul 10, 2026
8ecae0f
chore: remove unneeded file
infiniteflower Jul 10, 2026
3ec0ea3
chore: more cleanup
infiniteflower Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
242 changes: 242 additions & 0 deletions domains/swaps/knowledge/add-network-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,242 @@
---
name: add-network-core
domain: swaps
description: Core controller SSOT for adding EVM or non-EVM networks to the Bridge and BridgeStatus controllers
---

# Add Swaps/Bridge Network To Core Controllers

## Use This Standard When

- A task adds a new EVM or non-EVM network to the Core Bridge or BridgeStatus controller packages.
- The request mentions bridge controller allowlists, chain IDs, native token metadata, CAIP formatters, quote transaction schemas, trade extraction, submit/status handling, or package contract changes.
- Client work in Extension or Mobile depends on new `@metamask/bridge-controller` or `@metamask/bridge-status-controller` behavior.

Core owns the shared package contract consumed by Extension and Mobile. Treat exported types, constants, controller state, messenger actions, events, and transaction payload formats as cross-client API changes.

## Classify The Network First

Before editing code, classify the network:

- EVM: uses EVM chain IDs and EVM transaction data (`TxData`) for approvals and trades.
- Non-EVM: uses a CAIP scope, network-specific account type, and a non-EVM transaction format signed through the appropriate account or snap path.
- Hybrid or unknown: stop and identify the bridge API transaction format, account model, signing path, and CAIP identifiers before implementation.

## Common Prerequisites

Confirm all are true before implementation:

- The bridge backend supports the network.
- Chain identifiers are known, including EVM decimal chain ID or non-EVM CAIP scope.
- Native token metadata is known, including symbol, decimals, token address convention, and icon availability.
- The target network has a clear signing path through existing account/keyring support.
- Extension and Mobile client support requirements are understood.
- Public package contract changes are planned for downstream consumers.

If any prerequisite is missing, stop and report the blocker instead of partially wiring the feature.

## Reference Implementations

Use these references before coding:

- Non-EVM Tron Core integration: `https://github.com/MetaMask/core/pull/6862`
- EVM Robinhood Chain Core integration (minimal constants-only template): `https://github.com/MetaMask/core/pull/9459`
- Existing non-EVM Solana, Bitcoin, and Tron handling in `packages/bridge-controller/` and `packages/bridge-status-controller/`
- Existing EVM chain entries in `packages/bridge-controller/src/constants/chains.ts`, `packages/bridge-controller/src/constants/bridge.ts`, `packages/bridge-controller/src/constants/tokens.ts`, and `packages/bridge-controller/src/types.ts`

Review the closest EVM or non-EVM implementation in the target checkout and mirror existing naming, ordering, validation, and test style.

### Minimal EVM Path

For a standard EVM network whose backend returns existing `TxData` trade and approval shapes, Core onboarding is usually limited to:

1. `packages/bridge-controller/src/constants/chains.ts` — `CHAIN_IDS`, display name, and `NETWORK_TO_NAME_MAP`
2. `packages/bridge-controller/src/types.ts` — decimal `ChainId` enum entry
3. `packages/bridge-controller/src/constants/bridge.ts` — `ALLOWED_BRIDGE_CHAIN_IDS` and `DEFAULT_CHAIN_RANKING`
4. `packages/bridge-controller/src/constants/tokens.ts` — native currency symbol, network token object, and `SWAPS_CHAINID_DEFAULT_TOKEN_MAP`
5. `packages/bridge-controller/CHANGELOG.md` — an `Added` entry under `Unreleased`

Robinhood Chain PR #9459 changed only these five files. It did not update validators, trade utilities, CAIP formatters, exports, BridgeStatus, or tests. Skip the extended sections below unless the network introduces a new trade or approval shape, signing path, CAIP behavior, fee behavior, or public helper.

## Agent Execution Standard (SSOT)

For agent implementation or review tasks, follow this workflow exactly:

1. Confirm prerequisites and classify the network as EVM, non-EVM, or hybrid/unknown.
2. Review the closest existing Core implementation before editing.
3. For a standard EVM network, follow the Minimal EVM Path. Update validators, trade utilities, CAIP formatters, or exports only when the network introduces behavior that existing generic EVM handling does not cover.
4. Update `packages/bridge-status-controller` only when the network changes non-EVM detection, transaction submission, snap/client request construction, or status handling.
5. Add a changelog entry when allowlists or public behavior change. Re-check exports and generated messenger action types only when exported helpers, types, or controller messenger contracts change.
6. Run targeted package tests and note any remaining client validation gaps.

## Core Implementation Checklist

### 1. Network Constants

Update chain and bridge constants when the new network should be available to Bridge:

- `packages/bridge-controller/src/constants/chains.ts`
- For EVM networks, add the hex chain ID to `CHAIN_IDS`, for example `ROBINHOOD: '0x1237'`.
- For EVM networks, add the display name constant.
- For EVM networks, add the `NETWORK_TO_NAME_MAP` entry.
- Do not add non-EVM scopes here unless the file already has a matching local pattern; non-EVM allowlists use keyring scopes instead.
- `packages/bridge-controller/src/types.ts`
- Add the bridge API numeric chain ID to the `ChainId` enum when controller code needs a numeric ID.
- For EVM networks, the enum decimal value must equal the hex `CHAIN_IDS` value, for example `4663` equals `0x1237`.
- For non-EVM networks, follow the Tron pattern with entries such as `TRON = 728126428`.
- `packages/bridge-controller/src/constants/bridge.ts`
- Add the network to `ALLOWED_BRIDGE_CHAIN_IDS`.
- For EVM networks, add the hex `CHAIN_IDS.<NETWORK>` constant to `ALLOWED_BRIDGE_CHAIN_IDS`.
- For non-EVM networks, import and add the keyring scope, for example `TrxScope.Mainnet`.
- Add the `DEFAULT_CHAIN_RANKING` entry using the correct CAIP chain ID format, for example `eip155:4663` for EVM or `tron:728126428` for Tron.
- Keep ordering consistent with existing networks.
- Keep EVM `CHAIN_IDS.*` entries grouped before non-EVM keyring scopes in `ALLOWED_BRIDGE_CHAIN_IDS`.
- Place new `DEFAULT_CHAIN_RANKING` entries alongside peer networks and use the canonical display name.
- Use hex `CHAIN_IDS` constants such as `CHAIN_IDS.MAINNET` or `'0x1'` for EVM allowlists.
- Use EIP-155 CAIP chain IDs such as `eip155:1` for feature flag ranking and CAIP-formatted asset IDs.
- Prefer CAIP scopes from `@metamask/keyring-api` for non-EVM networks.
- Prefer existing constants from the package before adding new local helpers.

Update native token metadata in `packages/bridge-controller/src/constants/tokens.ts` when the network needs package-level default token support:

- Add a network key to `CURRENCY_SYMBOLS`, with the native symbol as its value, for example `ROBINHOOD: 'ETH'`.
- Define `<NETWORK>_SWAPS_TOKEN_OBJECT`; for an ETH-native EVM chain, spread `ETH_SWAPS_TOKEN_OBJECT` instead of duplicating its fields.
- Map `[CHAIN_IDS.<NETWORK>]` to the network token object in `SWAPS_CHAINID_DEFAULT_TOKEN_MAP`.
- For non-EVM networks, follow the Tron pattern: add the native currency symbol such as `TRX`, define a token object such as `TRX_SWAPS_TOKEN_OBJECT`, map `[TrxScope.Mainnet]` in `SWAPS_CHAINID_DEFAULT_TOKEN_MAP`, and add the native asset entry in `SYMBOL_TO_SLIP44_MAP`, for example `TRX: 'slip44:195'`.
- For an ETH-native EVM network, inherit the native address convention, decimals, and icon fields from `ETH_SWAPS_TOKEN_OBJECT`; do not add a new SLIP-44 mapping.

### 2. Types And Validators (New Backend Shapes Only)

For a standard EVM network, only add the `ChainId` enum entry described above. Update the following internals only where the bridge API introduces a shape that does not already exist:

- `packages/bridge-controller/src/types.ts`
- Add network-specific trade data types.
- Extend `QuoteResponse` generic defaults when the trade or approval type becomes part of the public package contract.
- `packages/bridge-controller/src/utils/validators.ts`
- Extend quote response validation schemas for new trade or approval shapes.
- `packages/bridge-controller/src/validators/trade.ts`
- Add type guards such as `is<Network>Trade` for custom non-EVM trade data.
- Follow existing `isEvmTxData`, `isBitcoinTrade`, `isTronTrade`, and `isStellarTrade` patterns.

Keep type narrowing explicit through validators and type guards instead of broad casts.

EVM networks usually continue using existing `TxData` handling. Non-EVM networks often need a custom schema such as Bitcoin PSBT, Solana serialized transaction, or Tron `raw_data_hex`.

### 3. Trade Utilities

Update `packages/bridge-controller/src/utils/trade-utils.ts`:

- Update `extractTradeData` so the transaction data matches the signing path expected by the account or snap client.
- Keep network-specific extraction behind the matching `is<Network>Trade` type guard.
- Export new type guards or helpers from `packages/bridge-controller/src/index.ts` when clients or `bridge-status-controller` need them.

Do not access network-specific trade fields without first narrowing the trade shape.

### 4. CAIP Formatters

Update `packages/bridge-controller/src/utils/caip-formatters.ts` and nearby bridge utilities:

- Verify `formatChainIdToCaip` handles the network correctly. EVM inputs should use the existing hex/number to `eip155:<decimal>` path; non-EVM inputs may need explicit mapping from bridge API numeric IDs or aliases to a CAIP scope.
- Verify `formatChainIdToDec` handles the network correctly for supported inputs: number, hex, CAIP chain ID, or numeric string. Non-EVM CAIP scopes may need explicit mapping back to the bridge API numeric chain ID.
- Update `formatChainIdToHex` only for EVM-compatible numeric/CAIP inputs that need app-facing hex IDs.
- Update `formatAddressToAssetId` when asset ID construction differs from the existing EVM `erc20`, Solana `token`, or Tron `trc20` behavior.
- In `packages/bridge-controller/src/utils/bridge.ts`, add `is<Network>ChainId` helpers and update `isNonEvmChainId` for non-EVM networks that need shared detection.
- In `packages/bridge-controller/src/utils/bridge.ts`, update `getNativeAssetForChainId` when the network needs a native asset CAIP ID.
- For non-EVM networks, include testnet scopes only when the backend and clients need them.
- For EVM networks, prefer the existing EIP-155 and hex conversion paths unless the chain needs special handling.
- Verify the same identifiers are used across constants, request formatting, and client-facing exports.

### 5. Bridge Status Transaction Handling

Update BridgeStatus internals only where the submit/status path differs:

- `packages/bridge-status-controller/src/bridge-status-controller.ts`
- Update `submitTx` when the new network changes submit behavior, approval sequencing, history metadata, or polling behavior.
- Preserve existing EVM submit behavior for EVM networks.
- `packages/bridge-status-controller/src/strategy/index.ts`
- In current strategy-based flows, update `validateParams` and the non-EVM branch in `executeSubmitStrategy` so the network routes to `submitNonEvmHandler`.
- `packages/bridge-status-controller/src/utils/snaps.ts`
- Update `getClientRequest` when a non-EVM signing request needs network-specific scope, account ID, encoded transaction data, or options.
- Keep request construction aligned with `extractTradeData`.
- `packages/bridge-status-controller/src/utils/bridge-status.ts` and `packages/bridge-status-controller/src/utils/history.ts`
- Update only if non-EVM status or history behavior differs.

Ensure approval handling is included only when the network supports approvals.

Non-EVM transaction data must be converted to the exact format the signing path expects. For example, Tron raw transaction hex may need base64 encoding and request options derived from the raw contract type.

## EVM-Specific Handling

For EVM networks:

- Reuse existing `TxData` quote and approval types unless the backend introduces a new shape.
- Add chain constants in `constants/chains.ts`, the decimal `ChainId` enum entry in `types.ts`, bridge allowlist/ranking entries in `constants/bridge.ts`, and native/default token mappings in `constants/tokens.ts`.
- Verify quote fee logic if the network has unusual fee semantics.
- Confirm approval flow behavior for token swaps and bridge transactions.
- Do not update `bridge-status-controller` submit strategy code unless the new EVM network changes submit behavior beyond existing `TxData` handling.
- Avoid adding non-EVM CAIP or snap-specific handling unless the network actually needs it.

## Non-EVM-Specific Handling

For non-EVM networks:

- Use the network scope from `@metamask/keyring-api`.
- Add SLIP-44 metadata when needed.
- Define custom transaction schemas only for real backend response shapes.
- Add type guards and extraction utilities for network-specific transaction data.
- Update CAIP conversion helpers.
- Update `isNonEvmChainId` style detection.
- Ensure the selected account has the correct snap/account metadata for signing.
- Pass network-specific request options to the signing path only when required.

## Gating And Rollout

Core package changes usually gate availability through exported allowlists and package versions. Coordinate with client rollouts:

- Extension and Mobile must consume a package version that includes the new network.
- LaunchDarkly/client flags still control user-facing rollout in the consuming repos.
- Public exports and behavior changes need changelog or release note handling according to Core repo conventions.
- EVM allowlist additions in `@metamask/bridge-controller` should include a `packages/bridge-controller/CHANGELOG.md` entry.

## Validation Checklist

Before finishing, verify:

- Standard EVM constants and token metadata are present in the five Minimal EVM Path files.
- Existing EVM CAIP conversion and `TxData` handling cover the new chain without code changes.
- For non-EVM or custom trade shapes, type guards, `extractTradeData`, and CAIP formatters are updated and tested.
- BridgeStatus remains untouched for a standard EVM network and changes only when submit, status, or signing behavior differs.
- `CHANGELOG.md` includes an `Unreleased` entry when an allowlist changes.
- Package exports and generated messenger action types are checked only when their contracts change.
- Downstream Extension and Mobile impact is explicitly called out.

## Test Guidance

Run targeted tests for the touched package areas:

- `yarn workspace @metamask/bridge-controller test`
- `yarn workspace @metamask/bridge-status-controller test` only when BridgeStatus is touched

Also run build/type or generated contract checks when relevant:

- `yarn workspace @metamask/bridge-controller build`
- `yarn workspace @metamask/bridge-status-controller build` only when BridgeStatus is touched
- Messenger action type checks when messenger actions or controller events change
- Changelog validation when public package behavior changes

If behavior changes, add or update tests in the closest package test suites.

Constants-only EVM allowlist additions such as PR #9459 may require no new unit tests when existing generic EVM formatter and validator coverage applies. Still run the Bridge controller package tests to check for regressions.

## Required Agent Response Sections

When using this standard, return:

1. `Prerequisites Check`
2. `Network Classification`
3. `Implementation Checklist`
4. `Files Changed`
5. `Package Contract Impact`
6. `Gating Behavior Verified`
7. `Tests Run`
8. `Remaining Gaps`
Loading