Common Scenarios

Worked examples for TokenPool v2.0 contracts. v1.x pools differences are noted inline.

The examples show capacity and refill calculations for common rate limit use cases. Recalculate the values for your token, lane, and risk tolerance.

All scenarios assume you are the pool owner or its rateLimitAdmin, have inspected the current configuration, and have validated decimals on each chain.

Scenario: 18-decimal tokens (default bucket)

Tokens with 18 decimals (LINK, ETH) on the default bucket.

Source chain: outbound capacity 10 tokens, refill 0.1 tokens/sec.

outbound capacity: 10 × 10^18  = 10000000000000000000
outbound rate:     0.1 × 10^18 = 100000000000000000

Destination chain: inbound capacity 11 tokens (10% headroom), refill 0.11 tokens/sec.

inbound capacity: 11 × 10^18   = 11000000000000000000
inbound rate:     0.11 × 10^18 = 110000000000000000

Submit the outbound values on the source pool and the inbound values on the destination pool.

Scenario: 6-decimal tokens (default bucket)

Stablecoins or other 6-decimal tokens.

Source chain:

outbound capacity: 1000 × 10^6 = 1000000000
outbound rate:     5 × 10^6    = 5000000

Destination chain:

inbound capacity: 1100 × 10^6 = 1100000000
inbound rate:     5.5 × 10^6  = 5500000

Ensure fractional rates produce integer base-unit values.

Scenario: fast-finality bucket (v2.0 pools only)

Fast-finality buckets are optional and often configured with tighter limits than default buckets because FTF transfers have a different risk profile.

When to use this

Use this when the lane carries FTF transfers (the source pool allows them through setAllowedFinalityConfig) and you want separate limits for that traffic.

Example configuration

Assume the default buckets are configured as in the 18-decimal scenario above. On the source chain, add a fast-finality outbound limit at 50% of the default:

fastFinality: true
outbound capacity: 5 × 10^18  = 5000000000000000000
outbound rate:     0.05 × 10^18 = 50000000000000000

On the destination chain, configure the fast-finality inbound bucket with 10% headroom:

fastFinality: true
inbound capacity: 5.5 × 10^18 = 5500000000000000000
inbound rate:     0.055 × 10^18 = 55000000000000000

If a fast-finality bucket is not enabled (isEnabled = false), FTF transfers in that direction use the default bucket instead.

Scenario: batch update - default + fast-finality (v2.0 pools only)

Update both bucket types in one transaction on a single pool:

RateLimitConfigArgs[] memory args = new RateLimitConfigArgs[](2);

args[0] = RateLimitConfigArgs({
  remoteChainSelector: REMOTE_SELECTOR,
  fastFinality: false,
  outboundRateLimiterConfig: Config(true, 10000000000000000000, 100000000000000000),
  inboundRateLimiterConfig: Config(true, 11000000000000000000, 110000000000000000)
});

args[1] = RateLimitConfigArgs({
  remoteChainSelector: REMOTE_SELECTOR,
  fastFinality: true,
  outboundRateLimiterConfig: Config(true, 5000000000000000000, 50000000000000000),
  inboundRateLimiterConfig: Config(true, 5500000000000000000, 55000000000000000)
});

tokenPool.setRateLimitConfig(args);

Scenario: pausing a lane

Setting a lane's rate limits to zero pauses transfers on that lane.

When to use this

Use this pattern during incidents, investigations, or maintenance when you need to halt transfers temporarily.

Set these values on both chains for the relevant direction (outbound on the source, inbound on the destination). If a fast-finality bucket is enabled for that direction, set them on both bucket types:

isEnabled = true
capacity  = 0
rate      = 0

This blocks all transfers in that direction without disabling the limiter.

See Emergency Actions for owner-only alternatives, such as removing the lane from the token pool.

Scenario: removing rate limits

Disabling a bucket removes its rate limits entirely.

When to use this

Use this pattern only when you intentionally want transfers to be unconstrained by rate limits for that bucket.

Configuration pattern

To remove rate limits for a bucket:

isEnabled = false
capacity  = 0
rate      = 0

Apply this to both inbound and outbound if you want both directions unconstrained, and to both the default and fast-finality entries if both were previously enabled.

Important notes

Always recalculate scenario values for the specific token, lane, and chain decimals
Do not copy example values without adjusting for decimals and desired behavior
Changes take effect immediately and, on v2.0 pools, refill buckets to full capacity
A lane requires coordinated configuration on both the source and destination pools
When a fast-finality bucket is enabled, configure or lock down both bucket types

Disclaimer

Chainlink CCIP is an interoperability messaging protocol. Chainlink does not hold or transfer any assets. The performance and behaviour of applications using Chainlink CCIP may depend on coding, engineering, configuration, and other technical implementation choices made by developers, token issuers, Cross-Chain Verifiers, and other participants. Users remain responsible for evaluating, configuring, testing, deploying, operating, and maintaining their own applications and integrations, including assessing any applicable operational, security, technical, and legal or regulatory risks. Please review the Chainlink Terms of Service which provides important information and disclosures. By using Chainlink CCIP, you expressly acknowledge and agree to accept these terms. Cross-Chain Verifiers (CCVs) may be operated by third parties. The security, availability, governance, and operational profile of a CCV varies depending on the verifier selected. Users are solely responsible for evaluating any CCVs used in connection with their applications or integrations and determining whether they are appropriate for their intended use case. This code represents an example of using a Chainlink product or service. It is provided "AS IS" and "AS AVAILABLE" without warranties of any kind, has not been audited, and may omit checks or error handling. Each party intending to use this reference implementation must perform its own audits, security and code review, and testing before any production deployment and ensure the operation and performance of such code matches expectations. Neither Chainlink Labs, the Chainlink Foundation, nor Chainlink node operators are responsible for outcomes due to errors in this example or how it is deployed or operated. Use of the Chainlink Network is subject to the Chainlink Foundation Terms of Service, which provides important information and disclosures. By using this code, you acknowledge and agree to these terms.

Common Scenarios

Get the latest Chainlink content straight to your inbox.