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

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.

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

> **NOTE: v2.0**
>
> Use `setRateLimitConfig` with `fastFinality: false`.

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

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

## Scenario: removing rate limits

> **CAUTION: Not recommended**
>
> Removing rate limits entirely removes a defensive safety mechanism. Use this pattern only when you intentionally want
> transfers to be unconstrained by rate limits for that bucket.

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

> **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.