{ "openrpc": "1.0.0-rc1", "info": { "version": "0.10.4-rc.0", "title": "StarkNet Trace API", "license": {} }, "servers": [], "methods": [ { "name": "starknet_traceTransaction", "summary": "For a given executed transaction, return the trace of its execution, including internal calls", "description": "Returns the execution trace of the transaction designated by the input hash", "params": [ { "name": "transaction_hash", "summary": "The hash of the transaction to trace", "required": true, "schema": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN_HASH" } } ], "result": { "name": "trace", "description": "The function call trace of the transaction designated by the given hash", "schema": { "$ref": "#/components/schemas/TRANSACTION_TRACE" } }, "errors": [ { "$ref": "./api/starknet_api_openrpc.json#/components/errors/TXN_HASH_NOT_FOUND" }, { "$ref": "#/components/errors/NO_TRACE_AVAILABLE" } ] }, { "name": "starknet_simulateTransactions", "summary": "Simulate a given sequence of transactions on the requested state, and generate the execution traces. Note that some of the transactions may revert, in which case no error is thrown, but revert details can be seen on the returned trace object. Note that some of the transactions may revert, this will be reflected by the revert_error property in the trace. Other types of failures (e.g. unexpected error or failure in the validation phase) will result in TRANSACTION_EXECUTION_ERROR.", "params": [ { "name": "block_id", "description": "The hash of the requested block, or number (height) of the requested block, or a block tag, for the block referencing the state or call the transaction on.", "required": true, "schema": { "$ref": "#/components/schemas/BLOCK_ID" } }, { "name": "transactions", "description": "The transactions to simulate", "required": true, "schema": { "type": "array", "description": "a sequence of transactions to simulate, running each transaction on the state resulting from applying all the previous ones", "items": { "$ref": "#/components/schemas/BROADCASTED_TXN" } } }, { "name": "simulation_flags", "description": "describes what parts of the transaction should be executed", "required": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SIMULATION_FLAG" } } } ], "result": { "name": "simulated_transactions", "description": "The execution trace and consumed resources of the required transactions. When RETURN_INITIAL_READS is not present in simulation_flags, returns an array. When RETURN_INITIAL_READS is present in simulation_flags, returns an object with simulated_transactions and initial_reads fields.", "schema": { "oneOf": [ { "type": "array", "description": "The execution trace and consumed resources of the required transactions. This format is returned when RETURN_INITIAL_READS is not present in simulation_flags, maintaining compatibility with JSON-RPC 0.10.0.", "items": { "type": "object", "properties": { "transaction_trace": { "title": "the transaction's trace", "$ref": "#/components/schemas/TRANSACTION_TRACE" }, "fee_estimation": { "title": "the transaction's resources and fee", "$ref": "#/components/schemas/FEE_ESTIMATE" } } } }, { "type": "object", "description": "The execution trace and consumed resources of the required transactions, along with initial reads when RETURN_INITIAL_READS is present in simulation_flags.", "properties": { "simulated_transactions": { "type": "array", "description": "The execution trace and consumed resources of the required transactions", "items": { "type": "object", "properties": { "transaction_trace": { "title": "the transaction's trace", "$ref": "#/components/schemas/TRANSACTION_TRACE" }, "fee_estimation": { "title": "the transaction's resources and fee", "$ref": "#/components/schemas/FEE_ESTIMATE" } } } }, "initial_reads": { "title": "Initial reads", "description": "The set of state values fetched from the underlying state reader during execution for all transactions in the simulation. Required when RETURN_INITIAL_READS is present in simulation_flags.", "$ref": "#/components/schemas/INITIAL_READS" } }, "required": ["simulated_transactions", "initial_reads"] } ] } }, "errors": [ { "$ref": "./api/starknet_api_openrpc.json#/components/errors/BLOCK_NOT_FOUND" }, { "$ref": "./api/starknet_api_openrpc.json#/components/errors/TRANSACTION_EXECUTION_ERROR" } ] }, { "name": "starknet_traceBlockTransactions", "summary": "Retrieve traces for all transactions in the given block", "description": "Returns the execution traces of all transactions included in the given block", "params": [ { "name": "block_id", "description": "The hash of the requested block, or number (height) of the requested block, or a block tag", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/BLOCK_ID" }, { "not": { "enum": ["pre_confirmed"] } } ] } }, { "name": "trace_flags", "description": "Flags that indicate what additional information should be included in the trace", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TRACE_FLAG" } } } ], "result": { "name": "traces", "description": "The traces of all transactions in the block. When RETURN_INITIAL_READS is not present in trace_flags (or trace_flags is not provided), returns an array. When RETURN_INITIAL_READS is present in trace_flags, returns an object with traces and initial_reads fields.", "schema": { "oneOf": [ { "type": "array", "description": "The traces of all transactions in the block. This format is returned when RETURN_INITIAL_READS is not present in trace_flags (or trace_flags is not provided), maintaining compatibility with JSON-RPC 0.10.0.", "items": { "type": "object", "description": "A single pair of transaction hash and corresponding trace", "properties": { "transaction_hash": { "$ref": "#/components/schemas/FELT" }, "trace_root": { "$ref": "#/components/schemas/TRANSACTION_TRACE" } } } }, { "type": "object", "description": "The traces of all transactions in the block, along with initial reads when RETURN_INITIAL_READS is present in trace_flags.", "properties": { "traces": { "type": "array", "description": "The traces of all transactions in the block", "items": { "type": "object", "description": "A single pair of transaction hash and corresponding trace", "properties": { "transaction_hash": { "$ref": "#/components/schemas/FELT" }, "trace_root": { "$ref": "#/components/schemas/TRANSACTION_TRACE" } } } }, "initial_reads": { "title": "Initial reads", "description": "The set of state values fetched from the underlying state reader during execution for all transactions in the block. Required when RETURN_INITIAL_READS is present in trace_flags. Returns an empty object instead of INITIAL_READS when the execution trace for the referenced block is inconsistent with the canonical block trace.", "$ref": "#/components/schemas/INITIAL_READS" } }, "required": ["traces", "initial_reads"] } ] } }, "errors": [ { "$ref": "./api/starknet_api_openrpc.json#/components/errors/BLOCK_NOT_FOUND" } ] } ], "components": { "contentDescriptors": {}, "schemas": { "TRANSACTION_TRACE": { "oneOf": [ { "name": "INVOKE_TXN_TRACE", "type": "object", "description": "the execution trace of an invoke transaction", "properties": { "validate_invocation": { "$ref": "#/components/schemas/FUNCTION_INVOCATION" }, "execute_invocation": { "description": "the trace of the __execute__ call", "$ref": "#/components/schemas/REVERTIBLE_FUNCTION_INVOCATION" }, "fee_transfer_invocation": { "$ref": "#/components/schemas/FUNCTION_INVOCATION" }, "state_diff": { "title": "state_diff", "description": "the state diffs induced by the transaction", "$ref": "#/components/schemas/STATE_DIFF" }, "execution_resources": { "title": "Execution resources", "description": "the resources consumed by the transaction, includes both computation and data", "$ref": "#/components/schemas/EXECUTION_RESOURCES" }, "type": { "title": "Type", "type": "string", "enum": ["INVOKE"] } }, "required": ["type", "execute_invocation", "execution_resources"] }, { "name": "DECLARE_TXN_TRACE", "type": "object", "description": "the execution trace of a declare transaction", "properties": { "validate_invocation": { "$ref": "#/components/schemas/FUNCTION_INVOCATION" }, "fee_transfer_invocation": { "$ref": "#/components/schemas/FUNCTION_INVOCATION" }, "state_diff": { "title": "state_diff", "description": "the state diffs induced by the transaction", "$ref": "#/components/schemas/STATE_DIFF" }, "execution_resources": { "title": "Execution resources", "description": "the resources consumed by the transaction, includes both computation and data", "$ref": "#/components/schemas/EXECUTION_RESOURCES" }, "type": { "title": "Type", "type": "string", "enum": ["DECLARE"] } }, "required": ["type", "execution_resources"] }, { "name": "DEPLOY_ACCOUNT_TXN_TRACE", "type": "object", "description": "the execution trace of a deploy account transaction", "properties": { "validate_invocation": { "$ref": "#/components/schemas/FUNCTION_INVOCATION" }, "constructor_invocation": { "description": "the trace of the constructor call", "$ref": "#/components/schemas/FUNCTION_INVOCATION" }, "fee_transfer_invocation": { "$ref": "#/components/schemas/FUNCTION_INVOCATION" }, "state_diff": { "title": "state_diff", "description": "the state diffs induced by the transaction", "$ref": "#/components/schemas/STATE_DIFF" }, "execution_resources": { "title": "Execution resources", "description": "the resources consumed by the transaction, includes both computation and data", "$ref": "#/components/schemas/EXECUTION_RESOURCES" }, "type": { "title": "Type", "type": "string", "enum": ["DEPLOY_ACCOUNT"] } }, "required": [ "type", "execution_resources", "constructor_invocation" ] }, { "name": "L1_HANDLER_TXN_TRACE", "type": "object", "description": "the execution trace of an L1 handler transaction", "properties": { "function_invocation": { "description": "the trace of the L1 handler call", "$ref": "#/components/schemas/REVERTIBLE_FUNCTION_INVOCATION" }, "state_diff": { "title": "state_diff", "description": "the state diffs induced by the transaction", "$ref": "#/components/schemas/STATE_DIFF" }, "execution_resources": { "title": "Execution resources", "description": "the resources consumed by the transaction, includes both computation and data", "$ref": "#/components/schemas/EXECUTION_RESOURCES" }, "type": { "title": "Type", "type": "string", "enum": ["L1_HANDLER"] } }, "required": ["type", "function_invocation", "execution_resources"] } ] }, "SIMULATION_FLAG": { "type": "string", "enum": ["SKIP_VALIDATE", "SKIP_FEE_CHARGE", "RETURN_INITIAL_READS"], "description": "Flags that indicate how to simulate a given transaction. By default, the sequencer behavior is replicated locally (enough funds are expected to be in the account, and fee will be deducted from the balance before the simulation of the next transaction). To skip the fee charge, use the SKIP_FEE_CHARGE flag. When RETURN_INITIAL_READS is present, the node returns the minimal set of concrete state values fetched from the underlying state reader during execution for all transactions in the simulation." }, "TRACE_FLAG": { "type": "string", "enum": ["RETURN_INITIAL_READS"], "description": "Flags that indicate what additional information should be included in the trace. When RETURN_INITIAL_READS is present, the node returns the minimal set of concrete state values fetched from the underlying state reader during execution for all transactions in the block. Returns an empty object instead of INITIAL_READS when the execution trace for the referenced block is inconsistent with the canonical block trace." }, "INITIAL_READS": { "title": "Initial reads", "description": "The set of state values fetched from the underlying state reader during execution. This is a complete witness sufficient to reconstruct the cached state needed for re-execution.", "type": "object", "properties": { "storage": { "title": "Storage", "description": "Storage entries that were read during simulation: (contract_address, storage_key) -> value", "type": "array", "items": { "type": "object", "properties": { "contract_address": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/ADDRESS" }, "key": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/STORAGE_KEY" }, "value": { "$ref": "#/components/schemas/FELT" } }, "required": ["contract_address", "key", "value"] } }, "nonces": { "title": "Nonces", "description": "Contract nonces that were read during simulation: contract_address -> nonce", "type": "array", "items": { "type": "object", "properties": { "contract_address": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/ADDRESS" }, "nonce": { "$ref": "#/components/schemas/FELT" } }, "required": ["contract_address", "nonce"] } }, "class_hashes": { "title": "Class hashes", "description": "Contract class hashes that were read during simulation: contract_address -> class_hash", "type": "array", "items": { "type": "object", "properties": { "contract_address": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/ADDRESS" }, "class_hash": { "$ref": "#/components/schemas/FELT" } }, "required": ["contract_address", "class_hash"] } }, "declared_contracts": { "title": "Declared contracts", "description": "Class declaration status that was read during simulation: class_hash -> is_declared", "type": "array", "items": { "type": "object", "properties": { "class_hash": { "$ref": "#/components/schemas/FELT" }, "is_declared": { "type": "boolean" } }, "required": ["class_hash", "is_declared"] } } } }, "NESTED_CALL": { "$ref": "#/components/schemas/FUNCTION_INVOCATION" }, "FUNCTION_INVOCATION": { "allOf": [ { "$ref": "#/components/schemas/FUNCTION_CALL" }, { "type": "object", "properties": { "caller_address": { "title": "Caller Address", "description": "The address of the invoking contract. 0 for the root invocation", "$ref": "#/components/schemas/FELT" }, "class_hash": { "title": "Class hash", "description": "The hash of the class being called", "$ref": "#/components/schemas/FELT" }, "entry_point_type": { "$ref": "#/components/schemas/ENTRY_POINT_TYPE" }, "call_type": { "$ref": "#/components/schemas/CALL_TYPE" }, "result": { "title": "Invocation Result", "description": "The value returned from the function invocation", "type": "array", "items": { "$ref": "#/components/schemas/FELT" } }, "calls": { "title": "Nested Calls", "description": "The calls made by this invocation", "type": "array", "items": { "$ref": "#/components/schemas/NESTED_CALL" } }, "events": { "title": "Invocation Events", "description": "The events emitted in this invocation", "type": "array", "items": { "$ref": "#/components/schemas/ORDERED_EVENT" } }, "messages": { "title": "L1 Messages", "description": "The messages sent by this invocation to L1", "type": "array", "items": { "$ref": "#/components/schemas/ORDERED_MESSAGE" } }, "execution_resources": { "title": "Execution resources", "description": "Resources consumed by the call tree rooted at this given call (including the root)", "$ref": "#/components/schemas/INNER_CALL_EXECUTION_RESOURCES" }, "is_reverted": { "title": "Is Reverted", "description": "true if this inner call panicked", "type": "boolean" } }, "required": [ "caller_address", "class_hash", "entry_point_type", "call_type", "result", "calls", "events", "messages", "execution_resources", "is_reverted" ] } ] }, "ENTRY_POINT_TYPE": { "type": "string", "enum": ["EXTERNAL", "L1_HANDLER", "CONSTRUCTOR"] }, "CALL_TYPE": { "type": "string", "enum": ["LIBRARY_CALL", "CALL", "DELEGATE"] }, "ORDERED_EVENT": { "type": "object", "title": "orderedEvent", "description": "an event alongside its order within the transaction", "allOf": [ { "type": "object", "properties": { "order": { "title": "order", "description": "the order of the event within the transaction", "type": "integer", "minimum": 0 } } }, { "$ref": "#/components/schemas/EVENT" } ] }, "ORDERED_MESSAGE": { "type": "object", "title": "orderedMessage", "description": "a message alongside its order within the transaction", "allOf": [ { "type": "object", "properties": { "order": { "title": "order", "description": "the order of the message within the transaction", "type": "integer", "minimum": 0 } } }, { "$ref": "#/components/schemas/MSG_TO_L1" } ] }, "INNER_CALL_EXECUTION_RESOURCES": { "type": "object", "title": "Execution resources", "description": "the resources consumed by an inner call (does not account for state diffs since data is squashed across the transaction)", "properties": { "l1_gas": { "title": "L1Gas", "description": "l1 gas consumed by this transaction, used for l2-->l1 messages and state updates if blobs are not used", "type": "integer", "minimum": 0 }, "l2_gas": { "title": "L2Gas", "description": "l2 gas consumed by this transaction, used for computation and calldata", "type": "integer", "minimum": 0 } }, "required": ["l1_gas", "l2_gas"] }, "REVERTIBLE_FUNCTION_INVOCATION": { "oneOf": [ { "$ref": "#/components/schemas/FUNCTION_INVOCATION" }, { "type": "object", "properties": { "revert_reason": { "name": "revert reason", "description": "the revert reason for the failed invocation", "type": "string" } }, "required": ["revert_reason"] } ] }, "FELT": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/FELT" }, "FUNCTION_CALL": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/FUNCTION_CALL" }, "EVENT": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/EVENT_CONTENT" }, "MSG_TO_L1": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/MSG_TO_L1" }, "BLOCK_ID": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/BLOCK_ID" }, "FEE_ESTIMATE": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/FEE_ESTIMATE" }, "BROADCASTED_TXN": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/BROADCASTED_TXN" }, "STATE_DIFF": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/STATE_DIFF" }, "EXECUTION_RESOURCES": { "$ref": "./api/starknet_api_openrpc.json#/components/schemas/EXECUTION_RESOURCES" } }, "errors": { "NO_TRACE_AVAILABLE": { "code": 10, "message": "No trace available for transaction", "data": { "type": "object", "description": "Extra information on why trace is not available. Either it wasn't executed yet (RECEIVED), or the transaction failed (REJECTED)", "properties": { "status": { "type": "string", "enum": ["RECEIVED", "REJECTED"] } } } } } } }