Skip to content

Commit c09a505

Browse files
infiniteflowerinfiniteflower
committed
feat: add swaps core controller content for adding a new network
1 parent fad21fb commit c09a505

2 files changed

Lines changed: 235 additions & 0 deletions

File tree

‎domains/swaps/knowledge/add-network-core.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
---
2+
name: add-network-core
3+
domain: swaps
4+
description: Core controller SSOT for adding EVM or non-EVM networks to the Bridge and BridgeStatus controllers
5+
---
6+
7+
# Add Swaps/Bridge Network To Core Controllers
8+
9+
## Use This Standard When
10+
11+
- A task adds a new EVM or non-EVM network to the Core Bridge or BridgeStatus controller packages.
12+
- 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.
13+
- Client work in Extension or Mobile depends on new `@metamask/bridge-controller` or `@metamask/bridge-status-controller` behavior.
14+
15+
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.
16+
17+
## Classify The Network First
18+
19+
Before editing code, classify the network:
20+
21+
- EVM: uses EVM chain IDs and EVM transaction data (`TxData`) for approvals and trades.
22+
- Non-EVM: uses a CAIP scope, network-specific account type, and a non-EVM transaction format signed through the appropriate account or snap path.
23+
- Hybrid or unknown: stop and identify the bridge API transaction format, account model, signing path, and CAIP identifiers before implementation.
24+
25+
## Common Prerequisites
26+
27+
Confirm all are true before implementation:
28+
29+
- The bridge backend supports the network.
30+
- Chain identifiers are known, including EVM decimal chain ID or non-EVM CAIP scope.
31+
- Native token metadata is known, including symbol, decimals, token address convention, and icon availability.
32+
- The target network has a clear signing path through existing account/keyring support.
33+
- Extension and Mobile client support requirements are understood.
34+
- Public package contract changes are planned for downstream consumers.
35+
36+
If any prerequisite is missing, stop and report the blocker instead of partially wiring the feature.
37+
38+
## Reference Implementations
39+
40+
Use these references before coding:
41+
42+
- Non-EVM Tron Core integration: `https://github.com/MetaMask/core/pull/6862`
43+
- Existing non-EVM Solana, Bitcoin, and Tron handling in `packages/bridge-controller/` and `packages/bridge-status-controller/`
44+
- Existing EVM chain entries in `packages/bridge-controller/src/constants/bridge.ts` and `packages/bridge-controller/src/constants/tokens.ts`
45+
46+
Review the closest EVM or non-EVM implementation in the target checkout and mirror existing naming, ordering, validation, and test style.
47+
48+
## Agent Execution Standard (SSOT)
49+
50+
For agent implementation or review tasks, follow this workflow exactly:
51+
52+
1. Confirm prerequisites and classify the network as EVM, non-EVM, or hybrid/unknown.
53+
2. Review the closest existing Core implementation before editing.
54+
3. Update `packages/bridge-controller` constants, token metadata, types, validators, trade utilities, CAIP formatters, and exports as needed.
55+
4. Update `packages/bridge-status-controller` non-EVM detection, transaction submission, snap/client request construction, and status handling as needed.
56+
5. Validate exported package contracts, generated messenger action types, and changelog requirements when public behavior changes.
57+
6. Run targeted package tests and note any remaining client validation gaps.
58+
59+
## Core Implementation Checklist
60+
61+
### 1. Network Constants
62+
63+
Update `packages/bridge-controller/src/constants/bridge.ts` and related constants when the new network should be available to Bridge:
64+
65+
- Add the network to allowed chain ID lists.
66+
- Keep ordering consistent with existing networks.
67+
- Use hex `CHAIN_IDS` constants such as `CHAIN_IDS.MAINNET` or `'0x1'` for EVM allowlists.
68+
- Use EIP-155 CAIP chain IDs such as `eip155:1` for feature flag ranking and CAIP-formatted asset IDs.
69+
- Prefer CAIP scopes from `@metamask/keyring-api` for non-EVM networks.
70+
- Prefer existing constants from the package before adding new local helpers.
71+
72+
Update native token metadata in `packages/bridge-controller/src/constants/tokens.ts` when the network needs package-level default token support:
73+
74+
- Symbol and display name
75+
- Native token address convention
76+
- Decimals
77+
- Icon URL or icon lookup convention
78+
- SLIP-44 mapping when applicable
79+
80+
### 2. Types And Validators
81+
82+
Update type and validator internals only where the bridge API introduces a shape that does not already exist:
83+
84+
- `packages/bridge-controller/src/types.ts`
85+
- Add network-specific trade data types.
86+
- Extend `QuoteResponse` generic defaults when the trade or approval type becomes part of the public package contract.
87+
- `packages/bridge-controller/src/utils/validators.ts`
88+
- Extend quote response validation schemas for new trade or approval shapes.
89+
- `packages/bridge-controller/src/validators/trade.ts`
90+
- Add type guards such as `is<Network>Trade` for custom non-EVM trade data.
91+
- Follow existing `isEvmTxData`, `isBitcoinTrade`, `isTronTrade`, and `isStellarTrade` patterns.
92+
93+
Keep type narrowing explicit through validators and type guards instead of broad casts.
94+
95+
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`.
96+
97+
### 3. Trade Utilities
98+
99+
Update `packages/bridge-controller/src/utils/trade-utils.ts`:
100+
101+
- Update `extractTradeData` so the transaction data matches the signing path expected by the account or snap client.
102+
- Keep network-specific extraction behind the matching `is<Network>Trade` type guard.
103+
- Export new type guards or helpers from `packages/bridge-controller/src/index.ts` when clients or `bridge-status-controller` need them.
104+
105+
Do not access network-specific trade fields without first narrowing the trade shape.
106+
107+
### 4. CAIP Formatters
108+
109+
Update `packages/bridge-controller/src/utils/caip-formatters.ts` and nearby bridge utilities:
110+
111+
- 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.
112+
- 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.
113+
- Update `formatChainIdToHex` only for EVM-compatible numeric/CAIP inputs that need app-facing hex IDs.
114+
- Update `formatAddressToAssetId` when asset ID construction differs from the existing EVM `erc20`, Solana `token`, or Tron `trc20` behavior.
115+
- In `packages/bridge-controller/src/utils/bridge.ts`, add `is<Network>ChainId` helpers and update `isNonEvmChainId` for non-EVM networks that need shared detection.
116+
- In `packages/bridge-controller/src/utils/bridge.ts`, update `getNativeAssetForChainId` when the network needs a native asset CAIP ID.
117+
- For non-EVM networks, include testnet scopes only when the backend and clients need them.
118+
- For EVM networks, prefer the existing EIP-155 and hex conversion paths unless the chain needs special handling.
119+
- Verify the same identifiers are used across constants, request formatting, and client-facing exports.
120+
121+
### 5. Bridge Status Transaction Handling
122+
123+
Update BridgeStatus internals only where the submit/status path differs:
124+
125+
- `packages/bridge-status-controller/src/bridge-status-controller.ts`
126+
- Update `submitTx` when the new network changes submit behavior, approval sequencing, history metadata, or polling behavior.
127+
- Preserve existing EVM submit behavior for EVM networks.
128+
- `packages/bridge-status-controller/src/strategy/index.ts`
129+
- In current strategy-based flows, update `validateParams` and the non-EVM branch in `executeSubmitStrategy` so the network routes to `submitNonEvmHandler`.
130+
- `packages/bridge-status-controller/src/utils/snaps.ts`
131+
- Update `getClientRequest` when a non-EVM signing request needs network-specific scope, account ID, encoded transaction data, or options.
132+
- Keep request construction aligned with `extractTradeData`.
133+
- `packages/bridge-status-controller/src/utils/bridge-status.ts` and `packages/bridge-status-controller/src/utils/history.ts`
134+
- Update only if non-EVM status or history behavior differs.
135+
136+
Ensure approval handling is included only when the network supports approvals.
137+
138+
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.
139+
140+
## EVM-Specific Handling
141+
142+
For EVM networks:
143+
144+
- Reuse existing `TxData` quote and approval types unless the backend introduces a new shape.
145+
- Add chain constants, native token metadata, allowlists, and default token mappings as needed.
146+
- Verify quote fee logic if the network has unusual fee semantics.
147+
- Confirm approval flow behavior for token swaps and bridge transactions.
148+
- Avoid adding non-EVM CAIP or snap-specific handling unless the network actually needs it.
149+
150+
## Non-EVM-Specific Handling
151+
152+
For non-EVM networks:
153+
154+
- Use the network scope from `@metamask/keyring-api`.
155+
- Add SLIP-44 metadata when needed.
156+
- Define custom transaction schemas only for real backend response shapes.
157+
- Add type guards and extraction utilities for network-specific transaction data.
158+
- Update CAIP conversion helpers.
159+
- Update `isNonEvmChainId` style detection.
160+
- Ensure the selected account has the correct snap/account metadata for signing.
161+
- Pass network-specific request options to the signing path only when required.
162+
163+
## Gating And Rollout
164+
165+
Core package changes usually gate availability through exported allowlists and package versions. Coordinate with client rollouts:
166+
167+
- Extension and Mobile must consume a package version that includes the new network.
168+
- LaunchDarkly/client flags still control user-facing rollout in the consuming repos.
169+
- Public exports and behavior changes need changelog or release note handling according to Core repo conventions.
170+
171+
## Validation Checklist
172+
173+
Before finishing, verify:
174+
175+
- Constants and token metadata are present and exported where needed.
176+
- CAIP formatting works both directions.
177+
- Type guards correctly identify network-specific trades.
178+
- Transaction data extraction returns the format expected by the signer.
179+
- EVM approval/trade flows still use existing `TxData` handling.
180+
- Non-EVM approval/trade flows work with and without approvals when applicable.
181+
- Package exports are updated for new public helpers or types.
182+
- Generated messenger action types are updated or checked when controller messenger contracts change.
183+
- Downstream Extension and Mobile impact is explicitly called out.
184+
185+
## Test Guidance
186+
187+
Run targeted tests for the touched package areas:
188+
189+
- `yarn workspace @metamask/bridge-controller test`
190+
- `yarn workspace @metamask/bridge-status-controller test`
191+
192+
Also run build/type or generated contract checks when relevant:
193+
194+
- `yarn workspace @metamask/bridge-controller build`
195+
- `yarn workspace @metamask/bridge-status-controller build`
196+
- Messenger action type checks when messenger actions or controller events change
197+
- Changelog validation when public package behavior changes
198+
199+
If behavior changes, add or update tests in the closest package test suites.
200+
201+
## Required Agent Response Sections
202+
203+
When using this standard, return:
204+
205+
1. `Prerequisites Check`
206+
2. `Network Classification`
207+
3. `Implementation Checklist`
208+
4. `Files Changed`
209+
5. `Package Contract Impact`
210+
6. `Gating Behavior Verified`
211+
7. `Tests Run`
212+
8. `Remaining Gaps`

‎domains/swaps/skills/add-network/repos/core.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
repo: core
3+
parent: add-network
4+
---
5+
6+
7+
# Add Swaps/Bridge Network (Core Controllers)
8+
9+
`knowledge/add-network-core.md` is the single source of truth.
10+
11+
Follow `knowledge/add-network-core.md` section `Agent Execution Standard (SSOT)` for:
12+
13+
- prerequisites
14+
- network classification
15+
- reference implementations
16+
- implementation checklist
17+
- package contract validation
18+
- required response sections
19+
20+
## Validation
21+
22+
1. `yarn workspace @metamask/bridge-controller test`
23+
2. `yarn workspace @metamask/bridge-status-controller test`

0 commit comments

Comments
 (0)