From 7d2a6a01240436c1833517247a636bb747cd9767 Mon Sep 17 00:00:00 2001
From: aelmanaa <aelmanaa@gmail.com>
Date: Thu, 16 Jan 2025 09:54:53 +0100
Subject: [PATCH] regorg

---
 .../sidebar/ccip/api-reference/v1_5_0.json    |    4 +
 .../sidebar/ccip/api-reference/v1_5_1.json    |   12 +
 src/config/versions/page-availability.ts      |    6 +
 .../v1.5.0/i-type-and-version.mdx             |   34 +
 .../v1.5.1/burn-from-mint-token-pool.mdx      |  108 +-
 .../api-reference/v1.5.1/burn-mint-erc20.mdx  |  402 +++--
 .../v1.5.1/burn-mint-token-pool-abstract.mdx  |  130 +-
 .../v1.5.1/burn-mint-token-pool.mdx           |  112 +-
 .../api-reference/v1.5.1/ccip-receiver.mdx    |  177 +-
 .../ccip/api-reference/v1.5.1/client.mdx      |  217 ++-
 .../api-reference/v1.5.1/i-router-client.mdx  |  128 +-
 .../v1.5.1/i-type-and-version.mdx             |   34 +
 .../ccip/api-reference/v1.5.1/index.mdx       |   18 +-
 .../v1.5.1/lock-release-token-pool.mdx        |  372 ++--
 .../v1.5.1/ownable-2-step-msg-sender.mdx      |   51 +
 .../api-reference/v1.5.1/ownable-2-step.mdx   |  222 +++
 .../ccip/api-reference/v1.5.1/pool.mdx        |  147 +-
 .../api-reference/v1.5.1/rate-limiter.mdx     |  313 ++--
 .../v1.5.1/registry-module-owner-custom.mdx   |  239 ++-
 .../v1.5.1/token-admin-registry.mdx           |  667 +++++---
 .../ccip/api-reference/v1.5.1/token-pool.mdx  | 1504 +++++++++++------
 src/content/ccip/best-practices.mdx           |    2 +-
 22 files changed, 3306 insertions(+), 1593 deletions(-)
 create mode 100644 src/content/ccip/api-reference/v1.5.0/i-type-and-version.mdx
 create mode 100644 src/content/ccip/api-reference/v1.5.1/i-type-and-version.mdx
 create mode 100644 src/content/ccip/api-reference/v1.5.1/ownable-2-step-msg-sender.mdx
 create mode 100644 src/content/ccip/api-reference/v1.5.1/ownable-2-step.mdx

diff --git a/src/config/sidebar/ccip/api-reference/v1_5_0.json b/src/config/sidebar/ccip/api-reference/v1_5_0.json
index 36b3f4fae03..6d456357a30 100644
--- a/src/config/sidebar/ccip/api-reference/v1_5_0.json
+++ b/src/config/sidebar/ccip/api-reference/v1_5_0.json
@@ -3,6 +3,10 @@
     "title": "Client Library",
     "url": "ccip/api-reference/v1.5.0/client"
   },
+  {
+    "title": "ITypeAndVersion",
+    "url": "ccip/api-reference/v1.5.0/i-type-and-version"
+  },
   {
     "title": "IRouterClient",
     "url": "ccip/api-reference/v1.5.0/i-router-client"
diff --git a/src/config/sidebar/ccip/api-reference/v1_5_1.json b/src/config/sidebar/ccip/api-reference/v1_5_1.json
index 99801228da3..7b44a661313 100644
--- a/src/config/sidebar/ccip/api-reference/v1_5_1.json
+++ b/src/config/sidebar/ccip/api-reference/v1_5_1.json
@@ -3,6 +3,10 @@
     "title": "Client Library",
     "url": "ccip/api-reference/v1.5.1/client"
   },
+  {
+    "title": "ITypeAndVersion",
+    "url": "ccip/api-reference/v1.5.1/i-type-and-version"
+  },
   {
     "title": "IRouterClient",
     "url": "ccip/api-reference/v1.5.1/i-router-client"
@@ -54,5 +58,13 @@
   {
     "title": "Errors",
     "url": "ccip/api-reference/v1.5.1/errors"
+  },
+  {
+    "title": "Ownable2Step",
+    "url": "ccip/api-reference/v1.5.1/ownable-2-step"
+  },
+  {
+    "title": "Ownable2StepMsgSender",
+    "url": "ccip/api-reference/v1.5.1/ownable-2-step-msg-sender"
   }
 ]
diff --git a/src/config/versions/page-availability.ts b/src/config/versions/page-availability.ts
index f23c8cd5447..bb9f93708ec 100644
--- a/src/config/versions/page-availability.ts
+++ b/src/config/versions/page-availability.ts
@@ -11,6 +11,12 @@ export const PAGE_AVAILABILITY: Record<string, Record<string, PageAvailability>>
     "rate-limiter": {
       notAvailableIn: ["v1.5.0"],
     },
+    "ownable-2-step-msg-sender": {
+      notAvailableIn: ["v1.5.0"],
+    },
+    "ownable-2-step": {
+      notAvailableIn: ["v1.5.0"],
+    },
   },
   "chainlink-local": {
     "mock-evm2evm-offramp": {
diff --git a/src/content/ccip/api-reference/v1.5.0/i-type-and-version.mdx b/src/content/ccip/api-reference/v1.5.0/i-type-and-version.mdx
new file mode 100644
index 00000000000..05f492abe0e
--- /dev/null
+++ b/src/content/ccip/api-reference/v1.5.0/i-type-and-version.mdx
@@ -0,0 +1,34 @@
+---
+section: ccip
+date: Last Modified
+title: "CCIP v1.5.0 ITypeAndVersion Interface API Reference"
+metadata:
+  description: "API documentation for the ITypeAndVersion interface in Chainlink CCIP v1.5.0, providing type and version information for contracts."
+---
+
+import { Aside } from "@components"
+import CcipCommon from "@features/ccip/CcipCommon.astro"
+
+<CcipCommon callout="importCCIPPackage151" />
+
+## ITypeAndVersion
+
+An interface that provides type and version information for contracts.
+
+[Git Source](https://github.com/smartcontractkit/ccip/tree/release/contracts-ccip-1.5.0/contracts/src/v0.8/shared/interfaces/ITypeAndVersion.sol)
+
+## Functions
+
+### typeAndVersion
+
+Returns the type and version of the contract.
+
+```solidity
+function typeAndVersion() external pure returns (string memory);
+```
+
+**Returns**
+
+| Type     | Description                           |
+| -------- | ------------------------------------- |
+| `string` | The type and version of the contract. |
diff --git a/src/content/ccip/api-reference/v1.5.1/burn-from-mint-token-pool.mdx b/src/content/ccip/api-reference/v1.5.1/burn-from-mint-token-pool.mdx
index f6b5897a841..4f0b025aceb 100644
--- a/src/content/ccip/api-reference/v1.5.1/burn-from-mint-token-pool.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/burn-from-mint-token-pool.mdx
@@ -11,71 +11,95 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`BurnFromMintTokenPool`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/pools/BurnFromMintTokenPool.sol) contract extends BurnMintTokenPoolAbstract to implement burn/mint functionality for third-party tokens using the `burnFrom(from, amount)` signature.
+## BurnFromMintTokenPool
+
+A specialized token pool contract that manages third-party tokens through minting and burning operations, specifically using the `burnFrom` function.
+
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/pools/BurnFromMintTokenPool.sol)
+
+**Inherits:**
+
+- [BurnMintTokenPoolAbstract](/ccip/api-reference/v1.5.1/burn-mint-token-pool-abstract)
+- [ITypeAndVersion](/ccip/api-reference/v1.5.1/i-type-and-version)
+
+<Aside>
+
+This pool manages third-party token minting and burning operations with the following characteristics:
+
+- The pool's whitelisting mode is permanently set during contract deployment
+- The pool can be configured to either:
+  - Accept transactions from any address as originalSender
+  - Accept transactions only from whitelisted originalSender addresses
+- Whitelisting mode can only be changed by deploying a new pool
+- Before deployment, ensure the token's burner/minter roles can be adjusted if needed
+- This implementation extends BurnMintTokenPool by using the `burnFrom(from, amount)` function
 
-<Aside type="caution">
-  Pool whitelisting mode is set in the constructor and cannot be modified later. It either accepts any address as
-  originalSender, or only accepts whitelisted originalSender. The only way to change whitelisting mode is to deploy a
-  new pool. If that is expected, please make sure the token's burner/minter roles are adjustable.
 </Aside>
 
-## Functions
+## State Variables
 
-### constructor
+### typeAndVersion
 
 ```solidity
-constructor(
-    IBurnMintERC20 token,
-    uint8 localTokenDecimals,
-    address[] memory allowlist,
-    address rmnProxy,
-    address router
-) TokenPool(token, localTokenDecimals, allowlist, rmnProxy, router)
+string public constant override typeAndVersion = "BurnFromMintTokenPool 1.5.1";
 ```
 
-Initializes the token pool with the specified parameters and approves the pool to burn from itself.
+<Aside>A constant identifier that specifies the contract type and version number.</Aside>
 
-<Aside type="note">
-  Some tokens allow burning from the sender without approval, but not all do. To be safe, the constructor approves the
-  pool to burn from itself with the maximum allowance.
-</Aside>
+**Returns**
 
-#### Parameters
+| Type     | Description                                           |
+| -------- | ----------------------------------------------------- |
+| `string` | The contract identifier "BurnFromMintTokenPool 1.5.1" |
 
-| Name               | Type           | Description                                                                                                                                                              |
-| ------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| token              | IBurnMintERC20 | The token managed by this pool                                                                                                                                           |
-| localTokenDecimals | uint8          | The number of decimals for the token on the local chain                                                                                                                  |
-| allowlist          | address[]      | List of addresses allowed to be original senders for token transfers. When allowlist is enabled, it ensures only token-developer specified addresses can transfer tokens |
-| rmnProxy           | address        | Address of the RMN proxy                                                                                                                                                 |
-| router             | address        | Address of the router                                                                                                                                                    |
+## Functions
 
 ### \_burn
 
+Internal function that executes the token burning operation.
+
 ```solidity
-function _burn(
-    uint256 amount
-) internal virtual override
+function _burn(uint256 amount) internal virtual override;
 ```
 
-Burns the specified amount of tokens using the `burnFrom(from, amount)` signature.
+<Aside>
+Implements the core burn functionality for the pool.
+
+The function can be overridden in derived contracts to implement different burning mechanisms while preserving the base logic.
 
-#### Parameters
+</Aside>
 
-| Name   | Type    | Description              |
-| ------ | ------- | ------------------------ |
-| amount | uint256 | Amount of tokens to burn |
+**Parameters**
 
-### typeAndVersion
+| Name     | Type      | Description                    |
+| -------- | --------- | ------------------------------ |
+| `amount` | `uint256` | The quantity of tokens to burn |
+
+### constructor
 
 ```solidity
-string public constant override typeAndVersion = "BurnFromMintTokenPool 1.5.1"
+constructor(
+  IBurnMintERC20 token,
+  uint8 localTokenDecimals,
+  address[] memory allowlist,
+  address rmnProxy,
+  address router
+) TokenPool(token, localTokenDecimals, allowlist, rmnProxy, router);
 ```
 
-Returns the type and version of the contract.
+<Aside>
+Sets up the BurnFromMintTokenPool contract with initial configuration.
+
+For maximum compatibility, the constructor automatically grants the pool maximum allowance to burn tokens from itself, as some tokens require explicit approval for burning operations.
+
+</Aside>
 
-#### Return Value
+**Parameters**
 
-| Type   | Description                              |
-| ------ | ---------------------------------------- |
-| string | The string "BurnFromMintTokenPool 1.5.1" |
+| Name                 | Type             | Description                                            |
+| -------------------- | ---------------- | ------------------------------------------------------ |
+| `token`              | `IBurnMintERC20` | Address of the token contract to be managed            |
+| `localTokenDecimals` | `uint8`          | Decimal precision of the local token                   |
+| `allowlist`          | `address[]`      | List of addresses authorized to interact with the pool |
+| `rmnProxy`           | `address`        | Address of the RMN proxy contract                      |
+| `router`             | `address`        | Address of the router contract                         |
diff --git a/src/content/ccip/api-reference/v1.5.1/burn-mint-erc20.mdx b/src/content/ccip/api-reference/v1.5.1/burn-mint-erc20.mdx
index da1881f5d1f..575d8f0b246 100644
--- a/src/content/ccip/api-reference/v1.5.1/burn-mint-erc20.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/burn-mint-erc20.mdx
@@ -11,192 +11,404 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`BurnMintERC20`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/shared/token/ERC20/BurnMintERC20.sol) contract implements a basic ERC20 token with burn and mint capabilities controlled through roles.
+## BurnMintERC20
 
-<Aside type="caution">
+An ERC20-compliant token contract that extends the standard functionality with controlled minting and burning capabilities through role-based access control.
 
-This contract has not been audited and is not yet approved for production use.
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/shared/token/ERC20/BurnMintERC20.sol)
+
+<Aside>
+
+Key features of this token contract:
+
+- Implements standard ERC20 functionality
+- Supports controlled token minting and burning through role assignments
+- Allows setting a maximum supply limit during deployment
+- Note: This contract is not yet audited or approved for production use
 
 </Aside>
 
+## Events
+
+### CCIPAdminTransferred
+
+```solidity
+event CCIPAdminTransferred(address indexed previousAdmin, address indexed newAdmin);
+```
+
+<Aside>
+  Logs when the CCIP administrator role changes hands. This event helps track administrative changes and provides
+  transparency for role transfers.
+</Aside>
+
+**Parameters**
+
+| Name            | Type      | Indexed | Description                    |
+| --------------- | --------- | ------- | ------------------------------ |
+| `previousAdmin` | `address` | Yes     | The address that held the role |
+| `newAdmin`      | `address` | Yes     | The address receiving the role |
+
 ## Errors
 
+### InvalidRecipient
+
+```solidity
+error InvalidRecipient(address recipient);
+```
+
+<Aside>
+  Thrown when an operation attempts to interact with an invalid address: - When the recipient is the zero address
+  (`address(0)`) - When the recipient is the token contract itself (`address(this)`)
+</Aside>
+
 ### MaxSupplyExceeded
 
 ```solidity
-error MaxSupplyExceeded(uint256 supplyAfterMint)
+error MaxSupplyExceeded(uint256 supplyAfterMint);
 ```
 
-Thrown when a mint would exceed the maximum token supply.
+<Aside>
+  Thrown when a minting operation would cause the total supply to exceed the maximum allowed supply. The error includes
+  the would-be total supply for debugging purposes.
+</Aside>
 
-| Parameter       | Type    | Description                                  |
-| --------------- | ------- | -------------------------------------------- |
-| supplyAfterMint | uint256 | Total supply that would result from the mint |
+## State Variables
 
-### InvalidRecipient
+### BURNER_ROLE
 
 ```solidity
-error InvalidRecipient(address recipient)
+bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");
 ```
 
-Thrown when trying to transfer or approve tokens for the contract itself.
+<Aside>
+  A unique identifier for the role that permits token burning operations. This role must be explicitly granted to
+  addresses that need burning capabilities.
+</Aside>
 
-| Parameter | Type    | Description               |
-| --------- | ------- | ------------------------- |
-| recipient | address | Invalid recipient address |
+### MINTER_ROLE
 
-## Events
+```solidity
+bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
+```
 
-### CCIPAdminTransferred
+<Aside>
+  A unique identifier for the role that permits token minting operations. This role must be explicitly granted to
+  addresses that need minting capabilities.
+</Aside>
+
+## Functions
+
+### \_approve
+
+Internal function that manages token spending allowances with built-in safety checks.
 
 ```solidity
-event CCIPAdminTransferred(address indexed previousAdmin, address indexed newAdmin)
+function _approve(address owner, address spender, uint256 amount) internal virtual override;
 ```
 
-Emitted when the CCIP admin role is transferred.
+<Aside>
 
-| Parameter     | Type    | Description                 |
-| ------------- | ------- | --------------------------- |
-| previousAdmin | address | Previous CCIP admin address |
-| newAdmin      | address | New CCIP admin address      |
+Extends OpenZeppelin's ERC20 approve functionality with additional safety measures:
 
-## Constants
+- Prevents approvals to the zero address (`address(0)`)
+- Prevents approvals to the token contract itself (`address(this)`)
 
-### MINTER_ROLE
+</Aside>
+
+**Parameters**
+
+| Name      | Type      | Description                                      |
+| --------- | --------- | ------------------------------------------------ |
+| `owner`   | `address` | The address that currently owns the tokens       |
+| `spender` | `address` | The address that will be allowed to spend tokens |
+| `amount`  | `uint256` | The number of tokens to approve for spending     |
+
+### burn (with amount)
+
+Allows authorized addresses to burn (destroy) tokens from their own account.
 
 ```solidity
-bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE")
+function burn(uint256 amount) public override(IBurnMintERC20, ERC20Burnable) onlyRole(BURNER_ROLE);
 ```
 
-Role identifier for addresses allowed to mint tokens.
+<Aside>
+Extends OpenZeppelin's ERC20 burn functionality with role-based restrictions:
 
-### BURNER_ROLE
+- Caller must have the `BURNER_ROLE`
+- Prevents burning from the zero address
+- Automatically reduces the total token supply
+
+</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description                     |
+| -------- | --------- | ------------------------------- |
+| `amount` | `uint256` | The number of tokens to destroy |
+
+### burn (with account)
+
+Alternative burn function that allows burning tokens from a specified account.
 
 ```solidity
-bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE")
+function burn(address account, uint256 amount) public virtual override;
 ```
 
-Role identifier for addresses allowed to burn tokens.
+<Aside>
 
-## Functions
+This function serves as a compatibility layer for older systems:
+
+- Internally calls `burnFrom` to handle the actual burning process
+- Maintains backward compatibility with systems using the older naming convention
+- Requires the same permissions as `burnFrom`
+
+</Aside>
+
+**Parameters**
+
+| Name      | Type      | Description                       |
+| --------- | --------- | --------------------------------- |
+| `account` | `address` | The account to remove tokens from |
+| `amount`  | `uint256` | The number of tokens to destroy   |
+
+### burnFrom
+
+Burns tokens from a specified account, requiring prior approval.
+
+```solidity
+function burnFrom(address account, uint256 amount) public override(IBurnMintERC20, ERC20Burnable) onlyRole(BURNER_ROLE);
+```
+
+<Aside>
+
+Enhanced burning functionality with multiple safety checks:
+
+- Caller must have the `BURNER_ROLE`
+- Requires prior approval from the token owner
+- Prevents burning from the zero address
+- Automatically reduces the total token supply
+
+</Aside>
+
+**Parameters**
+
+| Name      | Type      | Description                       |
+| --------- | --------- | --------------------------------- |
+| `account` | `address` | The account to remove tokens from |
+| `amount`  | `uint256` | The number of tokens to destroy   |
 
 ### constructor
 
 ```solidity
 constructor(
-    string memory name,
-    string memory symbol,
-    uint8 decimals_,
-    uint256 maxSupply_,
-    uint256 preMint
-) ERC20(name, symbol)
+  string memory name,
+  string memory symbol,
+  uint8 decimals_,
+  uint256 maxSupply_,
+  uint256 preMint
+) ERC20(name, symbol);
 ```
 
-Initializes the token with its basic properties.
+<Aside>
+
+Initializes a new token contract with the following setup:
 
-#### Parameters
+- Configures basic token properties (name, symbol, decimals)
+- Sets the maximum supply limit (if desired)
+- Mints initial tokens to the deployer (if specified)
+- Assigns the deployer as the default administrator
+
+</Aside>
 
-| Name        | Type    | Description                              |
-| ----------- | ------- | ---------------------------------------- |
-| name        | string  | Token name                               |
-| symbol      | string  | Token symbol                             |
-| decimals\_  | uint8   | Number of decimal places                 |
-| maxSupply\_ | uint256 | Maximum token supply (0 for unlimited)   |
-| preMint     | uint256 | Amount to mint to the deployer initially |
+**Parameters**
 
-### burn
+| Name         | Type      | Description                                        |
+| ------------ | --------- | -------------------------------------------------- |
+| `name`       | `string`  | The display name of the token                      |
+| `symbol`     | `string`  | The token's ticker symbol                          |
+| `decimals_`  | `uint8`   | The number of decimal places for token amounts     |
+| `maxSupply_` | `uint256` | The maximum allowed token supply (0 for unlimited) |
+| `preMint`    | `uint256` | The amount of tokens to mint to the deployer       |
+
+### decimals
+
+Returns the token's decimal precision.
 
 ```solidity
-function burn(uint256 amount) public override(IBurnMintERC20, ERC20Burnable) onlyRole(BURNER_ROLE)
+function decimals() public view virtual override returns (uint8);
 ```
 
-Burns tokens from the caller's balance.
+<Aside>
+  Provides the number of decimal places used to represent token amounts. For example, if decimals is 18, then 1 token is
+  represented as 1000000000000000000.
+</Aside>
 
-#### Parameters
+**Returns**
 
-| Name   | Type    | Description              |
-| ------ | ------- | ------------------------ |
-| amount | uint256 | Amount of tokens to burn |
+| Type    | Description                                         |
+| ------- | --------------------------------------------------- |
+| `uint8` | The number of decimal places used for token amounts |
 
-### burnFrom
+### getCCIPAdmin
+
+Retrieves the current CCIP administrator's address.
 
 ```solidity
-function burnFrom(
-    address account,
-    uint256 amount
-) public override(IBurnMintERC20, ERC20Burnable) onlyRole(BURNER_ROLE)
+function getCCIPAdmin() external view returns (address);
 ```
 
-Burns tokens from a specific account (requires approval).
+<Aside>
+  Returns the address that currently holds the CCIP administrator role. This role is used for CCIP token registry
+  management but has no other special permissions.
+</Aside>
 
-#### Parameters
+**Returns**
 
-| Name    | Type    | Description                 |
-| ------- | ------- | --------------------------- |
-| account | address | Account to burn tokens from |
-| amount  | uint256 | Amount of tokens to burn    |
+| Type      | Description                              |
+| --------- | ---------------------------------------- |
+| `address` | The current CCIP administrator's address |
 
-### mint
+### grantMintAndBurnRoles
+
+Assigns both minting and burning permissions to a single address.
 
 ```solidity
-function mint(address account, uint256 amount) external override onlyRole(MINTER_ROLE)
+function grantMintAndBurnRoles(address burnAndMinter) external;
 ```
 
-Mints new tokens to a specified account.
+<Aside>
+A convenience function that:
 
-#### Parameters
+- Grants both `MINTER_ROLE` and `BURNER_ROLE` to the specified address
+- Uses existing role management functions for the actual permission assignment
+- Inherits access controls from the individual role granting functions
 
-| Name    | Type    | Description                    |
-| ------- | ------- | ------------------------------ |
-| account | address | Recipient of the minted tokens |
-| amount  | uint256 | Amount of tokens to mint       |
+</Aside>
 
-### CCIP Admin Management
+**Parameters**
 
-### getCCIPAdmin
+| Name            | Type      | Description                                              |
+| --------------- | --------- | -------------------------------------------------------- |
+| `burnAndMinter` | `address` | The address that will receive minting and burning rights |
+
+### maxSupply
+
+Returns the token's maximum supply limit.
+
+```solidity
+function maxSupply() public view virtual returns (uint256);
+```
+
+<Aside>
+  Provides the maximum number of tokens that can exist. A value of 0 indicates no maximum supply limit is enforced.
+</Aside>
+
+**Returns**
+
+| Type      | Description                                          |
+| --------- | ---------------------------------------------------- |
+| `uint256` | The maximum allowed token supply (0 means unlimited) |
+
+### mint
+
+Creates new tokens and assigns them to a specified address.
 
 ```solidity
-function getCCIPAdmin() external view returns (address)
+function mint(address account, uint256 amount) external override onlyRole(MINTER_ROLE);
 ```
 
-Returns the current CCIP admin address.
+<Aside>
+Creates new tokens with multiple safety checks:
 
-#### Return Value
+- Caller must have the `MINTER_ROLE`
+- Prevents minting to invalid addresses (zero address or contract itself)
+- Enforces the maximum supply limit (if set)
+- Increases the total token supply
 
-| Type    | Description                |
-| ------- | -------------------------- |
-| address | Current CCIP admin address |
+</Aside>
+
+**Parameters**
+
+| Name      | Type      | Description                                  |
+| --------- | --------- | -------------------------------------------- |
+| `account` | `address` | The address that will receive the new tokens |
+| `amount`  | `uint256` | The number of new tokens to create           |
 
 ### setCCIPAdmin
 
+Updates the CCIP administrator role.
+
 ```solidity
-function setCCIPAdmin(address newAdmin) public onlyRole(DEFAULT_ADMIN_ROLE)
+function setCCIPAdmin(address newAdmin) public onlyRole(DEFAULT_ADMIN_ROLE);
 ```
 
-Transfers the CCIP admin role to a new address.
+<Aside>
+Transfers the CCIP administrator role with the following rules:
+
+- Only the contract owner (`DEFAULT_ADMIN_ROLE`) can call this function
+- The current CCIP administrator cannot transfer their own role
+- Setting to `address(0)` effectively removes the role
+- Uses a single-step transfer process
 
-<Aside type="note">
-  Only the contract owner can call this function, not the current CCIP admin. Setting to address(0) revokes the role.
 </Aside>
 
-#### Parameters
+**Parameters**
 
-| Name     | Type    | Description            |
-| -------- | ------- | ---------------------- |
-| newAdmin | address | New CCIP admin address |
+| Name       | Type      | Description                                             |
+| ---------- | --------- | ------------------------------------------------------- |
+| `newAdmin` | `address` | The address that will become the new CCIP administrator |
 
-### Role Management
+### supportsInterface
 
-### grantMintAndBurnRoles
+Determines whether the contract implements a specific interface.
 
 ```solidity
-function grantMintAndBurnRoles(address burnAndMinter) external
+function supportsInterface(bytes4 interfaceId) public pure virtual override(AccessControl, IERC165) returns (bool);
 ```
 
-Grants both minting and burning roles to an address.
+<Aside>
+Implements EIP-165 interface detection, supporting:
+
+- ERC20 interface
+- BurnMintERC20 interface
+- ERC165 interface
+- AccessControl interface
+- CCIP Admin interface
+
+</Aside>
+
+**Parameters**
+
+| Name          | Type     | Description                       |
+| ------------- | -------- | --------------------------------- |
+| `interfaceId` | `bytes4` | The interface identifier to check |
+
+**Returns**
+
+| Type   | Description                                               |
+| ------ | --------------------------------------------------------- |
+| `bool` | `true` if the contract implements the specified interface |
+
+### \_transfer
+
+Internal function that handles token transfers between addresses.
+
+```solidity
+function _transfer(address from, address to, uint256 amount) internal virtual override;
+```
+
+<Aside>
+Extends OpenZeppelin's ERC20 transfer functionality with additional safety measures:
+
+- Prevents transfers to the zero address (`address(0)`)
+- Prevents transfers to the token contract itself (`address(this)`)
+
+</Aside>
 
-#### Parameters
+**Parameters**
 
-| Name          | Type    | Description                   |
-| ------------- | ------- | ----------------------------- |
-| burnAndMinter | address | Address to receive both roles |
+| Name     | Type      | Description                      |
+| -------- | --------- | -------------------------------- |
+| `from`   | `address` | The address sending tokens       |
+| `to`     | `address` | The address receiving tokens     |
+| `amount` | `uint256` | The number of tokens to transfer |
diff --git a/src/content/ccip/api-reference/v1.5.1/burn-mint-token-pool-abstract.mdx b/src/content/ccip/api-reference/v1.5.1/burn-mint-token-pool-abstract.mdx
index c3d9c35d201..c5239617cd8 100644
--- a/src/content/ccip/api-reference/v1.5.1/burn-mint-token-pool-abstract.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/burn-mint-token-pool-abstract.mdx
@@ -3,7 +3,7 @@ section: ccip
 date: Last Modified
 title: "CCIP v1.5.1 BurnMintTokenPoolAbstract Contract API Reference"
 metadata:
-  description: "API documentation for the BurnMintTokenPoolAbstract contract in Chainlink CCIP v1.5.1, implementing burn/mint functionality for cross-chain token transfers."
+  description: "API documentation for the BurnMintTokenPoolAbstract contract in Chainlink CCIP v1.5.1"
 ---
 
 import { Aside } from "@components"
@@ -11,68 +11,134 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`BurnMintTokenPoolAbstract`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/pools/BurnMintTokenPoolAbstract.sol) contract extends TokenPool to implement burn/mint functionality for cross-chain token transfers.
+## BurnMintTokenPoolAbstract
+
+An abstract contract that implements core token pool functionality for burning and minting operations in cross-chain token transfers.
+
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/pools/BurnMintTokenPoolAbstract.sol)
+
+**Inherits:**
+
+- [TokenPool](/ccip/api-reference/v1.5.1/token-pool)
+
+## Events
+
+### Burned
+
+```solidity
+event Burned(address indexed sender, uint256 amount);
+```
+
+<Aside>Emitted when tokens are burned in the pool.</Aside>
+
+**Parameters**
+
+| Name     | Type      | Indexed | Description                               |
+| -------- | --------- | ------- | ----------------------------------------- |
+| `sender` | `address` | Yes     | The address initiating the burn operation |
+| `amount` | `uint256` | No      | The number of tokens burned               |
+
+### Minted
+
+```solidity
+event Minted(address indexed sender, address indexed recipient, uint256 amount);
+```
+
+<Aside>Emitted when new tokens are minted from the pool.</Aside>
+
+**Parameters**
+
+| Name        | Type      | Indexed | Description                               |
+| ----------- | --------- | ------- | ----------------------------------------- |
+| `sender`    | `address` | Yes     | The address initiating the mint operation |
+| `recipient` | `address` | Yes     | The address receiving the minted tokens   |
+| `amount`    | `uint256` | No      | The number of tokens minted               |
 
 ## Functions
 
 ### \_burn
 
+Internal function that executes the token burning operation.
+
 ```solidity
-function _burn(uint256 amount) internal virtual
+function _burn(uint256 amount) internal virtual;
 ```
 
-Contains the specific burn call for a pool. This function is virtual to allow different burn signatures without duplicating logic.
+<Aside>
+Contains the specific burn call for a pool.
+
+This method can be overridden to create pools with different burn signatures without duplicating the underlying logic.
 
-#### Parameters
+</Aside>
 
-| Name   | Type    | Description                  |
-| ------ | ------- | ---------------------------- |
-| amount | uint256 | The amount of tokens to burn |
+**Parameters**
+
+| Name     | Type      | Description                  |
+| -------- | --------- | ---------------------------- |
+| `amount` | `uint256` | The number of tokens to burn |
 
 ### lockOrBurn
 
+Burns tokens in the pool during a cross-chain transfer.
+
 ```solidity
 function lockOrBurn(
-    Pool.LockOrBurnInV1 calldata lockOrBurnIn
-) external virtual override returns (Pool.LockOrBurnOutV1 memory)
+  Pool.LockOrBurnInV1 calldata lockOrBurnIn
+) external virtual override returns (Pool.LockOrBurnOutV1 memory);
 ```
 
-Burns tokens in the pool after validating the operation.
+<Aside>
+
+Burns tokens in the pool with essential security validation:
+
+- Performs security validation through `_validateLockOrBurn`
+- Burns the specified amount of tokens
+- Emits a `Burned` event
+- Returns destination token information
 
-<Aside type="caution">The _validateLockOrBurn check is an essential security check that must not be bypassed.</Aside>
+</Aside>
 
-#### Parameters
+**Parameters**
 
-| Name         | Type                | Description                             |
-| ------------ | ------------------- | --------------------------------------- |
-| lockOrBurnIn | Pool.LockOrBurnInV1 | Input parameters for the burn operation |
+| Name           | Type                                                                    | Description                             |
+| -------------- | ----------------------------------------------------------------------- | --------------------------------------- |
+| `lockOrBurnIn` | [`Pool.LockOrBurnInV1`](/ccip/api-reference/v1.5.1/pool#lockorburninv1) | Input parameters for the burn operation |
 
-#### Return Value
+**Returns**
 
-| Type                 | Description                                              |
-| -------------------- | -------------------------------------------------------- |
-| Pool.LockOrBurnOutV1 | Contains destination token address and pool decimal data |
+| Type                                                                      | Description                                      |
+| ------------------------------------------------------------------------- | ------------------------------------------------ |
+| [`Pool.LockOrBurnOutV1`](/ccip/api-reference/v1.5.1/pool#lockorburnoutv1) | Contains destination token address and pool data |
 
 ### releaseOrMint
 
+Mints new tokens to a recipient during a cross-chain transfer.
+
 ```solidity
 function releaseOrMint(
-    Pool.ReleaseOrMintInV1 calldata releaseOrMintIn
-) external virtual override returns (Pool.ReleaseOrMintOutV1 memory)
+  Pool.ReleaseOrMintInV1 calldata releaseOrMintIn
+) external virtual override returns (Pool.ReleaseOrMintOutV1 memory);
 ```
 
-Mints tokens from the pool to the recipient after validating the operation.
+<Aside>
+
+Mints tokens to a specified recipient with the following steps:
+
+- Performs security validation through `_validateReleaseOrMint`
+- Calculates the correct local token amount using decimal adjustments
+- Mints tokens to the specified receiver
+- Emits a `Minted` event
 
-<Aside type="caution">The _validateReleaseOrMint check is an essential security check that must not be bypassed.</Aside>
+</Aside>
 
-#### Parameters
+**Parameters**
 
-| Name            | Type                   | Description                             |
-| --------------- | ---------------------- | --------------------------------------- |
-| releaseOrMintIn | Pool.ReleaseOrMintInV1 | Input parameters for the mint operation |
+| Name              | Type                                                                          | Description                             |
+| ----------------- | ----------------------------------------------------------------------------- | --------------------------------------- |
+| `releaseOrMintIn` | [`Pool.ReleaseOrMintInV1`](/ccip/api-reference/v1.5.1/pool#releaseormintinv1) | Input parameters for the mint operation |
 
-#### Return Value
+**Returns**
 
-| Type                    | Description                                  |
-| ----------------------- | -------------------------------------------- |
-| Pool.ReleaseOrMintOutV1 | Contains the final destination amount minted |
+| Type                                                                            | Description                                      |
+| ------------------------------------------------------------------------------- | ------------------------------------------------ |
+| [`Pool.ReleaseOrMintOutV1`](/ccip/api-reference/v1.5.1/pool#releaseormintoutv1) | Contains the final amount minted in local tokens |
diff --git a/src/content/ccip/api-reference/v1.5.1/burn-mint-token-pool.mdx b/src/content/ccip/api-reference/v1.5.1/burn-mint-token-pool.mdx
index f2620028a21..4dd607b063d 100644
--- a/src/content/ccip/api-reference/v1.5.1/burn-mint-token-pool.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/burn-mint-token-pool.mdx
@@ -11,66 +11,102 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`BurnMintTokenPool`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/pools/BurnMintTokenPool.sol) contract extends BurnMintTokenPoolAbstract to implement burn/mint functionality for third-party tokens using the `burn(amount)` signature.
+## BurnMintTokenPool
+
+A specialized token pool implementation that handles the minting and burning of third-party tokens using the standard `burn(amount)` function.
+
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/pools/BurnMintTokenPool.sol)
+
+**Inherits:**
+
+- [BurnMintTokenPoolAbstract](/ccip/api-reference/v1.5.1/burn-mint-token-pool-abstract)
+- [ITypeAndVersion](/ccip/api-reference/v1.5.1/i-type-and-version)
+
+<Aside>
+Key characteristics of this token pool:
+
+- Manages minting and burning operations for third-party tokens
+- Implements configurable whitelisting for transaction originators:
+  - Can accept transactions from any address
+  - Can restrict to only whitelisted addresses
+- Whitelisting configuration is permanent after deployment
+- Requires adjustable burner/minter roles in the token contract if pool redeployment is anticipated
+- Uses the standard `burn(amount)` function for token burning operations
 
-<Aside type="caution">
-  Pool whitelisting mode is set in the constructor and cannot be modified later. It either accepts any address as
-  originalSender, or only accepts whitelisted originalSender. The only way to change whitelisting mode is to deploy a
-  new pool. If that is expected, please make sure the token's burner/minter roles are adjustable.
 </Aside>
 
-## Functions
+## State Variables
 
-### constructor
+### typeAndVersion
 
 ```solidity
-constructor(
-    IBurnMintERC20 token,
-    uint8 localTokenDecimals,
-    address[] memory allowlist,
-    address rmnProxy,
-    address router
-) TokenPool(token, localTokenDecimals, allowlist, rmnProxy, router)
+string public constant override typeAndVersion = "BurnMintTokenPool 1.5.1";
 ```
 
-Initializes the token pool with the specified parameters.
+<Aside>
+  A constant identifier that specifies the contract type and version number for interface detection and version
+  management.
+</Aside>
+
+**Returns**
 
-#### Parameters
+| Type     | Description                                       |
+| -------- | ------------------------------------------------- |
+| `string` | The contract identifier "BurnMintTokenPool 1.5.1" |
 
-| Name               | Type           | Description                                                                                                                                                              |
-| ------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| token              | IBurnMintERC20 | The token managed by this pool                                                                                                                                           |
-| localTokenDecimals | uint8          | The number of decimals for the token on the local chain                                                                                                                  |
-| allowlist          | address[]      | List of addresses allowed to be original senders for token transfers. When allowlist is enabled, it ensures only token-developer specified addresses can transfer tokens |
-| rmnProxy           | address        | Address of the RMN proxy                                                                                                                                                 |
-| router             | address        | Address of the router                                                                                                                                                    |
+## Functions
 
 ### \_burn
 
+Internal function that executes the token burning operation using the standard burn interface.
+
 ```solidity
-function _burn(
-    uint256 amount
-) internal virtual override
+function _burn(uint256 amount) internal virtual override;
 ```
 
-Burns the specified amount of tokens using the `burn(amount)` signature.
+<Aside>
 
-#### Parameters
+Implements the abstract burn function from BurnMintTokenPoolAbstract:
 
-| Name   | Type    | Description              |
-| ------ | ------- | ------------------------ |
-| amount | uint256 | Amount of tokens to burn |
+- Calls the token's `burn(amount)` function directly
+- Requires the pool to have sufficient burning permissions
 
-### typeAndVersion
+</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description                  |
+| -------- | --------- | ---------------------------- |
+| `amount` | `uint256` | The number of tokens to burn |
+
+### constructor
 
 ```solidity
-string public constant override typeAndVersion = "BurnMintTokenPool 1.5.1"
+constructor(
+  IBurnMintERC20 token,
+  uint8 localTokenDecimals,
+  address[] memory allowlist,
+  address rmnProxy,
+  address router
+) TokenPool(token, localTokenDecimals, allowlist, rmnProxy, router);
 ```
 
-Returns the type and version of the contract.
+<Aside>
+Initializes the token pool with its configuration parameters:
+
+- Sets up the token contract reference
+- Configures decimal precision for local tokens
+- Establishes the initial whitelist of authorized addresses
+- Links to the RMN proxy and router contracts
+
+</Aside>
 
-#### Return Value
+**Parameters**
 
-| Type   | Description                          |
-| ------ | ------------------------------------ |
-| string | The string "BurnMintTokenPool 1.5.1" |
+| Name                 | Type             | Description                                          |
+| -------------------- | ---------------- | ---------------------------------------------------- |
+| `token`              | `IBurnMintERC20` | The third-party token contract to manage             |
+| `localTokenDecimals` | `uint8`          | The decimal precision for the local token            |
+| `allowlist`          | `address[]`      | Initial list of addresses authorized to use the pool |
+| `rmnProxy`           | `address`        | Address of the RMN proxy contract                    |
+| `router`             | `address`        | Address of the router contract                       |
diff --git a/src/content/ccip/api-reference/v1.5.1/ccip-receiver.mdx b/src/content/ccip/api-reference/v1.5.1/ccip-receiver.mdx
index 44e43521078..cde3d27ec62 100644
--- a/src/content/ccip/api-reference/v1.5.1/ccip-receiver.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/ccip-receiver.mdx
@@ -6,110 +6,183 @@ metadata:
   description: "API documentation for the CCIPReceiver contract in Chainlink CCIP v1.5.1, the base contract for applications receiving cross-chain messages."
 ---
 
+import { Aside } from "@components"
 import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-CCIP receiver contracts inherit from [`CCIPReceiver`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/applications/CCIPReceiver.sol).
+## CCIPReceiver
 
-```solidity
-import {CCIPReceiver} from "@chainlink/contracts-ccip/src/v0.8/ccip/applications/CCIPReceiver.sol";
-...
+An abstract base contract that provides core functionality for CCIP-enabled applications to receive cross-chain messages.
 
-constructor(address _router) CCIPReceiver(router) {
- }
-```
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/applications/CCIPReceiver.sol)
+
+<Aside>
+Base contract for CCIP applications that can receive messages, providing:
+
+- Secure message reception through router validation
+- Interface detection support (ERC165)
+- Customizable message handling through virtual functions
+
+</Aside>
 
 ## Errors
 
 ### InvalidRouter
 
 ```solidity
-error InvalidRouter(address router)
+error InvalidRouter(address router);
 ```
 
-## Functions
+<Aside>
 
-### constructor
+Thrown when:
 
-```solidity
-constructor(address router) internal
-```
+- A zero address is provided during contract initialization
+- A function restricted to the router is called by an unauthorized address
 
-#### Parameters
+</Aside>
 
-| Name   | Type    | Description         |
-| ------ | ------- | ------------------- |
-| router | address | The router address. |
+**Parameters**
 
-### supportsInterface
+| Name     | Type      | Description                |
+| -------- | --------- | -------------------------- |
+| `router` | `address` | The invalid router address |
+
+## State Variables
+
+### i_ccipRouter
 
 ```solidity
-function supportsInterface(bytes4 interfaceId) public pure returns (bool)
+address internal immutable i_ccipRouter;
 ```
 
-[IERC165](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/vendor/openzeppelin-solidity/v5.0.2/contracts/utils/introspection/IERC165.sol) supports an interfaceId. This allows CCIP to check if `ccipReceive` is available before calling it.
+<Aside>
+  The immutable address of the CCIP router contract that is authorized to deliver messages to this receiver.
+</Aside>
 
-- If this returns false or reverts, only tokens are transferred to the receiver.
-- If this returns true, tokens are transferred and ccipReceive is called atomically.
-- If the receiver address does not have code associated with it at execution time (EXTCODESIZE returns 0), only tokens will be transferred.
+## Modifiers
 
-#### Parameters
+### onlyRouter
 
-| Name        | Type   | Description              |
-| ----------- | ------ | ------------------------ |
-| interfaceId | bytes4 | The interfaceId to check |
+```solidity
+modifier onlyRouter();
+```
 
-#### Return Values
+<Aside>
+  Ensures that only the designated CCIP router can call the modified function. Reverts with `InvalidRouter` if called by
+  any other address.
+</Aside>
 
-| Name | Type | Description                          |
-| ---- | ---- | ------------------------------------ |
-| [0]  | bool | true if the interfaceId is supported |
+## Functions
 
 ### ccipReceive
 
+Processes incoming CCIP messages from the router.
+
 ```solidity
-function ccipReceive(Client.Any2EVMMessage calldata message) external
+function ccipReceive(Client.Any2EVMMessage calldata message) external virtual override onlyRouter;
 ```
 
-#### Parameters
+<Aside>
 
-| Name    | Type                                                                             | Description    |
-| ------- | -------------------------------------------------------------------------------- | -------------- |
-| message | struct [Client.Any2EVMMessage](/ccip/api-reference/v1.5.1/client#any2evmmessage) | Any2EVMMessage |
+Called by the Router to deliver a message with the following characteristics:
 
-### \_ccipReceive
+- Only accepts calls from the authorized router
+- If this function reverts, any associated token transfers also revert
+- Failed messages enter a FAILED state and become available for manual execution
+
+</Aside>
+
+**Parameters**
+
+| Name      | Type                                                                        | Description      |
+| --------- | --------------------------------------------------------------------------- | ---------------- |
+| `message` | [`Client.Any2EVMMessage`](/ccip/api-reference/v1.5.1/client#any2evmmessage) | The CCIP message |
+
+### constructor
 
 ```solidity
-function _ccipReceive(Client.Any2EVMMessage memory message) internal virtual
+constructor(address router);
 ```
 
-Override this function in your implementation.
+<Aside>
 
-#### Parameters
+Initializes the CCIPReceiver contract with a router address:
 
-| Name    | Type                                                                             | Description    |
-| ------- | -------------------------------------------------------------------------------- | -------------- |
-| message | struct [Client.Any2EVMMessage](/ccip/api-reference/v1.5.1/client#any2evmmessage) | Any2EVMMessage |
+- Validates that the router address is not zero
+- Stores the router address immutably
+
+</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description                      |
+| -------- | --------- | -------------------------------- |
+| `router` | `address` | The CCIP router contract address |
 
 ### getRouter
 
+Returns the address of the current CCIP router.
+
 ```solidity
-function getRouter() public view returns (address)
+function getRouter() public view virtual returns (address);
 ```
 
-This function returns the current Router address.
+<Aside>Provides access to the immutable router address used for message validation.</Aside>
 
-#### Return Values
+**Returns**
 
-| Name | Type    | Description      |
-| ---- | ------- | ---------------- |
-| [0]  | address | i_router address |
+| Type      | Description                     |
+| --------- | ------------------------------- |
+| `address` | The current CCIP router address |
 
-### onlyRouter
+### supportsInterface
+
+Determines whether the contract implements specific interfaces.
 
 ```solidity
-modifier onlyRouter()
+function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool);
 ```
 
-_Only calls from the set router are accepted._
+<Aside>
+
+Implements ERC165 interface detection with CCIP-specific behavior:
+
+- Returns true for IAny2EVMMessageReceiver and IERC165 interfaces
+- Used by CCIP to check if ccipReceive is available
+- If returns false or reverts: only tokens are transferred
+- If returns true: tokens are transferred and ccipReceive is called atomically
+- If contract has no code (EXTCODESIZE = 0): only tokens are transferred
+
+</Aside>
+
+**Parameters**
+
+| Name          | Type     | Description                       |
+| ------------- | -------- | --------------------------------- |
+| `interfaceId` | `bytes4` | The interface identifier to check |
+
+**Returns**
+
+| Type   | Description                        |
+| ------ | ---------------------------------- |
+| `bool` | True if the interface is supported |
+
+### \_ccipReceive
+
+Internal function to be implemented by derived contracts for custom message handling.
+
+```solidity
+function _ccipReceive(Client.Any2EVMMessage memory message) internal virtual;
+```
+
+<Aside>
+  Virtual function that must be overridden in implementing contracts to define custom message handling logic.
+</Aside>
+
+**Parameters**
+
+| Name      | Type                                                                        | Description                 |
+| --------- | --------------------------------------------------------------------------- | --------------------------- |
+| `message` | [`Client.Any2EVMMessage`](/ccip/api-reference/v1.5.1/client#any2evmmessage) | The message to be processed |
diff --git a/src/content/ccip/api-reference/v1.5.1/client.mdx b/src/content/ccip/api-reference/v1.5.1/client.mdx
index e019394285c..464588c3032 100644
--- a/src/content/ccip/api-reference/v1.5.1/client.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/client.mdx
@@ -11,33 +11,17 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-CCIP senders and receivers use the CCIP [`Client`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/libraries/Client.sol) library to build CCIP messages.
+## Client
 
-```solidity
-import { Client } from "@chainlink/contracts-ccip/src/v0.8/ccip/libraries/Client.sol";
-```
+A library that provides core data structures and utilities for building and handling cross-chain messages in CCIP.
 
-## Types and Constants
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/libraries/Client.sol)
 
-### EVMTokenAmount
-
-Use this solidity struct to specify the token address and amount.
-
-```solidity
-struct EVMTokenAmount {
-  address token;
-  uint256 amount;
-}
-```
-
-| Name   | Type    | Description                       |
-| ------ | ------- | --------------------------------- |
-| token  | address | token address on the local chain. |
-| amount | uint256 | Amount of tokens.                 |
+## Structs
 
 ### Any2EVMMessage
 
-CCIP receivers use this solidity struct to parse the received CCIP message.
+Structure representing a message received from any chain to an EVM chain.
 
 ```solidity
 struct Any2EVMMessage {
@@ -49,17 +33,30 @@ struct Any2EVMMessage {
 }
 ```
 
-| Name                | Type             | Description                                                                          |
-| ------------------- | ---------------- | ------------------------------------------------------------------------------------ |
-| messageId           | bytes32          | CCIP messageId, generated on the source chain.                                       |
-| sourceChainSelector | uint64           | Source chain selector.                                                               |
-| sender              | bytes            | Sender address. `abi.decode(sender, (address))` if the source chain is an EVM chain. |
-| data                | bytes            | Payload sent within the CCIP message.                                                |
-| destTokenAmounts    | EVMTokenAmount[] | Tokens and their amounts in their destination chain representation.                  |
+<Aside>
+
+Contains all necessary information about an incoming cross-chain message:
+
+- Message identification and source chain details
+- Sender information (can be decoded if from an EVM chain)
+- Custom message payload
+- Token transfer details in destination chain format
+
+</Aside>
+
+**Properties**
+
+| Name                  | Type                                  | Description                                       |
+| --------------------- | ------------------------------------- | ------------------------------------------------- |
+| `messageId`           | `bytes32`                             | Message ID corresponding to ccipSend on source    |
+| `sourceChainSelector` | `uint64`                              | Identifier of the source chain                    |
+| `sender`              | `bytes`                               | Sender address (use abi.decode if from EVM chain) |
+| `data`                | `bytes`                               | Custom payload from the original message          |
+| `destTokenAmounts`    | [`EVMTokenAmount[]`](#evmtokenamount) | Token amounts in destination chain representation |
 
 ### EVM2AnyMessage
 
-CCIP senders use this solidity struct to build a CCIP message.
+Structure for sending a message from an EVM chain to any supported chain.
 
 ```solidity
 struct EVM2AnyMessage {
@@ -71,84 +68,160 @@ struct EVM2AnyMessage {
 }
 ```
 
-| Name         | Type             | Description                                                    |
-| ------------ | ---------------- | -------------------------------------------------------------- |
-| receiver     | bytes            | abi.encode(receiver address) for destination EVM chains.       |
-| data         | bytes            | Data payload.                                                  |
-| tokenAmounts | EVMTokenAmount[] | Token transfers.                                               |
-| feeToken     | address          | Address of feeToken. address(0) means you will send msg.value. |
-| extraArgs    | bytes            | Populate this with \_argsToBytes(EVMExtraArgsV2).              |
+<Aside>
 
-### EVMExtraArgs
+Defines the format for outgoing cross-chain messages:
 
-#### EVMExtraArgsV1
+- Default gas limit is 200k if extraArgs is empty
+- Fee token can be set to address(0) to use native tokens (msg.value)
+- Extra arguments should be encoded using \_argsToBytes([`EVMExtraArgsV2`](#evmextraargsv2))
 
-```solidity
-bytes4 public constant EVM_EXTRA_ARGS_V1_TAG = 0x97a657c9;
+</Aside>
+
+**Properties**
+
+| Name           | Type                                  | Description                                         |
+| -------------- | ------------------------------------- | --------------------------------------------------- |
+| `receiver`     | `bytes`                               | Encoded receiver address for destination EVM chains |
+| `data`         | `bytes`                               | Custom payload to send                              |
+| `tokenAmounts` | [`EVMTokenAmount[]`](#evmtokenamount) | Tokens and amounts to transfer                      |
+| `feeToken`     | `address`                             | Token used for fees (address(0) for native tokens)  |
+| `extraArgs`    | `bytes`                               | Additional arguments encoded with \_argsToBytes     |
 
+### EVMExtraArgsV1
+
+Structure for V1 extra arguments in cross-chain messages.
+
+```solidity
 struct EVMExtraArgsV1 {
   uint256 gasLimit;
 }
 ```
 
-#### EVMExtraArgsV2
+<Aside>First version of extra arguments, supporting basic gas limit configuration.</Aside>
 
-```solidity
-bytes4 public constant EVM_EXTRA_ARGS_V2_TAG = 0x181dcf10;
+**Properties**
+
+| Name       | Type      | Description                                  |
+| ---------- | --------- | -------------------------------------------- |
+| `gasLimit` | `uint256` | Gas limit for execution on destination chain |
+
+### EVMExtraArgsV2
+
+Structure for V2 extra arguments in cross-chain messages.
 
+```solidity
 struct EVMExtraArgsV2 {
   uint256 gasLimit;
   bool allowOutOfOrderExecution;
 }
 ```
 
-| Name                     | Type    | Description                                                                                                                                                                                                                                                                           |
-| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| gasLimit                 | uint256 | specifies the maximum amount of gas CCIP can consume to execute `ccipReceive()` on the contract located on the destination blockchain. Read [Setting gasLimit](/ccip/best-practices#setting-gaslimit) for more details.                                                               |
-| allowOutOfOrderExecution | bool    | if true, it indicates that the message can be executed in any order relative to other messages from the same sender. This value's default varies by chain. On some chains, a particular value is enforced, meaning if the expected value is not set, the message request will revert. |
+<Aside>
 
-## Functions
+Enhanced version of extra arguments adding execution order control:
+
+- Includes configurable gas limit
+- Allows specifying out-of-order execution preference
+- Default value for allowOutOfOrderExecution varies by chain
+- Some chains enforce specific values and will revert if not set correctly
+
+</Aside>
 
-### \_argsToBytes
+**Properties**
 
-#### \_argsToBytes (v1)
+| Name                       | Type      | Description                                   |
+| -------------------------- | --------- | --------------------------------------------- |
+| `gasLimit`                 | `uint256` | Gas limit for execution on destination chain  |
+| `allowOutOfOrderExecution` | `bool`    | Whether messages can be executed in any order |
 
-<Aside type="note">This version (v1) is maintained for backward compatibility. You can already switch to v2.</Aside>
+### EVMTokenAmount
+
+Structure representing token amounts in CCIP messages.
 
 ```solidity
-function _argsToBytes(struct Client.EVMExtraArgsV1 extraArgs) internal pure returns (bytes bts)
+struct EVMTokenAmount {
+  address token;
+  uint256 amount;
+}
 ```
 
-It is used to convert the arguments to bytes.
+<Aside>
+
+Core structure for token transfers used by the Risk Management Network (RMN):
+
+- Changes to this struct require RMN maintainer notification
+- Represents token amounts in their chain-specific format
+
+</Aside>
+
+**Properties**
+
+| Name     | Type      | Description                      |
+| -------- | --------- | -------------------------------- |
+| `token`  | `address` | Token address on the local chain |
+| `amount` | `uint256` | Amount of tokens to transfer     |
+
+## State Variables
+
+### EVM_EXTRA_ARGS_V1_TAG
+
+```solidity
+bytes4 public constant EVM_EXTRA_ARGS_V1_TAG = 0x97a657c9;
+```
+
+<Aside>The identifier tag for V1 extra arguments (bytes4(keccak256("CCIP EVMExtraArgsV1"))).</Aside>
+
+### EVM_EXTRA_ARGS_V2_TAG
+
+```solidity
+bytes4 public constant EVM_EXTRA_ARGS_V2_TAG = 0x181dcf10;
+```
+
+<Aside>The identifier tag for V2 extra arguments (bytes4(keccak256("CCIP EVMExtraArgsV2"))).</Aside>
+
+## Functions
+
+### \_argsToBytes (V1)
+
+Encodes EVMExtraArgsV1 into bytes for message transmission.
+
+```solidity
+function _argsToBytes(EVMExtraArgsV1 memory extraArgs) internal pure returns (bytes memory bts);
+```
+
+<Aside>Serializes V1 extra arguments with the V1 tag identifier for cross-chain message processing.</Aside>
+
+**Parameters**
 
-##### Parameters
+| Name        | Type                                | Description                      |
+| ----------- | ----------------------------------- | -------------------------------- |
+| `extraArgs` | [`EVMExtraArgsV1`](#evmextraargsv1) | The V1 extra arguments to encode |
 
-| Name      | Type                                     | Description      |
-| --------- | ---------------------------------------- | ---------------- |
-| extraArgs | [Client.EVMExtraArgsV1](#evmextraargsv1) | Extra arguments. |
+**Returns**
 
-##### Return Values
+| Type    | Description                          |
+| ------- | ------------------------------------ |
+| `bytes` | The encoded extra arguments with tag |
 
-| Name | Type  | Description                         |
-| ---- | ----- | ----------------------------------- |
-| bts  | bytes | Encoded extra arguments in _bytes_. |
+### \_argsToBytes (V2)
 
-#### \_argsToBytes (v2)
+Encodes EVMExtraArgsV2 into bytes for message transmission.
 
 ```solidity
-function _argsToBytes(struct Client.EVMExtraArgsV2 extraArgs) internal pure returns (bytes bts)
+function _argsToBytes(EVMExtraArgsV2 memory extraArgs) internal pure returns (bytes memory bts);
 ```
 
-It is used to convert the arguments to bytes.
+<Aside>Serializes V2 extra arguments with the V2 tag identifier for cross-chain message processing.</Aside>
 
-##### Parameters
+**Parameters**
 
-| Name      | Type                                     | Description      |
-| --------- | ---------------------------------------- | ---------------- |
-| extraArgs | [Client.EVMExtraArgsV2](#evmextraargsv2) | Extra arguments. |
+| Name        | Type                                | Description                      |
+| ----------- | ----------------------------------- | -------------------------------- |
+| `extraArgs` | [`EVMExtraArgsV2`](#evmextraargsv2) | The V2 extra arguments to encode |
 
-##### Return Values
+**Returns**
 
-| Name | Type  | Description                         |
-| ---- | ----- | ----------------------------------- |
-| bts  | bytes | Encoded extra arguments in _bytes_. |
+| Type    | Description                          |
+| ------- | ------------------------------------ |
+| `bytes` | The encoded extra arguments with tag |
diff --git a/src/content/ccip/api-reference/v1.5.1/i-router-client.mdx b/src/content/ccip/api-reference/v1.5.1/i-router-client.mdx
index 3ef550cdaa2..152eb89f8cb 100644
--- a/src/content/ccip/api-reference/v1.5.1/i-router-client.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/i-router-client.mdx
@@ -11,100 +11,122 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-To send messages through CCIP, users must interact with the [`IRouterClient`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/interfaces/IRouterClient.sol) interface.
-After you import `IRouterClient.sol`, you can initialize a router client instance:
+## IRouterClient
 
-```solidity
-import {IRouterClient} from "@chainlink/contracts-ccip/src/v0.8/ccip/interfaces/IRouterClient.sol";
-...
-IRouterClient router;
-constructor(address _router) {
-     router = IRouterClient(_router);
- }
-```
+The IRouterClient interface provides the core functionality for sending cross-chain messages through CCIP (Chainlink Cross-Chain Interoperability Protocol).
+
+[Git Source](https://github.com/smartcontractkit/contracts/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/src/v0.8/ccip/interfaces/IRouterClient.sol)
 
 ## Errors
 
-### UnsupportedDestinationChain
+### InsufficientFeeTokenAmount
+
+Thrown when the provided fee token amount is insufficient for the message delivery.
 
 ```solidity
-error UnsupportedDestinationChain(uint64 destChainSelector)
+error InsufficientFeeTokenAmount();
 ```
 
-### InsufficientFeeTokenAmount
+### InvalidMsgValue
+
+Thrown when the provided msg.value is invalid for the operation.
 
 ```solidity
-error InsufficientFeeTokenAmount()
+error InvalidMsgValue();
 ```
 
-### InvalidMsgValue
+### UnsupportedDestinationChain
+
+Thrown when attempting to send a message to an unsupported destination chain.
 
 ```solidity
-error InvalidMsgValue()
+error UnsupportedDestinationChain(uint64 destChainSelector);
 ```
 
 ## Functions
 
-### isChainSupported
+### ccipSend
+
+Sends a message to the destination chain through CCIP.
 
 ```solidity
-function isChainSupported(uint64 destChainSelector) external view returns (bool supported)
+function ccipSend(
+  uint64 destinationChainSelector,
+  Client.EVM2AnyMessage calldata message
+) external payable returns (bytes32);
 ```
 
-Checks if the given chain ID is supported for sending/receiving.
+<Aside>
 
-#### Parameters
+Request a message to be sent to the destination chain.
 
-| Name              | Type   | Description         |
-| ----------------- | ------ | ------------------- |
-| destChainSelector | uint64 | The chain to check. |
+- Note: If msg.value is larger than the required fee (from getFee), the overpayment is accepted with no refund
+- The function will revert with an appropriate reason if the message is invalid
 
-#### Return Values
+</Aside>
+
+**Parameters**
+
+| Name                       | Type                                                                        | Description                                               |
+| -------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `destinationChainSelector` | `uint64`                                                                    | The destination chain ID                                  |
+| `message`                  | [`Client.EVM2AnyMessage`](/ccip/api-reference/v1.5.1/client#evm2anymessage) | The cross-chain CCIP message including data and/or tokens |
+
+**Returns**
 
-| Name      | Type | Description                                    |
-| --------- | ---- | ---------------------------------------------- |
-| supported | bool | returns true if it is supported, false if not. |
+| Name        | Type      | Description    |
+| ----------- | --------- | -------------- |
+| `messageId` | `bytes32` | The message ID |
 
 ### getFee
 
+Gets the fee required for sending a CCIP message to the destination chain.
+
 ```solidity
-function getFee(uint64 destinationChainSelector, struct Client.EVM2AnyMessage message) external view returns (uint256 fee)
+function getFee(
+  uint64 destinationChainSelector,
+  Client.EVM2AnyMessage memory message
+) external view returns (uint256 fee);
 ```
 
-#### Parameters
+<Aside>
+Calculates the execution fee for message delivery to the destination chain. The fee is denominated in the feeToken specified in the message.
+
+The function will revert with an appropriate reason if the message is invalid.
 
-| Name                     | Type                                                                             | Description                                               |
-| ------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| destinationChainSelector | uint64                                                                           | The destination chainSelector                             |
-| message                  | struct [Client.EVM2AnyMessage](/ccip/api-reference/v1.5.1/client#evm2anymessage) | The cross-chain CCIP message including data and/or tokens |
+</Aside>
 
-#### Return Values
+**Parameters**
 
-| Name | Type    | Description                                                                                  |
-| ---- | ------- | -------------------------------------------------------------------------------------------- |
-| fee  | uint256 | returns guaranteed execution fee for the specified message delivery to the destination chain |
+| Name                       | Type                                                                        | Description                                               |
+| -------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `destinationChainSelector` | `uint64`                                                                    | The destination chainSelector                             |
+| `message`                  | [`Client.EVM2AnyMessage`](/ccip/api-reference/v1.5.1/client#evm2anymessage) | The cross-chain CCIP message including data and/or tokens |
 
-### ccipSend
+**Returns**
+
+| Name  | Type      | Description                                                                                                                |
+| ----- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `fee` | `uint256` | Returns execution fee for the message delivery to destination chain, denominated in the feeToken specified in the message. |
+
+### isChainSupported
+
+Checks if the given chain ID is supported for sending/receiving.
 
 ```solidity
-function ccipSend(uint64 destinationChainSelector, struct Client.EVM2AnyMessage message) external payable returns (bytes32)
+function isChainSupported(uint64 destChainSelector) external view returns (bool supported);
 ```
 
-Request a message to be sent to the destination chain.
-
-<Aside type="caution">
-  If the `msg.value` exceeds the required fee from `getFee`, the overpayment is accepted with no refund.
-</Aside>
+<Aside>Checks if the given chain ID is supported for sending/receiving.</Aside>
 
-#### Parameters
+**Parameters**
 
-| Name                     | Type                                                                             | Description                                                |
-| ------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| destinationChainSelector | uint64                                                                           | The destination chain ID                                   |
-| message                  | struct [Client.EVM2AnyMessage](/ccip/api-reference/v1.5.1/client#evm2anymessage) | The cross-chain CCIP message, including data and/or tokens |
+| Name                | Type     | Description         |
+| ------------------- | -------- | ------------------- |
+| `destChainSelector` | `uint64` | The chain to check. |
 
-#### Return Values
+**Returns**
 
-| Name | Type    | Description              |
-| ---- | ------- | ------------------------ |
-| [0]  | bytes32 | messageId The message ID |
+| Name        | Type   | Description                               |
+| ----------- | ------ | ----------------------------------------- |
+| `supported` | `bool` | is true if it is supported, false if not. |
diff --git a/src/content/ccip/api-reference/v1.5.1/i-type-and-version.mdx b/src/content/ccip/api-reference/v1.5.1/i-type-and-version.mdx
new file mode 100644
index 00000000000..e518b461e43
--- /dev/null
+++ b/src/content/ccip/api-reference/v1.5.1/i-type-and-version.mdx
@@ -0,0 +1,34 @@
+---
+section: ccip
+date: Last Modified
+title: "CCIP v1.5.1 ITypeAndVersion Interface API Reference"
+metadata:
+  description: "API documentation for the ITypeAndVersion interface in Chainlink CCIP v1.5.1, providing type and version information for contracts."
+---
+
+import { Aside } from "@components"
+import CcipCommon from "@features/ccip/CcipCommon.astro"
+
+<CcipCommon callout="importCCIPPackage151" />
+
+## ITypeAndVersion
+
+An interface that provides type and version information for contracts.
+
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/shared/interfaces/ITypeAndVersion.sol)
+
+## Functions
+
+### typeAndVersion
+
+Returns the type and version of the contract.
+
+```solidity
+function typeAndVersion() external pure returns (string memory);
+```
+
+**Returns**
+
+| Type     | Description                           |
+| -------- | ------------------------------------- |
+| `string` | The type and version of the contract. |
diff --git a/src/content/ccip/api-reference/v1.5.1/index.mdx b/src/content/ccip/api-reference/v1.5.1/index.mdx
index 1e10c93f8b3..7a5f9485f7d 100644
--- a/src/content/ccip/api-reference/v1.5.1/index.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/index.mdx
@@ -17,25 +17,31 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 ### Core Components
 
-- [Client](/ccip/api-reference/v1.5.1/client) - Library providing structs and types for building CCIP messages
 - [CCIPReceiver](/ccip/api-reference/v1.5.1/ccip-receiver) - Base contract for receiving CCIP messages
+- [Client](/ccip/api-reference/v1.5.1/client) - Library providing structs and types for building CCIP messages
 - [IRouterClient](/ccip/api-reference/v1.5.1/i-router-client) - Interface for sending messages through CCIP
 - [Pool](/ccip/api-reference/v1.5.1/pool) - Library providing token pool functions for cross-chain operations
 - [RateLimiter](/ccip/api-reference/v1.5.1/rate-limiter) - Contract for managing rate limits on token transfers
+- [TypeAndVersion](/ccip/api-reference/v1.5.1/i-type-and-version) - Interface for contract versioning
 
 ### Token Pools
 
-- [TokenPool](/ccip/api-reference/v1.5.1/token-pool) - Base abstract class defining common functionality for all token pools
-- [BurnMintTokenPoolAbstract](/ccip/api-reference/v1.5.1/burn-mint-token-pool-abstract) - Abstract contract for burn/mint token handling
-- [BurnMintTokenPool](/ccip/api-reference/v1.5.1/burn-mint-token-pool) - Implementation using `burn(amount)` for token burning
 - [BurnFromMintTokenPool](/ccip/api-reference/v1.5.1/burn-from-mint-token-pool) - Implementation using `burnFrom(address, amount)` for token burning
-- [LockReleaseTokenPool](/ccip/api-reference/v1.5.1/lock-release-token-pool) - Implementation for locking and releasing tokens on their native chain
 - [BurnMintERC20](/ccip/api-reference/v1.5.1/burn-mint-erc20) - Implementation for burning and minting ERC20 tokens
+- [BurnMintTokenPool](/ccip/api-reference/v1.5.1/burn-mint-token-pool) - Implementation using `burn(amount)` for token burning
+- [BurnMintTokenPoolAbstract](/ccip/api-reference/v1.5.1/burn-mint-token-pool-abstract) - Abstract contract for burn/mint token handling
+- [LockReleaseTokenPool](/ccip/api-reference/v1.5.1/lock-release-token-pool) - Implementation for locking and releasing tokens on their native chain
+- [TokenPool](/ccip/api-reference/v1.5.1/token-pool) - Base abstract class defining common functionality for all token pools
+
+### Access Control
+
+- [Ownable2Step](/ccip/api-reference/v1.5.1/ownable-2-step) - Base contract implementing secure two-step ownership transfer
+- [Ownable2StepMsgSender](/ccip/api-reference/v1.5.1/ownable-2-step-msg-sender) - Extension of Ownable2Step that sets msg.sender as initial owner
 
 ### Registry Components
 
-- [TokenAdminRegistry](/ccip/api-reference/v1.5.1/token-admin-registry) - Contract for storing token pool configurations
 - [RegistryModuleOwnerCustom](/ccip/api-reference/v1.5.1/registry-module-owner-custom) - Registry module for token admin registration
+- [TokenAdminRegistry](/ccip/api-reference/v1.5.1/token-admin-registry) - Contract for storing token pool configurations
 
 ### Error Handling
 
diff --git a/src/content/ccip/api-reference/v1.5.1/lock-release-token-pool.mdx b/src/content/ccip/api-reference/v1.5.1/lock-release-token-pool.mdx
index f9283f3d2db..64a3e5477f8 100644
--- a/src/content/ccip/api-reference/v1.5.1/lock-release-token-pool.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/lock-release-token-pool.mdx
@@ -11,252 +11,346 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`LockReleaseTokenPool`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/pools/LockReleaseTokenPool.sol) contract manages tokens on their original blockchain (native chain). When tokens are transferred across chains:
+## LockReleaseTokenPool
 
-- On the source chain: tokens are locked (held) in this pool
-- On the destination chain: an equivalent amount is released to the recipient
+A specialized token pool for managing native tokens through a lock and release mechanism, with support for liquidity management.
 
-Since this pool needs to hold tokens to release them later, it includes features to:
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/pools/LockReleaseTokenPool.sol)
 
-- Add and remove liquidity (token reserves)
-- Track balances for both users and liquidity providers
-- Ensure proper accounting of all token movements
+**Inherits:**
 
-<Aside type="note">Each LockReleaseTokenPool can manage only one type of token.</Aside>
+- [TokenPool](/ccip/api-reference/v1.5.1/token-pool)
+- [ITypeAndVersion](/ccip/api-reference/v1.5.1/i-type-and-version)
+
+<Aside>
+
+A token pool designed for native chain tokens with the following features:
+
+- Manages one token per pool instance
+- Implements lock and release mechanisms for cross-chain transfers
+- Provides liquidity management functions for proper balance tracking
+- Supports liquidity provider operations
+- Facilitates pool upgrades through liquidity transfer mechanisms
+
+</Aside>
+
+## Events
+
+### LiquidityTransferred
+
+```solidity
+event LiquidityTransferred(address indexed from, uint256 amount);
+```
+
+<Aside>Emitted when liquidity is transferred from an older pool version during an upgrade.</Aside>
+
+**Parameters**
+
+| Name     | Type      | Indexed | Description                         |
+| -------- | --------- | ------- | ----------------------------------- |
+| `from`   | `address` | Yes     | The source pool address             |
+| `amount` | `uint256` | No      | The amount of liquidity transferred |
 
 ## Errors
 
 ### InsufficientLiquidity
 
 ```solidity
-error InsufficientLiquidity()
+error InsufficientLiquidity();
 ```
 
-Thrown when there is not enough liquidity in the pool for a withdrawal.
+<Aside>Thrown when attempting to withdraw more liquidity than available in the pool.</Aside>
 
 ### LiquidityNotAccepted
 
 ```solidity
-error LiquidityNotAccepted()
+error LiquidityNotAccepted();
 ```
 
-Thrown when trying to provide liquidity to a pool that doesn't accept it.
+<Aside>Thrown when attempting to provide liquidity to a pool that doesn't accept external liquidity.</Aside>
 
-## Events
+## State Variables
 
-### LiquidityTransferred
+### i_acceptLiquidity
 
 ```solidity
-event LiquidityTransferred(address indexed from, uint256 amount)
+bool internal immutable i_acceptLiquidity;
 ```
 
-Emitted when liquidity is transferred from an old pool version.
+<Aside>
+  Immutable flag indicating whether the pool accepts external liquidity. This setting cannot be changed after
+  deployment.
+</Aside>
 
-| Parameter | Type    | Description                     |
-| --------- | ------- | ------------------------------- |
-| from      | address | Address of the old pool         |
-| amount    | uint256 | Amount of liquidity transferred |
+### s_rebalancer
 
-## Functions
+```solidity
+address internal s_rebalancer;
+```
 
-### constructor
+<Aside>The address of the current rebalancer (liquidity manager) authorized to manage pool liquidity.</Aside>
+
+### typeAndVersion
 
 ```solidity
-constructor(
-    IERC20 token,
-    uint8 localTokenDecimals,
-    address[] memory allowlist,
-    address rmnProxy,
-    bool acceptLiquidity,
-    address router
-) TokenPool(token, localTokenDecimals, allowlist, rmnProxy, router)
+string public constant override typeAndVersion = "LockReleaseTokenPool 1.5.1";
 ```
 
-Initializes the token pool with the specified parameters.
+<Aside>A constant identifier specifying the contract type and version number.</Aside>
 
-#### Parameters
+## Functions
 
-| Name               | Type      | Description                                                                                                                                                              |
-| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| token              | IERC20    | The token managed by this pool                                                                                                                                           |
-| localTokenDecimals | uint8     | The number of decimals for the token on the local chain                                                                                                                  |
-| allowlist          | address[] | List of addresses allowed to be original senders for token transfers. When allowlist is enabled, it ensures only token-developer specified addresses can transfer tokens |
-| rmnProxy           | address   | Address of the RMN proxy                                                                                                                                                 |
-| acceptLiquidity    | bool      | Whether the pool accepts external liquidity                                                                                                                              |
-| router             | address   | Address of the router                                                                                                                                                    |
+### canAcceptLiquidity
 
-### lockOrBurn
+Determines whether the pool can accept external liquidity.
 
 ```solidity
-function lockOrBurn(
-    Pool.LockOrBurnInV1 calldata lockOrBurnIn
-) external virtual override returns (Pool.LockOrBurnOutV1 memory)
+function canAcceptLiquidity() external view returns (bool);
 ```
 
-Locks the token in the pool.
+<Aside>
 
-<Aside type="caution">The _validateLockOrBurn check is an essential security check.</Aside>
+Returns the immutable configuration indicating if the pool accepts external liquidity. External liquidity might not be required when:
 
-#### Parameters
+- There is one canonical token on the chain
+- CCIP handles mint/burn operations on other chains
+- The invariant `balanceOf(pool) on home chain >= sum(totalSupply(mint/burn "wrapped" token) on all remote chains)` is maintained
 
-| Name         | Type                | Description                             |
-| ------------ | ------------------- | --------------------------------------- |
-| lockOrBurnIn | Pool.LockOrBurnInV1 | Input parameters for the lock operation |
+</Aside>
 
-#### Return Value
+**Returns**
 
-| Type                 | Description                                               |
-| -------------------- | --------------------------------------------------------- |
-| Pool.LockOrBurnOutV1 | Struct containing destination token address and pool data |
+| Type   | Description                                 |
+| ------ | ------------------------------------------- |
+| `bool` | True if the pool accepts external liquidity |
 
-### releaseOrMint
+### constructor
 
 ```solidity
-function releaseOrMint(
-    Pool.ReleaseOrMintInV1 calldata releaseOrMintIn
-) external virtual override returns (Pool.ReleaseOrMintOutV1 memory)
+constructor(
+  IERC20 token,
+  uint8 localTokenDecimals,
+  address[] memory allowlist,
+  address rmnProxy,
+  bool acceptLiquidity,
+  address router
+) TokenPool(token, localTokenDecimals, allowlist, rmnProxy, router);
 ```
 
-Releases tokens from the pool to the recipient.
-
-<Aside type="caution">The _validateReleaseOrMint check is an essential security check.</Aside>
+<Aside>
 
-#### Parameters
+Initializes the token pool with its configuration parameters:
 
-| Name            | Type                   | Description                                |
-| --------------- | ---------------------- | ------------------------------------------ |
-| releaseOrMintIn | Pool.ReleaseOrMintInV1 | Input parameters for the release operation |
+- Sets up the token contract reference
+- Configures decimal precision for local tokens
+- Establishes the initial whitelist
+- Links to the RMN proxy and router
+- Sets the liquidity acceptance policy
 
-#### Return Value
+</Aside>
 
-| Type                    | Description                              |
-| ----------------------- | ---------------------------------------- |
-| Pool.ReleaseOrMintOutV1 | Struct containing the destination amount |
+**Parameters**
 
-### Liquidity Management Functions
+| Name                 | Type        | Description                                 |
+| -------------------- | ----------- | ------------------------------------------- |
+| `token`              | `IERC20`    | The token contract to manage                |
+| `localTokenDecimals` | `uint8`     | The decimal precision for the local token   |
+| `allowlist`          | `address[]` | Initial list of authorized addresses        |
+| `rmnProxy`           | `address`   | Address of the RMN proxy contract           |
+| `acceptLiquidity`    | `bool`      | Whether the pool accepts external liquidity |
+| `router`             | `address`   | Address of the router contract              |
 
 ### getRebalancer
 
+Returns the current rebalancer address.
+
 ```solidity
-function getRebalancer() external view returns (address)
+function getRebalancer() external view returns (address);
 ```
 
-Gets the LiquidityManager address.
+<Aside>
+  Provides the address of the current liquidity manager (rebalancer). Can return address(0) if none is configured.
+</Aside>
+
+**Returns**
 
-#### Return Value
+| Type      | Description                           |
+| --------- | ------------------------------------- |
+| `address` | The current liquidity manager address |
 
-| Type    | Description                                                          |
-| ------- | -------------------------------------------------------------------- |
-| address | The current liquidity manager (can be address(0) if none configured) |
+### lockOrBurn
 
-### setRebalancer
+Locks tokens in the pool for cross-chain transfer.
 
 ```solidity
-function setRebalancer(
-    address rebalancer
-) external onlyOwner
+function lockOrBurn(
+  Pool.LockOrBurnInV1 calldata lockOrBurnIn
+) external virtual override returns (Pool.LockOrBurnOutV1 memory);
 ```
 
-Sets the LiquidityManager address.
+<Aside>
 
-#### Parameters
+Processes token locking with security validation:
 
-| Name       | Type    | Description            |
-| ---------- | ------- | ---------------------- |
-| rebalancer | address | New rebalancer address |
+- Performs essential security checks through `_validateLockOrBurn`
+- Emits a `Locked` event upon successful locking
+- Returns destination token information
 
-### canAcceptLiquidity
+</Aside>
+
+**Parameters**
+
+| Name           | Type                                                                    | Description                             |
+| -------------- | ----------------------------------------------------------------------- | --------------------------------------- |
+| `lockOrBurnIn` | [`Pool.LockOrBurnInV1`](/ccip/api-reference/v1.5.1/pool#lockorburninv1) | Input parameters for the lock operation |
+
+**Returns**
+
+| Type                                                                      | Description                                      |
+| ------------------------------------------------------------------------- | ------------------------------------------------ |
+| [`Pool.LockOrBurnOutV1`](/ccip/api-reference/v1.5.1/pool#lockorburnoutv1) | Contains destination token address and pool data |
+
+### provideLiquidity
+
+Adds external liquidity to the pool.
 
 ```solidity
-function canAcceptLiquidity() external view returns (bool)
+function provideLiquidity(uint256 amount) external;
 ```
 
-Checks if the pool can accept liquidity.
+<Aside>
 
-#### Return Value
+Allows the rebalancer to add liquidity to the pool:
 
-| Type | Description                           |
-| ---- | ------------------------------------- |
-| bool | True if the pool can accept liquidity |
+- Requires prior token approval
+- Only callable by the authorized rebalancer
+- Only works if the pool accepts liquidity
 
-### provideLiquidity
+</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description                        |
+| -------- | --------- | ---------------------------------- |
+| `amount` | `uint256` | The amount of liquidity to provide |
+
+### releaseOrMint
+
+Releases tokens from the pool to a recipient.
 
 ```solidity
-function provideLiquidity(
-    uint256 amount
-) external
+function releaseOrMint(
+  Pool.ReleaseOrMintInV1 calldata releaseOrMintIn
+) external virtual override returns (Pool.ReleaseOrMintOutV1 memory);
 ```
 
-Adds liquidity to the pool. The tokens should be approved first.
+<Aside>
 
-#### Parameters
+Processes token release with security validation:
 
-| Name   | Type    | Description                    |
-| ------ | ------- | ------------------------------ |
-| amount | uint256 | Amount of liquidity to provide |
+- Performs essential security checks through `_validateReleaseOrMint`
+- Calculates correct local token amounts using decimal adjustments
+- Transfers tokens to the specified receiver
+- Emits a `Released` event
 
-### withdrawLiquidity
+</Aside>
+
+**Parameters**
+
+| Name              | Type                                                                          | Description                                |
+| ----------------- | ----------------------------------------------------------------------------- | ------------------------------------------ |
+| `releaseOrMintIn` | [`Pool.ReleaseOrMintInV1`](/ccip/api-reference/v1.5.1/pool#releaseormintinv1) | Input parameters for the release operation |
+
+**Returns**
+
+| Type                                                                            | Description                                        |
+| ------------------------------------------------------------------------------- | -------------------------------------------------- |
+| [`Pool.ReleaseOrMintOutV1`](/ccip/api-reference/v1.5.1/pool#releaseormintoutv1) | Contains the final amount released in local tokens |
+
+### setRebalancer
+
+Updates the rebalancer address.
 
 ```solidity
-function withdrawLiquidity(
-    uint256 amount
-) external
+function setRebalancer(address rebalancer) external onlyOwner;
 ```
 
-Removes liquidity from the pool. The tokens will be sent to msg.sender.
+<Aside>Allows the owner to update the liquidity manager (rebalancer) address.</Aside>
 
-#### Parameters
+**Parameters**
 
-| Name   | Type    | Description                   |
-| ------ | ------- | ----------------------------- |
-| amount | uint256 | Amount of liquidity to remove |
+| Name         | Type      | Description                       |
+| ------------ | --------- | --------------------------------- |
+| `rebalancer` | `address` | The new rebalancer address to set |
 
-### transferLiquidity
+### supportsInterface
+
+Checks interface support using ERC165.
 
 ```solidity
-function transferLiquidity(address from, uint256 amount) external onlyOwner
+function supportsInterface(bytes4 interfaceId) public pure virtual override returns (bool);
 ```
 
-Transfers liquidity from an old version of the pool to this new pool. This function is specifically designed for pool upgrades.
+<Aside>Implements ERC165 interface detection, adding support for ILiquidityContainer.</Aside>
 
-<Aside type="note">
-  Prerequisites:
+**Parameters**
 
-        - This pool must be set as the rebalancer in the old pool version
-        - Only the owner can call this function
+| Name          | Type     | Description                       |
+| ------------- | -------- | --------------------------------- |
+| `interfaceId` | `bytes4` | The interface identifier to check |
 
-</Aside>
+**Returns**
 
-There are two ways to use this function during a pool upgrade:
+| Type   | Description                        |
+| ------ | ---------------------------------- |
+| `bool` | True if the interface is supported |
 
-1. **Single Transaction Upgrade** (if multicall is available):
+### transferLiquidity
 
-   - Call this function at the same time as updating the pool in TokenAdminRegistry
-   - This ensures a smooth transition of both liquidity and transactions
+Transfers liquidity from an older pool version.
 
-2. **Gradual Upgrade** (if multicall is not available):
-   1. First, transfer some liquidity to the new pool
-   2. Update the TokenAdminRegistry to use the new pool
-   3. New transactions will now use the new pool and its liquidity
-   4. Finally, transfer the remaining liquidity using this function
+```solidity
+function transferLiquidity(address from, uint256 amount) external onlyOwner;
+```
 
-#### Parameters
+<Aside>
 
-| Name   | Type    | Description                     |
-| ------ | ------- | ------------------------------- |
-| from   | address | Address of the old pool         |
-| amount | uint256 | Amount of liquidity to transfer |
+Facilitates pool upgrades by transferring liquidity from an older pool version:
 
-### typeAndVersion
+- Requires this pool to be set as rebalancer in the source pool
+- Can be used in conjunction with TokenAdminRegistry updates
+- Supports both atomic and gradual migration strategies
+- Enables smooth transition of liquidity and transactions
+
+</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description                         |
+| -------- | --------- | ----------------------------------- |
+| `from`   | `address` | The address of the source pool      |
+| `amount` | `uint256` | The amount of liquidity to transfer |
+
+### withdrawLiquidity
+
+Removes liquidity from the pool.
 
 ```solidity
-string public constant override typeAndVersion = "LockReleaseTokenPool 1.5.1"
+function withdrawLiquidity(uint256 amount) external;
 ```
 
-Returns the type and version of the contract.
+<Aside>
+
+Allows the rebalancer to withdraw liquidity:
+
+- Only callable by the authorized rebalancer
+- Requires sufficient pool balance
+- Transfers tokens directly to the caller
+
+</Aside>
 
-#### Return Value
+**Parameters**
 
-| Type   | Description                             |
-| ------ | --------------------------------------- |
-| string | The string "LockReleaseTokenPool 1.5.1" |
+| Name     | Type      | Description                         |
+| -------- | --------- | ----------------------------------- |
+| `amount` | `uint256` | The amount of liquidity to withdraw |
diff --git a/src/content/ccip/api-reference/v1.5.1/ownable-2-step-msg-sender.mdx b/src/content/ccip/api-reference/v1.5.1/ownable-2-step-msg-sender.mdx
new file mode 100644
index 00000000000..1bc4ddc805c
--- /dev/null
+++ b/src/content/ccip/api-reference/v1.5.1/ownable-2-step-msg-sender.mdx
@@ -0,0 +1,51 @@
+---
+section: ccip
+date: Last Modified
+title: "CCIP v1.5.1 Ownable2StepMsgSender Contract API Reference"
+metadata:
+  description: "API documentation for the Ownable2StepMsgSender contract in Chainlink CCIP v1.5.1"
+---
+
+import { Aside } from "@components"
+import CcipCommon from "@features/ccip/CcipCommon.astro"
+
+<CcipCommon callout="importCCIPPackage151" />
+
+## Ownable2StepMsgSender
+
+A contract that facilitates two-step ownership transfer, providing enhanced security for ownership management. This contract extends `Ownable2Step` and automatically sets the deploying address (`msg.sender`) as the initial owner with no pending owner.
+
+**Inherits:**
+
+- [`Ownable2Step`](/ccip/api-reference/v1.5.1/ownable-2-step) - Provides secure two-step ownership transfer functionality
+
+<Aside type="note">
+The two-step ownership transfer process enhances security by:
+1. Requiring the current owner to initiate the transfer (step 1)
+2. Requiring the new owner to accept ownership (step 2)
+
+This prevents accidental transfers to incorrect or inaccessible addresses.
+
+</Aside>
+
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/shared/access/Ownable2StepMsgSender.sol)
+
+## Functions
+
+### constructor
+
+Initializes the contract with the deploying address as the owner and no pending owner.
+
+```solidity
+constructor() Ownable2Step(msg.sender, address(0));
+```
+
+<Aside>
+
+The constructor:
+
+- Sets `msg.sender` as the initial owner
+- Sets `address(0)` as the initial pending owner (indicating no pending transfer)
+- Inherits from Ownable2Step with these initial values
+
+</Aside>
diff --git a/src/content/ccip/api-reference/v1.5.1/ownable-2-step.mdx b/src/content/ccip/api-reference/v1.5.1/ownable-2-step.mdx
new file mode 100644
index 00000000000..7b504190a3c
--- /dev/null
+++ b/src/content/ccip/api-reference/v1.5.1/ownable-2-step.mdx
@@ -0,0 +1,222 @@
+---
+section: ccip
+date: Last Modified
+title: "CCIP v1.5.1 Ownable2Step Contract API Reference"
+metadata:
+  description: "API documentation for the Ownable2Step contract in Chainlink CCIP v1.5.1"
+---
+
+import { Aside } from "@components"
+import CcipCommon from "@features/ccip/CcipCommon.astro"
+
+<CcipCommon callout="importCCIPPackage151" />
+
+## Ownable2Step
+
+A minimal contract that implements 2-step ownership transfer and nothing more. It's made to be minimal to reduce the impact of the bytecode size on any contract that inherits from it.
+
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/shared/access/Ownable2Step.sol)
+
+<Aside type="note">
+This contract implements a secure two-step ownership transfer process:
+
+1. Current owner initiates transfer using `transferOwnership`
+2. New owner must accept using `acceptOwnership`
+3. Transfer only completes after both steps
+
+This prevents accidental transfers to incorrect or inaccessible addresses.
+
+</Aside>
+
+## Events
+
+### OwnershipTransferRequested
+
+```solidity
+event OwnershipTransferRequested(address indexed from, address indexed to);
+```
+
+<Aside>Emitted when the current owner initiates an ownership transfer.</Aside>
+
+**Parameters**
+
+| Name   | Type      | Description                           |
+| ------ | --------- | ------------------------------------- |
+| `from` | `address` | Current owner initiating the transfer |
+| `to`   | `address` | Proposed new owner                    |
+
+### OwnershipTransferred
+
+```solidity
+event OwnershipTransferred(address indexed from, address indexed to);
+```
+
+<Aside>Emitted when an ownership transfer is completed.</Aside>
+
+**Parameters**
+
+| Name   | Type      | Description    |
+| ------ | --------- | -------------- |
+| `from` | `address` | Previous owner |
+| `to`   | `address` | New owner      |
+
+## Errors
+
+### CannotTransferToSelf
+
+```solidity
+error CannotTransferToSelf();
+```
+
+<Aside>Thrown when attempting to transfer ownership to the current owner.</Aside>
+
+### MustBeProposedOwner
+
+```solidity
+error MustBeProposedOwner();
+```
+
+<Aside>Thrown when someone other than the pending owner tries to accept ownership.</Aside>
+
+### OnlyCallableByOwner
+
+```solidity
+error OnlyCallableByOwner();
+```
+
+<Aside>Thrown when a restricted function is called by someone other than the owner.</Aside>
+
+### OwnerCannotBeZero
+
+```solidity
+error OwnerCannotBeZero();
+```
+
+<Aside>Thrown when attempting to set the owner to address(0).</Aside>
+
+## State Variables
+
+### s_owner
+
+The owner is the current owner of the contract.
+
+```solidity
+address private s_owner;
+```
+
+<Aside>
+  The owner is the second storage variable so any implementing contract could pack other state with it instead of the
+  much less used s_pendingOwner.
+</Aside>
+
+### s_pendingOwner
+
+The pending owner is the address to which ownership may be transferred.
+
+```solidity
+address private s_pendingOwner;
+```
+
+## Functions
+
+### acceptOwnership
+
+Allows an ownership transfer to be completed by the recipient.
+
+```solidity
+function acceptOwnership() external override;
+```
+
+<Aside>
+
+Reverts with `MustBeProposedOwner` if caller is not the pending owner.
+
+When successful:
+
+- Updates owner to the caller
+- Clears pending owner
+- Emits OwnershipTransferred event
+
+</Aside>
+
+### constructor
+
+Initializes the contract with an owner and optionally a pending owner.
+
+```solidity
+constructor(address newOwner, address pendingOwner);
+```
+
+<Aside>
+
+- Reverts with `OwnerCannotBeZero` if newOwner is address(0)
+- Sets newOwner as the initial owner
+- If pendingOwner is not address(0), initiates ownership transfer to pendingOwner
+
+</Aside>
+
+**Parameters**
+
+| Name           | Type      | Description                                        |
+| -------------- | --------- | -------------------------------------------------- |
+| `newOwner`     | `address` | The initial owner of the contract                  |
+| `pendingOwner` | `address` | Optional address to initiate ownership transfer to |
+
+### onlyOwner
+
+Modifier that restricts function access to the contract owner.
+
+```solidity
+modifier onlyOwner();
+```
+
+<Aside>Reverts with `OnlyCallableByOwner` if caller is not the current owner.</Aside>
+
+### owner
+
+Returns the current owner's address.
+
+```solidity
+function owner() public view override returns (address);
+```
+
+**Returns**
+
+| Type      | Description                      |
+| --------- | -------------------------------- |
+| `address` | The address of the current owner |
+
+### transferOwnership
+
+Allows an owner to begin transferring ownership to a new address.
+
+```solidity
+function transferOwnership(address to) public override onlyOwner;
+```
+
+<Aside>
+
+The new owner must call `acceptOwnership` to complete the transfer. No permissions are changed until acceptance.
+
+Reverts with:
+
+- `OnlyCallableByOwner` if caller is not the current owner
+- `CannotTransferToSelf` if attempting to transfer to current owner
+
+</Aside>
+
+**Parameters**
+
+| Name | Type      | Description                                        |
+| ---- | --------- | -------------------------------------------------- |
+| `to` | `address` | The address to which ownership will be transferred |
+
+### \_validateOwnership
+
+Internal function to validate access control.
+
+```solidity
+function _validateOwnership() internal view;
+```
+
+<Aside>Reverts with `OnlyCallableByOwner` if caller is not the current owner. Used by the onlyOwner modifier.</Aside>
diff --git a/src/content/ccip/api-reference/v1.5.1/pool.mdx b/src/content/ccip/api-reference/v1.5.1/pool.mdx
index 1d8001e25ac..20429d15fc8 100644
--- a/src/content/ccip/api-reference/v1.5.1/pool.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/pool.mdx
@@ -11,41 +11,28 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`Pool`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/libraries/Pool.sol) library provides various token pool functions to construct return data for cross-chain operations in Chainlink's CCIP.
+## Pool
 
-```solidity
-import { Pool } from "@chainlink/contracts-ccip/src/v0.8/ccip/libraries/Pool.sol";
-```
+A library that provides core data structures and constants for token pool operations in cross-chain transfers.
 
-## Types and Constants
-
-### CCIP_POOL_V1
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/libraries/Pool.sol)
 
-The tag used to signal support for the Pool v1 standard.
+<Aside>
 
-```solidity
-bytes4 public constant CCIP_POOL_V1 = 0xaff2afbf;
-```
+This library defines the fundamental structures and constants used in token pool operations:
 
-### CCIP_POOL_V1_RET_BYTES
-
-The number of bytes in the return data for a pool v1 releaseOrMint call.
-
-```solidity
-uint16 public constant CCIP_POOL_V1_RET_BYTES = 32;
-```
-
-### CCIP_LOCK_OR_BURN_V1_RET_BYTES
+- Standardizes cross-chain token transfer data structures
+- Provides version identification and compatibility checks
+- Defines size constraints for return data
+- Facilitates secure token locking, burning, releasing, and minting operations through [`TokenPool`](/ccip/api-reference/v1.5.1/token-pool)
 
-The default max number of bytes in the return data for a pool v1 lockOrBurn call.
+</Aside>
 
-```solidity
-uint32 public constant CCIP_LOCK_OR_BURN_V1_RET_BYTES = 32;
-```
+## Structs
 
 ### LockOrBurnInV1
 
-This struct represents the input data for a `lockOrBurn` call.
+Input parameters for locking or burning tokens in cross-chain transfers.
 
 ```solidity
 struct LockOrBurnInV1 {
@@ -57,17 +44,23 @@ struct LockOrBurnInV1 {
 }
 ```
 
-| Name                | Type    | Description                                                                      |
-| ------------------- | ------- | -------------------------------------------------------------------------------- |
-| receiver            | bytes   | The recipient of the tokens on the destination chain, ABI encoded                |
-| remoteChainSelector | uint64  | The chain ID of the destination chain                                            |
-| originalSender      | address | The original sender of the transaction on the source chain                       |
-| amount              | uint256 | The amount of tokens to lock or burn, denominated in the source token's decimals |
-| localToken          | address | The address on this chain of the token to lock or burn                           |
+<Aside>
+
+Defines the parameters required for initiating a token lock or burn operation:
+
+- `receiver`: The destination chain recipient address (ABI encoded)
+- `remoteChainSelector`: The destination chain identifier
+- `originalSender`: The transaction initiator on the source chain
+- `amount`: Token quantity in source token decimals
+- `localToken`: The token contract address on the source chain
+
+The result of this operation is returned in [`LockOrBurnOutV1`](#lockorburnoutv1).
+
+</Aside>
 
 ### LockOrBurnOutV1
 
-This struct represents the output data from a `lockOrBurn` call.
+Output data from a lock or burn operation.
 
 ```solidity
 struct LockOrBurnOutV1 {
@@ -76,14 +69,18 @@ struct LockOrBurnOutV1 {
 }
 ```
 
-| Name             | Type  | Description                                                                                                                                                                                                                                    |
-| ---------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| destTokenAddress | bytes | The address of the destination token, ABI encoded in the case of EVM chains. This value is UNTRUSTED as any pool owner can return whatever value they want.                                                                                    |
-| destPoolData     | bytes | Optional pool data to be transferred to the destination chain. By default this is capped at CCIP_LOCK_OR_BURN_V1_RET_BYTES bytes. If more data is required, the TokenTransferFeeConfig.destBytesOverhead has to be set for the specific token. |
+<Aside>
+
+Contains the results of a token lock or burn operation initiated by [`LockOrBurnInV1`](#lockorburninv1):
+
+- `destTokenAddress`: The token address on the destination chain (ABI encoded for EVM chains). **Note**: This value is UNTRUSTED as pool owners can return arbitrary values
+- `destPoolData`: Optional data for the destination chain, limited by [`CCIP_LOCK_OR_BURN_V1_RET_BYTES`](#ccip_lock_or_burn_v1_ret_bytes) unless configured otherwise in TokenTransferFeeConfig.destBytesOverhead
+
+</Aside>
 
 ### ReleaseOrMintInV1
 
-This struct represents the input data for a `releaseOrMint` call.
+Input parameters for releasing or minting tokens in cross-chain transfers.
 
 ```solidity
 struct ReleaseOrMintInV1 {
@@ -98,30 +95,26 @@ struct ReleaseOrMintInV1 {
 }
 ```
 
-| Name                | Type    | Description                                                                         |
-| ------------------- | ------- | ----------------------------------------------------------------------------------- |
-| originalSender      | bytes   | The original sender of the transaction on the source chain                          |
-| remoteChainSelector | uint64  | The chain ID of the source chain                                                    |
-| receiver            | address | The recipient of the tokens on the destination chain                                |
-| amount              | uint256 | The amount of tokens to release or mint, denominated in the source token's decimals |
-| localToken          | address | The address on this chain of the token to release or mint                           |
-| sourcePoolAddress   | bytes   | The address of the source pool, abi encoded in the case of EVM chains               |
-| sourcePoolData      | bytes   | The data received from the source pool to process the release or mint               |
-| offchainTokenData   | bytes   | The offchain data to process the release or mint                                    |
-
-<Aside type="note">
+<Aside>
 
-    - The `sourcePoolAddress` field in `ReleaseOrMintInV1` should be verified before any processing occurs to ensure that it matches the expected pool address for the given `remoteChainSelector`. <br />
+Defines the parameters required for token release or mint operations:
 
-    - The `offchainTokenData` field is considered untrusted data and should be handled accordingly. <br />
+- `originalSender`: The transaction initiator on the source chain (ABI encoded)
+- `remoteChainSelector`: The source chain identifier
+- `receiver`: The recipient address on the destination chain
+- `amount`: Token quantity in source token decimals
+- `localToken`: The token contract address on the destination chain
+- `sourcePoolAddress`: The source pool contract address (ABI encoded for EVM chains). **WARNING**: Must be validated against expected pool address for the given `remoteChainSelector`
+- `sourcePoolData`: Processing data from the source pool
+- `offchainTokenData`: Additional processing data. **WARNING**: This is untrusted data
 
-    - Fields like `destTokenAddress` and `sourcePoolAddress` may contain ABI encoded data for EVM chains.
+The result of this operation is returned in [`ReleaseOrMintOutV1`](#releaseormintoutv1).
 
 </Aside>
 
 ### ReleaseOrMintOutV1
 
-This struct represents the output data from a `releaseOrMint` call.
+Output data from a release or mint operation.
 
 ```solidity
 struct ReleaseOrMintOutV1 {
@@ -129,6 +122,46 @@ struct ReleaseOrMintOutV1 {
 }
 ```
 
-| Name              | Type    | Description                                                                                                                                      |
-| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| destinationAmount | uint256 | The number of tokens released or minted on the destination chain, denominated in the local token's decimals. Expected to match the input amount. |
+<Aside>
+
+Contains the result of a token release or mint operation initiated by [`ReleaseOrMintInV1`](#releaseormintinv1):
+
+- `destinationAmount`: The quantity of tokens released or minted on the destination chain, denominated in the local token's decimals
+- Expected to match [`ReleaseOrMintInV1`](#releaseormintinv1).amount when source and destination chains use the same decimal precision
+
+</Aside>
+
+## State Variables
+
+### CCIP_POOL_V1
+
+```solidity
+bytes4 public constant CCIP_POOL_V1 = 0xaff2afbf;
+```
+
+<Aside>
+  A tag that signals support for the pool v1 standard, computed as `bytes4(keccak256("CCIP_POOL_V1"))`. Used for version
+  compatibility checks.
+</Aside>
+
+### CCIP_POOL_V1_RET_BYTES
+
+```solidity
+uint16 public constant CCIP_POOL_V1_RET_BYTES = 32;
+```
+
+<Aside>
+  The fixed number of bytes in the return data for a pool v1 `releaseOrMint`call. This value matches the size of the
+  [`ReleaseOrMintOutV1`](#releaseormintoutv1) struct.
+</Aside>
+
+### CCIP_LOCK_OR_BURN_V1_RET_BYTES
+
+```solidity
+uint32 public constant CCIP_LOCK_OR_BURN_V1_RET_BYTES = 32;
+```
+
+<Aside>
+  The default maximum number of bytes in the return data for a pool v1 `lockOrBurn` call. This limit can be adjusted
+  through TokenTransferFeeConfig.destBytesOverhead if additional data capacity is needed.
+</Aside>
diff --git a/src/content/ccip/api-reference/v1.5.1/rate-limiter.mdx b/src/content/ccip/api-reference/v1.5.1/rate-limiter.mdx
index 0caa84d069d..edbe32aa51a 100644
--- a/src/content/ccip/api-reference/v1.5.1/rate-limiter.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/rate-limiter.mdx
@@ -11,89 +11,139 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`RateLimiter`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/libraries/RateLimiter.sol) library implements Token Bucket rate limiting for CCIP operations.
+## RateLimiter
+
+A library implementing the Token Bucket algorithm for rate limiting cross-chain operations.
+
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/libraries/RateLimiter.sol)
+
+<Aside>
+
+This library provides rate limiting functionality with the following features:
+
+- Uses uint128 for safe state management
+- Supports USD value rate limiting with 18 decimals precision
+- Handles ERC20 token amount rate limiting
+- Implements automatic token bucket refill
+- Provides configuration validation and safety checks through [`Config`](#config)
+- Includes overflow protection for exceptional scenarios
 
-<Aside type="note">
-  uint128 is safe for rate limiter state: - For USD value rate limiting, it can adequately store USD value in 18
-  decimals - For ERC20 token amount rate limiting, all listed tokens will have at most a supply of uint128.max tokens -
-  If a token transfer amount exceeds uint128 (which could indicate a security concern), the RateLimiter's built-in
-  safety checks will detect this and revert the transaction
 </Aside>
 
+## Events
+
+### TokensConsumed
+
+```solidity
+event TokensConsumed(uint256 tokens);
+```
+
+<Aside>Emitted when tokens are successfully consumed from the [`TokenBucket`](#tokenbucket).</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description                   |
+| -------- | --------- | ----------------------------- |
+| `tokens` | `uint256` | The number of tokens consumed |
+
+### ConfigChanged
+
+```solidity
+event ConfigChanged(Config config);
+```
+
+<Aside>Emitted when the rate limiter [`Config`](#config) is updated.</Aside>
+
+**Parameters**
+
+| Name     | Type                | Description                   |
+| -------- | ------------------- | ----------------------------- |
+| `config` | [`Config`](#config) | The new configuration applied |
+
 ## Errors
 
 ### BucketOverfilled
 
 ```solidity
-error BucketOverfilled()
+error BucketOverfilled();
 ```
 
+<Aside>Thrown when the [`TokenBucket`](#tokenbucket) contains more tokens than its capacity.</Aside>
+
 ### OnlyCallableByAdminOrOwner
 
 ```solidity
-error OnlyCallableByAdminOrOwner()
+error OnlyCallableByAdminOrOwner();
 ```
 
+<Aside>Thrown when a restricted function is called by an unauthorized address.</Aside>
+
 ### TokenMaxCapacityExceeded
 
 ```solidity
-error TokenMaxCapacityExceeded(uint256 capacity, uint256 requested, address tokenAddress)
+error TokenMaxCapacityExceeded(uint256 capacity, uint256 requested, address tokenAddress);
 ```
 
+<Aside>Thrown when attempting to consume more tokens than the [`TokenBucket`](#tokenbucket)'s capacity.</Aside>
+
 ### TokenRateLimitReached
 
 ```solidity
-error TokenRateLimitReached(uint256 minWaitInSeconds, uint256 available, address tokenAddress)
+error TokenRateLimitReached(uint256 minWaitInSeconds, uint256 available, address tokenAddress);
 ```
 
+<Aside>
+  Thrown when attempting to consume more tokens than currently available in the [`TokenBucket`](#tokenbucket).
+</Aside>
+
 ### AggregateValueMaxCapacityExceeded
 
 ```solidity
-error AggregateValueMaxCapacityExceeded(uint256 capacity, uint256 requested)
+error AggregateValueMaxCapacityExceeded(uint256 capacity, uint256 requested);
 ```
 
+<Aside>Thrown when attempting to consume more aggregate value than the [`TokenBucket`](#tokenbucket)'s capacity.</Aside>
+
 ### AggregateValueRateLimitReached
 
 ```solidity
-error AggregateValueRateLimitReached(uint256 minWaitInSeconds, uint256 available)
+error AggregateValueRateLimitReached(uint256 minWaitInSeconds, uint256 available);
 ```
 
+<Aside>
+  Thrown when attempting to consume more aggregate value than currently available in the [`TokenBucket`](#tokenbucket).
+</Aside>
+
 ### InvalidRateLimitRate
 
 ```solidity
-error InvalidRateLimitRate(Config rateLimiterConfig)
+error InvalidRateLimitRate(Config rateLimiterConfig);
 ```
 
-### DisabledNonZeroRateLimit
-
-```solidity
-error DisabledNonZeroRateLimit(Config config)
-```
+<Aside>Thrown when the rate limit [`Config`](#config) is invalid (rate is zero or exceeds capacity).</Aside>
 
-### RateLimitMustBeDisabled
+### DisabledNonZeroRateLimit
 
 ```solidity
-error RateLimitMustBeDisabled()
+error DisabledNonZeroRateLimit(Config config);
 ```
 
-## Events
+<Aside>Thrown when a disabled [`Config`](#config) has non-zero rate or capacity values.</Aside>
 
-### TokensConsumed
+### RateLimitMustBeDisabled
 
 ```solidity
-event TokensConsumed(uint256 tokens)
+error RateLimitMustBeDisabled();
 ```
 
-### ConfigChanged
-
-```solidity
-event ConfigChanged(Config config)
-```
+<Aside>Thrown when attempting to enable rate limiting in a context where it must be disabled.</Aside>
 
 ## Structs
 
 ### TokenBucket
 
+Represents the state and configuration of a token bucket rate limiter.
+
 ```solidity
 struct TokenBucket {
   uint128 tokens;
@@ -104,16 +154,24 @@ struct TokenBucket {
 }
 ```
 
-| Name        | Type    | Description                                                        |
-| ----------- | ------- | ------------------------------------------------------------------ |
-| tokens      | uint128 | Current number of tokens that are in the bucket                    |
-| lastUpdated | uint32  | Timestamp in seconds of the last token refill, good for 100+ years |
-| isEnabled   | bool    | Indication whether the rate limiting is enabled or not             |
-| capacity    | uint128 | Maximum number of tokens that can be in the bucket                 |
-| rate        | uint128 | Number of tokens per second that the bucket is refilled            |
+<Aside>
+
+State management structure:
+
+- `tokens`: Current token balance in the bucket
+- `lastUpdated`: Timestamp of the last refill (in seconds, supports 100+ years)
+- `isEnabled`: Whether rate limiting is active
+- `capacity`: Maximum token capacity
+- `rate`: Tokens added per second during refill
+
+This struct uses the configuration parameters defined in [`Config`](#config).
+
+</Aside>
 
 ### Config
 
+Configuration parameters for the rate limiter.
+
 ```solidity
 struct Config {
   bool isEnabled;
@@ -122,125 +180,182 @@ struct Config {
 }
 ```
 
-| Name      | Type    | Description                                            |
-| --------- | ------- | ------------------------------------------------------ |
-| isEnabled | bool    | Indication whether the rate limiting should be enabled |
-| capacity  | uint128 | Specifies the capacity of the rate limiter             |
-| rate      | uint128 | Specifies the rate of the rate limiter                 |
+<Aside>
+
+Configuration structure used to configure [`TokenBucket`](#tokenbucket):
+
+- `isEnabled`: Activation state of the rate limiter
+- `capacity`: Maximum token capacity
+- `rate`: Token refill rate per second
+
+</Aside>
 
 ## Functions
 
 ### \_consume
 
+Removes tokens from the pool, reducing the available rate capacity for subsequent calls.
+
 ```solidity
-function _consume(TokenBucket storage s_bucket, uint256 requestTokens, address tokenAddress) internal
+function _consume(TokenBucket storage s_bucket, uint256 requestTokens, address tokenAddress) internal;
 ```
 
-Removes the given tokens from the pool, lowering the rate tokens allowed to be consumed for subsequent calls.
+<Aside>
 
-#### Parameters
+Key behaviors:
 
-| Name          | Type        | Description                                                                     |
-| ------------- | ----------- | ------------------------------------------------------------------------------- |
-| s_bucket      | TokenBucket | The token bucket to consume from                                                |
-| requestTokens | uint256     | The total tokens to be consumed from the bucket                                 |
-| tokenAddress  | address     | The token to consume capacity for, use 0x0 to indicate aggregate value capacity |
+- Skips execution if rate limiting is disabled or requestTokens is zero
+- Automatically refills tokens based on elapsed time
+- Enforces capacity and rate limits
+- Emits [`TokensConsumed`](#tokensconsumed) event for non-zero consumption
+- Reverts with [`TokenMaxCapacityExceeded`](#tokenmaxcapacityexceeded) or [`TokenRateLimitReached`](#tokenratelimitreached) on violations
 
-<Aside type="caution">
-  - Reverts when requestTokens exceeds bucket capacity or available tokens in the bucket - Emits removal of
-  requestTokens if requestTokens is > 0
 </Aside>
 
+**Parameters**
+
+| Name            | Type                          | Description                                                     |
+| --------------- | ----------------------------- | --------------------------------------------------------------- |
+| `s_bucket`      | [`TokenBucket`](#tokenbucket) | The token bucket to consume from                                |
+| `requestTokens` | `uint256`                     | The number of tokens to consume                                 |
+| `tokenAddress`  | `address`                     | The token address (use address(0) for aggregate value capacity) |
+
 ### \_currentTokenBucketState
 
+Retrieves the current state of a token bucket, including automatic refill calculations.
+
 ```solidity
-function _currentTokenBucketState(TokenBucket memory bucket) internal view returns (TokenBucket memory)
+function _currentTokenBucketState(TokenBucket memory bucket) internal view returns (TokenBucket memory);
 ```
 
-Gets the token bucket with its values for the block it was requested at.
+<Aside>
+
+Updates the bucket state to reflect the current block timestamp:
 
-#### Parameters
+- Calculates token refill based on elapsed time
+- Updates the lastUpdated timestamp
+- Returns the current state without modifying storage
 
-| Name   | Type        | Description      |
-| ------ | ----------- | ---------------- |
-| bucket | TokenBucket | The token bucket |
+</Aside>
 
-#### Return Values
+**Returns**
 
-| Type        | Description                                |
-| ----------- | ------------------------------------------ |
-| TokenBucket | The token bucket with current block values |
+| Type                          | Description                           |
+| ----------------------------- | ------------------------------------- |
+| [`TokenBucket`](#tokenbucket) | The current state of the token bucket |
 
 ### \_setTokenBucketConfig
 
+Updates the rate limiter configuration.
+
 ```solidity
-function _setTokenBucketConfig(TokenBucket storage s_bucket, Config memory config) internal
+function _setTokenBucketConfig(TokenBucket storage s_bucket, Config memory config) internal;
 ```
 
-Sets the rate limited config.
+<Aside>
+
+Configuration update process:
 
-#### Parameters
+- Updates bucket state with current refill before applying changes
+- Adjusts token amount to respect new capacity
+- Updates bucket parameters (enabled state, capacity, rate)
+- Emits [`ConfigChanged`](#configchanged) event
 
-| Name     | Type        | Description      |
-| -------- | ----------- | ---------------- |
-| s_bucket | TokenBucket | The token bucket |
-| config   | Config      | The new config   |
+</Aside>
+
+**Parameters**
+
+| Name       | Type                          | Description                    |
+| ---------- | ----------------------------- | ------------------------------ |
+| `s_bucket` | [`TokenBucket`](#tokenbucket) | The token bucket to configure  |
+| `config`   | [`Config`](#config)           | The new configuration to apply |
 
 ### \_validateTokenBucketConfig
 
+Validates rate limiter configuration parameters.
+
 ```solidity
-function _validateTokenBucketConfig(Config memory config, bool mustBeDisabled) internal pure
+function _validateTokenBucketConfig(Config memory config, bool mustBeDisabled) internal pure;
 ```
 
-Validates the token bucket config.
+<Aside>
 
-#### Parameters
+Validation rules:
 
-| Name           | Type   | Description                         |
-| -------------- | ------ | ----------------------------------- |
-| config         | Config | The config to validate              |
-| mustBeDisabled | bool   | Whether the config must be disabled |
+- For enabled configurations:
+  - Rate must be non-zero and less than capacity
+  - Validates against mustBeDisabled requirement
+- For disabled configurations:
+  - Rate and capacity must be zero
+- May throw [`InvalidRateLimitRate`](#invalidratelimitrate), [`DisabledNonZeroRateLimit`](#disablednonzeroratelimit), or [`RateLimitMustBeDisabled`](#ratelimitmustbedisabled)
+
+</Aside>
+
+**Parameters**
+
+| Name             | Type                | Description                                |
+| ---------------- | ------------------- | ------------------------------------------ |
+| `config`         | [`Config`](#config) | The configuration to validate              |
+| `mustBeDisabled` | `bool`              | Whether the configuration must be disabled |
 
 ### \_calculateRefill
 
+Calculates the number of tokens to add during a refill operation.
+
 ```solidity
-function _calculateRefill(uint256 capacity, uint256 tokens, uint256 timeDiff, uint256 rate) private pure returns (uint256)
+function _calculateRefill(
+  uint256 capacity,
+  uint256 tokens,
+  uint256 timeDiff,
+  uint256 rate
+) private pure returns (uint256);
 ```
 
-Calculate refilled tokens.
+<Aside>
 
-#### Parameters
+Refill calculation:
 
-| Name     | Type    | Description                             |
-| -------- | ------- | --------------------------------------- |
-| capacity | uint256 | bucket capacity                         |
-| tokens   | uint256 | current bucket tokens                   |
-| timeDiff | uint256 | block time difference since last refill |
-| rate     | uint256 | bucket refill rate                      |
+- Computes tokens to add based on elapsed time and rate
+- Ensures result doesn't exceed bucket capacity
+- Returns the new token balance
+- Used internally by [`_currentTokenBucketState`](#_currenttokenbucketstate)
 
-#### Return Values
+</Aside>
 
-| Type    | Description                      |
-| ------- | -------------------------------- |
-| uint256 | the value of tokens after refill |
+**Parameters**
+
+| Name       | Type      | Description                                 |
+| ---------- | --------- | ------------------------------------------- |
+| `capacity` | `uint256` | Maximum token capacity                      |
+| `tokens`   | `uint256` | Current token balance                       |
+| `timeDiff` | `uint256` | Time elapsed since last refill (in seconds) |
+| `rate`     | `uint256` | Tokens per second refill rate               |
+
+**Returns**
+
+| Type      | Description                        |
+| --------- | ---------------------------------- |
+| `uint256` | The new token balance after refill |
 
 ### \_min
 
+Returns the smaller of two numbers.
+
 ```solidity
-function _min(uint256 a, uint256 b) internal pure returns (uint256)
+function _min(uint256 a, uint256 b) internal pure returns (uint256);
 ```
 
-Return the smallest of two integers.
+<Aside>Utility function for safe minimum value calculation.</Aside>
 
-#### Parameters
+**Parameters**
 
-| Name | Type    | Description |
-| ---- | ------- | ----------- |
-| a    | uint256 | first int   |
-| b    | uint256 | second int  |
+| Name | Type      | Description   |
+| ---- | --------- | ------------- |
+| `a`  | `uint256` | First number  |
+| `b`  | `uint256` | Second number |
 
-#### Return Values
+**Returns**
 
-| Type    | Description      |
-| ------- | ---------------- |
-| uint256 | smallest integer |
+| Type      | Description                    |
+| --------- | ------------------------------ |
+| `uint256` | The smaller of the two numbers |
diff --git a/src/content/ccip/api-reference/v1.5.1/registry-module-owner-custom.mdx b/src/content/ccip/api-reference/v1.5.1/registry-module-owner-custom.mdx
index 179bb73f630..470d5191795 100644
--- a/src/content/ccip/api-reference/v1.5.1/registry-module-owner-custom.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/registry-module-owner-custom.mdx
@@ -11,142 +11,237 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`RegistryModuleOwnerCustom`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/tokenAdminRegistry/RegistryModuleOwnerCustom.sol) contract provides different methods for token developers to register themselves as administrators for their tokens in CCIP.
+## RegistryModuleOwnerCustom
+
+A contract that facilitates token administrator registration through various ownership patterns.
+
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/tokenAdminRegistry/RegistryModuleOwnerCustom.sol)
+
+**Inherits:**
+
+- [ITypeAndVersion](/ccip/api-reference/v1.5.1/i-type-and-version)
+
+<Aside>
+
+This contract provides multiple methods for registering token administrators:
+
+- Supports registration via [`getCCIPAdmin`](#registeradminviagetccipadmin) method
+- Supports registration via [`owner`](#registeradminviaowner) method
+- Supports registration via OpenZeppelin's [`AccessControl`](#registeraccesscontroldefaultadmin)
+- Enforces self-registration security pattern
+- Integrates with [`TokenAdminRegistry`](/ccip/api-reference/v1.5.1/token-admin-registry) for administrator management
+
+</Aside>
+
+## Events
+
+### AdministratorRegistered
+
+```solidity
+event AdministratorRegistered(address indexed token, address indexed administrator);
+```
+
+<Aside>
+  Emitted when a new administrator is successfully registered for a token through any of the registration methods
+  ([`registerAccessControlDefaultAdmin`](#registeraccesscontroldefaultadmin),
+  [`registerAdminViaGetCCIPAdmin`](#registeradminviagetccipadmin), or
+  [`registerAdminViaOwner`](#registeradminviaowner)).
+</Aside>
+
+**Parameters**
+
+| Name            | Type      | Indexed | Description                          |
+| --------------- | --------- | ------- | ------------------------------------ |
+| `token`         | `address` | Yes     | The token contract address           |
+| `administrator` | `address` | Yes     | The registered administrator address |
 
 ## Errors
 
+### AddressZero
+
+```solidity
+error AddressZero();
+```
+
+<Aside>
+  Thrown when attempting to initialize with a zero address for the
+  [`TokenAdminRegistry`](/ccip/api-reference/v1.5.1/token-admin-registry).
+</Aside>
+
 ### CanOnlySelfRegister
 
 ```solidity
-error CanOnlySelfRegister(address admin, address token)
+error CanOnlySelfRegister(address admin, address token);
 ```
 
-Thrown when someone tries to register an admin address that does not belong to them.
+<Aside>
+  Thrown when an address attempts to register an administrator other than itself through any of the registration
+  methods.
+</Aside>
+
+**Parameters**
 
-| Parameter | Type    | Description            |
-| --------- | ------- | ---------------------- |
-| admin     | address | Expected admin address |
-| token     | address | Token being registered |
+| Name    | Type      | Description                        |
+| ------- | --------- | ---------------------------------- |
+| `admin` | `address` | The expected administrator address |
+| `token` | `address` | The token contract address         |
 
 ### RequiredRoleNotFound
 
 ```solidity
-error RequiredRoleNotFound(address msgSender, bytes32 role, address token)
+error RequiredRoleNotFound(address msgSender, bytes32 role, address token);
 ```
 
-Thrown when caller doesn't have the required role for registration.
+<Aside>
+  Thrown when the caller lacks the required role for administrator registration in
+  [`registerAccessControlDefaultAdmin`](#registeraccesscontroldefaultadmin).
+</Aside>
 
-| Parameter | Type    | Description                         |
-| --------- | ------- | ----------------------------------- |
-| msgSender | address | Address that attempted registration |
-| role      | bytes32 | Required role that was missing      |
-| token     | address | Token being registered              |
+**Parameters**
 
-### AddressZero
+| Name        | Type      | Description                  |
+| ----------- | --------- | ---------------------------- |
+| `msgSender` | `address` | The caller's address         |
+| `role`      | `bytes32` | The required role identifier |
+| `token`     | `address` | The token contract address   |
+
+## State Variables
+
+### i_tokenAdminRegistry
 
 ```solidity
-error AddressZero()
+ITokenAdminRegistry internal immutable i_tokenAdminRegistry;
 ```
 
-Thrown when trying to set the TokenAdminRegistry address to zero.
+<Aside>
+  Immutable reference to the [`TokenAdminRegistry`](/ccip/api-reference/v1.5.1/token-admin-registry) contract that
+  manages administrator registrations.
+</Aside>
 
-## Events
-
-### AdministratorRegistered
+### typeAndVersion
 
 ```solidity
-event AdministratorRegistered(address indexed token, address indexed administrator)
+string public constant override typeAndVersion = "RegistryModuleOwnerCustom 1.6.0";
 ```
 
-Emitted when an administrator is successfully registered for a token.
-
-| Parameter     | Type    | Description                             |
-| ------------- | ------- | --------------------------------------- |
-| token         | address | Token address that got an administrator |
-| administrator | address | Address registered as administrator     |
+<Aside>Contract identifier that specifies the implementation version.</Aside>
 
 ## Functions
 
 ### constructor
 
 ```solidity
-constructor(
-    address tokenAdminRegistry
-)
+constructor(address tokenAdminRegistry);
 ```
 
-Initializes the contract with the TokenAdminRegistry address.
+<Aside>
 
-#### Parameters
+Initializes the contract with a reference to the [`TokenAdminRegistry`](/ccip/api-reference/v1.5.1/token-admin-registry):
 
-| Name               | Type    | Description                                |
-| ------------------ | ------- | ------------------------------------------ |
-| tokenAdminRegistry | address | Address of the TokenAdminRegistry contract |
+- Validates the tokenAdminRegistry address is not zero (reverts with [`AddressZero`](#addresszero))
+- Sets up the immutable registry reference
 
-### registerAdminViaGetCCIPAdmin
+</Aside>
+
+**Parameters**
+
+| Name                 | Type      | Description                                    |
+| -------------------- | --------- | ---------------------------------------------- |
+| `tokenAdminRegistry` | `address` | The address of the TokenAdminRegistry contract |
+
+### registerAccessControlDefaultAdmin
+
+Registers a token administrator using OpenZeppelin's AccessControl DEFAULT_ADMIN_ROLE.
 
 ```solidity
-function registerAdminViaGetCCIPAdmin(
-    address token
-) external
+function registerAccessControlDefaultAdmin(address token) external;
 ```
 
-Registers an administrator using the token's `getCCIPAdmin()` method.
+<Aside>
 
-<Aside type="note">The caller must be the same address returned by the token's getCCIPAdmin() function.</Aside>
+Validates and registers an administrator using AccessControl:
 
-#### Parameters
+- Verifies caller has DEFAULT_ADMIN_ROLE (reverts with [`RequiredRoleNotFound`](#requiredrolenotfound))
+- Only allows self-registration (reverts with [`CanOnlySelfRegister`](#canonlyselfregister))
+- Emits [`AdministratorRegistered`](#administratorregistered) event on success
 
-| Name  | Type    | Description                                 |
-| ----- | ------- | ------------------------------------------- |
-| token | address | Token address to register administrator for |
+</Aside>
 
-### registerAdminViaOwner
+**Parameters**
+
+| Name    | Type      | Description                              |
+| ------- | --------- | ---------------------------------------- |
+| `token` | `address` | The token contract to register admin for |
+
+### registerAdminViaGetCCIPAdmin
+
+Registers a token administrator using the `getCCIPAdmin` method.
 
 ```solidity
-function registerAdminViaOwner(
-    address token
-) external
+function registerAdminViaGetCCIPAdmin(address token) external;
 ```
 
-Registers an administrator using the token's `owner()` method.
+<Aside>
 
-<Aside type="note">The caller must be the same address returned by the token's owner() function.</Aside>
+Validates and registers an administrator using getCCIPAdmin:
 
-#### Parameters
+- Calls token's getCCIPAdmin method
+- Only allows self-registration (reverts with [`CanOnlySelfRegister`](#canonlyselfregister))
+- Emits [`AdministratorRegistered`](#administratorregistered) event on success
 
-| Name  | Type    | Description                                 |
-| ----- | ------- | ------------------------------------------- |
-| token | address | Token address to register administrator for |
+</Aside>
 
-### registerAccessControlDefaultAdmin
+**Parameters**
+
+| Name    | Type      | Description                              |
+| ------- | --------- | ---------------------------------------- |
+| `token` | `address` | The token contract to register admin for |
+
+### registerAdminViaOwner
+
+Registers a token administrator using the `owner` method.
 
 ```solidity
-function registerAccessControlDefaultAdmin(
-    address token
-) external
+function registerAdminViaOwner(address token) external;
 ```
 
-Registers an administrator using OpenZeppelin's AccessControl DEFAULT_ADMIN_ROLE.
+<Aside>
 
-<Aside type="note">The caller must have the DEFAULT_ADMIN_ROLE in the token contract.</Aside>
+Validates and registers an administrator using owner pattern:
 
-#### Parameters
+- Calls token's owner method
+- Only allows self-registration (reverts with [`CanOnlySelfRegister`](#canonlyselfregister))
+- Emits [`AdministratorRegistered`](#administratorregistered) event on success
 
-| Name  | Type    | Description                                 |
-| ----- | ------- | ------------------------------------------- |
-| token | address | Token address to register administrator for |
+</Aside>
 
-### typeAndVersion
+**Parameters**
+
+| Name    | Type      | Description                              |
+| ------- | --------- | ---------------------------------------- |
+| `token` | `address` | The token contract to register admin for |
+
+### \_registerAdmin
+
+Internal function to handle administrator registration.
 
 ```solidity
-string public constant override typeAndVersion = "RegistryModuleOwnerCustom 1.6.0"
+function _registerAdmin(address token, address admin) internal;
 ```
 
-Returns the type and version of the contract.
+<Aside>
+
+Core registration logic:
+
+- Validates caller is the admin (reverts with [`CanOnlySelfRegister`](#canonlyselfregister))
+- Proposes administrator to registry
+- Emits [`AdministratorRegistered`](#administratorregistered) event
+
+</Aside>
 
-#### Return Value
+**Parameters**
 
-| Type   | Description                                  |
-| ------ | -------------------------------------------- |
-| string | The string "RegistryModuleOwnerCustom 1.6.0" |
+| Name    | Type      | Description                                |
+| ------- | --------- | ------------------------------------------ |
+| `token` | `address` | The token contract to register admin for   |
+| `admin` | `address` | The administrator address being registered |
diff --git a/src/content/ccip/api-reference/v1.5.1/token-admin-registry.mdx b/src/content/ccip/api-reference/v1.5.1/token-admin-registry.mdx
index 45de050a028..2b438584069 100644
--- a/src/content/ccip/api-reference/v1.5.1/token-admin-registry.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/token-admin-registry.mdx
@@ -11,457 +11,578 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`TokenAdminRegistry`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/tokenAdminRegistry/TokenAdminRegistry.sol) contract manages which tokens can be transferred through CCIP and who can configure them. Key features:
+## TokenAdminRegistry
 
-- Token developers can register their tokens without needing permission from CCIP
-- Each token has an administrator who controls its CCIP settings
-- Administrators can enable or disable their tokens for CCIP transfers
-- The contract is not upgradeable to ensure data persistence
+A contract that manages token pool configurations and administrator access for CCIP-enabled tokens.
 
-## Errors
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/tokenAdminRegistry/TokenAdminRegistry.sol)
 
-### OnlyRegistryModuleOrOwner
+**Inherits:**
 
-```solidity
-error OnlyRegistryModuleOrOwner(address sender)
-```
+- [ITypeAndVersion](/ccip/api-reference/v1.5.1/i-type-and-version)
 
-Thrown when someone tries to perform an action restricted to registry modules or the owner.
+<Aside>
 
-| Parameter | Type    | Description                                  |
-| --------- | ------- | -------------------------------------------- |
-| sender    | address | Address that attempted the restricted action |
+This contract provides self-service token registration and administration:
 
-### OnlyAdministrator
+- Manages token pool configurations
+- Handles administrator permissions through [`proposeAdministrator`](#proposeadministrator) and [`acceptAdminRole`](#acceptadminrole)
+- Supports registry modules for flexible registration via [`addRegistryModule`](#addregistrymodule)
+- Implements secure admin role transfers using [`transferAdminRole`](#transferadminrole)
+- Not upgradeable due to significant data storage
 
-```solidity
-error OnlyAdministrator(address sender, address token)
-```
+Note: This contract is designed as a customer-facing interface and stores substantial data, making it non-upgradeable by design.
 
-Thrown when someone tries to perform an action restricted to the token's administrator.
+</Aside>
 
-| Parameter | Type    | Description                                  |
-| --------- | ------- | -------------------------------------------- |
-| sender    | address | Address that attempted the restricted action |
-| token     | address | Token address that was being configured      |
+## Functions
 
-### OnlyPendingAdministrator
+### acceptAdminRole
+
+Accepts the administrator role for a token.
 
 ```solidity
-error OnlyPendingAdministrator(address sender, address token)
+function acceptAdminRole(address localToken) external;
 ```
 
-Thrown when someone other than the pending administrator tries to accept the administrator role.
+<Aside>
 
-| Parameter | Type    | Description                               |
-| --------- | ------- | ----------------------------------------- |
-| sender    | address | Address that attempted to accept the role |
-| token     | address | Token address involved                    |
+Second step of the two-step administrator transfer process:
 
-### AlreadyRegistered
+- Only callable by the pending administrator
+- Clears the pending administrator after acceptance
+- Emits AdministratorTransferred event
+
+</Aside>
+
+**Parameters**
+
+| Name         | Type      | Description                                |
+| ------------ | --------- | ------------------------------------------ |
+| `localToken` | `address` | The token to accept the administrator role |
+
+### addRegistryModule
+
+Adds a new registry module to the allowed modules list.
 
 ```solidity
-error AlreadyRegistered(address token)
+function addRegistryModule(address module) external onlyOwner;
 ```
 
-Thrown when trying to register a token that already has an administrator.
+<Aside>
+
+Registry module management:
+
+- Only callable by contract owner
+- Emits RegistryModuleAdded event if module is added
+- No effect if module is already registered
+
+</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description             |
+| -------- | --------- | ----------------------- |
+| `module` | `address` | The module to authorize |
 
-| Parameter | Type    | Description                               |
-| --------- | ------- | ----------------------------------------- |
-| token     | address | Token address that was already registered |
+### getAllConfiguredTokens
 
-### ZeroAddress
+Returns a paginated list of configured tokens.
 
 ```solidity
-error ZeroAddress()
+function getAllConfiguredTokens(uint64 startIndex, uint64 maxCount) external view returns (address[] memory tokens);
 ```
 
-Thrown when trying to set a critical address to zero (except for specific allowed cases).
+<Aside>
 
-### InvalidTokenPoolToken
+Pagination features:
+
+- Supports partial list retrieval to prevent RPC timeouts
+- Maintains consistent ordering
+- Returns empty array if startIndex is beyond list length
+- Automatically adjusts count if it exceeds available tokens
+
+</Aside>
+
+**Parameters**
+
+| Name         | Type     | Description                                               |
+| ------------ | -------- | --------------------------------------------------------- |
+| `startIndex` | `uint64` | Starting position in the list (0 for beginning)           |
+| `maxCount`   | `uint64` | Maximum tokens to retrieve (use type(uint64).max for all) |
+
+**Returns**
+
+| Type        | Description                        |
+| ----------- | ---------------------------------- |
+| `address[]` | List of configured token addresses |
+
+### getPool
+
+Returns the pool address for a specific token.
 
 ```solidity
-error InvalidTokenPoolToken(address token)
+function getPool(address token) external view returns (address);
 ```
 
-Thrown when trying to set a pool that doesn't support the specified token.
+<Aside>
+
+Returns address(0) if:
 
-| Parameter | Type    | Description                                 |
-| --------- | ------- | ------------------------------------------- |
-| token     | address | Token address that the pool doesn't support |
+- Token is not configured
+- Token is delisted from CCIP
 
-<Aside type="note">
-  This error helps prevent misconfiguration by ensuring pools are compatible with their assigned tokens.
 </Aside>
 
-## Events
+**Parameters**
 
-### PoolSet
+| Name    | Type      | Description        |
+| ------- | --------- | ------------------ |
+| `token` | `address` | The token to query |
+
+**Returns**
+
+| Type      | Description              |
+| --------- | ------------------------ |
+| `address` | The token's pool address |
+
+### getPools
+
+Returns pool addresses for multiple tokens.
 
 ```solidity
-event PoolSet(
-    address indexed token,
-    address indexed previousPool,
-    address indexed newPool
-)
+function getPools(address[] calldata tokens) external view returns (address[] memory);
 ```
 
-Emitted when a token's pool address is changed. This indicates a change in how the token is handled in CCIP.
+<Aside>
 
-| Parameter    | Type    | Description                                                        |
-| ------------ | ------- | ------------------------------------------------------------------ |
-| token        | address | Token address whose pool was changed                               |
-| previousPool | address | Old pool address (can be address(0))                               |
-| newPool      | address | New pool address (can be address(0) to disable CCIP for the token) |
+Batch query functionality:
 
-### AdministratorTransferRequested
+- Returns address(0) for unconfigured tokens
+- Maintains order corresponding to input array
+- Useful for efficient multi-token queries
+
+</Aside>
+
+**Parameters**
+
+| Name     | Type        | Description     |
+| -------- | ----------- | --------------- |
+| `tokens` | `address[]` | Tokens to query |
+
+**Returns**
+
+| Type        | Description                           |
+| ----------- | ------------------------------------- |
+| `address[]` | Array of corresponding pool addresses |
+
+### getTokenConfig
+
+Returns the complete configuration for a token.
 
 ```solidity
-event AdministratorTransferRequested(
-    address indexed token,
-    address indexed currentAdmin,
-    address indexed newAdmin
-)
+function getTokenConfig(address token) external view returns (TokenConfig memory);
 ```
 
-Emitted when the first step of an administrator transfer is initiated.
+<Aside>
 
-| Parameter    | Type    | Description                                                             |
-| ------------ | ------- | ----------------------------------------------------------------------- |
-| token        | address | Token address whose administrator is being changed                      |
-| currentAdmin | address | Current administrator address (can be address(0) for new registrations) |
-| newAdmin     | address | Proposed new administrator address                                      |
+Returns all token configuration data:
 
-### AdministratorTransferred
+- Current administrator
+- Pending administrator (if any)
+- Token pool address
+
+</Aside>
+
+**Parameters**
+
+| Name    | Type      | Description    |
+| ------- | --------- | -------------- |
+| `token` | `address` | Token to query |
+
+**Returns**
+
+| Type          | Description                  |
+| ------------- | ---------------------------- |
+| `TokenConfig` | Complete token configuration |
+
+### isAdministrator
+
+Checks if an address is the administrator for a token.
 
 ```solidity
-event AdministratorTransferred(
-    address indexed token,
-    address indexed newAdmin
-)
+function isAdministrator(address localToken, address administrator) external view returns (bool);
 ```
 
-Emitted when an administrator transfer is completed (after the new administrator accepts the role).
+<Aside>
 
-| Parameter | Type    | Description                               |
-| --------- | ------- | ----------------------------------------- |
-| token     | address | Token address whose administrator changed |
-| newAdmin  | address | Address of the new administrator          |
+Permission verification helper:
 
-### RegistryModuleAdded
+- Returns true only for current administrator
+- Does not consider pending administrators
+
+</Aside>
+
+**Parameters**
+
+| Name            | Type      | Description       |
+| --------------- | --------- | ----------------- |
+| `localToken`    | `address` | Token to check    |
+| `administrator` | `address` | Address to verify |
+
+**Returns**
+
+| Type   | Description                              |
+| ------ | ---------------------------------------- |
+| `bool` | True if address is current administrator |
+
+### isRegistryModule
+
+Checks if an address is an authorized registry module.
 
 ```solidity
-event RegistryModuleAdded(address module)
+function isRegistryModule(address module) public view returns (bool);
 ```
 
-Emitted when a new registry module is added to the system.
+<Aside>
 
-| Parameter | Type    | Description                                |
-| --------- | ------- | ------------------------------------------ |
-| module    | address | Address of the newly added registry module |
+Module verification helper:
 
-### RegistryModuleRemoved
+- Returns true for authorized modules
+- Used for permission checks in proposeAdministrator
+
+</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description       |
+| -------- | --------- | ----------------- |
+| `module` | `address` | Address to verify |
+
+**Returns**
+
+| Type   | Description                          |
+| ------ | ------------------------------------ |
+| `bool` | True if address is authorized module |
+
+### proposeAdministrator
+
+Proposes an initial administrator for a token.
 
 ```solidity
-event RegistryModuleRemoved(address indexed module)
+function proposeAdministrator(address localToken, address administrator) external;
 ```
 
-Emitted when a registry module is removed from the system.
+<Aside>
+
+Initial administrator setup:
 
-| Parameter | Type    | Description                            |
-| --------- | ------- | -------------------------------------- |
-| module    | address | Address of the removed registry module |
+- Only callable by registry modules (see [`isRegistryModule`](#isregistrymodule)) or owner
+- Cannot override existing administrator (reverts with [`AlreadyRegistered`](#alreadyregistered))
+- Initiates two-step transfer process requiring [`acceptAdminRole`](#acceptadminrole)
+- Adds token to configured tokens list
+- Emits [`AdministratorTransferRequested`](#administratortransferrequested) event
 
-<Aside type="note">
-  Registry modules are special contracts that can propose administrators for tokens. Adding or removing them can only be
-  done by the contract owner.
 </Aside>
 
-## Data Structures
+**Parameters**
 
-### TokenConfig
+| Name            | Type      | Description                    |
+| --------------- | --------- | ------------------------------ |
+| `localToken`    | `address` | Token to configure             |
+| `administrator` | `address` | Proposed administrator address |
+
+### removeRegistryModule
+
+Removes a registry module from the allowed modules list.
 
 ```solidity
-struct TokenConfig {
-  address administrator;
-  address pendingAdministrator;
-  address tokenPool;
-}
+function removeRegistryModule(address module) external onlyOwner;
 ```
 
-Configuration data for each token:
-| Field | Type | Description |
-|-------|------|-------------|
-| administrator | address | Current administrator who can manage the token's CCIP settings |
-| pendingAdministrator | address | Address nominated to become the new administrator (part of 2-step transfer) |
-| tokenPool | address | Pool contract that handles the token's cross-chain transfers. If set to address(0), the token is disabled for CCIP |
+<Aside>
 
-## Core Query Functions
+Registry module management:
 
-### getPools
+- Only callable by contract owner
+- Emits RegistryModuleRemoved event if module is removed
+- No effect if module is not registered
+
+</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description          |
+| -------- | --------- | -------------------- |
+| `module` | `address` | The module to remove |
+
+### setPool
+
+Sets or updates the pool for a token.
 
 ```solidity
-function getPools(
-    address[] calldata tokens
-) external view returns (address[] memory)
+function setPool(address localToken, address pool) external onlyTokenAdmin(localToken);
 ```
 
-Gets the pool addresses for multiple tokens at once.
+<Aside>
 
-#### Parameters
+Pool configuration management:
 
-| Name   | Type      | Description                       |
-| ------ | --------- | --------------------------------- |
-| tokens | address[] | Array of token addresses to query |
+- Only callable by token administrator (reverts with [`OnlyAdministrator`](#onlyadministrator))
+- Can delist token by setting address(0)
+- Validates pool supports token (reverts with [`InvalidTokenPoolToken`](#invalidtokenpooltoken))
+- Emits [`PoolSet`](#poolset) event on changes
 
-#### Return Value
+</Aside>
 
-| Type      | Description                                                          |
-| --------- | -------------------------------------------------------------------- |
-| address[] | Array of pool addresses. Will be address(0) for tokens without pools |
+**Parameters**
 
-### getPool
+| Name         | Type      | Description                       |
+| ------------ | --------- | --------------------------------- |
+| `localToken` | `address` | Token to configure                |
+| `pool`       | `address` | New pool address (or 0 to delist) |
+
+### transferAdminRole
+
+Initiates transfer of administrator role.
 
 ```solidity
-function getPool(
-    address token
-) external view returns (address)
+function transferAdminRole(address localToken, address newAdmin) external onlyTokenAdmin(localToken);
 ```
 
-Gets the pool address for a single token.
+<Aside>
+
+First step of two-step administrator transfer:
 
-#### Parameters
+- Only callable by current administrator (reverts with [`OnlyAdministrator`](#onlyadministrator))
+- Can cancel pending transfer with address(0)
+- Requires [`acceptAdminRole`](#acceptadminrole) call to complete
+- Emits [`AdministratorTransferRequested`](#administratortransferrequested) event
 
-| Name  | Type    | Description            |
-| ----- | ------- | ---------------------- |
-| token | address | Token address to query |
+</Aside>
 
-#### Return Value
+**Parameters**
 
-| Type    | Description                                                 |
-| ------- | ----------------------------------------------------------- |
-| address | Pool address for the token, or address(0) if not configured |
+| Name         | Type      | Description                                              |
+| ------------ | --------- | -------------------------------------------------------- |
+| `localToken` | `address` | The token contract whose admin role is being transferred |
+| `newAdmin`   | `address` | The proposed new administrator address (or 0 to cancel)  |
 
-### getTokenConfig
+## Events
+
+### AdministratorTransferRequested
 
 ```solidity
-function getTokenConfig(
-    address token
-) external view returns (TokenConfig memory)
+event AdministratorTransferRequested(address indexed token, address indexed currentAdmin, address indexed newAdmin);
 ```
 
-Gets the complete configuration for a token.
+<Aside>
+  Emitted when an administrator transfer is initiated via [`transferAdminRole`](#transferadminrole) or canceled.
+</Aside>
+
+**Parameters**
+
+| Name           | Type      | Indexed | Description                                              |
+| -------------- | --------- | ------- | -------------------------------------------------------- |
+| `token`        | `address` | Yes     | The token contract whose admin role is being transferred |
+| `currentAdmin` | `address` | Yes     | The current administrator address                        |
+| `newAdmin`     | `address` | Yes     | The proposed new administrator address                   |
 
-#### Parameters
+### AdministratorTransferred
+
+```solidity
+event AdministratorTransferred(address indexed token, address indexed newAdmin);
+```
 
-| Name  | Type    | Description            |
-| ----- | ------- | ---------------------- |
-| token | address | Token address to query |
+<Aside>Emitted when an administrator transfer is completed via [`acceptAdminRole`](#acceptadminrole).</Aside>
 
-#### Return Value
+**Parameters**
 
-| Type        | Description                                                                           |
-| ----------- | ------------------------------------------------------------------------------------- |
-| TokenConfig | Complete token configuration including administrator, pending administrator, and pool |
+| Name       | Type      | Indexed | Description                                              |
+| ---------- | --------- | ------- | -------------------------------------------------------- |
+| `token`    | `address` | Yes     | The token contract whose admin role has been transferred |
+| `newAdmin` | `address` | Yes     | The new administrator address                            |
 
-### getAllConfiguredTokens
+### PoolSet
 
 ```solidity
-function getAllConfiguredTokens(
-    uint64 startIndex,
-    uint64 maxCount
-) external view returns (address[] memory tokens)
+event PoolSet(address indexed token, address indexed previousPool, address indexed newPool);
 ```
 
-Gets a list of all configured tokens, with pagination support to handle large lists.
+<Aside>Emitted when a token's pool configuration is changed via [`setPool`](#setpool).</Aside>
 
-<Aside type="note">
-  The order of tokens is guaranteed to remain consistent as tokens cannot be removed from the registry.
-</Aside>
+**Parameters**
 
-#### Parameters
+| Name           | Type      | Indexed | Description                        |
+| -------------- | --------- | ------- | ---------------------------------- |
+| `token`        | `address` | Yes     | The token address being configured |
+| `previousPool` | `address` | Yes     | The previous pool address          |
+| `newPool`      | `address` | Yes     | The new pool address               |
 
-| Name       | Type   | Description                                                                       |
-| ---------- | ------ | --------------------------------------------------------------------------------- |
-| startIndex | uint64 | Position to start reading from (0 for beginning)                                  |
-| maxCount   | uint64 | Maximum number of tokens to return. Use type(uint64).max for all remaining tokens |
+### RegistryModuleAdded
 
-#### Return Value
+```solidity
+event RegistryModuleAdded(address module);
+```
 
-| Type      | Description              |
-| --------- | ------------------------ |
-| address[] | Array of token addresses |
+<Aside>Emitted when a new registry module is authorized.</Aside>
 
-## Administrator Management Functions
+**Parameters**
 
-### setPool
+| Name     | Type      | Indexed | Description                                |
+| -------- | --------- | ------- | ------------------------------------------ |
+| `module` | `address` | No      | The address of the newly authorized module |
+
+### RegistryModuleRemoved
 
 ```solidity
-function setPool(
-    address localToken,
-    address pool
-) external onlyTokenAdmin(localToken)
+event RegistryModuleRemoved(address indexed module);
 ```
 
-Sets or changes the pool for a token. Only callable by the token's administrator.
+<Aside>Emitted when a registry module is deauthorized.</Aside>
 
-<Aside type="note">Setting the pool to address(0) effectively disables the token for CCIP transfers.</Aside>
+**Parameters**
 
-#### Parameters
+| Name     | Type      | Indexed | Description                       |
+| -------- | --------- | ------- | --------------------------------- |
+| `module` | `address` | Yes     | The address of the removed module |
 
-| Name       | Type    | Description                                |
-| ---------- | ------- | ------------------------------------------ |
-| localToken | address | Token to configure                         |
-| pool       | address | New pool address, or address(0) to disable |
+## Errors
 
-### transferAdminRole
+### AddressZero
 
 ```solidity
-function transferAdminRole(
-    address localToken,
-    address newAdmin
-) external onlyTokenAdmin(localToken)
+error ZeroAddress();
 ```
 
-Initiates the transfer of administrator rights to a new address.
+<Aside>Thrown when attempting to use address(0) where not allowed.</Aside>
 
-<Aside type="note">
-  This is step 1 of a 2-step process. The new admin must call acceptAdminRole to complete the transfer.
-</Aside>
+### AlreadyRegistered
 
-#### Parameters
+```solidity
+error AlreadyRegistered(address token);
+```
 
-| Name       | Type    | Description                                                           |
-| ---------- | ------- | --------------------------------------------------------------------- |
-| localToken | address | Token whose administrator is being changed                            |
-| newAdmin   | address | Proposed new administrator (or address(0) to cancel pending transfer) |
+<Aside>Thrown when attempting to register an administrator for a token that already has one.</Aside>
 
-### acceptAdminRole
+**Parameters**
+
+| Name    | Type      | Description                                         |
+| ------- | --------- | --------------------------------------------------- |
+| `token` | `address` | The token address that already has an administrator |
+
+### InvalidTokenPoolToken
 
 ```solidity
-function acceptAdminRole(
-    address localToken
-) external
+error InvalidTokenPoolToken(address token);
 ```
 
-Completes the transfer of administrator rights. Must be called by the pending administrator.
+<Aside>Thrown when attempting to set a pool that doesn't support the token.</Aside>
 
-#### Parameters
+**Parameters**
 
-| Name       | Type    | Description                            |
-| ---------- | ------- | -------------------------------------- |
-| localToken | address | Token to accept administrator role for |
+| Name    | Type      | Description                                         |
+| ------- | --------- | --------------------------------------------------- |
+| `token` | `address` | The token address that is not supported by the pool |
 
-### isAdministrator
+### OnlyAdministrator
 
 ```solidity
-function isAdministrator(
-    address localToken,
-    address administrator
-) external view returns (bool)
+error OnlyAdministrator(address sender, address token);
 ```
 
-Checks if an address is the administrator for a token.
+<Aside>Thrown when a function restricted to the token administrator is called by another address.</Aside>
 
-#### Parameters
+**Parameters**
 
-| Name          | Type    | Description       |
-| ------------- | ------- | ----------------- |
-| localToken    | address | Token to check    |
-| administrator | address | Address to verify |
+| Name     | Type      | Description                       |
+| -------- | --------- | --------------------------------- |
+| `sender` | `address` | The unauthorized caller's address |
+| `token`  | `address` | The token address being accessed  |
 
-#### Return Value
+### OnlyPendingAdministrator
 
-| Type | Description                                      |
-| ---- | ------------------------------------------------ |
-| bool | True if the address is the token's administrator |
+```solidity
+error OnlyPendingAdministrator(address sender, address token);
+```
 
-### proposeAdministrator
+<Aside>Thrown when acceptAdminRole is called by an address other than the pending administrator.</Aside>
+
+**Parameters**
+
+| Name     | Type      | Description                       |
+| -------- | --------- | --------------------------------- |
+| `sender` | `address` | The unauthorized caller's address |
+| `token`  | `address` | The token address being accessed  |
+
+### OnlyRegistryModuleOrOwner
 
 ```solidity
-function proposeAdministrator(
-    address localToken,
-    address administrator
-) external
+error OnlyRegistryModuleOrOwner(address sender);
 ```
 
-Proposes an initial administrator for a token. Can only be called by registry modules or owner.
+<Aside>Thrown when a function restricted to registry modules or owner is called by another address.</Aside>
 
-<Aside type="caution">Will revert if the token already has an administrator.</Aside>
+**Parameters**
 
-#### Parameters
+| Name     | Type      | Description                       |
+| -------- | --------- | --------------------------------- |
+| `sender` | `address` | The unauthorized caller's address |
 
-| Name          | Type    | Description                    |
-| ------------- | ------- | ------------------------------ |
-| localToken    | address | Token to set administrator for |
-| administrator | address | Proposed administrator address |
+## Structs
 
-## Registry Module Management
+### TokenConfig
 
-### isRegistryModule
+Configuration data structure for each token.
 
 ```solidity
-function isRegistryModule(
-    address module
-) public view returns (bool)
+struct TokenConfig {
+  address administrator;
+  address pendingAdministrator;
+  address tokenPool;
+}
 ```
 
-Checks if an address is an authorized registry module.
+<Aside>
 
-#### Parameters
+Token configuration fields:
 
-| Name   | Type    | Description      |
-| ------ | ------- | ---------------- |
-| module | address | Address to check |
+- `administrator`: Current token administrator
+- `pendingAdministrator`: Address pending administrator role transfer
+- `tokenPool`: Associated token pool address (0 if delisted)
 
-#### Return Value
+</Aside>
 
-| Type | Description                                          |
-| ---- | ---------------------------------------------------- |
-| bool | True if the address is an authorized registry module |
+## State Variables
 
-### addRegistryModule
+### s_registryModules
 
 ```solidity
-function addRegistryModule(
-    address module
-) external onlyOwner
+EnumerableSet.AddressSet internal s_registryModules;
 ```
 
-Adds a new registry module. Only callable by owner.
-
-#### Parameters
+<Aside>Set of authorized registry modules that can register administrators.</Aside>
 
-| Name   | Type    | Description              |
-| ------ | ------- | ------------------------ |
-| module | address | Address of module to add |
-
-### removeRegistryModule
+### s_tokenConfig
 
 ```solidity
-function removeRegistryModule(
-    address module
-) external onlyOwner
+mapping(address token => TokenConfig) internal s_tokenConfig;
 ```
 
-Removes a registry module. Only callable by owner.
+<Aside>Stores configuration data for each token, including administrators and pool addresses.</Aside>
 
-#### Parameters
+### s_tokens
 
-| Name   | Type    | Description                 |
-| ------ | ------- | --------------------------- |
-| module | address | Address of module to remove |
+```solidity
+EnumerableSet.AddressSet internal s_tokens;
+```
+
+<Aside>Set of all configured tokens for efficient enumeration.</Aside>
 
 ### typeAndVersion
 
 ```solidity
-string public constant override typeAndVersion = "TokenAdminRegistry 1.5.0"
+string public constant override typeAndVersion = "TokenAdminRegistry 1.5.0";
 ```
 
-Returns the type and version of the contract.
-
-#### Return Value
-
-| Type   | Description                           |
-| ------ | ------------------------------------- |
-| string | The string "TokenAdminRegistry 1.5.0" |
+<Aside>Contract identifier that specifies the implementation version.</Aside>
diff --git a/src/content/ccip/api-reference/v1.5.1/token-pool.mdx b/src/content/ccip/api-reference/v1.5.1/token-pool.mdx
index a2a4511fe0d..3f491910342 100644
--- a/src/content/ccip/api-reference/v1.5.1/token-pool.mdx
+++ b/src/content/ccip/api-reference/v1.5.1/token-pool.mdx
@@ -11,349 +11,432 @@ import CcipCommon from "@features/ccip/CcipCommon.astro"
 
 <CcipCommon callout="importCCIPPackage151" />
 
-The [`TokenPool`](https://github.com/smartcontractkit/ccip/blob/release/contracts-ccip-1.5.1/contracts/src/v0.8/ccip/pools/TokenPool.sol) abstract contract provides base functionality for token pools in CCIP, handling cross-chain token transfers with decimal adjustments and rate limiting.
+## TokenPool
 
-<Aside type="caution">
-**Cross-Chain Token Decimal Precision**
+An abstract contract that provides base functionality for managing cross-chain token operations in CCIP. It handles token decimals across different chains, rate limiting, and access control.
 
-This pool handles tokens with different decimal places across chains. When transferring tokens between chains with different decimal precision:
+[Git Source](https://github.com/smartcontractkit/ccip/blob/0df0625eea603ba8572d5382d72979a7f2b12bfb/contracts/src/v0.8/ccip/pools/TokenPool.sol)
 
-1. Source Chain: The full amount is locked/burned with its original precision
-2. Destination Chain: The amount is adjusted to match the destination chain's decimal precision
-3. Impact: This adjustment can lead to a small loss of precision when:
-   - Transferring from higher precision to lower precision chains
-   - Transferring back to the original chain
+**Inherits:**
 
-For example:
+- [Ownable2StepMsgSender](/ccip/api-reference/v1.5.1/ownable-2-step-msg-sender)
 
-- Chain A: Token has 6 decimals
-- Chain B: Token has 3 decimals
-- Transfer 1.234567 tokens from A to B
+<Aside>
+This contract supports tokens with different decimals across chains. However, this feature can affect token precision:
 
-  - B can only represent 1.234 tokens
-  - When sending 1.234 back to A, you'll receive 1.234000 tokens
-  - The "lost" 0.000567 tokens:
+- When tokens move from a chain with higher decimals to one with lower decimals, rounding occurs
+- Example: Moving 1.234567 tokens (6 decimals) to a chain with 3 decimals results in 1.234 tokens
+- When these tokens return to the original chain, they maintain the rounded value (1.234000)
+- The difference (0.000567) is either burned or remains in the pool, depending on the pool type
 
-    - In a burnMint pool: Are permanently burned on Chain A
-    - In a lockRelease pool: Accumulate in the pool on Chain A
+Note: This precision loss only occurs with different decimal configurations across chains.
 
 </Aside>
 
-## Errors
+## Events
 
-### CallerIsNotARampOnRouter
+### AllowListAdd
+
+Emitted when an address is added to the allowlist via [`applyAllowListUpdates`](#applyallowlistupdates).
 
 ```solidity
-error CallerIsNotARampOnRouter(address caller)
+event AllowListAdd(address sender);
 ```
 
-Thrown when caller is not a valid ramp on router.
+**Parameters**
 
-### ZeroAddressNotAllowed
+| Name     | Type      | Indexed | Description                                 |
+| -------- | --------- | ------- | ------------------------------------------- |
+| `sender` | `address` | No      | The address that was added to the allowlist |
+
+### AllowListRemove
+
+Emitted when an address is removed from the allowlist via [`applyAllowListUpdates`](#applyallowlistupdates).
 
 ```solidity
-error ZeroAddressNotAllowed()
+event AllowListRemove(address sender);
 ```
 
-Thrown when a zero address is provided.
+**Parameters**
 
-### SenderNotAllowed
+| Name     | Type      | Indexed | Description                                     |
+| -------- | --------- | ------- | ----------------------------------------------- |
+| `sender` | `address` | No      | The address that was removed from the allowlist |
+
+### Burned
+
+Emitted when tokens are burned by the pool.
 
 ```solidity
-error SenderNotAllowed(address sender)
+event Burned(address indexed sender, uint256 amount);
 ```
 
-Thrown when sender is not on allowlist.
+**Parameters**
 
-### AllowListNotEnabled
+| Name     | Type      | Indexed | Description                               |
+| -------- | --------- | ------- | ----------------------------------------- |
+| `sender` | `address` | Yes     | The address initiating the burn operation |
+| `amount` | `uint256` | No      | The amount of tokens burned               |
+
+### ChainAdded
+
+Emitted when a new chain is configured in the pool via [`applyChainUpdates`](#applychainupdates).
 
 ```solidity
-error AllowListNotEnabled()
+event ChainAdded(
+  uint64 remoteChainSelector,
+  bytes remoteToken,
+  RateLimiter.Config outboundRateLimiterConfig,
+  RateLimiter.Config inboundRateLimiterConfig
+);
 ```
 
-Thrown when trying to use allowlist features while disabled.
+**Parameters**
 
-### NonExistentChain
+| Name                        | Type                                                                   | Indexed | Description                                     |
+| --------------------------- | ---------------------------------------------------------------------- | ------- | ----------------------------------------------- |
+| `remoteChainSelector`       | `uint64`                                                               | No      | The identifier of the newly added chain         |
+| `remoteToken`               | `bytes`                                                                | No      | The token address on the remote chain           |
+| `outboundRateLimiterConfig` | [`RateLimiter.Config`](/ccip/api-reference/v1.5.1/rate-limiter#config) | No      | Rate limit configuration for outbound transfers |
+| `inboundRateLimiterConfig`  | [`RateLimiter.Config`](/ccip/api-reference/v1.5.1/rate-limiter#config) | No      | Rate limit configuration for inbound transfers  |
+
+### ChainConfigured
+
+Emitted when a chain's configuration is updated via [`setChainRateLimiterConfig`](#setchainratelimiterconfig) or [`setChainRateLimiterConfigs`](#setchainratelimiterconfigs).
 
 ```solidity
-error NonExistentChain(uint64 remoteChainSelector)
+event ChainConfigured(
+  uint64 remoteChainSelector,
+  RateLimiter.Config outboundRateLimiterConfig,
+  RateLimiter.Config inboundRateLimiterConfig
+);
 ```
 
-Thrown when chain selector doesn't exist.
+**Parameters**
 
-### ChainNotAllowed
+| Name                        | Type                                                                   | Indexed | Description                                             |
+| --------------------------- | ---------------------------------------------------------------------- | ------- | ------------------------------------------------------- |
+| `remoteChainSelector`       | `uint64`                                                               | No      | The identifier of the chain being configured            |
+| `outboundRateLimiterConfig` | [`RateLimiter.Config`](/ccip/api-reference/v1.5.1/rate-limiter#config) | No      | Updated rate limit configuration for outbound transfers |
+| `inboundRateLimiterConfig`  | [`RateLimiter.Config`](/ccip/api-reference/v1.5.1/rate-limiter#config) | No      | Updated rate limit configuration for inbound transfers  |
+
+### ChainRemoved
+
+Emitted when a chain is removed from the pool's configuration via [`applyChainUpdates`](#applychainupdates).
 
 ```solidity
-error ChainNotAllowed(uint64 remoteChainSelector)
+event ChainRemoved(uint64 remoteChainSelector);
 ```
 
-Thrown when chain is not configured.
+**Parameters**
 
-### CursedByRMN
+| Name                  | Type     | Indexed | Description                               |
+| --------------------- | -------- | ------- | ----------------------------------------- |
+| `remoteChainSelector` | `uint64` | No      | The identifier of the chain being removed |
+
+### Locked
+
+Emitted when tokens are locked by the pool.
 
 ```solidity
-error CursedByRMN()
+event Locked(address indexed sender, uint256 amount);
 ```
 
-Thrown when RMN has cursed the operation.
+**Parameters**
 
-### ChainAlreadyExists
+| Name     | Type      | Indexed | Description                               |
+| -------- | --------- | ------- | ----------------------------------------- |
+| `sender` | `address` | Yes     | The address initiating the lock operation |
+| `amount` | `uint256` | No      | The amount of tokens locked               |
+
+### Minted
+
+Emitted when tokens are minted by the pool.
 
 ```solidity
-error ChainAlreadyExists(uint64 chainSelector)
+event Minted(address indexed sender, address indexed recipient, uint256 amount);
 ```
 
-Thrown when adding an existing chain.
+**Parameters**
 
-### InvalidSourcePoolAddress
+| Name        | Type      | Indexed | Description                               |
+| ----------- | --------- | ------- | ----------------------------------------- |
+| `sender`    | `address` | Yes     | The address initiating the mint operation |
+| `recipient` | `address` | Yes     | The address receiving the minted tokens   |
+| `amount`    | `uint256` | No      | The amount of tokens minted               |
+
+### RemotePoolAdded
+
+Emitted when a new remote pool is added via [`addRemotePool`](#addremotepool) or [`applyChainUpdates`](#applychainupdates).
 
 ```solidity
-error InvalidSourcePoolAddress(bytes sourcePoolAddress)
+event RemotePoolAdded(uint64 indexed remoteChainSelector, bytes remotePoolAddress);
 ```
 
-Thrown when source pool address is invalid.
+**Parameters**
 
-### InvalidToken
+| Name                  | Type     | Indexed | Description                                  |
+| --------------------- | -------- | ------- | -------------------------------------------- |
+| `remoteChainSelector` | `uint64` | Yes     | The identifier of the chain for the new pool |
+| `remotePoolAddress`   | `bytes`  | No      | The address of the newly added pool          |
+
+### Released
+
+Emitted when tokens are released by the pool.
 
 ```solidity
-error InvalidToken(address token)
+event Released(address indexed sender, address indexed recipient, uint256 amount);
 ```
 
-Thrown when token is not supported.
+**Parameters**
 
-### Unauthorized
+| Name        | Type      | Indexed | Description                                  |
+| ----------- | --------- | ------- | -------------------------------------------- |
+| `sender`    | `address` | Yes     | The address initiating the release operation |
+| `recipient` | `address` | Yes     | The address receiving the released tokens    |
+| `amount`    | `uint256` | No      | The amount of tokens released                |
+
+### RemotePoolRemoved
+
+Emitted when a remote pool is removed via [`removeRemotePool`](#removeremotepool).
 
 ```solidity
-error Unauthorized(address caller)
+event RemotePoolRemoved(uint64 indexed remoteChainSelector, bytes remotePoolAddress);
 ```
 
-Thrown when caller lacks required permissions.
+**Parameters**
 
-### PoolAlreadyAdded
+| Name                  | Type     | Indexed | Description                              |
+| --------------------- | -------- | ------- | ---------------------------------------- |
+| `remoteChainSelector` | `uint64` | Yes     | The identifier of the chain for the pool |
+| `remotePoolAddress`   | `bytes`  | No      | The address of the removed pool          |
+
+### RouterUpdated
+
+Emitted when the router address is updated via [`setRouter`](#setrouter).
 
 ```solidity
-error PoolAlreadyAdded(uint64 remoteChainSelector, bytes remotePoolAddress)
+event RouterUpdated(address oldRouter, address newRouter);
 ```
 
-Thrown when attempting to add an already existing pool.
+**Parameters**
 
-### InvalidRemotePoolForChain
+| Name        | Type      | Indexed | Description                          |
+| ----------- | --------- | ------- | ------------------------------------ |
+| `oldRouter` | `address` | No      | The previous router contract address |
+| `newRouter` | `address` | No      | The new router contract address      |
+
+### RateLimitAdminSet
+
+Emitted when the rate limit administrator is changed via [`setRateLimitAdmin`](#setratelimitadmin).
 
 ```solidity
-error InvalidRemotePoolForChain(uint64 remoteChainSelector, bytes remotePoolAddress)
+event RateLimitAdminSet(address rateLimitAdmin);
 ```
 
-Thrown when remote pool configuration is invalid for the specified chain.
+**Parameters**
 
-### InvalidRemoteChainDecimals
+| Name             | Type      | Indexed | Description                              |
+| ---------------- | --------- | ------- | ---------------------------------------- |
+| `rateLimitAdmin` | `address` | No      | The new rate limit administrator address |
+
+## Errors
+
+### AllowListNotEnabled
 
 ```solidity
-error InvalidRemoteChainDecimals(bytes sourcePoolData)
+error AllowListNotEnabled();
 ```
 
-Thrown when remote chain decimals data is invalid.
+<Aside>Thrown when attempting to modify the allowlist when the feature is disabled.</Aside>
 
-### OverflowDetected
+### CallerIsNotARampOnRouter
 
 ```solidity
-error OverflowDetected(uint8 remoteDecimals, uint8 localDecimals, uint256 remoteAmount)
+error CallerIsNotARampOnRouter(address caller);
 ```
 
-Thrown when decimal conversion would result in overflow.
+<Aside>Thrown when an unauthorized address attempts to act as an onRamp or offRamp.</Aside>
 
-### InvalidDecimalArgs
+### ChainAlreadyExists
 
 ```solidity
-error InvalidDecimalArgs(uint8 expected, uint8 actual)
+error ChainAlreadyExists(uint64 chainSelector);
 ```
 
-Thrown when provided decimal arguments don't match expected values.
+<Aside>Thrown when attempting to add a chain that is already configured.</Aside>
 
-## Events
+**Parameters**
 
-### Locked
+| Name            | Type     | Description                                   |
+| --------------- | -------- | --------------------------------------------- |
+| `chainSelector` | `uint64` | The selector of the chain that already exists |
+
+### ChainNotAllowed
 
 ```solidity
-event Locked(address indexed sender, uint256 amount)
+error ChainNotAllowed(uint64 remoteChainSelector);
 ```
 
-Emitted when tokens are locked in the pool.
-
-| Parameter | Type    | Description                     |
-| --------- | ------- | ------------------------------- |
-| sender    | address | Address that initiated the lock |
-| amount    | uint256 | Amount of tokens locked         |
+<Aside>Thrown when attempting to use a chain that is not authorized.</Aside>
 
-### Burned
+### CursedByRMN
 
 ```solidity
-event Burned(address indexed sender, uint256 amount)
+error CursedByRMN();
 ```
 
-Emitted when tokens are burned.
-
-| Parameter | Type    | Description                     |
-| --------- | ------- | ------------------------------- |
-| sender    | address | Address that initiated the burn |
-| amount    | uint256 | Amount of tokens burned         |
+<Aside>Thrown when the Risk Management Network has flagged operations as unsafe.</Aside>
 
-### Released
+### InvalidDecimalArgs
 
 ```solidity
-event Released(address indexed sender, address indexed recipient, uint256 amount)
+error InvalidDecimalArgs(uint8 expected, uint8 actual);
 ```
 
-Emitted when tokens are released from the pool.
+<Aside>Thrown when token decimals don't match the expected configuration.</Aside>
 
-| Parameter | Type    | Description                        |
-| --------- | ------- | ---------------------------------- |
-| sender    | address | Address that initiated the release |
-| recipient | address | Address receiving the tokens       |
-| amount    | uint256 | Amount of tokens released          |
+**Parameters**
 
-### Minted
+| Name       | Type    | Description                            |
+| ---------- | ------- | -------------------------------------- |
+| `expected` | `uint8` | The expected number of decimals        |
+| `actual`   | `uint8` | The actual number of decimals provided |
+
+### InvalidRemoteChainDecimals
 
 ```solidity
-event Minted(address indexed sender, address indexed recipient, uint256 amount)
+error InvalidRemoteChainDecimals(bytes sourcePoolData);
 ```
 
-Emitted when tokens are minted.
+<Aside>Thrown when the decimal configuration from a remote chain is invalid or malformed.</Aside>
 
-| Parameter | Type    | Description                         |
-| --------- | ------- | ----------------------------------- |
-| sender    | address | Address that initiated the mint     |
-| recipient | address | Address receiving the minted tokens |
-| amount    | uint256 | Amount of tokens minted             |
+**Parameters**
 
-### ChainAdded
+| Name             | Type    | Description                            |
+| ---------------- | ------- | -------------------------------------- |
+| `sourcePoolData` | `bytes` | The invalid decimal configuration data |
+
+### InvalidRemotePoolForChain
 
 ```solidity
-event ChainAdded(
-    uint64 remoteChainSelector,
-    bytes remoteToken,
-    RateLimiter.Config outboundRateLimiterConfig,
-    RateLimiter.Config inboundRateLimiterConfig
-)
+error InvalidRemotePoolForChain(uint64 remoteChainSelector, bytes remotePoolAddress);
 ```
 
-Emitted when a new chain is added to the pool.
+<Aside>Thrown when attempting to remove a pool that isn't configured for the specified chain.</Aside>
 
-| Parameter                 | Type               | Description                            |
-| ------------------------- | ------------------ | -------------------------------------- |
-| remoteChainSelector       | uint64             | Selector of the added chain            |
-| remoteToken               | bytes              | Address of token on remote chain       |
-| outboundRateLimiterConfig | RateLimiter.Config | Configuration for outbound rate limits |
-| inboundRateLimiterConfig  | RateLimiter.Config | Configuration for inbound rate limits  |
+**Parameters**
 
-### ChainConfigured
+| Name                  | Type     | Description                      |
+| --------------------- | -------- | -------------------------------- |
+| `remoteChainSelector` | `uint64` | The chain selector being queried |
+| `remotePoolAddress`   | `bytes`  | The invalid pool address         |
+
+### InvalidSourcePoolAddress
 
 ```solidity
-event ChainConfigured(
-    uint64 remoteChainSelector,
-    RateLimiter.Config outboundRateLimiterConfig,
-    RateLimiter.Config inboundRateLimiterConfig
-)
+error InvalidSourcePoolAddress(bytes sourcePoolAddress);
 ```
 
-Emitted when a chain's configuration is updated.
+<Aside>Thrown when attempting to use an unconfigured or invalid remote pool address.</Aside>
 
-| Parameter                 | Type               | Description                           |
-| ------------------------- | ------------------ | ------------------------------------- |
-| remoteChainSelector       | uint64             | Selector of the configured chain      |
-| outboundRateLimiterConfig | RateLimiter.Config | New outbound rate limit configuration |
-| inboundRateLimiterConfig  | RateLimiter.Config | New inbound rate limit configuration  |
-
-### ChainRemoved
+### InvalidToken
 
 ```solidity
-event ChainRemoved(uint64 remoteChainSelector)
+error InvalidToken(address token);
 ```
 
-Emitted when a chain is removed from the pool.
+<Aside>Thrown when attempting to operate with a token that is not supported by the pool.</Aside>
 
-| Parameter           | Type   | Description                   |
-| ------------------- | ------ | ----------------------------- |
-| remoteChainSelector | uint64 | Selector of the removed chain |
+**Parameters**
 
-### RemotePoolAdded
+| Name    | Type      | Description                      |
+| ------- | --------- | -------------------------------- |
+| `token` | `address` | The address of the invalid token |
+
+### MismatchedArrayLengths
 
 ```solidity
-event RemotePoolAdded(uint64 indexed remoteChainSelector, bytes remotePoolAddress)
+error MismatchedArrayLengths();
 ```
 
-Emitted when a remote pool is added.
+<Aside>Thrown when array parameters have different lengths in multi-chain operations.</Aside>
 
-| Parameter           | Type   | Description                        |
-| ------------------- | ------ | ---------------------------------- |
-| remoteChainSelector | uint64 | Chain selector for the remote pool |
-| remotePoolAddress   | bytes  | Address of the added remote pool   |
+### NonExistentChain
 
-### RemotePoolRemoved
+```solidity
+error NonExistentChain(uint64 remoteChainSelector);
+```
+
+<Aside>Thrown when attempting to operate with an unconfigured chain.</Aside>
+
+### OverflowDetected
 
 ```solidity
-event RemotePoolRemoved(uint64 indexed remoteChainSelector, bytes remotePoolAddress)
+error OverflowDetected(uint8 remoteDecimals, uint8 localDecimals, uint256 remoteAmount);
 ```
 
-Emitted when a remote pool is removed.
+<Aside>Thrown when a token amount conversion would result in an arithmetic overflow.</Aside>
 
-| Parameter           | Type   | Description                        |
-| ------------------- | ------ | ---------------------------------- |
-| remoteChainSelector | uint64 | Chain selector for the remote pool |
-| remotePoolAddress   | bytes  | Address of the removed remote pool |
+**Parameters**
 
-### AllowListAdd
+| Name             | Type      | Description                         |
+| ---------------- | --------- | ----------------------------------- |
+| `remoteDecimals` | `uint8`   | The decimals on the remote chain    |
+| `localDecimals`  | `uint8`   | The decimals on the local chain     |
+| `remoteAmount`   | `uint256` | The amount that caused the overflow |
+
+### PoolAlreadyAdded
 
 ```solidity
-event AllowListAdd(address sender)
+error PoolAlreadyAdded(uint64 remoteChainSelector, bytes remotePoolAddress);
 ```
 
-Emitted when an address is added to the allowlist.
+<Aside>Thrown when attempting to add a pool that is already configured for a chain.</Aside>
 
-| Parameter | Type    | Description                |
-| --------- | ------- | -------------------------- |
-| sender    | address | Address added to allowlist |
+**Parameters**
 
-### AllowListRemove
+| Name                  | Type     | Description                              |
+| --------------------- | -------- | ---------------------------------------- |
+| `remoteChainSelector` | `uint64` | The chain selector where the pool exists |
+| `remotePoolAddress`   | `bytes`  | The address of the already existing pool |
+
+### SenderNotAllowed
 
 ```solidity
-event AllowListRemove(address sender)
+error SenderNotAllowed(address sender);
 ```
 
-Emitted when an address is removed from the allowlist.
-
-| Parameter | Type    | Description                    |
-| --------- | ------- | ------------------------------ |
-| sender    | address | Address removed from allowlist |
+<Aside>Thrown when a non-allowlisted address attempts an operation in allowlist mode.</Aside>
 
-### RouterUpdated
+### Unauthorized
 
 ```solidity
-event RouterUpdated(address oldRouter, address newRouter)
+error Unauthorized(address caller);
 ```
 
-Emitted when the router address is updated.
+<Aside>Thrown when a caller lacks the required permissions for an operation.</Aside>
 
-| Parameter | Type    | Description             |
-| --------- | ------- | ----------------------- |
-| oldRouter | address | Previous router address |
-| newRouter | address | New router address      |
+**Parameters**
 
-### RateLimitAdminSet
+| Name     | Type      | Description                           |
+| -------- | --------- | ------------------------------------- |
+| `caller` | `address` | The address that attempted the action |
+
+### ZeroAddressNotAllowed
 
 ```solidity
-event RateLimitAdminSet(address rateLimitAdmin)
+error ZeroAddressNotAllowed();
 ```
 
-Emitted when the rate limit admin is set.
-
-| Parameter      | Type    | Description                  |
-| -------------- | ------- | ---------------------------- |
-| rateLimitAdmin | address | New rate limit admin address |
+<Aside>Thrown when attempting to use address(0) for critical contract addresses.</Aside>
 
 ## Structs
 
 ### ChainUpdate
 
+Configuration data for adding or updating a chain.
+
 ```solidity
 struct ChainUpdate {
   uint64 remoteChainSelector;
@@ -364,667 +447,964 @@ struct ChainUpdate {
 }
 ```
 
-| Field                     | Type               | Description                                        |
-| ------------------------- | ------------------ | -------------------------------------------------- |
-| remoteChainSelector       | uint64             | Remote chain selector                              |
-| remotePoolAddresses       | bytes[]            | Remote pool addresses (ABI encoded for EVM chains) |
-| remoteTokenAddress        | bytes              | Remote token address (ABI encoded for EVM chains)  |
-| outboundRateLimiterConfig | RateLimiter.Config | Rate limits for onRamps                            |
-| inboundRateLimiterConfig  | RateLimiter.Config | Rate limits for offRamps                           |
+<Aside>
 
-## Functions
+Fields:
 
-### constructor
+- `remoteChainSelector`: Chain identifier
+- `remotePoolAddresses`: List of authorized pool addresses on the
+  remote chain
+- `remoteTokenAddress`: Token address on the remote chain
+- `outboundRateLimiterConfig`: Rate limits for
+  sending tokens to this chain
+- `inboundRateLimiterConfig`: Rate limits for receiving tokens from this chain
+
+</Aside>
+
+### RemoteChainConfig
+
+Internal configuration for a remote chain.
 
 ```solidity
-constructor(
-    IERC20 token,
-    uint8 localTokenDecimals,
-    address[] memory allowlist,
-    address rmnProxy,
-    address router
-)
+struct RemoteChainConfig {
+  RateLimiter.TokenBucket outboundRateLimiterConfig;
+  RateLimiter.TokenBucket inboundRateLimiterConfig;
+  bytes remoteTokenAddress;
+  EnumerableSet.Bytes32Set remotePools;
+}
 ```
 
-Initializes the token pool with the specified parameters.
+<Aside>
+
+Fields:
+
+- `outboundRateLimiterConfig`: Active rate limiter for sending tokens
+- `inboundRateLimiterConfig`: Active rate limiter for receiving tokens
+- `remoteTokenAddress`: Token address on the remote chain
+- `remotePools`: Set of authorized pool addresses (stored as hashes)
+
+</Aside>
 
-#### Parameters
+## State Variables
 
-| Name               | Type      | Description                                                                                                                                                              |
-| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| token              | IERC20    | The token managed by this pool                                                                                                                                           |
-| localTokenDecimals | uint8     | The number of decimals for the token on the local chain                                                                                                                  |
-| allowlist          | address[] | List of addresses allowed to be original senders for token transfers. When allowlist is enabled, it ensures only token-developer specified addresses can transfer tokens |
-| rmnProxy           | address   | Address of the RMN proxy                                                                                                                                                 |
-| router             | address   | Address of the router                                                                                                                                                    |
+### i_token
 
-### Chain Management
+The token managed by this pool. Currently supports one token per pool.
 
 ```solidity
-function applyChainUpdates(
-    uint64[] calldata remoteChainSelectorsToRemove,
-    ChainUpdate[] calldata chainsToAdd
-) external onlyOwner
+IERC20 internal immutable i_token;
 ```
 
-Updates supported chains and their configurations.
+### i_tokenDecimals
 
-### Rate Limiting
+The number of decimals for the managed token.
 
 ```solidity
-function setChainRateLimiterConfig(
-    uint64 remoteChainSelector,
-    RateLimiter.Config memory outboundConfig,
-    RateLimiter.Config memory inboundConfig
-) external
+uint8 internal immutable i_tokenDecimals;
 ```
 
-Sets rate limiting configuration for a chain.
-
-<Aside type="note">
-  Inbound rate limits should be slightly higher than outbound limits to handle batch processing: - Chains finalize
-  blocks in batches - CCIP commits messages in batches - A 5-10% buffer is recommended
-</Aside>
+### i_rmnProxy
 
-### Validation
+The Risk Management Network (RMN) proxy address.
 
 ```solidity
-function _validateLockOrBurn(
-    Pool.LockOrBurnInV1 calldata lockOrBurnIn
-) internal
+address internal immutable i_rmnProxy;
 ```
 
-Validates lock/burn operations for:
-
-- Token validity
-- RMN curse status
-- Allowlist status
-- OnRamp validity
-- Rate limits
+### i_allowlistEnabled
 
-### Decimal Handling
+Flag indicating if the pool uses access control.
 
 ```solidity
-function _calculateLocalAmount(
-    uint256 remoteAmount,
-    uint8 remoteDecimals
-) internal view returns (uint256)
+bool internal immutable i_allowlistEnabled;
 ```
 
-Calculates local token amounts based on remote amounts and decimals, with overflow protection.
+### s_allowlist
 
-### Token Management
+Set of addresses authorized to initiate cross-chain operations.
 
-### isSupportedToken
+<Aside>Only active when i_allowlistEnabled is true. Used to restrict token movements to authorized addresses.</Aside>
 
 ```solidity
-function isSupportedToken(
-    address token
-) public view virtual returns (bool)
+EnumerableSet.AddressSet internal s_allowlist;
 ```
 
-Checks if the given token is supported by this pool.
-
-#### Parameters
+### s_router
 
-| Name  | Type    | Description               |
-| ----- | ------- | ------------------------- |
-| token | address | Address of token to check |
+The CCIP Router contract address.
 
-#### Return Value
+```solidity
+IRouter internal s_router;
+```
 
-| Type | Description                |
-| ---- | -------------------------- |
-| bool | True if token is supported |
+### s_remoteChainSelectors
 
-### getToken
+Set of authorized chain selectors for cross-chain operations.
 
 ```solidity
-function getToken() public view returns (IERC20 token)
+EnumerableSet.UintSet internal s_remoteChainSelectors;
 ```
 
-Gets the IERC20 token that this pool can lock or burn.
+### s_remoteChainConfigs
 
-#### Return Value
+Configuration for each remote chain, including rate limits and token details.
 
-| Type   | Description                    |
-| ------ | ------------------------------ |
-| IERC20 | The token managed by this pool |
+```solidity
+mapping(uint64 remoteChainSelector => RemoteChainConfig) internal s_remoteChainConfigs;
+```
 
-### Router Management
+### s_remotePoolAddresses
 
-### getRmnProxy
+Maps hashed pool addresses to their original form for verification.
 
 ```solidity
-function getRmnProxy() public view returns (address rmnProxy)
+mapping(bytes32 poolAddressHash => bytes poolAddress) internal s_remotePoolAddresses;
 ```
 
-Gets the RMN proxy address.
+### s_rateLimitAdmin
 
-#### Return Value
+The address authorized to manage rate limits.
 
-| Type    | Description          |
-| ------- | -------------------- |
-| address | Address of RMN proxy |
+```solidity
+address internal s_rateLimitAdmin;
+```
 
-### getRouter
+## Functions
+
+### \_applyAllowListUpdates
+
+Internal version of applyAllowListUpdates to allow for reuse in the constructor.
 
 ```solidity
-function getRouter() public view returns (address router)
+function _applyAllowListUpdates(address[] memory removes, address[] memory adds) internal;
 ```
 
-Gets the pool's Router address.
+<Aside>
 
-#### Return Value
+Updates the allowlist by removing and adding addresses in a single operation.
+Only callable when allowlist is enabled (i_allowlistEnabled = true).
 
-| Type    | Description               |
-| ------- | ------------------------- |
-| address | The pool's Router address |
+Emits:
 
-### setRouter
+- AllowListAdd for each successfully added address
+- AllowListRemove for each successfully removed address
+
+</Aside>
+
+**Parameters**
+
+| Name      | Type        | Description                                     |
+| --------- | ----------- | ----------------------------------------------- |
+| `removes` | `address[]` | Array of addresses to remove from the allowlist |
+| `adds`    | `address[]` | Array of addresses to add to the allowlist      |
+
+### \_calculateLocalAmount
+
+Calculates the local amount based on the remote amount and decimals.
+
+_This function protects against overflows. If there is a transaction that hits the overflow check, it is
+probably incorrect as that means the amount cannot be represented on this chain. If the local decimals have been
+wrongly configured, the token issuer could redeploy the pool with the correct decimals and manually re-execute the
+CCIP tx to fix the issue._
 
 ```solidity
-function setRouter(
-    address newRouter
-) public onlyOwner
+function _calculateLocalAmount(uint256 remoteAmount, uint8 remoteDecimals) internal view virtual returns (uint256);
 ```
 
-Sets the pool's Router address.
+**Parameters**
 
-#### Parameters
+| Name             | Type      | Description                                    |
+| ---------------- | --------- | ---------------------------------------------- |
+| `remoteAmount`   | `uint256` | The amount on the remote chain.                |
+| `remoteDecimals` | `uint8`   | The decimals of the token on the remote chain. |
 
-| Name      | Type    | Description            |
-| --------- | ------- | ---------------------- |
-| newRouter | address | The new Router address |
+**Returns**
 
-### Interface Support
+| Name     | Type      | Description       |
+| -------- | --------- | ----------------- |
+| `<none>` | `uint256` | The local amount. |
 
-### supportsInterface
+### \_checkAllowList
+
+Internal function to verify if a sender is authorized when allowlist is enabled.
 
 ```solidity
-function supportsInterface(
-    bytes4 interfaceId
-) public pure virtual override returns (bool)
+function _checkAllowList(address sender) internal view;
 ```
 
-Signals which version of the pool interface is supported.
+<Aside>
+
+Performs access control validation based on the i_allowlistEnabled flag:
 
-#### Parameters
+- If allowlist is disabled (i_allowlistEnabled = false), returns without checks
+- If allowlist is enabled, verifies sender is in s_allowlist
 
-| Name        | Type   | Description                   |
-| ----------- | ------ | ----------------------------- |
-| interfaceId | bytes4 | Interface identifier to check |
+Reverts with [`SenderNotAllowed`](#sendernotallowed) if:
 
-#### Return Value
+- Allowlist is enabled
+- Sender is not in the allowlist
 
-| Type | Description                    |
-| ---- | ------------------------------ |
-| bool | True if interface is supported |
+</Aside>
 
-### Validation Functions
+**Parameters**
 
-### \_validateLockOrBurn
+| Name     | Type      | Description                         |
+| -------- | --------- | ----------------------------------- |
+| `sender` | `address` | The address to check for permission |
+
+### \_consumeInboundRateLimit
+
+Internal function to consume rate limiting capacity for incoming transfers.
 
 ```solidity
-function _validateLockOrBurn(
-    Pool.LockOrBurnInV1 calldata lockOrBurnIn
-) internal
+function _consumeInboundRateLimit(uint64 remoteChainSelector, uint256 amount) internal;
 ```
 
-Validates lock or burn operations for security and configuration requirements.
+<Aside>
+
+Uses token bucket algorithm to manage rate limits:
+
+- Updates token bucket state based on elapsed time
+- Validates if requested amount can be consumed
+- Reduces available capacity by the consumed amount
+
+Reverts if:
+
+- Requested amount exceeds current capacity
+- Rate limiting is enabled and limits are exceeded
 
-<Aside type="caution">
-  This function should always be called before executing a lock or burn operation to prevent exploits.
 </Aside>
 
-#### Parameters
+**Parameters**
 
-| Name         | Type                | Description                                  |
-| ------------ | ------------------- | -------------------------------------------- |
-| lockOrBurnIn | Pool.LockOrBurnInV1 | Input parameters for the lock/burn operation |
+| Name                  | Type      | Description                             |
+| --------------------- | --------- | --------------------------------------- |
+| `remoteChainSelector` | `uint64`  | The chain selector for the source chain |
+| `amount`              | `uint256` | The amount of tokens being transferred  |
 
-### \_validateReleaseOrMint
+### \_consumeOutboundRateLimit
+
+Internal function to consume rate limiting capacity for outgoing transfers.
 
 ```solidity
-function _validateReleaseOrMint(
-    Pool.ReleaseOrMintInV1 calldata releaseOrMintIn
-) internal
+function _consumeOutboundRateLimit(uint64 remoteChainSelector, uint256 amount) internal;
 ```
 
-Validates release or mint operations for security and configuration requirements.
+<Aside>
+
+Uses token bucket algorithm to manage rate limits:
+
+- Updates token bucket state based on elapsed time
+- Validates if requested amount can be consumed
+- Reduces available capacity by the consumed amount
+
+Reverts if:
+
+- Requested amount exceeds current capacity
+- Rate limiting is enabled and limits are exceeded
 
-<Aside type="caution">
-  This function should always be called before executing a release or mint operation to prevent exploits.
 </Aside>
 
-#### Parameters
+**Parameters**
 
-| Name            | Type                   | Description                                     |
-| --------------- | ---------------------- | ----------------------------------------------- |
-| releaseOrMintIn | Pool.ReleaseOrMintInV1 | Input parameters for the release/mint operation |
+| Name                  | Type      | Description                                  |
+| --------------------- | --------- | -------------------------------------------- |
+| `remoteChainSelector` | `uint64`  | The chain selector for the destination chain |
+| `amount`              | `uint256` | The amount of tokens being transferred       |
 
-### Token Decimals Functions
+### \_encodeLocalDecimals
 
-### getTokenDecimals
+Internal function to encode the local token's decimals for cross-chain communication.
 
 ```solidity
-function getTokenDecimals() public view virtual returns (uint8 decimals)
+function _encodeLocalDecimals() internal view virtual returns (bytes memory);
 ```
 
-Gets the IERC20 token decimals on the local chain.
+<Aside>
+  Used when communicating token decimal information to other chains. The encoding format ensures compatibility across
+  different chains.
+</Aside>
 
-#### Return Value
+**Returns**
 
-| Type  | Description                            |
-| ----- | -------------------------------------- |
-| uint8 | Number of decimals for the local token |
+| Type    | Description                                   |
+| ------- | --------------------------------------------- |
+| `bytes` | ABI-encoded decimal places of the local token |
 
-### \_encodeLocalDecimals
+### \_onlyOffRamp
+
+Checks whether remote chain selector is configured on this contract, and if the msg.sender
+is a permissioned offRamp for the given chain on the Router.
 
 ```solidity
-function _encodeLocalDecimals() internal view virtual returns (bytes memory)
+function _onlyOffRamp(uint64 remoteChainSelector) internal view;
 ```
 
-Encodes the local token decimals for cross-chain communication.
+<Aside>
 
-#### Return Value
+Critical security check that validates:
 
-| Type  | Description                      |
-| ----- | -------------------------------- |
-| bytes | ABI-encoded local token decimals |
+- Chain selector is configured in the pool
+- Caller is registered as an offRamp in the Router contract
+- Chain is active and allowed for transfers
 
-### \_parseRemoteDecimals
+Reverts with:
+
+- [`ChainNotAllowed`](#chainnotallowed) if the chain is not configured
+- [`CallerIsNotARampOnRouter`](#callerisnotaramponrouter) if the caller is not an authorized offRamp
+
+</Aside>
+
+**Parameters**
+
+| Name                  | Type     | Description                                      |
+| --------------------- | -------- | ------------------------------------------------ |
+| `remoteChainSelector` | `uint64` | The chain selector to validate authorization for |
+
+### \_onlyOnRamp
+
+Checks whether remote chain selector is configured on this contract, and if the msg.sender
+is a permissioned onRamp for the given chain on the Router.
 
 ```solidity
-function _parseRemoteDecimals(
-    bytes memory sourcePoolData
-) internal view virtual returns (uint8)
+function _onlyOnRamp(uint64 remoteChainSelector) internal view;
 ```
 
-Parses the remote chain's token decimals from the source pool data.
+<Aside>
 
-#### Parameters
+Critical security check that validates:
 
-| Name           | Type  | Description                   |
-| -------------- | ----- | ----------------------------- |
-| sourcePoolData | bytes | Encoded data from source pool |
+- Chain selector is configured in the pool
+- Caller is the designated onRamp in the Router contract
+- Chain is active and allowed for transfers
 
-#### Return Value
+Reverts with:
 
-| Type  | Description                        |
-| ----- | ---------------------------------- |
-| uint8 | Number of decimals on remote chain |
+- [`ChainNotAllowed`](#chainnotallowed) if the chain is not configured
+- [`CallerIsNotARampOnRouter`](#callerisnotaramponrouter) if the caller is not the authorized onRamp
 
-### \_calculateLocalAmount
+</Aside>
+
+**Parameters**
+
+| Name                  | Type     | Description                                      |
+| --------------------- | -------- | ------------------------------------------------ |
+| `remoteChainSelector` | `uint64` | The chain selector to validate authorization for |
+
+### \_parseRemoteDecimals
+
+Internal function to decode the decimal configuration received from a remote chain.
 
 ```solidity
-function _calculateLocalAmount(
-    uint256 remoteAmount,
-    uint8 remoteDecimals
-) internal view virtual returns (uint256)
+function _parseRemoteDecimals(bytes memory sourcePoolData) internal view virtual returns (uint8);
 ```
 
-Calculates the local amount based on remote amount and decimals.
+<Aside>
+
+- Falls back to local token decimals if source pool data is empty (for backward compatibility)
+- Validates that the decoded value is within uint8 range
+- Expects the data to be ABI-encoded uint256 that fits in uint8
+
+Reverts with [`InvalidRemoteChainDecimals`](#invalidremotechaindecimals) if:
+
+- Data length is not 32 bytes (invalid ABI encoding)
+- Decoded value exceeds uint8 range
 
-<Aside type="caution">
-  This function includes overflow protection. If a transaction hits the overflow check, the amount likely cannot be
-  represented on this chain.
 </Aside>
 
-#### Parameters
+**Parameters**
 
-| Name           | Type    | Description                       |
-| -------------- | ------- | --------------------------------- |
-| remoteAmount   | uint256 | Amount on remote chain            |
-| remoteDecimals | uint8   | Decimals of token on remote chain |
+| Name             | Type    | Description                            |
+| ---------------- | ------- | -------------------------------------- |
+| `sourcePoolData` | `bytes` | The encoded decimal configuration data |
 
-#### Return Value
+**Returns**
 
-| Type    | Description                     |
-| ------- | ------------------------------- |
-| uint256 | Adjusted amount for local chain |
+| Type    | Description                                     |
+| ------- | ----------------------------------------------- |
+| `uint8` | The number of decimals used on the remote chain |
 
-### Chain Permissions Functions
+### \_setRateLimitConfig
 
-### getRemotePools
+Internal function to update rate limit configuration for a chain.
 
 ```solidity
-function getRemotePools(
-    uint64 remoteChainSelector
-) public view returns (bytes[] memory)
+function _setRateLimitConfig(
+  uint64 remoteChainSelector,
+  RateLimiter.Config memory outboundConfig,
+  RateLimiter.Config memory inboundConfig
+) internal;
 ```
 
-Gets the pool addresses on the remote chain.
+<Aside>
 
-#### Parameters
+- Validates that the chain exists
+- Validates both rate limit configurations
+- Updates both inbound and outbound rate
+  limits
+- Emits [`ChainConfigured`](#chainconfigured) event
 
-| Name                | Type   | Description           |
-| ------------------- | ------ | --------------------- |
-| remoteChainSelector | uint64 | Remote chain selector |
+</Aside>
 
-#### Return Value
+**Parameters**
 
-| Type    | Description                    |
-| ------- | ------------------------------ |
-| bytes[] | Array of remote pool addresses |
+| Name                  | Type                 | Description                                     |
+| --------------------- | -------------------- | ----------------------------------------------- |
+| `remoteChainSelector` | `uint64`             | The chain selector to configure                 |
+| `outboundConfig`      | `RateLimiter.Config` | Rate limit configuration for outgoing transfers |
+| `inboundConfig`       | `RateLimiter.Config` | Rate limit configuration for incoming transfers |
 
-### isRemotePool
+### \_setRemotePool
+
+Internal function to add a pool address to the allowed remote token pools for a chain. Called during chain configuration and when adding individual remote pools.
 
 ```solidity
-function isRemotePool(
-    uint64 remoteChainSelector,
-    bytes calldata remotePoolAddress
-) public view returns (bool)
+function _setRemotePool(uint64 remoteChainSelector, bytes memory remotePoolAddress) internal;
 ```
 
-Checks if a pool address is configured on the remote chain.
+<Aside>
 
-#### Parameters
+The pool address is stored both as a hash for efficient lookups and in its original form for retrieval.
 
-| Name                | Type   | Description           |
-| ------------------- | ------ | --------------------- |
-| remoteChainSelector | uint64 | Remote chain selector |
-| remotePoolAddress   | bytes  | Address to check      |
+Reverts with:
 
-#### Return Value
+- [`ZeroAddressNotAllowed`](#zeroaddressnotallowed) if the pool address is empty
+- [`PoolAlreadyAdded`](#poolalreadyadded) if the pool is already configured for this chain
 
-| Type | Description                |
-| ---- | -------------------------- |
-| bool | True if pool is configured |
+Emits [`RemotePoolAdded`](#remotepooladded) when the pool is successfully added.
 
-### getRemoteToken
+</Aside>
+
+**Parameters**
+
+| Name                  | Type     | Description                                                        |
+| --------------------- | -------- | ------------------------------------------------------------------ |
+| `remoteChainSelector` | `uint64` | The chain selector to add the pool for                             |
+| `remotePoolAddress`   | `bytes`  | The address of the remote pool (encoded to support non-EVM chains) |
+
+### \_validateLockOrBurn
+
+Internal function to validate lock or burn operations.
 
 ```solidity
-function getRemoteToken(
-    uint64 remoteChainSelector
-) public view returns (bytes memory)
+function _validateLockOrBurn(Pool.LockOrBurnInV1 calldata lockOrBurnIn) internal;
 ```
 
-Gets the token address on the remote chain.
+<Aside>
+  
+Validates:
 
-#### Parameters
+- Token is supported
+- RMN status is safe
+- Sender is allowlisted (if enabled)
+- Caller is authorized onRamp
+- Rate limits are not exceeded
 
-| Name                | Type   | Description           |
-| ------------------- | ------ | --------------------- |
-| remoteChainSelector | uint64 | Remote chain selector |
+</Aside>
 
-#### Return Value
+### \_validateReleaseOrMint
 
-| Type  | Description                  |
-| ----- | ---------------------------- |
-| bytes | Encoded remote token address |
+Internal function to validate release or mint operations.
+
+```solidity
+function _validateReleaseOrMint(Pool.ReleaseOrMintInV1 calldata releaseOrMintIn) internal;
+```
+
+<Aside>
+
+Validates:
+
+- Token is supported
+- RMN status is safe
+- Caller is authorized offRamp
+- Source pool is valid
+- Rate limits are not exceeded
+
+</Aside>
 
 ### addRemotePool
 
+Adds a new pool address for a remote chain.
+
 ```solidity
-function addRemotePool(
-    uint64 remoteChainSelector,
-    bytes calldata remotePoolAddress
-) external onlyOwner
+function addRemotePool(uint64 remoteChainSelector, bytes calldata remotePoolAddress) external onlyOwner;
 ```
 
-Adds a remote pool for a given chain selector. Useful when a pool is upgraded on the remote chain.
+<Aside>
 
-#### Parameters
+- Only callable by owner
+- Allows multiple pools per chain for upgrades
+- Previous pools remain valid for inflight messages
 
-| Name                | Type   | Description                |
-| ------------------- | ------ | -------------------------- |
-| remoteChainSelector | uint64 | Remote chain selector      |
-| remotePoolAddress   | bytes  | Address of new remote pool |
+</Aside>
 
-### removeRemotePool
+### applyAllowListUpdates
+
+Apply updates to the allow list.
 
 ```solidity
-function removeRemotePool(
-    uint64 remoteChainSelector,
-    bytes calldata remotePoolAddress
-) external onlyOwner
+function applyAllowListUpdates(address[] calldata removes, address[] calldata adds) external onlyOwner;
 ```
 
-Removes a remote pool address for a given chain selector.
+**Parameters**
 
-<Aside type="caution">
-  All inflight transactions from the remote pool will be rejected after removal. Ensure no inflight transactions exist
-  before removing.
-</Aside>
+| Name      | Type        | Description                  |
+| --------- | ----------- | ---------------------------- |
+| `removes` | `address[]` | The addresses to be removed. |
+| `adds`    | `address[]` | The addresses to be added.   |
 
-#### Parameters
+### applyChainUpdates
 
-| Name                | Type   | Description               |
-| ------------------- | ------ | ------------------------- |
-| remoteChainSelector | uint64 | Remote chain selector     |
-| remotePoolAddress   | bytes  | Address of pool to remove |
+Updates chain configurations in bulk.
 
-### Chain Support Functions
+```solidity
+function applyChainUpdates(
+  uint64[] calldata remoteChainSelectorsToRemove,
+  ChainUpdate[] calldata chainsToAdd
+) external virtual onlyOwner;
+```
 
-### isSupportedChain
+<Aside>
+
+Allows:
+
+- Removing existing chains
+- Adding new chains with rate limits
+- Updating chain configurations Only callable by owner.
+
+</Aside>
+
+### constructor
 
 ```solidity
-function isSupportedChain(
-    uint64 remoteChainSelector
-) public view returns (bool)
+constructor(IERC20 token, uint8 localTokenDecimals, address[] memory allowlist, address rmnProxy, address router);
 ```
 
-Checks if a chain is supported.
+<Aside>
 
-#### Parameters
+Performs initial setup:
 
-| Name                | Type   | Description             |
-| ------------------- | ------ | ----------------------- |
-| remoteChainSelector | uint64 | Chain selector to check |
+- Validates non-zero addresses for token, router, and RMN proxy
+- Verifies token decimals match if ERC20Metadata is supported
+- Initializes allowlist if provided
+- Sets up immutable contract references
 
-#### Return Value
+</Aside>
 
-| Type | Description                |
-| ---- | -------------------------- |
-| bool | True if chain is supported |
+**Parameters**
 
-### getSupportedChains
+| Name                 | Type        | Description                                  |
+| -------------------- | ----------- | -------------------------------------------- |
+| `token`              | `IERC20`    | The token to be managed by this pool         |
+| `localTokenDecimals` | `uint8`     | The token's decimal places on this chain     |
+| `allowlist`          | `address[]` | Initial set of authorized addresses (if any) |
+| `rmnProxy`           | `address`   | The Risk Management Network proxy address    |
+| `router`             | `address`   | The CCIP Router contract address             |
+
+### getAllowList
+
+Gets the allowed addresses.
 
 ```solidity
-function getSupportedChains() public view returns (uint64[] memory)
+function getAllowList() external view returns (address[] memory);
 ```
 
-Gets list of all supported chains.
+**Returns**
 
-#### Return Value
+| Name     | Type        | Description            |
+| -------- | ----------- | ---------------------- |
+| `<none>` | `address[]` | The allowed addresses. |
 
-| Type     | Description                        |
-| -------- | ---------------------------------- |
-| uint64[] | Array of supported chain selectors |
+### getAllowListEnabled
 
-### applyChainUpdates
+Returns whether allowlist functionality is active.
 
 ```solidity
-function applyChainUpdates(
-    uint64[] calldata remoteChainSelectorsToRemove,
-    ChainUpdate[] calldata chainsToAdd
-) external virtual onlyOwner
+function getAllowListEnabled() external view returns (bool);
 ```
 
-Updates chain permissions and configurations.
+**Returns**
 
-#### Parameters
+| Name     | Type   | Description                    |
+| -------- | ------ | ------------------------------ |
+| `<none>` | `bool` | true is enabled, false if not. |
 
-| Name                         | Type          | Description                           |
-| ---------------------------- | ------------- | ------------------------------------- |
-| remoteChainSelectorsToRemove | uint64[]      | Chain selectors to remove             |
-| chainsToAdd                  | ChainUpdate[] | New chains to add with configurations |
+### getCurrentInboundRateLimiterState
 
-### Rate Limiting Functions
+Returns the current state of inbound rate limiting for a chain.
 
-### setRateLimitAdmin
+```solidity
+function getCurrentInboundRateLimiterState(
+  uint64 remoteChainSelector
+) external view returns (RateLimiter.TokenBucket memory);
+```
+
+**Parameters**
+
+| Name                  | Type     | Description                                      |
+| --------------------- | -------- | ------------------------------------------------ |
+| `remoteChainSelector` | `uint64` | The chain selector to get rate limiter state for |
+
+**Returns**
+
+| Type                                                                             | Description                               |
+| -------------------------------------------------------------------------------- | ----------------------------------------- |
+| [`RateLimiter.TokenBucket`](/ccip/api-reference/v1.5.1/rate-limiter#tokenbucket) | Current state of the inbound rate limiter |
+
+### getCurrentOutboundRateLimiterState
+
+Returns the current state of outbound rate limiting for a chain.
 
 ```solidity
-function setRateLimitAdmin(
-    address rateLimitAdmin
-) external onlyOwner
+function getCurrentOutboundRateLimiterState(
+  uint64 remoteChainSelector
+) external view returns (RateLimiter.TokenBucket memory);
 ```
 
-Sets the rate limiter admin address.
+**Parameters**
+
+| Name                  | Type     | Description                                      |
+| --------------------- | -------- | ------------------------------------------------ |
+| `remoteChainSelector` | `uint64` | The chain selector to get rate limiter state for |
 
-#### Parameters
+**Returns**
 
-| Name           | Type    | Description                    |
-| -------------- | ------- | ------------------------------ |
-| rateLimitAdmin | address | New rate limiter admin address |
+| Type                                                                             | Description                                |
+| -------------------------------------------------------------------------------- | ------------------------------------------ |
+| [`RateLimiter.TokenBucket`](/ccip/api-reference/v1.5.1/rate-limiter#tokenbucket) | Current state of the outbound rate limiter |
 
 ### getRateLimitAdmin
 
+Returns the current rate limit administrator address.
+
+```solidity
+function getRateLimitAdmin() external view returns (address);
+```
+
+### getRemotePools
+
+Returns the configured pool addresses for a remote chain.
+
 ```solidity
-function getRateLimitAdmin() external view returns (address)
+function getRemotePools(uint64 remoteChainSelector) public view returns (bytes[] memory);
 ```
 
-Gets the rate limiter admin address.
+<Aside>Returns encoded addresses to support both EVM and non-EVM chains.</Aside>
 
-#### Return Value
+**Parameters**
 
-| Type    | Description                        |
-| ------- | ---------------------------------- |
-| address | Current rate limiter admin address |
+| Name                  | Type     | Description                 |
+| --------------------- | -------- | --------------------------- |
+| `remoteChainSelector` | `uint64` | The remote chain identifier |
 
-### getCurrentOutboundRateLimiterState
+**Returns**
+
+| Type      | Description                                     |
+| --------- | ----------------------------------------------- |
+| `bytes[]` | Array of encoded pool addresses on remote chain |
+
+### getRemoteToken
+
+Returns the token address on a remote chain.
 
 ```solidity
-function getCurrentOutboundRateLimiterState(
-    uint64 remoteChainSelector
-) external view returns (RateLimiter.TokenBucket memory)
+function getRemoteToken(uint64 remoteChainSelector) public view returns (bytes memory);
 ```
 
-Gets the current outbound token bucket state.
+<Aside>Returns encoded address to support both EVM and non-EVM chains.</Aside>
 
-#### Parameters
+**Parameters**
 
-| Name                | Type   | Description             |
-| ------------------- | ------ | ----------------------- |
-| remoteChainSelector | uint64 | Chain selector to check |
+| Name                  | Type     | Description                 |
+| --------------------- | -------- | --------------------------- |
+| `remoteChainSelector` | `uint64` | The remote chain identifier |
 
-#### Return Value
+**Returns**
 
-| Type                    | Description                |
-| ----------------------- | -------------------------- |
-| RateLimiter.TokenBucket | Current token bucket state |
+| Type    | Description                                   |
+| ------- | --------------------------------------------- |
+| `bytes` | The encoded token address on the remote chain |
 
-### getCurrentInboundRateLimiterState
+### getRmnProxy
+
+Returns the Risk Management Network proxy address.
 
 ```solidity
-function getCurrentInboundRateLimiterState(
-    uint64 remoteChainSelector
-) external view returns (RateLimiter.TokenBucket memory)
+function getRmnProxy() public view returns (address rmnProxy);
 ```
 
-Gets the current inbound token bucket state.
+**Returns**
 
-#### Parameters
+| Type      | Description                    |
+| --------- | ------------------------------ |
+| `address` | The RMN proxy contract address |
 
-| Name                | Type   | Description             |
-| ------------------- | ------ | ----------------------- |
-| remoteChainSelector | uint64 | Chain selector to check |
+### getRouter
 
-#### Return Value
+Returns the current router address.
 
-| Type                    | Description                |
-| ----------------------- | -------------------------- |
-| RateLimiter.TokenBucket | Current token bucket state |
+```solidity
+function getRouter() public view returns (address router);
+```
 
-### setChainRateLimiterConfig
+**Returns**
+
+| Type      | Description                      |
+| --------- | -------------------------------- |
+| `address` | The CCIP router contract address |
+
+### getSupportedChains
+
+Returns all configured chain selectors.
 
 ```solidity
-function setChainRateLimiterConfig(
-    uint64 remoteChainSelector,
-    RateLimiter.Config memory outboundConfig,
-    RateLimiter.Config memory inboundConfig
-) external
+function getSupportedChains() public view returns (uint64[] memory);
 ```
 
-Sets the chain rate limiter configuration.
+**Returns**
+
+| Type       | Description                         |
+| ---------- | ----------------------------------- |
+| `uint64[]` | Array of configured chain selectors |
 
-#### Parameters
+### getToken
+
+Returns the token managed by this pool.
+
+```solidity
+function getToken() public view returns (IERC20 token);
+```
 
-| Name                | Type               | Description                            |
-| ------------------- | ------------------ | -------------------------------------- |
-| remoteChainSelector | uint64             | Chain selector to configure            |
-| outboundConfig      | RateLimiter.Config | Configuration for outbound rate limits |
-| inboundConfig       | RateLimiter.Config | Configuration for inbound rate limits  |
+**Returns**
 
-### Access Control Functions
+| Type     | Description                |
+| -------- | -------------------------- |
+| `IERC20` | The token contract address |
 
-### \_onlyOnRamp
+### getTokenDecimals
+
+Returns the number of decimals for the managed token.
 
 ```solidity
-function _onlyOnRamp(
-    uint64 remoteChainSelector
-) internal view
+function getTokenDecimals() public view virtual returns (uint8 decimals);
 ```
 
-Validates that msg.sender is a permissioned onRamp for the given chain.
+**Returns**
 
-#### Parameters
+| Type    | Description                                |
+| ------- | ------------------------------------------ |
+| `uint8` | The number of decimal places for the token |
 
-| Name                | Type   | Description                |
-| ------------------- | ------ | -------------------------- |
-| remoteChainSelector | uint64 | Chain selector to validate |
+### isRemotePool
 
-### \_onlyOffRamp
+Verifies if a pool address is configured for a remote chain.
 
 ```solidity
-function _onlyOffRamp(
-    uint64 remoteChainSelector
-) internal view
+function isRemotePool(uint64 remoteChainSelector, bytes calldata remotePoolAddress) public view returns (bool);
 ```
 
-Validates that msg.sender is a permissioned offRamp for the given chain.
+**Parameters**
 
-#### Parameters
+| Name                  | Type     | Description                 |
+| --------------------- | -------- | --------------------------- |
+| `remoteChainSelector` | `uint64` | The remote chain identifier |
+| `remotePoolAddress`   | `bytes`  | The pool address to verify  |
 
-| Name                | Type   | Description                |
-| ------------------- | ------ | -------------------------- |
-| remoteChainSelector | uint64 | Chain selector to validate |
+**Returns**
 
-### Allowlist Functions
+| Type   | Description                                  |
+| ------ | -------------------------------------------- |
+| `bool` | True if the pool is configured for the chain |
 
-### getAllowListEnabled
+### isSupportedChain
+
+Checks if a chain is configured in the pool.
 
 ```solidity
-function getAllowListEnabled() external view returns (bool)
+function isSupportedChain(uint64 remoteChainSelector) public view returns (bool);
 ```
 
-Checks if allowlist functionality is enabled.
+**Returns**
 
-#### Return Value
+| Type   | Description                                 |
+| ------ | ------------------------------------------- |
+| `bool` | True if the chain is configured in the pool |
 
-| Type | Description                  |
-| ---- | ---------------------------- |
-| bool | True if allowlist is enabled |
+### isSupportedToken
 
-### getAllowList
+Checks if a given token is supported by this pool.
 
 ```solidity
-function getAllowList() external view returns (address[] memory)
+function isSupportedToken(address token) public view virtual returns (bool);
 ```
 
-Gets all allowed addresses.
+**Parameters**
 
-#### Return Value
+| Name    | Type      | Description                |
+| ------- | --------- | -------------------------- |
+| `token` | `address` | The token address to check |
 
-| Type      | Description                |
-| --------- | -------------------------- |
-| address[] | Array of allowed addresses |
+**Returns**
 
-### applyAllowListUpdates
+| Type   | Description                                 |
+| ------ | ------------------------------------------- |
+| `bool` | True if the token is supported by this pool |
+
+### removeRemotePool
+
+Removes a pool address from a remote chain's configuration.
 
 ```solidity
-function applyAllowListUpdates(
-    address[] calldata removes,
-    address[] calldata adds
-) external onlyOwner
+function removeRemotePool(uint64 remoteChainSelector, bytes calldata remotePoolAddress) external onlyOwner;
 ```
 
-Updates the allowlist by adding and removing addresses.
+<Aside type="caution">
+
+Ensure no inflight transactions exist before removal to prevent loss of funds.
+
+Reverts with:
+
+- [`NonExistentChain`](#nonexistentchain) if the chain is not configured
+- [`InvalidRemotePoolForChain`](#invalidremotepoolforchain) if the pool is not configured for the chain
+
+Emits [`RemotePoolRemoved`](#remotepoolremoved) when successful.
+
+</Aside>
+
+**Parameters**
+
+| Name                  | Type     | Description                                |
+| --------------------- | -------- | ------------------------------------------ |
+| `remoteChainSelector` | `uint64` | The chain selector to remove the pool from |
+| `remotePoolAddress`   | `bytes`  | The address of the pool to remove          |
+
+### setChainRateLimiterConfig
 
-#### Parameters
+Sets the chain rate limiter config.
+
+```solidity
+function setChainRateLimiterConfig(
+  uint64 remoteChainSelector,
+  RateLimiter.Config memory outboundConfig,
+  RateLimiter.Config memory inboundConfig
+) external;
+```
+
+**Parameters**
+
+| Name                  | Type                                                                   | Description                                                                               |
+| --------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `remoteChainSelector` | `uint64`                                                               | The remote chain selector for which the rate limits apply.                                |
+| `outboundConfig`      | [`RateLimiter.Config`](/ccip/api-reference/v1.5.1/rate-limiter#config) | The new outbound rate limiter config, meaning the onRamp rate limits for the given chain. |
+| `inboundConfig`       | [`RateLimiter.Config`](/ccip/api-reference/v1.5.1/rate-limiter#config) | The new inbound rate limiter config, meaning the offRamp rate limits for the given chain. |
+
+### setChainRateLimiterConfigs
+
+Updates rate limit configurations for multiple chains.
+
+```solidity
+function setChainRateLimiterConfigs(
+  uint64[] calldata remoteChainSelectors,
+  RateLimiter.Config[] calldata outboundConfigs,
+  RateLimiter.Config[] calldata inboundConfigs
+) external;
+```
 
-| Name    | Type      | Description                        |
-| ------- | --------- | ---------------------------------- |
-| removes | address[] | Addresses to remove from allowlist |
-| adds    | address[] | Addresses to add to allowlist      |
+<Aside>Callable by owner or rate limit admin. All array lengths must match.</Aside>
+
+**Parameters**
+
+| Name                   | Type                                                                     | Description                                                                                |
+| ---------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `remoteChainSelectors` | `uint64[]`                                                               | The chain selectors to configure                                                           |
+| `outboundConfigs`      | [`RateLimiter.Config[]`](/ccip/api-reference/v1.5.1/rate-limiter#config) | The new outbound rate limiter configs, meaning the onRamp rate limits for the given chains |
+| `inboundConfigs`       | [`RateLimiter.Config[]`](/ccip/api-reference/v1.5.1/rate-limiter#config) | The new inbound rate limiter configs, meaning the offRamp rate limits for the given chains |
+
+### setRateLimitAdmin
+
+Sets the address authorized to manage rate limits.
+
+```solidity
+function setRateLimitAdmin(address rateLimitAdmin) external onlyOwner;
+```
+
+<Aside>Only callable by owner. The rate limit admin can modify rate limit configurations independently.</Aside>
+
+### setRouter
+
+Updates the router contract address.
+
+```solidity
+function setRouter(address newRouter) public onlyOwner;
+```
+
+<Aside>Only callable by the contract owner. Emits [`RouterUpdated`](#routerupdated) event.</Aside>
+
+**Parameters**
+
+| Name        | Type      | Description                     |
+| ----------- | --------- | ------------------------------- |
+| `newRouter` | `address` | The new router contract address |
+
+### supportsInterface
+
+Implements ERC165 interface detection.
+
+```solidity
+function supportsInterface(bytes4 interfaceId) public pure virtual override returns (bool);
+```
+
+<Aside>
+
+Supports the following interfaces:
+
+- CCIP_POOL_V1
+- IPoolV1
+- IERC165
+
+</Aside>
+
+**Parameters**
+
+| Name          | Type     | Description                       |
+| ------------- | -------- | --------------------------------- |
+| `interfaceId` | `bytes4` | The interface identifier to check |
+
+**Returns**
+
+| Type   | Description                                   |
+| ------ | --------------------------------------------- |
+| `bool` | True if the contract implements the interface |
+
+## Rate Limiting
+
+<Aside type="note">
+Rate limiting is implemented with slightly higher inbound limits than outbound limits to accommodate chain finality and message batching:
+
+**Example Scenario:**
+
+1. Chain A and B both have:
+
+   - 100 tokens capacity
+   - 1 token per second refill rate
+
+2. Sequence of events:
+
+   - At time 0: Chain A sends 100 tokens to Chain B
+   - At time 5: Chain A sends 5 more tokens to Chain B
+   - At time 6: The epoch containing blocks [0-5] is finalized
+
+3. Impact:
+   - Both transactions are included in the same merkle root
+   - Both become executable simultaneously on Chain B
+   - Chain B's pool needs 105 token capacity to process both messages
+
+**Recommendation:**
+
+- Configure inbound limits 5-10% higher than outbound limits
+- Exact buffer depends on:
+  - Source chain epoch size
+  - CCIP round time
+  - Rate limit refill rate
+
+</Aside>
diff --git a/src/content/ccip/best-practices.mdx b/src/content/ccip/best-practices.mdx
index 1e504035680..ab29bcf5d5e 100644
--- a/src/content/ccip/best-practices.mdx
+++ b/src/content/ccip/best-practices.mdx
@@ -47,7 +47,7 @@ When you implement the `ccipReceive` [method](/ccip/api-reference/v1.5.1/ccip-re
 
 ## Using `extraArgs`
 
-The purpose of [`extraArgs`](/ccip/api-reference/v1.5.1/client#evmextraargs) is to allow compatibility with future CCIP upgrades. To get this benefit, make sure that `extraArgs` is mutable in production deployments. This allows you to build it offchain and pass it in a call to a function or store it in a variable that you can update on-demand.
+The purpose of [`extraArgs`](/ccip/api-reference/v1.5.1/client#evmextraargsv2) is to allow compatibility with future CCIP upgrades. To get this benefit, make sure that `extraArgs` is mutable in production deployments. This allows you to build it offchain and pass it in a call to a function or store it in a variable that you can update on-demand.
 
 If `extraArgs` are left empty, a default of _200000_ `gasLimit` will be set.