Skip to content

feat(sdk): add simplified token transfer API #96

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

Jump to bottom
Open
aelmanaa wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(sdk): add simplified token transfer API #96

aelmanaa wants to merge 2 commits into from

Conversation

@aelmanaa
Copy link
Collaborator

@aelmanaa aelmanaa commented Jan 4, 2026

This pull request introduces a major simplification and standardization to the SDK's token transfer API, making it easier to use and less error-prone. The core improvement is the introduction of a tokenTransfer() factory for single-token transfers, which allows users to create transfer messages without manually specifying extraArgs or data. The changes also include robust normalization logic to ensure all message types are handled consistently across supported chains, and comprehensive tests for these new utilities. Additionally, the SDK's public API is expanded to expose these new types and helper functions.

SDK API Simplification and Normalization:

  • Added tokenTransfer() and message() factory functions, along with new types (MessageInput, TokenTransferMessage, etc.), to simplify and standardize message creation for token transfers and full messages. These are now exported from the SDK's entry point (ccip-sdk/src/index.ts).
  • Introduced the normalizeMessage utility, which converts both tokenTransfer() and message() inputs into a normalized internal format, automatically applying sensible defaults for extraArgs depending on the destination chain. This is now used throughout the chain implementations (EVM, Aptos) to ensure consistent behavior. [1] [2] [3] [4] [5] [6]
  • Added getDefaultExtraArgs utility to centralize and document the default extraArgs for each supported chain family, ensuring correct and maintainable defaults for token-only transfers.

Type and Documentation Improvements:

  • Updated SendMessageOpts in chain.ts to accept both tokenTransfer() and full message() formats, improving type safety and developer experience. Added detailed usage examples and documentation.
  • Cleaned up imports and type usage to reflect the new message handling approach.

Testing and Validation:

  • Added comprehensive unit tests for getDefaultExtraArgs and normalizeMessage utilities, covering all supported chain families and edge cases (immutability, field population, etc.). [1] [2]

Changelog and Versioning:

  • Updated the changelog to highlight the new simplified token transfer API and bumped the CLI version. [1] [2]

Summary of most important changes:

SDK API Simplification

  • Introduced tokenTransfer() and message() factory functions and types for easier, safer message creation; exported these from the SDK entry point.
  • Updated SendMessageOpts to accept both simplified and full message formats, with improved documentation and examples.

Normalization and Defaults

  • Added normalizeMessage utility and integrated it into EVM and Aptos chain implementations to ensure all messages are normalized with proper defaults for each chain. [1] [2] [3] [4] [5] [6]
  • Created getDefaultExtraArgs to centralize and document default extraArgs logic for all supported chain families.

Testing

  • Added thorough tests for getDefaultExtraArgs and normalizeMessage, ensuring correct defaults and normalization for all chains and message types. [1] [2]

Changelog/Versioning

  • Updated changelog and CLI version to reflect the new API and improvements. [1] [2]

@aelmanaa
feat(sdk): add simplified token transfer API
20c6ea2 
  Add tokenTransfer() factory function for single-token transfers
  without manual extraArgs/data configuration. Chain-specific
  defaults are applied automatically based on destination chain family.

  - Add tokenTransfer() and message() factory functions
  - Add type guards isTokenTransfer() and isFullMessage()
  - Extend getFee and sendMessage to accept MessageInput union
  - Add comprehensive tests for message types, defaults, and normalizer
@aelmanaa aelmanaa requested a review from a team as a code owner January 4, 2026 18:38
@vercel
Copy link

vercel bot commented Jan 4, 2026 •
edited
Loading

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

Project Deployment Review Updated (UTC)
ccip-tools-ts Error Error Jan 4, 2026 6:51pm

@github-actions
Copy link

github-actions bot commented Jan 4, 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!

@github-actions
Copy link

github-actions bot commented Jan 4, 2026

Coverage Report

ℹ tests 676
ℹ suites 223
ℹ pass 676
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 169969.326369
-------------------------------|---------|----------|---------|---------|---------------------------
File                           | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s         
-------------------------------|---------|----------|---------|---------|---------------------------
All files                      |   67.29 |    79.99 |   56.58 |   67.29 |                           
 ccip-cli/src                  |   86.45 |    83.33 |      50 |   86.45 |                           
  index.ts                     |   86.45 |    83.33 |      50 |   86.45 | 72-76,82-83,88-93         
 ccip-cli/src/commands         |   53.03 |    79.44 |   55.55 |   53.03 |                           
  index.ts                     |     100 |      100 |     100 |     100 |                           
  lane-latency.ts              |   67.74 |     87.5 |   33.33 |   67.74 | 23-37,44-51,85-91         
  manual-exec.ts               |      21 |      100 |       0 |      21 | 42-106,113-123,125-236    
  parse.ts                     |   41.79 |      100 |       0 |   41.79 | 22-26,33-40,42-67         
  send.ts                      |   11.59 |      100 |       0 |   11.59 | 34-136,143-150,152-345    
  show.ts                      |   89.61 |    63.82 |      60 |   89.61 | ...23-129,135-137,146-147 
  supported-tokens.ts          |   23.48 |      100 |       0 |   23.48 | ...83-175,177-232,234-247 
  types.ts                     |     100 |      100 |     100 |     100 |                           
  utils.ts                     |   86.59 |    84.03 |    91.3 |   86.59 | ...99-517,524-532,542-548 
 ccip-cli/src/providers        |   53.94 |       75 |   17.39 |   53.94 |                           
  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.95 |    72.09 |      80 |   82.95 | 49-50,188-223             
  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.16 |    89.33 |   93.75 |   94.16 |                           
  chain.ts                     |   93.01 |       84 |   71.42 |   93.01 | ...65,284-322,610,668-677 
  commits.ts                   |     100 |       90 |     100 |     100 | 35,52                     
  execution.ts                 |   84.61 |      100 |      75 |   84.61 | 122-143                   
  explorer.ts                  |     100 |      100 |     100 |     100 |                           
  extra-args.ts                |     100 |    78.57 |     100 |     100 | 71,90,103                 
  gas.ts                       |   96.42 |    92.85 |     100 |   96.42 | 81-85                     
  http-status.ts               |     100 |      100 |     100 |     100 |                           
  index.ts                     |     100 |      100 |     100 |     100 |                           
  message-defaults.ts          |     100 |      100 |     100 |     100 |                           
  message-normalizer.ts        |     100 |      100 |     100 |     100 |                           
  message.ts                   |     100 |      100 |     100 |     100 |                           
  offchain.ts                  |     100 |      100 |     100 |     100 |                           
  requests.ts                  |   78.97 |    76.92 |   85.71 |   78.97 | ...02-303,307-308,331-352 
  supported-chains.ts          |     100 |      100 |     100 |     100 |                           
  types.ts                     |     100 |      100 |     100 |     100 |                           
  utils.ts                     |   95.11 |    90.86 |     100 |   95.11 | ...51,515-516,532,597-605 
 ccip-sdk/src/api              |     100 |    94.73 |     100 |     100 |                           
  index.ts                     |     100 |    94.73 |     100 |     100 | 145                       
 ccip-sdk/src/aptos            |   57.63 |    68.75 |      60 |   57.63 |                           
  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.39 |    71.95 |   62.22 |   58.39 | ...10-745,749-842,846-857 
  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                     |   69.72 |      100 |       0 |   69.72 | 25-32,77-101              
  utils.ts                     |     100 |      100 |     100 |     100 |                           
 ccip-sdk/src/errors           |   80.94 |    76.61 |   49.55 |   80.94 |                           
  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               |   73.21 |    71.91 |   46.72 |   73.21 | ...39,1647-1656,1664-1673 
  utils.ts                     |   94.52 |    77.77 |     100 |   94.52 | 16,18,23,25               
 ccip-sdk/src/evm              |    64.9 |    78.82 |   62.85 |    64.9 |                           
  const.ts                     |     100 |      100 |     100 |     100 |                           
  errors.ts                    |   82.48 |    78.46 |     100 |   82.48 | ...55-157,188-195,198-216 
  hasher.ts                    |     100 |     87.5 |     100 |     100 | 122                       
  index.ts                     |   58.53 |    84.61 |   58.49 |   58.53 | ...12,1316-1389,1393-1442 
  logs.ts                      |   33.99 |    46.66 |      25 |   33.99 | ...13-214,229-258,274-302 
  messages.ts                  |     100 |      100 |     100 |     100 |                           
  offchain.ts                  |    80.4 |    53.33 |      75 |    80.4 | ...45-147,151-165,191-196 
 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/solana           |   51.33 |    64.25 |   55.81 |   51.33 |                           
  cleanup.ts                   |   12.22 |      100 |       0 |   12.22 | 29-229                    
  exec.ts                      |    9.27 |      100 |       0 |    9.27 | ...66-341,343-382,384-496 
  hasher.ts                    |   96.58 |    81.81 |     100 |   96.58 | 67-70                     
  index.ts                     |   69.93 |    68.55 |   64.15 |   69.93 | ...19,1423-1447,1451-1472 
  logs.ts                      |   74.19 |    27.27 |     100 |   74.19 | ...,50-51,53-54,56-88,119 
  offchain.ts                  |   78.87 |     64.7 |      50 |   78.87 | ...,96-97,110-111,126-142 
  patchBorsh.ts                |   65.06 |    57.14 |      75 |   65.06 | 30-49,65-66,72-78         
  send.ts                      |   14.84 |      100 |       0 |   14.84 | ...63-252,265-331,333-384 
  types.ts                     |   74.46 |      100 |       0 |   74.46 | 36-47                     
  utils.ts                     |   54.14 |    77.77 |      60 |   54.14 | ...71-284,326-389,395-410 
 ccip-sdk/src/sui              |   31.15 |    76.47 |   11.11 |   31.15 |                           
  discovery.ts                 |   16.56 |      100 |       0 |   16.56 | 18-34,44-157              
  events.ts                    |   30.21 |      100 |       0 |   30.21 | ...83-154,199-288,296-321 
  hasher.ts                    |   98.16 |    66.66 |     100 |   98.16 | 33,49                     
  index.ts                     |   33.68 |       80 |     7.5 |   33.68 | ...36-737,741-742,746-747 
  objects.ts                   |   12.77 |      100 |       0 |   12.77 | ...05-146,157-207,218-360 
 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              |   88.11 |    87.35 |   73.52 |   88.11 |                           
  exec.ts                      |     100 |      100 |     100 |     100 |                           
  hasher.ts                    |   77.95 |    77.77 |      75 |   77.95 | 99-107,155-186            
  index.ts                     |   93.81 |    88.23 |   67.39 |   93.81 | ...56,1060-1061,1065-1066 
  logs.ts                      |     100 |    98.52 |     100 |     100 | 56                        
  types.ts                     |   78.41 |    69.23 |   66.66 |   78.41 | ...-76,94,121-134,136-139 
  utils.ts                     |   75.98 |    75.43 |     100 |   75.98 | ...55-261,273-327,329-332 
-------------------------------|---------|----------|---------|---------|---------------------------

@aelmanaa aelmanaa requested a review from andrevmatos January 6, 2026 10:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@andrevmatos andrevmatos Awaiting requested review from andrevmatos

At least 1 approving review is required to merge this pull request.

Assignees

@andrevmatos andrevmatos

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@aelmanaa @andrevmatos