Skip to content

Addressing some Feedback #4319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Genesis3800 merged 4 commits into from
Oct 16, 2026
Merged

Addressing some Feedback #4319

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
71173b2
fix: Addressed gaps in unlisted extraArgs page
Genesis3800 Oct 16, 2026
41ae816
fix: Addressed all of Ben's Feedback
Genesis3800 Oct 16, 2026
c6a9788
fix: addressing final round of counter review
Genesis3800 Oct 16, 2026
450b076
Merge branch 'main' into addressing-ben-fixes
Genesis3800 Oct 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

104 changes: 73 additions & 31 deletions src/content/ccip/llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82515,11 +82515,11 @@ If a legacy format omits fields introduced in newer versions, those fields resol

This ensures existing integrations do not require modification when migrating to newer CCIP infrastructure.

## EVMExtraArgsV3
## ExtraArgsV3

For EVM integrations, **EVMExtraArgsV3** is the latest format used to specify optional message configuration.
For EVM integrations, **ExtraArgsV3** is the latest format used to specify optional message configuration.

It provides a structured way for senders to override selected execution parameters while maintaining backwards compatibility.
It provides a structured way for senders to override selected execution parameters while maintaining backwards compatibility. The format also defines fields for selecting verification components (CCVs), an executor, and token-handling options.

At launch scope, the primary configuration exposed to developers is **confirmation depth selection**.

Expand All @@ -82529,24 +82529,37 @@ The following diagram shows how ExtraArgs influence message processing without c

![Diagram showing ExtraArgs influencing message verification and execution stages](/images/ccip/extraargs-message-processing.png)

## Confirmation Depth (`blockConfirmations`)
## Confirmation Depth (block depth)

A sender may request a specific confirmation depth for the source-chain transaction that emits a CCIP message.

This parameter determines the minimum number of blocks that must be included after the message transaction before verification begins.

It does not override chain finality or minimum confirmation requirements enforced by token pools.

The following example requests a confirmation depth of 10 blocks with a gas limit of 200,000, using the `ExtraArgsCodec` encoding helper:

```solidity
Client.EVMExtraArgsV3 memory extraArgs =
Client.EVMExtraArgsV3({
gasLimit: 200000,
blockConfirmations: 10
});
import {ExtraArgsCodec} from "chainlink-ccip/libraries/ExtraArgsCodec.sol";

bytes memory extraArgs = ExtraArgsCodec._getBasicEncodedExtraArgsV3BlockDepth(
200_000, // gasLimit: gas available for the receiver callback on the destination chain
10 // blockDepth: wait 10 blocks after the message transaction before verification begins
);
```

The helper encodes the confirmation depth into the 4-byte finality field of `ExtraArgsV3`: `0` requests full source-chain finality (the default), and values from 1 to 65,535 request that many blocks. The resulting bytes are passed as the message's `extraArgs`.

If a token pool enforces a higher minimum confirmation requirement, requests below that threshold will revert.

> **CAUTION: The destination receiver enforces its own finality policy**
>
> When a message calls a receiver on the destination chain, the receiver's finality policy is checked at execution, not
> at send time. Receivers built on the default `CCIPReceiver` base contract, and all receivers that predate CCIP 2.0,
> admit full-finality messages only. If the receiver does not admit the requested confirmation depth, the send succeeds
> but the message fails at execution with state `FAILURE`. It becomes executable only after the receiver updates its
> policy; waiting for full source-chain finality does not resolve this.

Confirmation depth directly affects **execution latency** and **reorganization risk**.

Lower values may reduce latency but increase exposure to chain reorganizations.
Expand All @@ -82557,7 +82570,7 @@ For a deeper explanation of this tradeoff, see [Execution Latency](/ccip/concept

## Default Confirmation Behavior

If `blockConfirmations` is not specified:
If no confirmation depth is requested:

**CCIP waits for full source-chain finality before verification begins.**

Expand All @@ -82567,15 +82580,13 @@ This default behavior provides the strongest protection against chain reorganiza

Token pools may enforce a **minimum confirmation requirement** for messages that transfer tokens.

If a sender requests a confirmation depth below the configured minimum, the transaction **reverts during message submission**.
If a sender requests a confirmation depth below the configured minimum, the transaction **reverts during message submission** with `InvalidRequestedFinality`.

This prevents unsafe token transfers that could be affected by source-chain reorganizations.

The effective confirmation requirement becomes the **maximum** of:
A pool using the default configuration accepts only full-finality requests: any requested confirmation depth reverts.

1. The sender-requested confirmation depth
2. The token pool’s minimum confirmation requirement
3. The lane’s operational finality configuration
The requested confirmation depth is carried unchanged in the message: it is not raised or lowered automatically. On the source chain, the request must satisfy the minimum confirmation requirement of every participant that enforces one: the token pool, the verifiers, and the executor. If any of them rejects the request, the submission reverts.

## Confirmation Depth and Finality

Expand All @@ -82585,9 +82596,9 @@ Some chains provide **deterministic finality**, while others rely on **probabili

When deterministic finality is available, CCIP may wait for that signal regardless of the requested confirmation depth.

If the requested `blockConfirmations` value is **greater than or equal to the chain’s effective finality threshold**, CCIP waits for finality.
If the requested confirmation depth is **greater than or equal to the chain’s effective finality threshold**, CCIP waits for finality.

In this case, specifying `blockConfirmations` does not change execution behavior.
In this case, specifying a confirmation depth does not change execution behavior.

## Interaction with the CCIP Message Lifecycle

Expand Down Expand Up @@ -82634,9 +82645,9 @@ ExtraArgs provide optional configuration for CCIP messages.

If ExtraArgs are omitted, messages follow the safest default path with full finality and standard execution infrastructure.

EVMExtraArgsV3 introduces a structured format for specifying configuration overrides while maintaining backwards compatibility with earlier integrations.
ExtraArgsV3 introduces a structured format for specifying configuration overrides while maintaining backwards compatibility with earlier integrations.

At launch scope, the primary parameter exposed to developers is **confirmation depth (`blockConfirmations`)**, which allows applications to tune the tradeoff between execution latency and reorganization risk.
At launch scope, the primary parameter exposed to developers is **confirmation depth**, which allows applications to tune the tradeoff between execution latency and reorganization risk.

---

Expand Down Expand Up @@ -88856,6 +88867,14 @@ Version tag for `GenericExtraArgsV2` encoding.

Version tag for `SVMExtraArgsV1` encoding.

### SUI_EXTRA_ARGS_V1_TAG

Version tag for `SuiExtraArgsV1` encoding.

### NO_EXECUTION_TAG

Tag to indicate no execution on the destination chain; used to derive `NO_EXECUTION_ADDRESS`.

### NO_EXECUTION_ADDRESS

```solidity
Expand Down Expand Up @@ -88901,6 +88920,11 @@ address public constant NO_EXECUTION_ADDRESS = address(bytes20(NO_EXECUTION_TAG)

### GenericExtraArgsV2

> **CAUTION: Legacy format**
>
> In CCIP 2.0, only the `gasLimit` field is honored; `allowOutOfOrderExecution` is deprecated. New integrations should
> use [`ExtraArgsV3`](/ccip/evm/api-reference/v2.0.0/extra-args-codec#genericextraargsv3).

| Field | Type |
| -------------------------- | --------- |
| `gasLimit` | `uint256` |
Expand Down Expand Up @@ -88938,20 +88962,21 @@ Used by:
- [`IRouterClient`](/ccip/evm/api-reference/v2.0.0/i-router-client)
- [`CCIPReceiver`](/ccip/evm/api-reference/v2.0.0/ccip-receiver)

Example:
Example: construct an outbound CCIP message with a gas limit of 300,000 and the default finality (wait for full finalization):

```solidity
import {Client} from "chainlink-ccip/libraries/Client.sol";
import {ExtraArgsCodec} from "chainlink-ccip/libraries/ExtraArgsCodec.sol";

// Construct outbound CCIP message
Client.EVM2AnyMessage memory message = Client.EVM2AnyMessage({
receiver: abi.encode(receiverAddress),
data: abi.encode(payload),
tokenAmounts: tokenAmounts,
feeToken: address(0),
extraArgs: Client._argsToBytes(
Client.GenericExtraArgsV2({
gasLimit: 300_000,
allowOutOfOrderExecution: false
})
extraArgs: ExtraArgsCodec._getBasicEncodedExtraArgsV3(
300_000, // gasLimit
bytes4(0) // finalityConfig: default, wait for full finalization
)
});
```
Expand Down Expand Up @@ -90714,11 +90739,11 @@ This library ensures that `extraArgs` are encoded in a format compatible with CC

## Usage Boundary

**You do not call this library directly in most cases.**
**Applications building `ExtraArgsV3` messages call this library directly.**

- CCIP contracts use this library to encode and decode execution parameters.
- Applications typically use `Client` helpers, which rely on this library internally.
- You may use this library directly when working with low-level or custom `extraArgs` encoding.
- Use `_getBasicEncodedExtraArgsV3` (or its block-depth and fast-confirmation variants) for messages that only set a gas limit and finality, or `_encodeGenericExtraArgsV3` for full control over the struct fields.
- `Client` helpers (`_argsToBytes`) cover only the legacy `EVMExtraArgsV1` and `GenericExtraArgsV2` formats.
- CCIP contracts use this library internally to decode `extraArgs` and validate their encoding.

## Contract

Expand Down Expand Up @@ -90942,6 +90967,23 @@ uint256 public constant GENERIC_EXTRA_ARGS_V3_STATIC_LENGTH_SIZE = 4 + 4 + 4 + 1

## Structs

### GenericExtraArgsV3

`GenericExtraArgsV3` is the `ExtraArgsV3` format for EVM-compatible chains. Empty `ccvs` select the default verifiers; pure token transfers (no data, zero gas limit) resolve to an empty verifier list instead. A zero `executor` selects the default executor. An empty `tokenReceiver` falls back to the message receiver when the message includes a token transfer.

| Field | Type |
| ------------------------- | ----------- |
| `gasLimit` | `uint32` |
| `requestedFinalityConfig` | `bytes4` |
| `ccvs` | `address[]` |
| `ccvArgs` | `bytes[]` |
| `executor` | `address` |
| `executorArgs` | `bytes` |
| `tokenReceiver` | `bytes` |
| `tokenArgs` | `bytes` |

***

### SVMExecutorArgsV1

| Field | Type |
Expand Down Expand Up @@ -104789,7 +104831,7 @@ Limits are enforced during message processing and execution. Values vary by chai
| Maximum message `data` length | `data` payload sent within the [CCIP message](/ccip/evm/api-reference/v2.0.0/client#evm2anymessage). | 32 kilobytes |
| Maximum number of tokens | Maximum number of token transfers (entries in the message's `tokenAmounts` array) a user can include in a single message. | 1 |
| Token Pool Execution Gas Limit | Maximum gas for executing the combined steps in token pools during cross-chain transfers, including (1) `balanceOf` check before minting/releasing, (2) `releaseOrMint` function, and (3) `balanceOf` check after minting/releasing. For more details on building custom token pools and handling gas constraints, refer to the [Token Pools documentation](/ccip/concepts/cross-chain-token/overview#token-pool-gas-requirements). | 90,000 |
| Message Execution Gas Limit | User-specified [gas limit](/ccip/evm/api-reference/v2.0.0/client#genericextraargsv2). | Varies by destination chain (see table below) |
| Message Execution Gas Limit | User-specified [gas limit](/ccip/evm/api-reference/v2.0.0/extra-args-codec#genericextraargsv3). | Varies by destination chain (see table below) |

### Message Execution Gas Limit by destination chain

Expand Down Expand Up @@ -105304,7 +105346,7 @@ to the Router. The important part for this tutorial is `extraArgs`:

- `extraArgs` is a `bytes` field that carries message execution parameters.
- On EVM chains, this includes a `gasLimit` field (for example, see
[`GenericExtraArgsV2.gasLimit`](/ccip/evm/api-reference/v2.0.0/client#genericextraargsv2)).
[`GenericExtraArgsV3.gasLimit`](/ccip/evm/api-reference/v2.0.0/extra-args-codec#genericextraargsv3)).
- In CCIP 2.0 tutorials, the scripts encode `extraArgs` off-chain (V2 or V3 depending on lane support) and pass the
encoded bytes to the contract. The contract treats it as opaque bytes and forwards it into the message payload.

Expand Down
Loading
Loading