Skip to content

docs: add programmable token transfers, non-EVM messaging, and Next.j…#165

Merged
aelmanaa merged 1 commit intomainfrom
docs/multi-chain-guides
Mar 3, 2026
Merged

docs: add programmable token transfers, non-EVM messaging, and Next.j…#165
aelmanaa merged 1 commit intomainfrom
docs/multi-chain-guides

Conversation

@aelmanaa
Copy link
Collaborator

@aelmanaa aelmanaa commented Mar 3, 2026

This pull request significantly improves the documentation for using the Chainlink CCIP SDK in browser environments and clarifies cross-chain messaging and token transfer usage. The updates focus on polyfill and dependency guidance for different bundlers, handling of dependency version conflicts, and clearer examples for cross-chain operations. The most important changes are grouped below.

Browser SDK Setup & Polyfill Guidance:

  • Clarified when the buffer polyfill is required: only for Solana, TON, and Sui chains, not for EVM- or Aptos-only projects. Added detailed tables and bundler-specific notes (Vite, Webpack, Next.js) for polyfill requirements.
  • Added explicit configuration examples for Webpack and Next.js, including how to set up resolve.alias for @noble/hashes and when to include polyfills for EVM-only vs. multi-chain projects. [1] [2] [3]
  • Added troubleshooting for common errors like "ERR_PACKAGE_PATH_NOT_EXPORTED" and "Buffer is not defined", with actionable solutions and cross-references to relevant sections.

Dependency Version Conflict Resolution:

  • Documented the version conflict between ethers and @mysten/sui for @noble/hashes, providing override/resolution instructions for npm, yarn, and pnpm, and emphasizing the need for a bundler alias to avoid runtime errors. [1] [2] [3] [4]
  • Added guidance for legacy Next.js versions (<13.4.5) on how to resolve type declaration issues via tsconfig.json paths.

Cross-Chain Messaging & Token Transfer Examples:

  • Added a new "Cross-Chain Token Transfers" section with clear, chain-specific code samples for EVM→EVM, EVM→Solana, and EVM→Aptos token transfers, highlighting that the SDK auto-populates chain-specific extraArgs for token-only transfers.
  • Clarified the difference between token-only transfers (now fully abstracted by the SDK) and programmable token transfers (which require explicit extraArgs), and provided links to in-depth tutorials for Solana and Aptos message construction. [1] [2] [3] [4] [5] [6] [7] [8]

General Improvements & Clarifications:

  • Reorganized and clarified documentation structure for SDK setup, tree-shaking, bundle sizes, and troubleshooting, making it easier for developers to find relevant information for their stack. [1] [2] [3]
  • Updated terminology and section headers for consistency (e.g., "Arbitrary Messaging (Data Only)" instead of "Simple Message") and clarified requirements for programmable token transfers. [1] [2] [3]

These changes make the SDK documentation more robust, developer-friendly, and accurate for multi-chain and cross-environment use cases.

…s configs

- Rename "Simple Message" to "Arbitrary Messaging (Data Only)"
- Add explicit "Programmable Token Transfer" section (data + tokens)
- Add cross-chain token transfer examples (EVM→Solana, EVM→Aptos)
- Add EVM↔Aptos messaging examples
- Link to central docs for non-EVM message building details
- Clarify SDK auto-populates extraArgs for token-only transfers
- Add Webpack EVM-only, Next.js EVM-only, and Next.js multi-chain configs
- Add @noble/hashes version conflict section and troubleshooting
@aelmanaa aelmanaa requested a review from a team as a code owner March 3, 2026 22:19
@vercel
Copy link

vercel bot commented Mar 3, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
ccip-tools-ts Ready Ready Preview, Comment Mar 3, 2026 10:23pm

Request Review

@github-actions
Copy link

github-actions bot commented Mar 3, 2026

👋 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!

@aelmanaa aelmanaa merged commit f8cd9b0 into main Mar 3, 2026
11 checks passed
@aelmanaa aelmanaa deleted the docs/multi-chain-guides branch March 3, 2026 22:24
@github-actions
Copy link

github-actions bot commented Mar 3, 2026

Coverage Report

ℹ tests 687
ℹ suites 211
ℹ pass 685
ℹ fail 0
ℹ cancelled 0
ℹ skipped 2
ℹ todo 0
ℹ duration_ms 42314.754188

> @chainlink/ccip-cli@1.0.0 test
> node --test

(node:4615) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
▶ lane-latency command
  ✔ should output JSON format correctly (4.771573ms)
  ✔ should resolve chain IDs to chain selectors (0.641175ms)
  ✔ should use custom API URL when provided (0.773632ms)
  ✔ should output log format correctly (0.716165ms)
  ✔ should handle chain IDs as input (0.610448ms)
  ✔ should handle chain selectors as input (0.581384ms)
  ✔ should throw CCIPApiClientNotAvailableError when --no-api flag is set (2.527343ms)
  ✔ should work normally when --no-api flag is false (0.597925ms)
  ▶ CCIP_API environment variable integration
    ✔ should respect CCIP_API=false environment variable (0.557269ms)
  ✔ CCIP_API environment variable integration (0.733769ms)
✔ lane-latency command (13.642194ms)
▶ e2e command show EVM
  ▶ pretty format (default)
    ✔ should show complete CCIP transaction details EVM to EVM (7788.859613ms)
  ✔ pretty format (default) (7789.944826ms)
  ▶ json format
    ✔ should output valid JSON with all expected fields (5562.764807ms)
  ✔ json format (5562.957065ms)
  ▶ log format
    ✔ should output in log format with object assignments (5645.482864ms)
  ✔ log format (5645.766394ms)
  ▶ verbose flag
    ✔ should work with verbose flag enabled (6245.808617ms)
  ✔ verbose flag (6246.058372ms)
  ▶ error handling
    ✔ should handle invalid transaction hash gracefully (7395.109154ms)
    ✔ should require transaction hash argument (1630.489552ms)
  ✔ error handling (9025.920667ms)
  ✔ should show complete CCIP transaction details EVM to Aptos (10309.304661ms)
  ✔ should show complete CCIP transaction details EVM to Solana (9658.833634ms)
✔ e2e command show EVM (54246.737027ms)
▶ e2e command show Solana
  ✔ should show complete CCIP transaction details Solana to EVM (5671.890507ms)
✔ e2e command show Solana (5672.129332ms)
▶ e2e command show Aptos
  ✔ should show complete CCIP transaction details Aptos to EVM (5693.421409ms)
✔ e2e command show Aptos (5693.618146ms)
﹣ e2e command show TON (0.057717ms) # SKIP
(node:4617) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
▶ formatCCIPError
  ✔ should return null for non-CCIPError instances (1.414096ms)
  ✔ should format CCIPError with code and message (0.526612ms)
  ✔ should include help section with recovery hint (0.187781ms)
  ✔ should include note section for transient errors (0.331999ms)
  ✔ should include retry timing for transient errors with retryAfterMs (0.332289ms)
  ✔ should not include note section for permanent errors (0.2035ms)
  ✔ should format error with structured output (0.250958ms)
  ✔ should include stack trace when verbose is true (0.378596ms)
  ✔ should not include stack trace when verbose is false (0.212707ms)
✔ formatCCIPError (5.688697ms)
ℹ tests 28
ℹ suites 12
ℹ pass 28
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 65822.823035
-------------------------------|---------|----------|---------|---------|---------------------------
File                           | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s         
-------------------------------|---------|----------|---------|---------|---------------------------
All files                      |   71.88 |    77.32 |   57.68 |   71.88 |                           
 ccip-cli/src                  |   89.09 |       80 |      50 |   89.09 |                           
  index.ts                     |   89.09 |       80 |      50 |   89.09 | 50-52,63-64,86-90,96-97   
 ccip-cli/src/commands         |   54.47 |    72.85 |    54.9 |   54.47 |                           
  index.ts                     |     100 |      100 |     100 |     100 |                           
  lane-latency.ts              |   72.97 |     87.5 |   33.33 |   72.97 | 41-55,62-69,103-109       
  manual-exec.ts               |   27.11 |      100 |       0 |   27.11 | 56-120,127-137,139-234    
  parse.ts                     |   57.14 |      100 |       0 |   57.14 | 46-50,57-64,66-91         
  send.ts                      |   16.29 |      100 |       0 |   16.29 | 52-153,160-167,169-356    
  show.ts                      |   90.07 |    63.63 |      60 |   90.07 | ...74-176,185-186,226-227 
  supported-tokens.ts          |   21.72 |      100 |       0 |   21.72 | ...99-195,197-252,254-267 
  token.ts                     |   22.72 |      100 |       0 |   22.72 | 24-53,60-67,69-132        
  types.ts                     |     100 |      100 |     100 |     100 |                           
  utils.ts                     |   85.29 |    74.28 |    92.3 |   85.29 | ...85-595,603-611,621-627 
 ccip-cli/src/providers        |    54.1 |    75.51 |   17.39 |    54.1 |                           
  aptos.ts                     |   53.65 |      100 |       0 |   53.65 | ...70,78-85,91-92,101-123 
  evm.ts                       |   46.03 |      100 |       0 |   46.03 | 20,31-63                  
  index.ts                     |   82.05 |    72.72 |      80 |   82.05 | 51-52,195-234             
  solana.ts                    |   50.42 |      100 |       0 |   50.42 | ...-71,79-85,89-90,99-117 
  sui.ts                       |   64.28 |      100 |       0 |   64.28 | 10-14                     
  ton.ts                       |   14.58 |      100 |       0 |   14.58 | 22-144                    
 ccip-sdk/src                  |   94.92 |     86.9 |   94.28 |   94.92 |                           
  chain.ts                     |   93.94 |       82 |   73.33 |   93.94 | ...43,1050,1139,1272-1282 
  commits.ts                   |     100 |    94.73 |     100 |     100 | 52                        
  execution.ts                 |   92.19 |     92.3 |     100 |   92.19 | 130-137,149-156           
  explorer.ts                  |     100 |      100 |     100 |     100 |                           
  extra-args.ts                |     100 |    86.66 |     100 |     100 | 169,204                   
  gas.ts                       |   88.88 |       50 |     100 |   88.88 | 100-111,134-138           
  http-status.ts               |     100 |      100 |     100 |     100 |                           
  index.ts                     |     100 |      100 |     100 |     100 |                           
  offchain.ts                  |   92.97 |    83.78 |     100 |   92.97 | ...37,157,172-174,176-182 
  requests.ts                  |   90.76 |    83.33 |     100 |   90.76 | ...64-368,433-434,438-439 
  supported-chains.ts          |     100 |      100 |     100 |     100 |                           
  types.ts                     |     100 |      100 |     100 |     100 |                           
  utils.ts                     |   95.55 |    90.26 |     100 |   95.55 | ...70,734-735,751,816-824 
 ccip-sdk/src/api              |   95.91 |    80.32 |   85.71 |   95.91 |                           
  index.ts                     |   95.91 |    80.32 |   85.71 |   95.91 | ...29-330,394-395,444-449 
 ccip-sdk/src/aptos            |    56.5 |    69.69 |   56.66 |    56.5 |                           
  exec.ts                      |   29.31 |      100 |       0 |   29.31 | 18-58                     
  hasher.ts                    |   76.31 |       80 |   66.66 |   76.31 | 19-38,52-58               
  index.ts                     |   58.02 |    75.34 |   59.52 |   58.02 | ...84-719,723-825,829-840 
  logs.ts                      |   78.52 |    57.44 |      75 |   78.52 | ...90-196,200-233,264-268 
  send.ts                      |    25.2 |      100 |       0 |    25.2 | 10-51,62-79,92-123        
  token.ts                     |   23.75 |       75 |     100 |   23.75 | 35-156                    
  types.ts                     |   65.62 |      100 |       0 |   65.62 | 25-32,64-88               
 ccip-sdk/src/errors           |   87.26 |     77.4 |   47.54 |   87.26 |                           
  CCIPError.ts                 |     100 |      100 |     100 |     100 |                           
  codes.ts                     |     100 |      100 |     100 |     100 |                           
  index.ts                     |     100 |      100 |     100 |     100 |                           
  recovery.ts                  |     100 |      100 |     100 |     100 |                           
  specialized.ts               |   84.49 |    72.72 |   44.82 |   84.49 | ...68,3289-3298,3319-3328 
  utils.ts                     |   94.44 |    81.48 |     100 |   94.44 | 15,17,22,24               
 ccip-sdk/src/evm              |   81.06 |    70.45 |   81.57 |   81.06 |                           
  const.ts                     |     100 |      100 |     100 |     100 |                           
  errors.ts                    |   86.42 |    79.22 |     100 |   86.42 | ...12-113,159-161,202-220 
  extra-args.ts                |   94.44 |    61.66 |     100 |   94.44 | ...82-183,208-209,326-338 
  fork.test.data.ts            |     100 |      100 |     100 |     100 |                           
  gas.ts                       |      98 |    53.84 |     100 |      98 | 72-73,75                  
  hasher.ts                    |     100 |    72.72 |     100 |     100 | 108,134,164               
  index.ts                     |   73.86 |    74.38 |   81.13 |   73.86 | ...76,1493-1536,1584-1591 
  logs.ts                      |   34.32 |    68.42 |      25 |   34.32 | ...13-214,229-258,275-302 
  messages.ts                  |   91.81 |    46.15 |     100 |   91.81 | ...47-248,257-258,282-283 
  offchain.ts                  |   56.25 |      100 |       0 |   56.25 | 10-16                     
  types.ts                     |     100 |    93.33 |     100 |     100 | 18                        
 ccip-sdk/src/evm/viem         |   77.72 |       92 |   69.23 |   77.72 |                           
  client-adapter.ts            |     100 |     92.3 |     100 |     100 | 48                        
  index.ts                     |     100 |      100 |     100 |     100 |                           
  wallet-adapter.ts            |   63.09 |     90.9 |   55.55 |   63.09 | ...6,53-73,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 | ...59-260,306-307,315-316 
 ccip-sdk/src/shared           |   88.05 |    69.23 |     100 |   88.05 |                           
  bcs-codecs.ts                |   87.87 |    66.66 |     100 |   87.87 | 75-87,104-106             
  constants.ts                 |     100 |      100 |     100 |     100 |                           
 ccip-sdk/src/solana           |   52.77 |    69.06 |   54.76 |   52.77 |                           
  cleanup.ts                   |   12.22 |      100 |       0 |   12.22 | 29-229                    
  exec.ts                      |    9.43 |      100 |       0 |    9.43 | ...68-343,345-384,386-498 
  hasher.ts                    |   96.58 |    81.81 |     100 |   96.58 | 67-70                     
  index.ts                     |   72.93 |    74.01 |    64.7 |   72.93 | ...10,1514-1538,1542-1563 
  logs.ts                      |   74.19 |    27.27 |     100 |   74.19 | ...,50-51,53-54,56-88,119 
  offchain.ts                  |   62.22 |      100 |       0 |   62.22 | 29-45                     
  patchBorsh.ts                |   65.06 |    57.14 |      75 |   65.06 | 30-49,65-66,72-78         
  send.ts                      |   13.93 |      100 |       0 |   13.93 | ...57-246,259-325,327-366 
  types.ts                     |   74.46 |      100 |       0 |   74.46 | 36-47                     
  utils.ts                     |   54.27 |    77.77 |   54.54 |   54.27 | ...40-353,395-458,464-479 
 ccip-sdk/src/sui              |   31.59 |    88.88 |   17.85 |   31.59 |                           
  discovery.ts                 |   15.13 |      100 |       0 |   15.13 | 20-36,49-185,188-218      
  events.ts                    |   19.85 |      100 |       0 |   19.85 | ...18-275,280-398,407-428 
  hasher.ts                    |   98.16 |    66.66 |     100 |   98.16 | 33,49                     
  index.ts                     |    37.6 |    92.85 |   17.94 |    37.6 | ...61-862,866-867,871-872 
  objects.ts                   |   19.04 |      100 |       0 |   19.04 | ...04-119,133-183,194-336 
 ccip-sdk/src/sui/manuallyExec |   39.46 |      100 |       0 |   39.46 |                           
  encoder.ts                   |   47.67 |      100 |       0 |   47.67 | 42-86                     
  index.ts                     |    34.3 |      100 |       0 |    34.3 | 48-137                    
 ccip-sdk/src/ton              |   74.12 |    82.41 |   64.78 |   74.12 |                           
  exec.ts                      |     100 |      100 |     100 |     100 |                           
  hasher.ts                    |   77.95 |    77.77 |      75 |   77.95 | 99-107,155-186            
  index.ts                     |   69.84 |    75.86 |   52.27 |   69.84 | ...10,1217-1218,1225-1226 
  logs.ts                      |     100 |    98.43 |     100 |     100 | 56                        
  send.ts                      |   96.39 |    73.91 |     100 |   96.39 | 38-45                     
  types.ts                     |   77.94 |    69.23 |   66.66 |   77.94 | ...-73,91,118-131,133-136 
  utils.ts                     |   60.88 |    83.72 |    87.5 |   60.88 | ...55-261,269-327,329-332 
-------------------------------|---------|----------|---------|---------|---------------------------

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.

2 participants