Common Scenarios

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

Worked configuration scenarios for common rate limit use cases. Examples illustrate capacity and refill calculations — recalculate for your token, lane, and risk tolerance.

All scenarios assume you are pool owner or rateLimitAdmin, have inspected current configuration, and 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 outbound on the source pool and inbound 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 fast-finality transfers have a different risk profile.

When to use this

Use this when your pool accepts fast-finality transfers (setAllowedFinalityConfig permits them) and you want separate limits for that traffic.

Example configuration

Assume default buckets are configured as in the 18-decimal scenario above. On the source chain, add a fast-finality outbound limit at 50% of 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 = 550000000000000000

If the fast-finality bucket is not enabled (isEnabled = false), fast-finality transfers 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, 550000000000000000)
});

tokenPool.setRateLimitConfig(args);

Scenario: pausing a lane

This scenario demonstrates how to effectively pause transfers on a specific lane using rate limits.

When to use this

Use this pattern during incidents, investigations, or maintenance when transfers must be temporarily halted.

Configuration pattern

On both chains, for both bucket types (if FTF is enabled), set:

isEnabled = true
capacity  = 0
rate      = 0

for the relevant direction (outbound on source, inbound on destination).

This blocks all transfers for that direction without disabling the limiter entirely.

See Emergency Actions for owner-only alternatives such as lane config removal for the token pool.

Scenario: removing rate limits

This scenario demonstrates how to remove rate limits entirely for a bucket.

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 to both inbound and outbound if you want both directions unconstrained. Apply to both default and fast-finality entries if both were previously enabled.

Important notes

Scenario values must always be recalculated 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 refill buckets to full capacity in v2.0
A lane requires coordinated configuration on both source and destination pools
When fast-finality 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.