# Common Scenarios
Source: https://docs.chain.link/ccip/evm/concepts/cross-chain-token/rate-limits/common-scenarios
Last Updated: 2025-06-09

> For the complete documentation index, see [llms.txt](/llms.txt).

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.

> **NOTE: v1.x pools**
>
> Use `setChainRateLimiterConfig(remoteSelector, outboundConfig, inboundConfig)` on each chain. Each call must include
> both outbound and inbound structs, so set the direction you are not changing to its current onchain values.

> **NOTE: v2.0 pools only**
>
> Use `setRateLimitConfig` with `fastFinality: false`. Each entry also sets both outbound and inbound, so set the
> direction you are not changing to its current onchain values.

## 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:

```solidity
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.

### Configuration pattern

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](/ccip/evm/concepts/cross-chain-token/rate-limits/emergency-actions) for owner-only alternatives, such as removing the lane from the token pool.

## Scenario: removing rate limits

> **CAUTION: Not recommended**
>
> Removing rate limits turns off a defensive safety mechanism.

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

> **CAUTION: 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](https://chain.link/terms) 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.