@chainlink/cre-sdk 1.0.0 → 1.0.2

package/dist/sdk/impl/runtime-impl.d.ts

@@ -3,44 +3,113 @@ import { type AwaitCapabilitiesRequest, type AwaitCapabilitiesResponse, type Awa
 import type { BaseRuntime, CallCapabilityParams, NodeRuntime, ReportRequest, ReportRequestJson, Runtime } from '..';
 import type { Report } from '../report';
 import { type ConsensusAggregation, type PrimitiveTypes, type UnwrapOptions } from '../utils';
+/**
+ * Base implementation shared by DON and Node runtimes.
+ *
+ * Call ID Management:
+ * - DON mode: IDs increment (1, 2, 3...)
+ * - Node mode: IDs decrement (-1, -2, -3...)
+ * This prevents collisions when both modes are active.
+ */
 export declare class BaseRuntimeImpl<C> implements BaseRuntime<C> {
     config: C;
     nextCallId: number;
     protected helpers: RuntimeHelpers;
     protected maxResponseSize: bigint;
     private mode;
+    /**
+     * When set, prevents operations that aren't allowed in current mode.
+     * - Set in DON mode when code tries to use NodeRuntime
+     * - Set in Node mode when code tries to use Runtime
+     */
     modeError?: Error;
     constructor(config: C, nextCallId: number, helpers: RuntimeHelpers, maxResponseSize: bigint, mode: Mode);
+    /**
+     * Calls a capability and returns a lazy result.
+     * The actual call happens immediately, but result retrieval is deferred.
+     */
     callCapability<I extends Message, O extends Message>({ capabilityId, method, payload, inputSchema, outputSchema, }: CallCapabilityParams<I, O>): {
         result: () => O;
     };
+    /**
+     * Allocates a unique callback ID for a capability request.
+     * DON mode increments, Node mode decrements (prevents collisions).
+     */
+    private allocateCallbackId;
+    /**
+     * Awaits capability response and unwraps the result or throws error.
+     */
+    private awaitAndUnwrapCapabilityResponse;
     getNextCallId(): number;
     now(): Date;
     log(message: string): void;
 }
+/**
+ * It is used when a BFT guarantee cannot be provided automatically (e.g. calling a standard API).
+ * You tell each node to perform a task on its own.
+ * Each node returns its own individual answer, and you are responsible for telling the SDK how to combine them into a single, trusted result by providing an aggregation algorithm.
+ *
+ * Useful in situation where you already expect non-determinism (e.g., inherently variable HTTP responses).
+ * Switching from Node Mode back to DON mode requires workflow authors to handle consensus themselves.
+ */
 export declare class NodeRuntimeImpl<C> extends BaseRuntimeImpl<C> implements NodeRuntime<C> {
     _isNodeRuntime: true;
     constructor(config: C, nextCallId: number, helpers: RuntimeHelpers, maxResponseSize: bigint);
 }
+/**
+ * It is used for operations that are guaranteed to be Byzantine Fault Tolerant (BFT).
+ * You ask the network to execute something, and CRE handles the underlying complexity to ensure you get back one final, secure, and trustworthy result.
+ */
 export declare class RuntimeImpl<C> extends BaseRuntimeImpl<C> implements Runtime<C> {
     private nextNodeCallId;
     constructor(config: C, nextCallId: number, helpers: RuntimeHelpers, maxResponseSize: bigint);
-    runInNodeMode<TArgs extends unknown[], TOutput>(fn: (nodeRuntime: NodeRuntime<C>, ...args: TArgs) => TOutput, consensusAggretation: ConsensusAggregation<TOutput, true>, unwrapOptions?: TOutput extends PrimitiveTypes ? never : UnwrapOptions<TOutput>): (...args: TArgs) => {
+    /**
+     * Executes a function in Node mode on each node, then aggregates via consensus.
+     *
+     * Flow:
+     * 1. Switches to Node mode, preventing DON operations
+     * 2. Executes fn() on each node independently
+     * 3. Captures result or error as "observation"
+     * 4. Switches back to DON mode
+     * 5. Runs consensus to aggregate observations
+     * 6. Returns aggregated result
+     */
+    runInNodeMode<TArgs extends unknown[], TOutput>(fn: (nodeRuntime: NodeRuntime<C>, ...args: TArgs) => TOutput, consensusAggregation: ConsensusAggregation<TOutput, true>, unwrapOptions?: TOutput extends PrimitiveTypes ? never : UnwrapOptions<TOutput>): (...args: TArgs) => {
         result: () => TOutput;
     };
+    private prepareConsensusInput;
+    private captureObservation;
+    private captureError;
+    private restoreDonMode;
+    private runConsensusAndWrap;
     getSecret(request: SecretRequest | SecretRequestJson): {
         result: () => Secret;
     };
+    private awaitAndUnwrapSecret;
+    /**
+     * Generates a report via consensus mechanism.
+     */
     report(input: ReportRequest | ReportRequestJson): {
         result: () => Report;
     };
 }
+/**
+ * Interface to the WASM host environment.
+ * Provides low-level access to capabilities, secrets, and utilities.
+ */
 export interface RuntimeHelpers {
+    /** Initiates a capability call. Returns false if capability not found. */
     call(request: CapabilityRequest): boolean;
+    /** Awaits capability responses. Blocks until responses are ready. */
     await(request: AwaitCapabilitiesRequest, maxResponseSize: bigint): AwaitCapabilitiesResponse;
+    /** Requests secrets from host. Returns false if host rejects request. */
     getSecrets(request: GetSecretsRequest, maxResponseSize: bigint): boolean;
+    /** Awaits secret responses. Blocks until secrets are ready. */
     awaitSecrets(request: AwaitSecretsRequest, maxResponseSize: bigint): AwaitSecretsResponse;
+    /** Switches execution mode (DON vs Node). Affects available operations. */
     switchModes(mode: Mode): void;
+    /** Returns current time in nanoseconds. */
     now(): number;
+    /** Logs a message to the host environment. */
     log(message: string): void;
 }

package/dist/sdk/impl/runtime-impl.js

@@ -5,13 +5,25 @@ import { ConsensusCapability } from '../../generated-sdk/capabilities/internal/c
 import { Value, } from '../utils';
 import { CapabilityError } from '../utils/capabilities/capability-error';
 import { DonModeError, NodeModeError, SecretsError } from '../errors';
+/**
+ * Base implementation shared by DON and Node runtimes.
+ *
+ * Call ID Management:
+ * - DON mode: IDs increment (1, 2, 3...)
+ * - Node mode: IDs decrement (-1, -2, -3...)
+ * This prevents collisions when both modes are active.
+ */
 export class BaseRuntimeImpl {
     config;
     nextCallId;
     helpers;
     maxResponseSize;
     mode;
-    // modeError must only be set from within NodeRuntimeImpl
+    /**
+     * When set, prevents operations that aren't allowed in current mode.
+     * - Set in DON mode when code tries to use NodeRuntime
+     * - Set in Node mode when code tries to use Runtime
+     */
     modeError;
     constructor(config, nextCallId, helpers, maxResponseSize, mode) {
         this.config = config;
@@ -20,7 +32,12 @@ export class BaseRuntimeImpl {
         this.maxResponseSize = maxResponseSize;
         this.mode = mode;
     }
+    /**
+     * Calls a capability and returns a lazy result.
+     * The actual call happens immediately, but result retrieval is deferred.
+     */
     callCapability({ capabilityId, method, payload, inputSchema, outputSchema, }) {
+        // Enforce mode restrictions
         if (this.modeError) {
             return {
                 result: () => {
@@ -28,22 +45,10 @@ export class BaseRuntimeImpl {
                 },
             };
         }
-        // nextCallId tracks the unique id for a request to the WASM host.
-        // to avoid collisions of the ID in different modes, it is
-        // incremented in DON mode and decremented in Node mode.
-        // eg. - first call don mode: nextCallId = 1
-        //     - second call: nextCallId = 2
-        //     - first call node mode: nextCallId = -1
-        //     - second call node mode: nextCallId = -2
-        //     - etc...
+        // Allocate unique callback ID for this request
+        const callbackId = this.allocateCallbackId();
+        // Send request to WASM host
         const anyPayload = anyPack(inputSchema, payload);
-        const callbackId = this.nextCallId;
-        if (this.mode === Mode.DON) {
-            this.nextCallId++;
-        }
-        else {
-            this.nextCallId--;
-        }
         const req = create(CapabilityRequestSchema, {
             id: capabilityId,
             method,
@@ -61,49 +66,68 @@ export class BaseRuntimeImpl {
                 },
             };
         }
+        // Return lazy result - await and unwrap when .result() is called
         return {
-            result: () => {
-                const awaitRequest = create(AwaitCapabilitiesRequestSchema, {
-                    ids: [callbackId],
-                });
-                const awaitResponse = this.helpers.await(awaitRequest, this.maxResponseSize);
-                const capabilityResponse = awaitResponse.responses[callbackId];
-                if (!capabilityResponse) {
-                    throw new CapabilityError(`No response found for callback ID ${callbackId}`, {
+            result: () => this.awaitAndUnwrapCapabilityResponse(callbackId, capabilityId, method, outputSchema),
+        };
+    }
+    /**
+     * Allocates a unique callback ID for a capability request.
+     * DON mode increments, Node mode decrements (prevents collisions).
+     */
+    allocateCallbackId() {
+        const callbackId = this.nextCallId;
+        if (this.mode === Mode.DON) {
+            this.nextCallId++;
+        }
+        else {
+            this.nextCallId--;
+        }
+        return callbackId;
+    }
+    /**
+     * Awaits capability response and unwraps the result or throws error.
+     */
+    awaitAndUnwrapCapabilityResponse(callbackId, capabilityId, method, outputSchema) {
+        const awaitRequest = create(AwaitCapabilitiesRequestSchema, {
+            ids: [callbackId],
+        });
+        const awaitResponse = this.helpers.await(awaitRequest, this.maxResponseSize);
+        const capabilityResponse = awaitResponse.responses[callbackId];
+        if (!capabilityResponse) {
+            throw new CapabilityError(`No response found for callback ID ${callbackId}`, {
+                capabilityId,
+                method,
+                callbackId,
+            });
+        }
+        const response = capabilityResponse.response;
+        switch (response.case) {
+            case 'payload': {
+                try {
+                    return anyUnpack(response.value, outputSchema);
+                }
+                catch {
+                    throw new CapabilityError(`Error cannot unwrap payload`, {
                         capabilityId,
                         method,
                         callbackId,
                     });
                 }
-                const response = capabilityResponse.response;
-                switch (response.case) {
-                    case 'payload': {
-                        try {
-                            return anyUnpack(response.value, outputSchema);
-                        }
-                        catch {
-                            throw new CapabilityError(`Error cannot unwrap payload`, {
-                                capabilityId,
-                                method,
-                                callbackId,
-                            });
-                        }
-                    }
-                    case 'error':
-                        throw new CapabilityError(`Error ${response.value}`, {
-                            capabilityId,
-                            method,
-                            callbackId,
-                        });
-                    default:
-                        throw new CapabilityError(`Error cannot unwrap ${response.case}`, {
-                            capabilityId,
-                            method,
-                            callbackId,
-                        });
-                }
-            },
-        };
+            }
+            case 'error':
+                throw new CapabilityError(`Error ${response.value}`, {
+                    capabilityId,
+                    method,
+                    callbackId,
+                });
+            default:
+                throw new CapabilityError(`Error cannot unwrap ${response.case}`, {
+                    capabilityId,
+                    method,
+                    callbackId,
+                });
+        }
     }
     getNextCallId() {
         return this.nextCallId;
@@ -116,6 +140,14 @@ export class BaseRuntimeImpl {
         this.helpers.log(message);
     }
 }
+/**
+ * It is used when a BFT guarantee cannot be provided automatically (e.g. calling a standard API).
+ * You tell each node to perform a task on its own.
+ * Each node returns its own individual answer, and you are responsible for telling the SDK how to combine them into a single, trusted result by providing an aggregation algorithm.
+ *
+ * Useful in situation where you already expect non-determinism (e.g., inherently variable HTTP responses).
+ * Switching from Node Mode back to DON mode requires workflow authors to handle consensus themselves.
+ */
 export class NodeRuntimeImpl extends BaseRuntimeImpl {
     _isNodeRuntime = true;
     constructor(config, nextCallId, helpers, maxResponseSize) {
@@ -123,58 +155,98 @@ export class NodeRuntimeImpl extends BaseRuntimeImpl {
         super(config, nextCallId, helpers, maxResponseSize, Mode.NODE);
     }
 }
+/**
+ * It is used for operations that are guaranteed to be Byzantine Fault Tolerant (BFT).
+ * You ask the network to execute something, and CRE handles the underlying complexity to ensure you get back one final, secure, and trustworthy result.
+ */
 export class RuntimeImpl extends BaseRuntimeImpl {
     nextNodeCallId = -1;
     constructor(config, nextCallId, helpers, maxResponseSize) {
         helpers.switchModes(Mode.DON);
         super(config, nextCallId, helpers, maxResponseSize, Mode.DON);
     }
-    runInNodeMode(fn, consensusAggretation, unwrapOptions) {
+    /**
+     * Executes a function in Node mode on each node, then aggregates via consensus.
+     *
+     * Flow:
+     * 1. Switches to Node mode, preventing DON operations
+     * 2. Executes fn() on each node independently
+     * 3. Captures result or error as "observation"
+     * 4. Switches back to DON mode
+     * 5. Runs consensus to aggregate observations
+     * 6. Returns aggregated result
+     */
+    runInNodeMode(fn, consensusAggregation, unwrapOptions) {
         return (...args) => {
+            // Step 1: Create node runtime and prevent DON operations
             this.modeError = new DonModeError();
             const nodeRuntime = new NodeRuntimeImpl(this.config, this.nextNodeCallId, this.helpers, this.maxResponseSize);
-            const consensusInput = create(SimpleConsensusInputsSchema, {
-                descriptors: consensusAggretation.descriptor,
-            });
-            if (consensusAggretation.defaultValue) {
-                // This cast is safe, since ConsensusAggregation can only have true its second argument if T extends CreSerializable<TOutput>
-                consensusInput.default = Value.from(consensusAggretation.defaultValue).proto();
-            }
+            // Step 2: Prepare consensus input with config
+            const consensusInput = this.prepareConsensusInput(consensusAggregation);
+            // Step 3: Execute node function and capture result/error
             try {
                 const observation = fn(nodeRuntime, ...args);
-                // This cast is safe, since ConsensusAggregation can only have true its second argument if T extends CreSerializable<TOutput>
-                consensusInput.observation = {
-                    case: 'value',
-                    value: Value.from(observation).proto(),
-                };
+                this.captureObservation(consensusInput, observation, consensusAggregation.descriptor);
             }
             catch (e) {
-                consensusInput.observation = {
-                    case: 'error',
-                    value: (e instanceof Error && e.message) || String(e),
-                };
+                this.captureError(consensusInput, e);
             }
             finally {
-                // Always restore DON mode before invoking consensus
-                this.modeError = undefined;
-                this.nextNodeCallId = nodeRuntime.nextCallId;
-                nodeRuntime.modeError = new NodeModeError();
-                this.helpers.switchModes(Mode.DON);
+                // Step 4: Always restore DON mode
+                this.restoreDonMode(nodeRuntime);
             }
-            const consensus = new ConsensusCapability();
-            const call = consensus.simple(this, consensusInput);
-            return {
-                result: () => {
-                    const result = call.result();
-                    const wrappedValue = Value.wrap(result);
-                    return unwrapOptions
-                        ? wrappedValue.unwrapToType(unwrapOptions)
-                        : wrappedValue.unwrap();
-                },
-            };
+            // Step 5: Run consensus and return lazy result
+            return this.runConsensusAndWrap(consensusInput, unwrapOptions);
+        };
+    }
+    prepareConsensusInput(consensusAggregation) {
+        const consensusInput = create(SimpleConsensusInputsSchema, {
+            descriptors: consensusAggregation.descriptor,
+        });
+        if (consensusAggregation.defaultValue) {
+            // Safe cast: ConsensusAggregation<T, true> implies T extends CreSerializable
+            const defaultValue = Value.from(consensusAggregation.defaultValue).proto();
+            clearIgnoredFields(defaultValue, consensusAggregation.descriptor);
+            consensusInput.default = defaultValue;
+        }
+        return consensusInput;
+    }
+    captureObservation(consensusInput, observation, descriptor) {
+        // Safe cast: ConsensusAggregation<T, true> implies T extends CreSerializable
+        const observationValue = Value.from(observation).proto();
+        clearIgnoredFields(observationValue, descriptor);
+        consensusInput.observation = {
+            case: 'value',
+            value: observationValue,
+        };
+    }
+    captureError(consensusInput, e) {
+        consensusInput.observation = {
+            case: 'error',
+            value: (e instanceof Error && e.message) || String(e),
+        };
+    }
+    restoreDonMode(nodeRuntime) {
+        this.modeError = undefined;
+        this.nextNodeCallId = nodeRuntime.nextCallId;
+        nodeRuntime.modeError = new NodeModeError();
+        this.helpers.switchModes(Mode.DON);
+    }
+    runConsensusAndWrap(consensusInput, unwrapOptions) {
+        const consensus = new ConsensusCapability();
+        const call = consensus.simple(this, consensusInput);
+        return {
+            result: () => {
+                const result = call.result();
+                const wrappedValue = Value.wrap(result);
+                return unwrapOptions
+                    ? wrappedValue.unwrapToType(unwrapOptions)
+                    : wrappedValue.unwrap();
+            },
         };
     }
     getSecret(request) {
+        // Enforce mode restrictions
         if (this.modeError) {
             return {
                 result: () => {
@@ -182,9 +254,11 @@ export class RuntimeImpl extends BaseRuntimeImpl {
                 },
             };
         }
+        // Normalize request (accept both protobuf and JSON formats)
         const secretRequest = request.$typeName
             ? request
             : create(SecretRequestSchema, request);
+        // Allocate callback ID and send request
         const id = this.nextCallId;
         this.nextCallId++;
         const secretsReq = create(GetSecretsRequestSchema, {
@@ -198,37 +272,68 @@ export class RuntimeImpl extends BaseRuntimeImpl {
                 },
             };
         }
+        // Return lazy result
         return {
-            result: () => {
-                const awaitRequest = create(AwaitSecretsRequestSchema, { ids: [id] });
-                const awaitResponse = this.helpers.awaitSecrets(awaitRequest, this.maxResponseSize);
-                const secretsResponse = awaitResponse.responses[id];
-                if (!secretsResponse) {
-                    throw new SecretsError(secretRequest, 'no response');
-                }
-                const responses = secretsResponse.responses;
-                if (responses.length !== 1) {
-                    throw new SecretsError(secretRequest, 'invalid value returned from host');
-                }
-                const response = responses[0].response;
-                switch (response.case) {
-                    case 'secret':
-                        return response.value;
-                    case 'error':
-                        throw new SecretsError(secretRequest, response.value.error);
-                    default:
-                        throw new SecretsError(secretRequest, 'cannot unmarshal returned value from host');
-                }
-            },
+            result: () => this.awaitAndUnwrapSecret(id, secretRequest),
         };
     }
+    awaitAndUnwrapSecret(id, secretRequest) {
+        const awaitRequest = create(AwaitSecretsRequestSchema, { ids: [id] });
+        const awaitResponse = this.helpers.awaitSecrets(awaitRequest, this.maxResponseSize);
+        const secretsResponse = awaitResponse.responses[id];
+        if (!secretsResponse) {
+            throw new SecretsError(secretRequest, 'no response');
+        }
+        const responses = secretsResponse.responses;
+        if (responses.length !== 1) {
+            throw new SecretsError(secretRequest, 'invalid value returned from host');
+        }
+        const response = responses[0].response;
+        switch (response.case) {
+            case 'secret':
+                return response.value;
+            case 'error':
+                throw new SecretsError(secretRequest, response.value.error);
+            default:
+                throw new SecretsError(secretRequest, 'cannot unmarshal returned value from host');
+        }
+    }
+    /**
+     * Generates a report via consensus mechanism.
+     */
     report(input) {
         const consensus = new ConsensusCapability();
         const call = consensus.report(this, input);
         return {
-            result: () => {
-                return call.result();
-            },
+            result: () => call.result(),
         };
     }
 }
+function clearIgnoredFields(value, descriptor) {
+    if (!descriptor || !value) {
+        return;
+    }
+    const fieldsMap = descriptor.descriptor?.case === 'fieldsMap' ? descriptor.descriptor.value : undefined;
+    if (!fieldsMap) {
+        return;
+    }
+    if (value.value?.case === 'mapValue') {
+        const mapValue = value.value.value;
+        if (!mapValue || !mapValue.fields) {
+            return;
+        }
+        for (const [key, val] of Object.entries(mapValue.fields)) {
+            const nestedDescriptor = fieldsMap.fields[key];
+            if (!nestedDescriptor) {
+                delete mapValue.fields[key];
+                continue;
+            }
+            const nestedFieldsMap = nestedDescriptor.descriptor?.case === 'fieldsMap'
+                ? nestedDescriptor.descriptor.value
+                : undefined;
+            if (nestedFieldsMap && val.value?.case === 'mapValue') {
+                clearIgnoredFields(val, nestedDescriptor);
+            }
+        }
+    }
+}

package/dist/sdk/runtime.d.ts

@@ -1,6 +1,7 @@
 import type { Message } from '@bufbuild/protobuf';
 import type { GenMessage } from '@bufbuild/protobuf/codegenv2';
 import type { ReportRequest, ReportRequestJson } from '../generated/sdk/v1alpha/sdk_pb';
+import type { Report } from './report';
 import type { ConsensusAggregation, PrimitiveTypes, UnwrapOptions } from './utils';
 import type { SecretsProvider } from '.';
 export type { ReportRequest, ReportRequestJson };
@@ -11,23 +12,40 @@ export type CallCapabilityParams<I extends Message, O extends Message> = {
     inputSchema: GenMessage<I>;
     outputSchema: GenMessage<O>;
 };
-import type { Report } from './report';
-export type BaseRuntime<C> = {
+/**
+ * Base runtime available in both DON and Node execution modes.
+ * Provides core functionality for calling capabilities and logging.
+ */
+export interface BaseRuntime<C> {
     config: C;
     callCapability<I extends Message, O extends Message>(params: CallCapabilityParams<I, O>): {
         result: () => O;
     };
     now(): Date;
     log(message: string): void;
-};
-export type Runtime<C> = BaseRuntime<C> & SecretsProvider & {
+}
+/**
+ * Runtime for Node mode execution.
+ */
+export interface NodeRuntime<C> extends BaseRuntime<C> {
+    readonly _isNodeRuntime: true;
+}
+/**
+ * Runtime for DON mode execution.
+ */
+export interface Runtime<C> extends BaseRuntime<C>, SecretsProvider {
+    /**
+     * Executes a function in Node mode and aggregates results via consensus.
+     *
+     * @param fn - Function to execute in each node (receives NodeRuntime)
+     * @param consensusAggregation - How to aggregate results across nodes
+     * @param unwrapOptions - Optional unwrapping config for complex return types
+     * @returns Wrapped function that returns aggregated result
+     */
     runInNodeMode<TArgs extends unknown[], TOutput>(fn: (nodeRuntime: NodeRuntime<C>, ...args: TArgs) => TOutput, consensusAggregation: ConsensusAggregation<TOutput, true>, unwrapOptions?: TOutput extends PrimitiveTypes ? never : UnwrapOptions<TOutput>): (...args: TArgs) => {
         result: () => TOutput;
     };
     report(input: ReportRequest | ReportRequestJson): {
         result: () => Report;
     };
-};
-export type NodeRuntime<C> = BaseRuntime<C> & {
-    readonly _isNodeRuntime: true;
-};
+}

package/dist/sdk/utils/capabilities/blockchain/blockchain-helpers.d.ts

@@ -1,6 +1,47 @@
 import type { CallMsgJson } from '../../../../generated/capabilities/blockchain/evm/v1alpha/client_pb';
 import type { ReportRequestJson } from '../../../../generated/sdk/v1alpha/sdk_pb';
+import { type BigInt as GeneratedBigInt } from '../../../../generated/values/v1/values_pb';
 import type { Address, Hex } from 'viem';
+/**
+ * Protobuf BigInt structure returned by SDK methods (e.g., headerByNumber).
+ * Uses Pick to extract just the data fields from the generated type.
+ */
+export type ProtoBigInt = Pick<GeneratedBigInt, 'absVal' | 'sign'>;
+/**
+ * Converts a native JS bigint to a protobuf BigInt JSON representation.
+ * Use this when passing bigint values to SDK methods.
+ *
+ * @example
+ * const response = evmClient.callContract(runtime, {
+ *   call: encodeCallMsg({...}),
+ *   blockNumber: bigintToProtoBigInt(9768438n)
+ * }).result()
+ *
+ * @param n - The native bigint, number, or string value.
+ * @returns The protobuf BigInt JSON representation.
+ */
+export declare const bigintToProtoBigInt: (n: number | bigint | string) => import("../../../../generated/values/v1/values_pb").BigIntJson;
+/**
+ * Converts a protobuf BigInt to a native JS bigint.
+ * Use this when extracting bigint values from SDK responses.
+ *
+ * @example
+ * const latestHeader = evmClient.headerByNumber(runtime, {}).result()
+ * const latestBlockNum = protoBigIntToBigint(latestHeader.header.blockNumber!)
+ * const customBlock = latestBlockNum - 500n
+ *
+ * @param pb - The protobuf BigInt object with absVal and sign fields.
+ * @returns The native JS bigint value.
+ */
+export declare const protoBigIntToBigint: (pb: ProtoBigInt) => bigint;
+/**
+ * Convenience alias for `bigintToProtoBigInt`.
+ * Creates a block number object for EVM capability requests.
+ *
+ * @param n - The block number.
+ * @returns The protobuf BigInt JSON representation.
+ */
+export declare const blockNumber: (n: number | bigint | string) => import("../../../../generated/values/v1/values_pb").BigIntJson;
 /**
  * EVM Capability Helper.
  *
@@ -8,6 +49,7 @@ import type { Address, Hex } from 'viem';
  * That blockNumber can be:
  *  - the latest mined block (`LATEST_BLOCK_NUMBER`) (default)
  * 	- the last finalized block (`LAST_FINALIZED_BLOCK_NUMBER`)
+ *  - a specific block number (use `blockNumber(n)` or `bigintToProtoBigInt(n)`)
  *
  * Using this constant will indicate that the call should be executed at the last finalized block.
  */
@@ -65,3 +107,4 @@ export declare const EVM_DEFAULT_REPORT_ENCODER: {
  * @returns The prepared report request.
  */
 export declare const prepareReportRequest: (hexEncodedPayload: Hex, reportEncoder?: Exclude<ReportRequestJson, "encodedPayload">) => ReportRequestJson;
+export declare const isChainSelectorSupported: (chainSelectorName: string) => boolean;