run

Executes candidate EVM programs sequentially against exact CLIENT state, then atomically publishes compact receipts and auditable local evidence. It never submits transactions or mutates the connected chain.

Example

Needs run · RPC required

1
WITH actors AS (
2
SELECT
3
'0x1000000000000000000000000000000000000001'::ADDRESS AS sender,
4
'0x2000000000000000000000000000000000000002'::ADDRESS AS writer,
5
'0x3000000000000000000000000000000000000003'::ADDRESS AS second_target,
6
'0x0000000000000000000000000000000000000000000000000000000000000000'::BYTES32 AS slot_zero
7
),
8
candidates(candidate_key) AS (
9
VALUES ('pass'::VARCHAR), ('later-revert'::VARCHAR)
10
),
11
requests AS (
12
SELECT
13
pin(
14
client(http_transport(
15
'http://127.0.0.1:4106'::VARCHAR,
16
31337::UBIGINT,
17
'{"retry_count":0,"timeout_ms":1000}'::JSON
18
)),
19
19000000::UBIGINT,
20
true
21
) AS client,
22
candidate_key,
23
program(
24
[
25
-- Funds the value transfer consumed by step zero.
26
assume_native_balance(sender, 1000000::UINT256, 'funds step value transfer'::VARCHAR),
27
assume_nonce(sender, 0::UBIGINT, 'step sender nonce'::VARCHAR),
28
assume_no_code(sender, 'step sender is an EOA'::VARCHAR),
29
assume_native_balance(writer, 0::UINT256, 'receives step value'::VARCHAR),
30
assume_nonce(writer, 0::UBIGINT, 'writer call target nonce'::VARCHAR),
31
-- Step zero consumes this runtime and initial slot.
32
assume_code(writer, '0x60003560005500'::BYTES, 'stores calldata word in slot zero'::VARCHAR),
33
assume_storage(writer, slot_zero, slot_zero, 'slot zero starts clear'::VARCHAR),
34
assume_native_balance(second_target, 0::UINT256, 'second target starts empty'::VARCHAR),
35
assume_nonce(second_target, 0::UBIGINT, 'second target nonce'::VARCHAR),
36
assume_code(
37
second_target,
38
CASE candidate_key WHEN 'pass' THEN '0x00'::BYTES ELSE '0x60006000fd'::BYTES END,
39
'step one either stops or deliberately reverts'::VARCHAR
40
)
41
],
42
[
43
execute_call(
44
sender,
45
writer,
46
'0x000000000000000000000000000000000000000000000000000000000000002a'::BYTES,
47
1::UINT256,
48
100000::UBIGINT
49
),
50
execute_contract(
51
-- 32 more lines load when JavaScript runs
Notebook ready in readonly mode.

API reference

Exact signatures with descriptions, requirements, inputs, returns, and examples.

run(CLIENT) # RPC required · Existing simulation required · Mutates simulation

Inputs

Name Type Use
candidates CLIENT required positional

Input relation columns

Name Type
client CLIENT

Exact live, pinned, or execution CLIENT used as state context and hydration authority. Required
candidate_key VARCHAR

Required 1-1024-byte valid UTF-8 key without NUL; byte-exact unique across the relation. Required
program PROGRAM

Non-empty typed PROGRAM whose steps execute sequentially until the first failure. Required
observations OBSERVATION[]

Optional keyed isolated reads at pre, retained post-step, or terminal checkpoints. Optional

The relation contains exactly client CLIENT, candidate_key VARCHAR, program PROGRAM, and optional observations OBSERVATION[], in any column order and with no extra columns.

Result columns

NameType
run_idUUID

Random UUID for this published run invocation; it is not a stable replay identity.

execution_idUUID

Random UUID for this candidate execution attempt; join it to public evm.execution_* evidence.

candidate_keyVARCHAR

Byte-exact, input-order-preserving candidate key supplied by the relation.

candidate_request_hashBYTES32

Stable hash of the candidate key, pinned client identity, program root, and requested observations.

chain_idUBIGINT

EVM chain identifier carried by the candidate CLIENT, or NULL before client resolution.

Showing fewer

One 18-column receipt per candidate. Returns input-order receipts while public evm.execution_* relations retain detailed attempts, checkpoints, observations, hydration evidence, state effects, and successful reusable artifacts.

Guidance

Behavior and consumption

Candidate keys are validated globally before execution and remain byte-exact and input-order preserving. An empty relation returns no receipts and publishes no run. Steps execute sequentially and stop after the first non-success; earlier successful checkpoints remain observable after a later failure.

  • Explicit assumptions preempt hydration at the same coordinate; duplicate assumption coordinates are rejected.
  • Successful step deltas supersede earlier state for later steps.
  • Missing state comes only from retained execution state, verified local evidence/cache, or hash-pinned RPC authority.
  • Pre observations use the initial snapshot; after_step(N) uses that retained post-checkpoint; terminal uses the latest retained executed-prefix snapshot.
  • Observations execute in isolated child overlays and modify neither PROGRAM state nor PROGRAM gas.

Same-statement evidence reads

When one SQL statement both invokes run and scans an evm.execution_* relation populated by that invocation, wrap run in WITH executions AS MATERIALIZED (SELECT * FROM run(...)). Materialization ensures publication completes before downstream observation scans initialize.

  • An ordinary CTE does not guarantee same-statement visibility.
  • Direct receipt reads and evm.execution_* scans in later statements do not require materialization.

Validation and failure timing

The relation shape and SQL types bind before execution. Candidate keys and duplicates are checked for the whole input before any candidate executes. Constructor content validation occurs when its scalar expression executes. Duplicate keys abort the statement before publication.

  • status is success, revert, out_of_gas, invalid, unsupported, state_unavailable, poisoned, or engine_error.
  • poisoned and engine_error are defensive or fault-injection outcomes, not ordinary authored-program results.
  • error_code is the stable machine-readable interpretation; do not branch on human error text.

Determinism, network, and side effects

run never mutates the connected chain. It may hydrate missing state only through retained state, verified local evidence/cache, or hash-pinned RPC authority. Receipts, attempts, observations, hydration evidence, and successful artifacts publish atomically with the SQL statement and caller transaction.

  • execution_closure_status: not_started, incomplete, complete.
  • observation_status: not_requested, complete, partial, failed.
  • transaction_gas_status: not_started, incomplete, complete_executed_prefix, complete_program.
  • cache_status: miss, invocation_local_hit, durable_hit.
  • EVM gas is measured execution gas; transaction gas is Determica's intrinsic/refund/floor calculation, not an RPC submission estimate.

Use and do not use

Use run to compare authored candidates at one explicit state boundary and audit every retained effect. Do not treat success as a guarantee of future onchain success, submit credentials in authored SQL, or interpret a failed program as a reusable terminal artifact or execution CLIENT.

  • Only successful complete artifacts can yield invocation_local_hit or durable_hit.
  • program roots, candidate request hashes, execution artifact hashes, random run/execution UUIDs, and replay status are distinct identities.

Related functions

Category and tags

Category
Simulation
Tag
Execution
Tag
Evidence
Tag
Client
Tag
Simulate