Skip to content

feat: support local devnet and fork chains - #389

Open
aelmanaa wants to merge 1 commit into
mainfrom
feat/local-testing
Open

feat: support local devnet and fork chains#389
aelmanaa wants to merge 1 commit into
mainfrom
feat/local-testing

Conversation

@aelmanaa

Copy link
Copy Markdown
Collaborator

This pull request adds support for using the CLI and SDK with local devnets, forks, and chains not present in the bundled selector table. It introduces the --chain-selectors CLI flag and CCIP_CHAIN_SELECTORS environment variable, allowing users to register custom chains at runtime. The documentation is updated with a new guide and troubleshooting section, and relevant references are added throughout the docs and README.

New Features:

  • CLI/SDK now support registering chains missing from the bundled selector table (e.g., local devnets, new public networks) via the --chain-selectors flag, CCIP_CHAIN_SELECTORS environment variable, or registerChains in the SDK. Supports shorthand, inline JSON, or JSON/YAML files. [1] [2] [3] [4] [5]
  • Forks served under a different chain id (e.g., Tenderly Virtual Environments, anvil --fork --chain-id) can be registered as forks, preserving selector and identity for correct message decoding. [1] [2]

Documentation Additions and Updates:

  • New guide: "Local Devnets and Forks" explains how to use the new chain registration features for local testing, including detailed examples and caveats. [1] [2]
  • CLI configuration docs updated to include --chain-selectors and CCIP_CHAIN_SELECTORS, with explanations and examples. [1] [2] [3]
  • Troubleshooting docs now include solutions for CHAIN_NOT_FOUND errors, guiding users to register missing chains or forks.
  • References to the new guide are added to the main doc index and sidebar. [1] [2]

SDK/CLI Behavior Changes:

  • EVM: decodeMessage now surfaces CHAIN_NOT_FOUND for unresolvable selectors, instead of a misleading MESSAGE_INVALID error.

These changes make it much easier to use the CLI and SDK in local development environments and with new or custom chains, improving the developer experience and error transparency.

@aelmanaa
aelmanaa requested review from a team as code owners August 30, 2026 13:40
@vercel

vercel Bot commented Aug 30, 2026

Copy link
Copy Markdown

You must have Developer access to commit code to Chainlink Labs on Vercel. If you contact an administrator and receive Developer access, commit again to see your changes.

Learn more: https://vercel.com/docs/accounts/team-members-and-roles/access-roles#team-level-roles

@github-actions

Copy link
Copy Markdown

👋 aelmanaa, thanks for creating this pull request!

To help reviewers, please consider creating future PRs as drafts first. This allows you to self-review and make any final changes before notifying the team.

Once you're ready, you can mark it as "Ready for review" to request feedback. Thanks!

@github-actions

Copy link
Copy Markdown

Coverage Report

File                                   | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
---------------------------------------|---------|----------|---------|---------|-------------------
All files                              |      78 |     79.2 |   67.92 |      78 |                   
 ccip-cli/src                          |   93.03 |    71.79 |   83.33 |   93.03 |                   
  chain-selectors.ts                   |   98.37 |       78 |     100 |   98.37 | 33,122            
  index.ts                             |   89.85 |    60.71 |      75 |   89.85 | ...89-193,199-204 
 ccip-cli/src/commands                 |   52.34 |       75 |   61.29 |   52.34 |                   
  index.ts                             |     100 |      100 |     100 |     100 |                   
  lane-latency.ts                      |   70.76 |    83.33 |   33.33 |   70.76 | ...,76-83,119-128 
  lane.ts                              |   86.98 |    68.42 |     100 |   86.98 | ...41-144,148-150 
  manual-exec.ts                       |   20.34 |      100 |       0 |   20.34 | ...39-149,151-347 
  parse.ts                             |    55.2 |      100 |       0 |    55.2 | 47-51,58-65,67-96 
  search.ts                            |   81.25 |      100 |       0 |   81.25 | 24-29             
  send.ts                              |   14.13 |      100 |       0 |   14.13 | ...09-237,239-552 
  show.ts                              |   75.68 |    63.75 |     100 |   75.68 | ...15-318,399-401 
  supported-tokens.ts                  |   17.93 |      100 |       0 |   17.93 | ...80-353,355-368 
  token.ts                             |   22.72 |      100 |       0 |   22.72 | ...3,60-67,69-132 
  types.ts                             |     100 |      100 |     100 |     100 |                   
  utils.ts                             |   86.69 |    78.91 |   93.33 |   86.69 | ...12-722,730-738 
 ccip-cli/src/commands/search          |   53.89 |    76.19 |    12.5 |   53.89 |                   
  messages.ts                          |   53.89 |    76.19 |    12.5 |   53.89 | ...36-258,260-295 
 ccip-cli/src/providers                |   58.73 |    87.17 |   32.72 |   58.73 |                   
  aptos.ts                             |   51.47 |      100 |       0 |   51.47 | ...,95-96,105-136 
  canton.ts                            |   84.98 |    96.29 |      90 |   84.98 | 183-201,252-273   
  evm.ts                               |    36.3 |      100 |       0 |    36.3 | ...69-104,116-168 
  index.ts                             |   84.27 |    83.52 |      90 |   84.27 | ...30-131,289-337 
  solana.ts                            |   47.44 |      100 |       0 |   47.44 | ...02-103,112-137 
  sui.ts                               |    49.5 |      100 |       0 |    49.5 | ...57-258,267-301 
  ton.ts                               |   15.03 |      100 |       0 |   15.03 | 24-153            
 ccip-sdk/src                          |   95.37 |    87.44 |      93 |   95.37 |                   
  chain.ts                             |   96.29 |    81.15 |   84.37 |   96.29 | ...2418,2451-2452 
  commits.ts                           |    90.9 |    81.25 |     100 |    90.9 | ...06,115-118,120 
  execution.ts                         |   89.69 |    85.29 |     100 |   89.69 | ...65-172,192-199 
  explorer.ts                          |     100 |      100 |     100 |     100 |                   
  extra-args.ts                        |     100 |    89.47 |     100 |     100 | 225,260,297,312   
  fetch.ts                             |   98.27 |    93.47 |   97.72 |   98.27 | ...-851,1094-1096 
  gas.ts                               |   85.17 |    86.04 |      75 |   85.17 | ...83-294,403-452 
  http-status.ts                       |     100 |      100 |     100 |     100 |                   
  index.ts                             |     100 |      100 |     100 |     100 |                   
  messages.ts                          |    79.2 |    46.15 |      40 |    79.2 | ...99-310,314-327 
  networks.ts                          |     100 |    89.55 |     100 |     100 | ...11,227,293,308 
  offchain.ts                          |   84.64 |    76.92 |     100 |   84.64 | ...18-227,236-237 
  requests.ts                          |    95.4 |    90.58 |     100 |    95.4 | ...54-655,680-685 
  supported-chains.ts                  |     100 |      100 |     100 |     100 |                   
  types.ts                             |     100 |      100 |     100 |     100 |                   
  utils.ts                             |    99.2 |    95.97 |     100 |    99.2 | ...12,217-218,220 
 ccip-sdk/src/api                      |   93.22 |    83.44 |   94.73 |   93.22 |                   
  index.ts                             |   93.22 |    83.44 |   94.73 |   93.22 | ...92-895,898-901 
 ccip-sdk/src/aptos                    |   69.29 |    81.14 |   64.06 |   69.29 |                   
  exec.ts                              |   29.31 |      100 |       0 |   29.31 | 18-58             
  hasher.ts                            |   75.89 |       80 |   66.66 |   75.89 | 17-36,50-56       
  index.ts                             |   67.11 |    74.76 |   66.66 |   67.11 | ...1021,1025-1036 
  logs.ts                              |   95.77 |    84.83 |   83.33 |   95.77 | ...56,424,533-544 
  send.ts                              |    25.6 |      100 |       0 |    25.6 | ...2,63-80,93-125 
  token.ts                             |   23.75 |       75 |     100 |   23.75 | 35-156            
  types.ts                             |   65.97 |      100 |       0 |   65.97 | 26-33,65-89       
 ccip-sdk/src/canton                   |   44.65 |    76.56 |   31.66 |   44.65 |                   
  amount.ts                            |   92.59 |       70 |     100 |   92.59 | 22-23             
  ccv-addresses.ts                     |     100 |    91.07 |     100 |     100 | 13,30,64,67       
  defaults.ts                          |   99.28 |    90.24 |     100 |   99.28 | 93                
  events.ts                            |   45.48 |     52.5 |   23.52 |   45.48 | ...16-528,534-543 
  index.ts                             |   33.53 |     60.6 |   12.82 |   33.53 | ...2536,2539-2541 
  types.ts                             |   95.34 |      100 |      50 |   95.34 | 55-62             
  update-id.ts                         |   98.11 |    88.88 |     100 |   98.11 | 52                
 ccip-sdk/src/canton/client            |   56.53 |     61.9 |   20.58 |   56.53 |                   
  client.ts                            |   54.67 |       60 |   20.58 |   54.67 | ...16-735,750-770 
  index.ts                             |     100 |      100 |     100 |     100 |                   
 ...dk/src/canton/explicit-disclosures |   74.81 |    69.35 |    55.1 |   74.81 |                   
  acs.ts                               |   87.36 |     69.1 |      90 |   87.36 | ...20,568,606-607 
  eds.ts                               |   54.34 |      100 |       0 |   54.34 | ...86-393,397-402 
 ccip-sdk/src/canton/token-metadata    |   62.64 |      100 |       0 |   62.64 |                   
  client.ts                            |   62.64 |      100 |       0 |   62.64 | 104-163,170-174   
 ...dk/src/canton/transfer-instruction |    53.4 |      100 |       0 |    53.4 |                   
  client.ts                            |    53.4 |      100 |       0 |    53.4 | 97-180,187-191    
 ccip-sdk/src/errors                   |   89.34 |    77.09 |   55.47 |   89.34 |                   
  CCIPError.ts                         |     100 |      100 |     100 |     100 |                   
  codes.ts                             |     100 |      100 |     100 |     100 |                   
  index.ts                             |     100 |      100 |     100 |     100 |                   
  pure.ts                              |     100 |    85.71 |     100 |     100 | 32                
  recovery.ts                          |     100 |      100 |     100 |     100 |                   
  specialized.ts                       |   86.89 |    73.36 |   52.71 |   86.89 | ...3636,3659-3668 
  utils.ts                             |   94.44 |    81.48 |     100 |   94.44 | 15,17,22,24       
 ccip-sdk/src/evm                      |   91.36 |     82.2 |   93.04 |   91.36 |                   
  const.ts                             |   98.66 |    92.85 |     100 |   98.66 | 122-123           
  errors.ts                            |   91.98 |    81.57 |     100 |   91.98 | ...85,239-242,247 
  extra-args.ts                        |    94.5 |    61.01 |     100 |    94.5 | ...11-212,328-340 
  fork.test.data.ts                    |     100 |      100 |     100 |     100 |                   
  gas.ts                               |   98.19 |    63.15 |     100 |   98.19 | 90-91,93          
  hasher.ts                            |     100 |     92.3 |     100 |     100 | 135               
  index.ts                             |   85.44 |    80.14 |   90.66 |   85.44 | ...2691,2846-2877 
  logs.ts                              |   99.16 |    92.02 |      90 |   99.16 | 69-70,75-76       
  messageCodec.ts                      |     100 |      100 |     100 |     100 |                   
  messages.ts                          |     100 |      100 |     100 |     100 |                   
  offchain.ts                          |    87.5 |    71.42 |     100 |    87.5 | 13-14             
  simulate.ts                          |     100 |    94.82 |     100 |     100 | 109-111,425       
  types.ts                             |     100 |      100 |     100 |     100 |                   
 ccip-sdk/src/evm/viem                 |   79.76 |    90.62 |   69.23 |   79.76 |                   
  client-adapter.ts                    |     100 |       90 |     100 |     100 | 48,74             
  index.ts                             |     100 |      100 |     100 |     100 |                   
  wallet-adapter.ts                    |   63.09 |     90.9 |   55.55 |   63.09 | ...91-124,131-157 
 ccip-sdk/src/hasher                   |   94.29 |    78.94 |     100 |   94.29 |                   
  common.ts                            |     100 |      100 |     100 |     100 |                   
  hasher.ts                            |     100 |    66.66 |     100 |     100 | 19                
  index.ts                             |     100 |      100 |     100 |     100 |                   
  merklemulti.ts                       |   93.43 |       78 |     100 |   93.43 | ...06-307,315-316 
 ccip-sdk/src/shared                   |   85.32 |    84.33 |   82.35 |   85.32 |                   
  bcs-codecs.ts                        |   79.07 |    60.86 |   66.66 |   79.07 | ...42-252,260-269 
  codec.ts                             |    94.3 |    93.22 |     100 |    94.3 | 139-140,178-186   
  constants.ts                         |     100 |      100 |     100 |     100 |                   
 ccip-sdk/src/solana                   |    77.4 |    72.65 |   82.56 |    77.4 |                   
  cleanup.ts                           |   26.95 |    66.66 |   33.33 |   26.95 | ...59-101,114-227 
  exec.ts                              |   69.11 |    62.96 |   66.66 |   69.11 | ...69-473,513-514 
  extra-args.ts                        |   58.07 |       75 |      60 |   58.07 | 84-120,130-188    
  fork.test.data.ts                    |     100 |      100 |     100 |     100 |                   
  gas.ts                               |   92.06 |    68.57 |     100 |   92.06 | ...,81-90,170-171 
  hasher.ts                            |   96.49 |    81.81 |     100 |   96.49 | 64-67             
  index.ts                             |   81.06 |    78.03 |   85.18 |   81.06 | ...2161,2165-2198 
  logs.ts                              |   87.79 |    74.07 |     100 |   87.79 | ...50-151,163-164 
  offchain.ts                          |     100 |      100 |     100 |     100 |                   
  patchBorsh.ts                        |   78.31 |       50 |     100 |   78.31 | ...47,65-66,72-78 
  send.ts                              |    77.6 |    33.33 |      80 |    77.6 | ...52-360,403-442 
  signatures-cache.ts                  |   79.78 |    71.15 |    87.5 |   79.78 | ...51-260,274-275 
  types.ts                             |     100 |      100 |     100 |     100 |                   
  utils.ts                             |   77.44 |    64.17 |   81.25 |   77.44 | ...54-556,588-603 
 ccip-sdk/src/sui                      |      67 |    61.87 |   76.69 |      67 |                   
  discovery.ts                         |   47.37 |    48.27 |      60 |   47.37 | ...34-782,785-819 
  events.ts                            |   71.09 |     67.1 |    90.9 |   71.09 | ...30-443,470-481 
  exec.ts                              |   30.71 |      100 |       0 |   30.71 | 37-89,101-153     
  hasher.ts                            |   98.19 |    66.66 |     100 |   98.19 | 35,51             
  index.ts                             |    73.7 |    57.58 |   77.96 |    73.7 | ...2118,2134-2135 
  objects.ts                           |   55.24 |    85.45 |   83.33 |   55.24 | ...57-313,324-467 
  types.ts                             |     100 |      100 |     100 |     100 |                   
 ccip-sdk/src/sui/manuallyExec         |   53.36 |       75 |      50 |   53.36 |                   
  encoder.ts                           |    83.9 |    66.66 |     100 |    83.9 | 51-58,73-77,82    
  index.ts                             |   33.82 |      100 |       0 |   33.82 | 47-136            
 ccip-sdk/src/ton                      |   86.21 |    81.92 |   88.97 |   86.21 |                   
  exec.ts                              |     100 |      100 |     100 |     100 |                   
  extra-args.ts                        |   98.66 |    72.72 |     100 |   98.66 | 156-157,222       
  hasher.ts                            |   78.07 |    77.77 |      75 |   78.07 | 100-108,156-187   
  index.ts                             |   85.04 |    81.29 |   80.64 |   85.04 | ...2097,2104-2105 
  logs.ts                              |   94.61 |    85.71 |     100 |   94.61 | ...95-602,658-661 
  send.ts                              |   95.52 |    66.66 |     100 |   95.52 | 37-44,188         
  ton-cache.ts                         |     100 |    96.29 |     100 |     100 | 102               
  types.ts                             |   91.24 |    81.25 |     100 |   91.24 | ...61-63,71-74,92 
  utils.ts                             |    63.1 |    77.77 |    90.9 |    63.1 | ...37-395,397-400 
 scripts                               |   77.92 |    63.46 |    90.9 |   77.92 |                   
  useResource.ts                       |   77.92 |    63.46 |    90.9 |   77.92 | ...76-281,296-297 
---------------------------------------|---------|----------|---------|---------|-------------------

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant