Ccip rate limit management

src/config/sidebar/__tests__/__snapshots__/ccip-dynamic.test.ts.snap

@@ -278,6 +278,47 @@ exports[`CCIP Sidebar Configuration Snapshot should match the expected sidebar s
         "title": "Manual execution",
         "url": "ccip/concepts/manual-execution",
       },
+      {
+        "children": [
+          {
+            "title": "Overview",
+            "url": "ccip/concepts/rate-limit-management/overview",
+          },
+          {
+            "title": "How Rate Limits Work",
+            "url": "ccip/concepts/rate-limit-management/how-rate-limits-work",
+          },
+          {
+            "title": "Prerequisites and Permissions",
+            "url": "ccip/concepts/rate-limit-management/prerequisites-and-permissions",
+          },
+          {
+            "title": "Inspect Current Rate Limits",
+            "url": "ccip/concepts/rate-limit-management/inspect-current-rate-limits",
+          },
+          {
+            "title": "Token Units and Decimals",
+            "url": "ccip/concepts/rate-limit-management/token-units-and-decimals",
+          },
+          {
+            "title": "Update Rate Limits",
+            "url": "ccip/concepts/rate-limit-management/update-rate-limits",
+          },
+          {
+            "title": "Emergency Actions",
+            "url": "ccip/concepts/rate-limit-management/emergency-actions",
+          },
+          {
+            "title": "Common Scenarios",
+            "url": "ccip/concepts/rate-limit-management/common-scenarios",
+          },
+          {
+            "title": "Executing with a Multisig",
+            "url": "ccip/concepts/rate-limit-management/executing-with-a-multisig",
+          },
+        ],
+        "title": "Rate Limit Management",
+      },
       {
         "chainTypes": [
           "evm",

src/config/sidebar/ccip-dynamic.ts

@@ -17,8 +17,8 @@
 import evmCcipV151Contents from "./ccip/api-reference/evm/v1_5_1.json" with { type: "json" }
 import evmCcipV160Contents from "./ccip/api-reference/evm/v1_6_0.json" with { type: "json" }
 import evmCcipV161Contents from "./ccip/api-reference/evm/v1_6_1.json" with { type: "json" }
 import evmCcipV162Contents from "./ccip/api-reference/evm/v1_6_2.json" with { type: "json" }
 import evmCcipV163Contents from "./ccip/api-reference/evm/v1_6_3.json" with { type: "json" }
 import aptosCcipV160Contents from "./ccip/api-reference/aptos/v1_6_0.json" with { type: "json" }
 import svmCcipV160Contents from "./ccip/api-reference/svm/v1_6_0.json" with { type: "json" }
 
@@ -253,6 +253,57 @@
         url: "ccip/concepts/manual-execution",
         // Universal
       },
+      // NEW: Rate Limit Management folder + children (Universal)
+      {
+        title: "Rate Limit Management",
+        children: [
+          {
+            title: "Overview",
+            url: "ccip/concepts/rate-limit-management/overview",
+            // Universal
+          },
+          {
+            title: "How Rate Limits Work",
+            url: "ccip/concepts/rate-limit-management/how-rate-limits-work",
+            // Universal
+          },
+          {
+            title: "Prerequisites and Permissions",
+            url: "ccip/concepts/rate-limit-management/prerequisites-and-permissions",
+            // Universal
+          },
+          {
+            title: "Inspect Current Rate Limits",
+            url: "ccip/concepts/rate-limit-management/inspect-current-rate-limits",
+            // Universal
+          },
+          {
+            title: "Token Units and Decimals",
+            url: "ccip/concepts/rate-limit-management/token-units-and-decimals",
+            // Universal
+          },
+          {
+            title: "Update Rate Limits",
+            url: "ccip/concepts/rate-limit-management/update-rate-limits",
+            // Universal
+          },
+          {
+            title: "Emergency Actions",
+            url: "ccip/concepts/rate-limit-management/emergency-actions",
+            // Universal
+          },
+          {
+            title: "Common Scenarios",
+            url: "ccip/concepts/rate-limit-management/common-scenarios",
+            // Universal
+          },
+          {
+            title: "Executing with a Multisig",
+            url: "ccip/concepts/rate-limit-management/executing-with-a-multisig",
+            // Universal
+          },
+        ],
+      },
       {
         title: "Best Practices",
         url: "ccip/concepts/best-practices/evm",

src/content/ccip/concepts/rate-limit-management/common-scenarios.mdx

@@ -0,0 +1,109 @@
+---
+section: ccip
+date: Last Modified
+title: "Common Scenarios"
+---
+
+This page provides worked configuration scenarios for common rate limit use cases. These examples illustrate how capacity and refill values are calculated and applied for different token types and operational goals.
+
+All scenarios assume:
+
+- you have the `rateLimitAdmin` role
+- you have inspected the current configuration
+- you have validated token units and decimals
+
+These scenarios are examples, not defaults. Values must always be recalculated for the specific token, lane, and risk tolerance.
+
+## Scenario: 18-decimal tokens
+
+This scenario applies to tokens with **18 decimals**, such as LINK or ETH.
+
+### When to use this
+
+Use this pattern when managing rate limits for an 18-decimal token and you want to allow a bounded amount of value to flow steadily between two chains.
+
+### Example configuration
+
+Assumptions:
+
+- desired inbound capacity: 20 tokens
+- desired outbound capacity: 10 tokens
+- refill rate: 0.1 tokens per second
+
+Converted to base units:
+
+- inbound capacity: `20 × 10^18 = 20000000000000000000`
+- outbound capacity (90% of inbound): `10 × 10^18 = 10000000000000000000`
+- refill rate: `0.1 × 10^18 = 100000000000000000`
+
+Inbound and outbound limits are configured separately for each token pool, with values swapped appropriately on each side of the lane.
+
+## Scenario: 6-decimal tokens
+
+This scenario applies to tokens with **6 decimals**, such as USDC or USDT.
+
+### When to use this
+
+Use this pattern when configuring rate limits for stablecoins or other low-decimal tokens.
+
+### Example configuration
+
+Assumptions:
+
+- desired inbound capacity: 2000 tokens
+- desired outbound capacity: 1000 tokens
+- inbound refill rate: 5 tokens per second
+- outbound refill rate: 10 tokens per second
+
+Converted to base units:
+
+- inbound capacity: `2000 × 10^6 = 2000000000`
+- outbound capacity (90% of inbound): `1000 × 10^6 = 1000000000`
+- inbound refill rate: `5 × 10^6 = 5000000`
+- outbound refill rate: `10 × 10^6 = 10000000`
+
+As with 18-decimal tokens, inbound and outbound configurations must be applied on both sides of the lane.
+
+## 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
+
+To lock down a lane:
+
+- enable the rate limit
+- set capacity to `1`
+- set refill rate to `1`
+
+Apply this configuration to **both inbound and outbound** limits for the lane.
+
+This allows only a negligible transfer before capacity is exhausted, causing subsequent transfers to fail.
+
+## Scenario: removing rate limits
+
+This scenario demonstrates how to remove rate limits entirely for a lane.
+
+### When to use this
+
+Use this pattern only when you intentionally want transfers to be unconstrained by rate limits.
+
+### Configuration pattern
+
+To remove rate limits:
+
+- set `isEnabled` to `false`
+- set `capacity` to `0`
+- set `rate` to `0`
+
+Apply this configuration to both inbound and outbound limits.
+
+## Important notes
+
+- Scenario values must always be recalculated for the specific token and lane
+- Do not copy example values without adjusting for decimals and desired behavior
+- Changes take effect immediately once the transaction is confirmed

src/content/ccip/concepts/rate-limit-management/emergency-actions.mdx

@@ -0,0 +1,65 @@
+---
+section: ccip
+date: Last Modified
+title: "Emergency Actions (Incident Response Only)"
+---
+
+This page describes emergency actions that can be taken to **contain or halt cross-chain transfers on a specific CCIP lane** using rate limit configuration.
+
+These actions are intended for **incident response, maintenance, or risk containment** scenarios. They should not be used for routine configuration.
+
+## When to use emergency actions
+
+You may need to take emergency action if:
+
+- abnormal or unexpected transfer activity is detected
+- a misconfiguration or incident is under investigation
+- maintenance requires temporarily stopping transfers on a lane
+
+Emergency actions are scoped to a **specific token pool and lane**. They do not pause CCIP globally.
+
+## Locking down a lane with minimal values
+
+To effectively stop bridging activity on a lane, you can configure rate limits with **very small capacity and refill values**.
+
+Because rate limits cannot be set to zero while enabled, the practical approach is to set:
+
+- **capacity** to the smallest transferable unit (for example, `1`)
+- **rate** to `1`
+
+This configuration allows only a negligible transfer before the bucket is depleted, causing subsequent transfers to fail.
+
+## Example configuration
+
+Conceptually, a lane can be locked down by calling `setChainRateLimiterConfig` with the following values:
+
+- outboundConfig: `[true, "1", "1"]`
+- inboundConfig: `[true, "1", "1"]`
+
+Both inbound and outbound limits should be set to ensure transfers are blocked in both directions.
+
+## Important considerations
+
+When locking down a lane:
+
+- transfers may still succeed for a minimal amount before capacity is exhausted
+- behavior depends on the token’s smallest unit
+- the change takes effect immediately after the transaction is confirmed
+
+This approach is intended to **contain activity**, not to permanently disable rate limits.
+
+## Restoring normal operation
+
+To resume normal transfers, update the inbound and outbound rate limit configuration with appropriate capacity and refill values.
+
+Always revalidate token units and existing configuration before restoring service.
+
+## What this page does not cover
+
+This page does not cover:
+
+- routine rate limit tuning
+- worked examples for different token decimals
+- fully removing rate limits
+
+Those topics are covered in the [common scenarios](/ccip/concepts/rate-limit-management/common-scenarios) section.