Token Units and Decimals

When you configure CCIP rate limits, you specify onchain values in the token's smallest unit on the chain where the pool is deployed, not in whole tokens.

Incorrect unit handling can result in rate limits orders of magnitude larger or smaller than intended.

Smallest unit vs human-readable amounts

A token's decimals determine its smallest unit:

• An 18-decimal token (for example, LINK or ETH) uses 10^18 base units per token
• A 6-decimal token (for example, USDC or USDT) uses 10^6 base units per token

Rate limit parameters such as capacity and rate must always be provided in these base units when you submit onchain transactions.

Local denomination on each chain

You set outbound limits on chain A and inbound limits on chain B in separate transactions, each scaled to that chain's decimals. Do not copy a base-unit value from one chain to another unless decimals match and you intend identical limits.

Converting values for onchain configuration

To convert a human-readable token amount into the value used onchain, apply the following formula:

On-chain value = human-readable amount × (10 ^ local token decimals)

This conversion applies to:

• capacity values
• refill rate values

Use the decimals of the chain where you are submitting the transaction.

Example: 18-decimal token

Token on Ethereum mainnet:

• Decimals: 18
• Desired outbound capacity: 100 tokens

Calculation:

100 × 10^18 = 100000000000000000000

The capacity value passed to the token pool contract on Ethereum must be 100000000000000000000.

If the token also uses 18 decimals on the remote chain, the counterpart inbound capacity is typically 110% of the outbound value, for headroom:

110 × 10^18 = 110000000000000000000

That inbound value is configured on the destination pool, not the source.

Example: 6-decimal token

Token that uses 6 decimals on the local chain:

• Decimals: 6
• Desired outbound capacity: 500 tokens

Calculation:

500 × 10^6 = 500000000

The capacity value passed to the token pool contract must be 500000000.

Cross-decimal lanes

If the same logical token uses different decimals on two chains, compute each side of the lane with that chain's local decimals. Do not reuse a base-unit value from one chain on another.

Common failure modes

The most common causes of misconfiguration include:

• assuming values are specified in whole tokens
• applying the wrong decimal precision
• copying a base-unit value from the source chain onto the destination chain without rescaling
• copying example values without recalculating for the target token

Any of these mistakes can:

• unintentionally block transfers
• allow far more volume than expected
• create operational risk that is difficult to detect immediately

Before updating rate limits

Before submitting any transaction that updates rate limits:

• verify the token's decimal precision on each chain in the lane
• recompute capacity and rate values from the human-readable amounts
• double-check values in base units
• confirm the inbound limit on the destination provides adequate headroom (typically ≥ 110% of source outbound)

Once values are submitted onchain, they take effect immediately and the bucket is refilled to full capacity.

What's next

After validating units and conversions, you can proceed to updating inbound and outbound rate limits for the selected token pool and lane.