@chainlink/ccip-sdk 0.95.0 → 0.97.0

package/dist/execution.d.ts

@@ -1,5 +1,5 @@
 import type { Chain } from './chain.ts';
-import { type CCIPCommit, type CCIPExecution, type CCIPMessage, type CCIPRequest, type CCIPVersion, type ExecutionReport, type Lane, type WithLogger } from './types.ts';
+import type { CCIPMessage, CCIPVersion, Lane, WithLogger } from './types.ts';
 /**
  * Pure/sync function to calculate/generate OffRamp.executeManually report for messageIds
  *
@@ -9,29 +9,69 @@ import { type CCIPCommit, type CCIPExecution, type CCIPMessage, type CCIPRequest
  * @param merkleRoot - Optional merkleRoot of the CommitReport, for validation
  * @param ctx - Context for logging
  * @returns ManualExec report arguments
+ * @throws CCIPMessageNotInBatchError - When the messageId is not found in the provided batch
+ * @throws CCIPMerkleRootMismatchError - When calculated merkle root doesn't match the provided one
+ *
+ * @remarks
+ * This is a pure/sync function that performs no I/O - all data must be pre-fetched.
+ * It builds a merkle tree from the messages, generates a proof for the target messageId,
+ * and optionally validates against the provided merkleRoot.
+ *
+ * The returned proof can be used with `execute` to manually execute a stuck message.
+ *
+ * @example
+ * ```typescript
+ * import { calculateManualExecProof, EVMChain } from '@chainlink/ccip-sdk'
+ *
+ * // Fetch the request and all messages in its batch
+ * const request = (await source.getMessagesInTx(txHash))[0]
+ * const verifications = await dest.getVerifications({ offRamp, request })
+ * const messages = await source.getMessagesInBatch(request, commit.report)
+ *
+ * // Calculate proof for manual execution
+ * const proof = calculateManualExecProof(
+ *   messages,
+ *   request.lane,
+ *   request.message.messageId,
+ *   commit.report.merkleRoot
+ * )
+ * console.log('Merkle root:', proof.merkleRoot)
+ * console.log('Proofs:', proof.proofs)
+ * ```
+ * @see {@link discoverOffRamp} - Find the OffRamp for manual execution
+ * @see {@link execute} - Execute the report on destination chain
+ * @see {@link generateUnsignedExecute} - Build unsigned execution tx
  **/
-export declare function calculateManualExecProof<V extends CCIPVersion = CCIPVersion>(messagesInBatch: readonly CCIPMessage<V>[], lane: Lane<V>, messageId: string, merkleRoot?: string, ctx?: WithLogger): Omit<ExecutionReport, 'offchainTokenData' | 'message'>;
+export declare function calculateManualExecProof<V extends CCIPVersion = CCIPVersion>(messagesInBatch: readonly CCIPMessage<V>[], lane: Lane<V>, messageId: string, merkleRoot?: string, ctx?: WithLogger): {
+    proofs: string[];
+    proofFlagBits: bigint;
+    merkleRoot: string;
+};
+/**
+ * Discover the OffRamp address for a given OnRamp and destination chain.
+ * Results are memoized for performance.
+ *
+ * @param source - Source chain instance.
+ * @param dest - Destination chain instance.
+ * @param onRamp - OnRamp contract address on source chain.
+ * @param ctx - Optional context with logger.
+ * @returns OffRamp address on destination chain.
+ * @throws CCIPOffRampNotFoundError - When no matching OffRamp is found for the OnRamp
+ * @example
+ * ```typescript
+ * import { discoverOffRamp, EVMChain } from '@chainlink/ccip-sdk'
+ *
+ * const source = await EVMChain.fromUrl('https://rpc.sepolia.org')
+ * const dest = await EVMChain.fromUrl('https://rpc.fuji.avax.network')
+ *
+ * const offRamp = await discoverOffRamp(source, dest, onRampAddress)
+ * console.log('OffRamp on destination:', offRamp)
+ * ```
+ * @see {@link calculateManualExecProof} - Use with OffRamp for manual execution
+ * @see {@link execute} - Execute on destination chain
+ * @see {@link getExecutionReceipts} - Check execution status
+ */
 export declare const discoverOffRamp: import("micro-memoize").Memoized<(source: Chain, dest: Chain, onRamp: string, { logger }?: WithLogger) => Promise<string>, {
     transformKey: ([source, dest, onRamp]: [source: Chain<import("./types.ts").ChainFamily>, dest: Chain<import("./types.ts").ChainFamily>, onRamp: string, (WithLogger | undefined)?]) => [bigint, bigint, string];
 }>;
-/**
- * Generic implementation for fetching ExecutionReceipts for given requests.
- * If more than one request is given, may yield them interleaved.
- * Completes as soon as there's no more work to be done.
- *
- * Two possible behaviors:
- * - if `startBlock|startTime` is given, pages forward from that block up;
- *   completes when success (final) receipt is found for all requests (or reach latest block)
- * - otherwise, pages backwards and returns only the most recent receipt per request;
- *   completes when receipts for all requests were seen
- *
- * @param dest - Provider to page through.
- * @param offRamp - OffRamp contract address.
- * @param request - CCIP request to search executions for.
- * @param commit - Optional commit info to narrow down search.
- * @param hints - Optional hints (e.g., `page` for getLogs pagination range).
- */
-export declare function getExecutionReceipts(dest: Chain, offRamp: string, request: CCIPRequest, commit?: CCIPCommit, hints?: {
-    page?: number;
-}): AsyncGenerator<CCIPExecution>;
 //# sourceMappingURL=execution.d.ts.map

package/dist/execution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,YAAY,CAAA;AAOpD,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,IAAI,EACT,KAAK,UAAU,EAEhB,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;IASI;AACJ,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC1E,eAAe,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,EAC1C,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,UAAU,GACf,IAAI,CAAC,eAAe,EAAE,mBAAmB,GAAG,SAAS,CAAC,CA2BxD;AAED,eAAO,MAAM,eAAe,4CAEhB,KAAK,QACP,KAAK,UACH,MAAM,eACQ,UAAU,KAC/B,OAAO,CAAC,MAAM,CAAC;;EAoCnB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAuB,oBAAoB,CACzC,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,UAAU,EACnB,KAAK,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxB,cAAc,CAAC,aAAa,CAAC,CAgB/B"}
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAOvC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAyCI;AACJ,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC1E,eAAe,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,EAC1C,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,UAAU;;;;EA4BjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,4CAEhB,KAAK,QACP,KAAK,UACH,MAAM,eACQ,UAAU,KAC/B,OAAO,CAAC,MAAM,CAAC;;EAsFnB,CAAA"}

package/dist/execution.js

@@ -1,7 +1,6 @@
 import { memoize } from 'micro-memoize';
 import { CCIPMerkleRootMismatchError, CCIPMessageNotInBatchError, CCIPOffRampNotFoundError, } from "./errors/index.js";
 import { Tree, getLeafHasher, proofFlagsToBits } from "./hasher/index.js";
-import { ExecutionState, } from "./types.js";
 /**
  * Pure/sync function to calculate/generate OffRamp.executeManually report for messageIds
  *
@@ -11,6 +10,38 @@ import { ExecutionState, } from "./types.js";
  * @param merkleRoot - Optional merkleRoot of the CommitReport, for validation
  * @param ctx - Context for logging
  * @returns ManualExec report arguments
+ * @throws CCIPMessageNotInBatchError - When the messageId is not found in the provided batch
+ * @throws CCIPMerkleRootMismatchError - When calculated merkle root doesn't match the provided one
+ *
+ * @remarks
+ * This is a pure/sync function that performs no I/O - all data must be pre-fetched.
+ * It builds a merkle tree from the messages, generates a proof for the target messageId,
+ * and optionally validates against the provided merkleRoot.
+ *
+ * The returned proof can be used with `execute` to manually execute a stuck message.
+ *
+ * @example
+ * ```typescript
+ * import { calculateManualExecProof, EVMChain } from '@chainlink/ccip-sdk'
+ *
+ * // Fetch the request and all messages in its batch
+ * const request = (await source.getMessagesInTx(txHash))[0]
+ * const verifications = await dest.getVerifications({ offRamp, request })
+ * const messages = await source.getMessagesInBatch(request, commit.report)
+ *
+ * // Calculate proof for manual execution
+ * const proof = calculateManualExecProof(
+ *   messages,
+ *   request.lane,
+ *   request.message.messageId,
+ *   commit.report.merkleRoot
+ * )
+ * console.log('Merkle root:', proof.merkleRoot)
+ * console.log('Proofs:', proof.proofs)
+ * ```
+ * @see {@link discoverOffRamp} - Find the OffRamp for manual execution
+ * @see {@link execute} - Execute the report on destination chain
+ * @see {@link generateUnsignedExecute} - Build unsigned execution tx
  **/
 export function calculateManualExecProof(messagesInBatch, lane, messageId, merkleRoot, ctx) {
     const hasher = getLeafHasher(lane, ctx);
@@ -35,25 +66,80 @@ export function calculateManualExecProof(messagesInBatch, lane, messageId, merkl
         merkleRoot: tree.root(),
     };
 }
+/**
+ * Discover the OffRamp address for a given OnRamp and destination chain.
+ * Results are memoized for performance.
+ *
+ * @param source - Source chain instance.
+ * @param dest - Destination chain instance.
+ * @param onRamp - OnRamp contract address on source chain.
+ * @param ctx - Optional context with logger.
+ * @returns OffRamp address on destination chain.
+ * @throws CCIPOffRampNotFoundError - When no matching OffRamp is found for the OnRamp
+ * @example
+ * ```typescript
+ * import { discoverOffRamp, EVMChain } from '@chainlink/ccip-sdk'
+ *
+ * const source = await EVMChain.fromUrl('https://rpc.sepolia.org')
+ * const dest = await EVMChain.fromUrl('https://rpc.fuji.avax.network')
+ *
+ * const offRamp = await discoverOffRamp(source, dest, onRampAddress)
+ * console.log('OffRamp on destination:', offRamp)
+ * ```
+ * @see {@link calculateManualExecProof} - Use with OffRamp for manual execution
+ * @see {@link execute} - Execute on destination chain
+ * @see {@link getExecutionReceipts} - Check execution status
+ */
 export const discoverOffRamp = memoize(async function discoverOffRamp_(source, dest, onRamp, { logger = console } = {}) {
     const sourceRouter = await source.getRouterForOnRamp(onRamp, dest.network.chainSelector);
     const sourceOffRamps = await source.getOffRampsForRouter(sourceRouter, dest.network.chainSelector);
     for (const offRamp of sourceOffRamps) {
-        const destOnRamp = await source.getOnRampForOffRamp(offRamp, dest.network.chainSelector);
-        const destRouter = await dest.getRouterForOnRamp(destOnRamp, source.network.chainSelector);
-        const destOffRamps = await dest.getOffRampsForRouter(destRouter, source.network.chainSelector);
-        for (const offRamp of destOffRamps) {
-            const offRampsOnRamp = await dest.getOnRampForOffRamp(offRamp, source.network.chainSelector);
-            logger.debug('discoverOffRamp: found, from', {
-                sourceOnRamp: onRamp,
-                sourceRouter,
-                sourceOffRamps,
-                destOnRamp,
-                destOffRamps,
-                offRampsOnRamp,
-            }, '=', offRamp);
-            if (offRampsOnRamp === onRamp) {
-                return offRamp;
+        let destOnRamps;
+        try {
+            destOnRamps = await source.getOnRampsForOffRamp(offRamp, dest.network.chainSelector);
+        }
+        catch (err) {
+            logger.debug('discoverOffRamp: skipping offRamp', offRamp, '(no valid source chain config)', err);
+            continue;
+        }
+        for (const destOnRamp of destOnRamps) {
+            const destRouter = await dest.getRouterForOnRamp(destOnRamp, source.network.chainSelector);
+            const destOffRamps = await dest.getOffRampsForRouter(destRouter, source.network.chainSelector);
+            for (const offRamp of destOffRamps) {
+                let offRampsOnRamps;
+                try {
+                    offRampsOnRamps = await dest.getOnRampsForOffRamp(offRamp, source.network.chainSelector);
+                }
+                catch (err) {
+                    logger.debug('discoverOffRamp: skipping dest offRamp', offRamp, '(no valid source chain config)', err);
+                    continue;
+                }
+                for (const offRampsOnRamp of offRampsOnRamps) {
+                    logger.debug('discoverOffRamp: found, from', {
+                        sourceOnRamp: onRamp,
+                        sourceRouter,
+                        sourceOffRamps,
+                        destOnRamp,
+                        destOffRamps,
+                        offRampsOnRamp,
+                    }, '=', offRamp);
+                    for (const offRamp of destOffRamps) {
+                        const offRampsOnRamps = await dest.getOnRampsForOffRamp(offRamp, source.network.chainSelector);
+                        for (const offRampsOnRamp of offRampsOnRamps) {
+                            logger.debug('discoverOffRamp: found, from', {
+                                sourceOnRamp: onRamp,
+                                sourceRouter,
+                                sourceOffRamps,
+                                destOnRamp,
+                                destOffRamps,
+                                offRampsOnRamps,
+                            }, '=', offRamp);
+                            if (offRampsOnRamp === onRamp) {
+                                return offRamp;
+                            }
+                        }
+                    }
+                }
             }
         }
     }
@@ -61,39 +147,4 @@ export const discoverOffRamp = memoize(async function discoverOffRamp_(source, d
 }, {
     transformKey: ([source, dest, onRamp]) => [source.network.chainSelector, dest.network.chainSelector, onRamp],
 });
-/**
- * Generic implementation for fetching ExecutionReceipts for given requests.
- * If more than one request is given, may yield them interleaved.
- * Completes as soon as there's no more work to be done.
- *
- * Two possible behaviors:
- * - if `startBlock|startTime` is given, pages forward from that block up;
- *   completes when success (final) receipt is found for all requests (or reach latest block)
- * - otherwise, pages backwards and returns only the most recent receipt per request;
- *   completes when receipts for all requests were seen
- *
- * @param dest - Provider to page through.
- * @param offRamp - OffRamp contract address.
- * @param request - CCIP request to search executions for.
- * @param commit - Optional commit info to narrow down search.
- * @param hints - Optional hints (e.g., `page` for getLogs pagination range).
- */
-export async function* getExecutionReceipts(dest, offRamp, request, commit, hints) {
-    const onlyLast = !commit?.log.blockNumber && !request.tx.timestamp; // backwards
-    for await (const log of dest.getLogs({
-        startBlock: commit?.log.blockNumber,
-        startTime: request.tx.timestamp,
-        address: offRamp,
-        topics: ['ExecutionStateChanged'],
-        ...hints,
-    })) {
-        const receipt = dest.constructor.decodeReceipt(log);
-        if (!receipt || receipt.messageId !== request.message.messageId)
-            continue;
-        const timestamp = log.tx?.timestamp ?? (await dest.getBlockTimestamp(log.blockNumber));
-        yield { receipt, log, timestamp };
-        if (onlyLast || receipt.state === ExecutionState.Success)
-            break;
-    }
-}
 //# sourceMappingURL=execution.js.map

package/dist/execution.js.map

@@ -1 +1 @@
-{"version":3,"file":"execution.js","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"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"}

package/dist/extra-args.d.ts

@@ -4,12 +4,21 @@ import { ChainFamily } from './types.ts';
 export declare const EVMExtraArgsV1Tag: "0x97a657c9";
 /** Tag identifier for EVMExtraArgsV2 encoding. */
 export declare const EVMExtraArgsV2Tag: "0x181dcf10";
+/** Tag identifier for GenericExtraArgsV3 encoding (tightly packed binary format). */
+export declare const GenericExtraArgsV3Tag: "0xa69dd4aa";
 /** Tag identifier for SVMExtraArgsV1 encoding. */
 export declare const SVMExtraArgsV1Tag: "0x1f3b3aba";
 /** Tag identifier for SuiExtraArgsV1 encoding. */
 export declare const SuiExtraArgsV1Tag: "0x21ea4ca9";
 /**
  * EVM extra arguments version 1 with gas limit only.
+ *
+ * @example
+ * ```typescript
+ * const args: EVMExtraArgsV1 = {
+ *   gasLimit: 200_000n,
+ * }
+ * ```
  */
 export type EVMExtraArgsV1 = {
     /** Gas limit for execution on the destination chain. */
@@ -18,13 +27,68 @@ export type EVMExtraArgsV1 = {
 /**
  * EVM extra arguments version 2 with out-of-order execution support.
  * Also known as GenericExtraArgsV2.
+ *
+ * @example
+ * ```typescript
+ * const args: EVMExtraArgsV2 = {
+ *   gasLimit: 200_000n,
+ *   allowOutOfOrderExecution: true,
+ * }
+ * ```
  */
 export type EVMExtraArgsV2 = EVMExtraArgsV1 & {
     /** Whether to allow out-of-order message execution. */
     allowOutOfOrderExecution: boolean;
 };
+/**
+ * Generic extra arguments version 3 with cross-chain verifiers and executor support.
+ * Uses tightly packed binary encoding (NOT ABI-encoded).
+ *
+ * @example
+ * ```typescript
+ * const args: GenericExtraArgsV3 = {
+ *   gasLimit: 200_000n,
+ *   blockConfirmations: 5,
+ *   ccvs: ['0x1234...'],
+ *   ccvArgs: ['0x010203'],
+ *   executor: '0x5678...',
+ *   executorArgs: '0x',
+ *   tokenReceiver: '0xReceiverAddress...',
+ *   tokenArgs: '0x',
+ * }
+ * ```
+ */
+export type GenericExtraArgsV3 = {
+    /** Gas limit for execution on the destination chain (uint32). */
+    gasLimit: bigint;
+    /** Number of block confirmations required. */
+    blockConfirmations: number;
+    /** Cross-chain verifier addresses (EVM addresses). */
+    ccvs: string[];
+    /** Per-CCV arguments (BytesLike). */
+    ccvArgs: BytesLike[];
+    /** Executor address (EVM address or empty string for none). */
+    executor: string;
+    /** Executor-specific arguments (BytesLike). */
+    executorArgs: BytesLike;
+    /** Token receiver address (checksummed EVM address or hex string). */
+    tokenReceiver: string;
+    /** Token pool-specific arguments (BytesLike). */
+    tokenArgs: BytesLike;
+};
 /**
  * Solana (SVM) extra arguments version 1.
+ *
+ * @example
+ * ```typescript
+ * const args: SVMExtraArgsV1 = {
+ *   computeUnits: 200_000n,
+ *   accountIsWritableBitmap: 0n,
+ *   allowOutOfOrderExecution: true,
+ *   tokenReceiver: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
+ *   accounts: [],
+ * }
+ * ```
  */
 export type SVMExtraArgsV1 = {
     /** Compute units for Solana execution. */
@@ -40,6 +104,16 @@ export type SVMExtraArgsV1 = {
 };
 /**
  * Sui extra arguments version 1.
+ *
+ * @example
+ * ```typescript
+ * const args: SuiExtraArgsV1 = {
+ *   gasLimit: 200_000n,
+ *   allowOutOfOrderExecution: true,
+ *   tokenReceiver: '0x1234...abcd',
+ *   receiverObjectIds: ['0xobject1...', '0xobject2...'],
+ * }
+ * ```
  */
 export type SuiExtraArgsV1 = EVMExtraArgsV2 & {
     /** Token receiver address on Sui. */
@@ -50,23 +124,58 @@ export type SuiExtraArgsV1 = EVMExtraArgsV2 & {
 /**
  * Union type of all supported extra arguments formats.
  */
-export type ExtraArgs = EVMExtraArgsV1 | EVMExtraArgsV2 | SVMExtraArgsV1 | SuiExtraArgsV1;
+export type ExtraArgs = EVMExtraArgsV1 | EVMExtraArgsV2 | GenericExtraArgsV3 | SVMExtraArgsV1 | SuiExtraArgsV1;
 /**
  * Encodes extra arguments for CCIP messages.
- * The args are *to* a dest network, but are encoded as a message *from* this source chain
- * e.g. Solana uses Borsh to encode extraArgs in its produced requests, even those targetting EVM
- **/
+ * The args are *to* a dest network, but are encoded as a message *from* this source chain.
+ * E.g. Solana uses Borsh to encode extraArgs in its produced requests, even those targeting EVM.
+ *
+ * @param args - Extra arguments to encode
+ * @param from - Source chain family for encoding format (defaults to EVM)
+ * @returns Encoded extra arguments as hex string
+ * @throws {@link CCIPChainFamilyUnsupportedError} if chain family not supported
+ *
+ * @example
+ * ```typescript
+ * import { encodeExtraArgs } from '@chainlink/ccip-sdk'
+ *
+ * const encoded = encodeExtraArgs({
+ *   gasLimit: 200_000n,
+ *   allowOutOfOrderExecution: true,
+ * })
+ * console.log('Encoded:', encoded) // '0x181dcf10...'
+ * ```
+ *
+ * @see {@link decodeExtraArgs} - Decode extra arguments from bytes
+ */
 export declare function encodeExtraArgs(args: ExtraArgs, from?: ChainFamily): string;
 /**
  * Parses extra arguments from CCIP messages.
  * @param data - Extra arguments bytearray data.
  * @param from - Optional chain family to narrow decoding attempts.
  * @returns Extra arguments object if found, undefined otherwise.
+ * @throws {@link CCIPChainFamilyUnsupportedError} if specified chain family not supported
+ * @throws {@link CCIPExtraArgsParseError} if data cannot be parsed as valid extra args
+ *
+ * @example
+ * ```typescript
+ * import { decodeExtraArgs } from '@chainlink/ccip-sdk'
+ *
+ * const decoded = decodeExtraArgs('0x181dcf10...')
+ * if (decoded?._tag === 'EVMExtraArgsV2') {
+ *   console.log('Gas limit:', decoded.gasLimit)
+ *   console.log('Out of order:', decoded.allowOutOfOrderExecution)
+ * }
+ * ```
+ *
+ * @see {@link encodeExtraArgs} - Encode extra arguments to bytes
  */
 export declare function decodeExtraArgs(data: BytesLike, from?: ChainFamily): (EVMExtraArgsV1 & {
     _tag: 'EVMExtraArgsV1';
 }) | (EVMExtraArgsV2 & {
     _tag: 'EVMExtraArgsV2';
+}) | (GenericExtraArgsV3 & {
+    _tag: 'GenericExtraArgsV3';
 }) | (SVMExtraArgsV1 & {
     _tag: 'SVMExtraArgsV1';
 }) | (SuiExtraArgsV1 & {

package/dist/extra-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extra-args.d.ts","sourceRoot":"","sources":["../src/extra-args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAM,MAAM,QAAQ,CAAA;AAI3C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAiD,YAAY,CAAA;AAC3F,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAiD,YAAY,CAAA;AAC3F,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAiD,YAAY,CAAA;AAC3F,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAiD,YAAY,CAAA;AAE3F;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C,uDAAuD;IACvD,wBAAwB,EAAE,OAAO,CAAA;CAClC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,uBAAuB,EAAE,MAAM,CAAA;IAC/B,uDAAuD;IACvD,wBAAwB,EAAE,OAAO,CAAA;IACjC,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAC5B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,cAAc,GAAG,cAAc,GAAG,cAAc,CAAA;AAEzF;;;;IAII;AACJ,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,WAA6B,GAAG,MAAM,CAI5F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,IAAI,CAAC,EAAE,WAAW,GAEhB,CAAC,cAAc,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC7C,CAAC,cAAc,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC7C,CAAC,cAAc,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC7C,CAAC,cAAc,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC7C,SAAS,CAeZ"}
+{"version":3,"file":"extra-args.d.ts","sourceRoot":"","sources":["../src/extra-args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAM,MAAM,QAAQ,CAAA;AAI3C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAiD,YAAY,CAAA;AAC3F,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAiD,YAAY,CAAA;AAC3F,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,EAAqD,YAAY,CAAA;AACnG,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAiD,YAAY,CAAA;AAC3F,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAiD,YAAY,CAAA;AAE3F;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C,uDAAuD;IACvD,wBAAwB,EAAE,OAAO,CAAA;CAClC,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,kBAAkB,EAAE,MAAM,CAAA;IAC1B,sDAAsD;IACtD,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,qCAAqC;IACrC,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAA;IAChB,+CAA+C;IAC/C,YAAY,EAAE,SAAS,CAAA;IACvB,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,SAAS,EAAE,SAAS,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,uBAAuB,EAAE,MAAM,CAAA;IAC/B,uDAAuD;IACvD,wBAAwB,EAAE,OAAO,CAAA;IACjC,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAC5B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,cAAc,GACd,kBAAkB,GAClB,cAAc,GACd,cAAc,CAAA;AAElB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,WAA6B,GAAG,MAAM,CAI5F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,IAAI,CAAC,EAAE,WAAW,GAEhB,CAAC,cAAc,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC7C,CAAC,cAAc,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC7C,CAAC,kBAAkB,GAAG;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC,GACrD,CAAC,cAAc,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC7C,CAAC,cAAc,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC7C,SAAS,CAeZ"}

package/dist/extra-args.js

@@ -6,15 +6,35 @@ import { ChainFamily } from "./types.js";
 export const EVMExtraArgsV1Tag = id('CCIP EVMExtraArgsV1').substring(0, 10);
 /** Tag identifier for EVMExtraArgsV2 encoding. */
 export const EVMExtraArgsV2Tag = id('CCIP EVMExtraArgsV2').substring(0, 10);
+/** Tag identifier for GenericExtraArgsV3 encoding (tightly packed binary format). */
+export const GenericExtraArgsV3Tag = id('CCIP GenericExtraArgsV3').substring(0, 10);
 /** Tag identifier for SVMExtraArgsV1 encoding. */
 export const SVMExtraArgsV1Tag = id('CCIP SVMExtraArgsV1').substring(0, 10);
 /** Tag identifier for SuiExtraArgsV1 encoding. */
 export const SuiExtraArgsV1Tag = id('CCIP SuiExtraArgsV1').substring(0, 10);
 /**
  * Encodes extra arguments for CCIP messages.
- * The args are *to* a dest network, but are encoded as a message *from* this source chain
- * e.g. Solana uses Borsh to encode extraArgs in its produced requests, even those targetting EVM
- **/
+ * The args are *to* a dest network, but are encoded as a message *from* this source chain.
+ * E.g. Solana uses Borsh to encode extraArgs in its produced requests, even those targeting EVM.
+ *
+ * @param args - Extra arguments to encode
+ * @param from - Source chain family for encoding format (defaults to EVM)
+ * @returns Encoded extra arguments as hex string
+ * @throws {@link CCIPChainFamilyUnsupportedError} if chain family not supported
+ *
+ * @example
+ * ```typescript
+ * import { encodeExtraArgs } from '@chainlink/ccip-sdk'
+ *
+ * const encoded = encodeExtraArgs({
+ *   gasLimit: 200_000n,
+ *   allowOutOfOrderExecution: true,
+ * })
+ * console.log('Encoded:', encoded) // '0x181dcf10...'
+ * ```
+ *
+ * @see {@link decodeExtraArgs} - Decode extra arguments from bytes
+ */
 export function encodeExtraArgs(args, from = ChainFamily.EVM) {
     const chain = supportedChains[from];
     if (!chain)
@@ -26,6 +46,21 @@ export function encodeExtraArgs(args, from = ChainFamily.EVM) {
  * @param data - Extra arguments bytearray data.
  * @param from - Optional chain family to narrow decoding attempts.
  * @returns Extra arguments object if found, undefined otherwise.
+ * @throws {@link CCIPChainFamilyUnsupportedError} if specified chain family not supported
+ * @throws {@link CCIPExtraArgsParseError} if data cannot be parsed as valid extra args
+ *
+ * @example
+ * ```typescript
+ * import { decodeExtraArgs } from '@chainlink/ccip-sdk'
+ *
+ * const decoded = decodeExtraArgs('0x181dcf10...')
+ * if (decoded?._tag === 'EVMExtraArgsV2') {
+ *   console.log('Gas limit:', decoded.gasLimit)
+ *   console.log('Out of order:', decoded.allowOutOfOrderExecution)
+ * }
+ * ```
+ *
+ * @see {@link encodeExtraArgs} - Encode extra arguments to bytes
  */
 export function decodeExtraArgs(data, from) {
     if (!data || data === '')

package/dist/extra-args.js.map

@@ -1 +1 @@
-{"version":3,"file":"extra-args.js","sourceRoot":"","sources":["../src/extra-args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,EAAE,EAAE,MAAM,QAAQ,CAAA;AAE3C,OAAO,EAAE,+BAA+B,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAiB,CAAA;AAC3F,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAiB,CAAA;AAC3F,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAiB,CAAA;AAC3F,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAiB,CAAA;AAkD3F;;;;IAII;AACJ,MAAM,UAAU,eAAe,CAAC,IAAe,EAAE,OAAoB,WAAW,CAAC,GAAG;IAClF,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;IACnC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,+BAA+B,CAAC,IAAI,CAAC,CAAA;IAC3D,OAAO,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAA;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAe,EACf,IAAkB;IAOlB,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE;QAAE,OAAM;IAChC,IAAI,MAAM,CAAA;IACV,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,+BAA+B,CAAC,IAAI,CAAC,CAAA;QAC3D,MAAM,GAAG,CAAC,KAAK,CAAC,CAAA;IAClB,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;IACzC,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAA;QAC3C,IAAI,OAAO;YAAE,OAAO,OAAO,CAAA;IAC7B,CAAC;IACD,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAA;AACzD,CAAC"}
+{"version":3,"file":"extra-args.js","sourceRoot":"","sources":["../src/extra-args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,EAAE,EAAE,MAAM,QAAQ,CAAA;AAE3C,OAAO,EAAE,+BAA+B,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAiB,CAAA;AAC3F,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAiB,CAAA;AAC3F,qFAAqF;AACrF,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC,yBAAyB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAiB,CAAA;AACnG,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAiB,CAAA;AAC3F,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAiB,CAAA;AAgI3F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAe,EAAE,OAAoB,WAAW,CAAC,GAAG;IAClF,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;IACnC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,+BAA+B,CAAC,IAAI,CAAC,CAAA;IAC3D,OAAO,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAA;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAe,EACf,IAAkB;IAQlB,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE;QAAE,OAAM;IAChC,IAAI,MAAM,CAAA;IACV,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,+BAA+B,CAAC,IAAI,CAAC,CAAA;QAC3D,MAAM,GAAG,CAAC,KAAK,CAAC,CAAA;IAClB,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;IACzC,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAA;QAC3C,IAAI,OAAO;YAAE,OAAO,OAAO,CAAA;IAC7B,CAAC;IACD,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAA;AACzD,CAAC"}

package/dist/gas.d.ts

@@ -1,7 +1,7 @@
 import { type BytesLike } from 'ethers';
 import type { Chain } from './chain.ts';
 /**
- * A subset of [[MessageInput]] for estimating receive execution gas.
+ * A subset of {@link MessageInput} for estimating receive execution gas.
  */
 export type EstimateMessageInput = {
     /** receiver contract address */
@@ -10,7 +10,7 @@ export type EstimateMessageInput = {
     messageId?: string;
     /** optional sender: zero address will be used if omitted */
     sender?: string;
-    /** optional data: zero bytes will be used if ommitted */
+    /** optional data: zero bytes will be used if omitted */
     data?: BytesLike;
     /**
      * optional tokenAmounts; `amount` with either source `token` (as in MessageInput) or
@@ -28,7 +28,7 @@ export type EstimateMessageInput = {
     }))[];
 };
 /**
- * Options for [[estimateReceiveExecution]] function.
+ * Options for {@link estimateReceiveExecution} function.
  */
 export type EstimateReceiveExecutionOpts = {
     /** Source chain instance (for token data retrieval) */
@@ -42,8 +42,34 @@ export type EstimateReceiveExecutionOpts = {
 };
 /**
  * Estimate CCIP gasLimit needed to execute a request on a contract receiver.
- * @param opts - Options for estimation: source and dest chains, router or ramp address, and message
- * @returns Estimated gasLimit.
+ *
+ * @param opts - {@link EstimateReceiveExecutionOpts} for estimation
+ * @returns Estimated gasLimit
+ *
+ * @throws {@link CCIPMethodUnsupportedError} if dest chain doesn't support estimation
+ * @throws {@link CCIPContractTypeInvalidError} if routerOrRamp is not a valid contract type
+ * @throws {@link CCIPTokenDecimalsInsufficientError} if dest token has insufficient decimals
+ *
+ * @example
+ * ```typescript
+ * import { estimateReceiveExecution, EVMChain } from '@chainlink/ccip-sdk'
+ *
+ * const source = await EVMChain.fromUrl('https://rpc.sepolia.org')
+ * const dest = await EVMChain.fromUrl('https://rpc.fuji.avax.network')
+ *
+ * const gasLimit = await estimateReceiveExecution({
+ *   source,
+ *   dest,
+ *   routerOrRamp: '0xRouter...',
+ *   message: {
+ *     sender: '0x...',
+ *     receiver: '0x...',
+ *     data: '0x...',
+ *     tokenAmounts: [],
+ *   },
+ * })
+ * console.log('Estimated gas:', gasLimit)
+ * ```
  */
 export declare function estimateReceiveExecution({ source, dest, routerOrRamp, message, }: EstimateReceiveExecutionOpts): Promise<number>;
 //# sourceMappingURL=gas.d.ts.map

package/dist/gas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gas.d.ts","sourceRoot":"","sources":["../src/gas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqC,MAAM,QAAQ,CAAA;AAE1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AASvC;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;QACvB,MAAM,EAAE,MAAM,CAAA;KACf,GAAG,CACA;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GACjB;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CACvF,CAAC,EAAE,CAAA;CACL,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,uDAAuD;IACvD,MAAM,EAAE,KAAK,CAAA;IACb,+DAA+D;IAC/D,IAAI,EAAE,KAAK,CAAA;IACX,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAA;IACpB,8BAA8B;IAC9B,OAAO,EAAE,oBAAoB,CAAA;CAC9B,CAAA;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,EAC7C,MAAM,EACN,IAAI,EACJ,YAAY,EACZ,OAAO,GACR,EAAE,4BAA4B,mBA0D9B"}
+{"version":3,"file":"gas.d.ts","sourceRoot":"","sources":["../src/gas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqC,MAAM,QAAQ,CAAA;AAE1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAUvC;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;QACvB,MAAM,EAAE,MAAM,CAAA;KACf,GAAG,CACA;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GACjB;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CACvF,CAAC,EAAE,CAAA;CACL,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,uDAAuD;IACvD,MAAM,EAAE,KAAK,CAAA;IACb,+DAA+D;IAC/D,IAAI,EAAE,KAAK,CAAA;IACX,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAA;IACpB,8BAA8B;IAC9B,OAAO,EAAE,oBAAoB,CAAA;CAC9B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,wBAAwB,CAAC,EAC7C,MAAM,EACN,IAAI,EACJ,YAAY,EACZ,OAAO,GACR,EAAE,4BAA4B,mBAgE9B"}