Understanding Call Result

Overview

OP_NET separates contract interactions into two distinct phases: simulation and execution. When a contract method is invoked, the library performs a simulation against an OP_NET node. The node executes the contract code in a virtual environment and returns comprehensive information about the execution outcome, including return values, gas estimates, events, and access patterns.

This information is encapsulated in a CallResult object, which serves as the bridge between simulation and execution. The CallResult provides a unified interface for:

• Accessing decoded return values from the contract method
• Detecting reverts and understanding why a call would fail
• Estimating gas costs before committing to a transaction
• Reviewing events that would be emitted during execution
• Executing the actual transaction on the network

The CallResult holds the simulation data and exposes the sendTransaction() method, which uses this data to construct and broadcast the actual Bitcoin transaction. This design ensures consistency between what was simulated and what is committed to the network.

For detailed information on simulation, refer to the Simulating Calls section.

For transaction execution details, refer to the Sending Transaction section.

interface CallResult<T> {
    // Decoded return value
    properties: T;

    // Error message if call reverted
    revert: string | undefined;

    // Gas information
    estimatedGas: bigint | undefined;
    refundedGas: bigint | undefined;
    estimatedSatGas: bigint;

    // Events emitted during simulation
    events: OPNetEvent[];

    // Storage access list
    accessList: IAccessList;

    // Raw result data
    result: BinaryReader;

    // Transaction sending method
    sendTransaction(params: TransactionParameters): Promise<Receipt>
}

interface CallResult<T> {
    // Decoded return value
    properties: T;

    // Error message if call reverted
    revert: string | undefined;

    // Gas information
    estimatedGas: bigint | undefined;
    refundedGas: bigint | undefined;
    estimatedSatGas: bigint;

    // Events emitted during simulation
    events: OPNetEvent[];

    // Storage access list
    accessList: IAccessList;

    // Raw result data
    result: BinaryReader;

    // Transaction sending method
    sendTransaction(params: TransactionParameters): Promise<Receipt>
}

Reverts

Contract calls may fail for various reasons. The CallResult captures these failures through the revert property. Always check for reverts before accessing return values or sending transactions.

Return Values

For successful calls, the CallResult provides type-safe access to decoded return values through the properties object. The structure of this object matches the contract method's signature.

Gas Estimation

The CallResult includes comprehensive gas information, enabling accurate fee estimation before transaction execution. Gas values are provided both in gas units and pre-calculated satoshi amounts.

For detailed information on gas estimation, refer to the Estimate Gas Costs section.

Event Information

Contract executions often emit events that provide insight into state changes. The CallResult automatically decodes these events based on the contract's ABI.

Access List

During contract execution, the OP_NET virtual machine tracks which storage slots are accessed. This information is captured in the accessList property of the CallResult. Access lists serve an important optimization purpose: by informing the node which storage slots will be needed before execution, subsequent calls can potentially reduce gas consumption.

When a contract method is called for the first time, the node must discover which storage slots are required during execution. This discovery process incurs additional overhead. By providing an access list from a previous simulation, the node can prepare the required storage data in advance, resulting in more efficient execution.

Access lists are particularly beneficial when performing multiple similar operations in sequence, such as batch transfers or repeated queries against the same contract state. The optimization is most effective when the storage access pattern remains consistent between calls.