Cross-Contract Call Patterns and Gas Management

NEAR Protocol enforces an asynchronous execution model for all cross-contract calls. Unlike single-threaded EVM environments where a contract call executes atomically within the caller's transaction, a cross-contract call on NEAR is split into multiple receipts. The initial transaction spawns one or more action receipts that are executed independently by the receiving contract's shard. Any return value or state mutation from the called contract is not available to the caller in the same execution context. Instead, the caller must define a callback function that the protocol invokes in a separate receipt once the callee's execution completes. This model is fundamental to NEAR's sharded runtime design, where each shard processes receipts for its own contracts in parallel, and cross-shard communication relies on the receipt system rather than synchronous state access.

This architecture directly impacts gas management and error handling. The user or originating account pre-pays for all gas across the receipt chain at transaction submission. If a cross-contract call fails—due to a panic, assertion failure, or gas exhaustion—the protocol does not automatically revert state changes made by the callee. The callback function must explicitly inspect the execution status and implement rollback or recovery logic. A common pattern is to check promise_result in the callback and either commit or revert state based on success or failure. Teams that assume atomic rollback semantics from EVM or SVM environments risk introducing state inconsistencies, such as burning tokens without completing a swap or locking funds in an intermediate contract. The #[private] macro and env::promise_return are critical tools for enforcing that only the expected callback can finalize a multi-step flow.

Operationally, builders must budget gas across the entire call chain, including the callback. Under-budgeting the callback can leave a contract in an unresolved state with no further execution possible unless a separate retry mechanism is implemented. Monitoring solutions should track receipt chains, not just top-level transactions, to detect stuck or failed cross-contract flows. Chainscore Labs reviews cross-contract architectures to verify that callback handling is exhaustive, gas budgets account for worst-case callback execution, and state invariants hold across asynchronous boundaries. For protocols integrating with NEAR-native DEXs, lending markets, or bridges, a formal review of the receipt-chain topology is essential to prevent composability failures that are unique to asynchronous runtimes.

On NEAR Protocol, cross-contract calls are not atomic synchronous executions but are instead decomposed into an asynchronous chain of Receipts. When a contract invokes another, the action is split into a series of receipts representing the function call, the transfer of attached tokens, and crucially, a callback receipt to return the result to the caller. This receipt-based model is fundamental to NEAR's sharded, parallelized runtime, allowing execution to be distributed across multiple shards without global locking, but it fundamentally changes how developers must handle errors, state, and gas.

Gas management in this model is deterministic but requires explicit budgeting. The initial transaction provides a fixed amount of gas, which is then partitioned and attached to each generated receipt. If a cross-contract call runs out of gas, the execution environment does not revert the entire transaction chain; instead, it signals a failure that must be handled by the developer-defined callback. This places a critical burden on the callback logic to manage state rollbacks, refund locked assets, or implement retry mechanisms. A missing or incorrectly implemented callback is a primary vector for permanently locked funds and broken protocol composability.

For builders and integration teams, the operational risk lies in the implicit trust chain of asynchronous calls. A protocol that relies on a multi-hop cross-contract interaction must verify that every contract in the chain correctly implements its callback interface and has a robust gas budget for failure scenarios. Chainscore Labs provides architecture reviews and formal verification of cross-contract call graphs to ensure that callback logic is resilient against out-of-gas errors and that state consistency is maintained across all asynchronous execution branches.