Interacting with Madara
Methods

Starknet JSON-RPC methods

ℹ️

Info: Madara is currently supporting the latest version of Starknet mainnet official JSON-RPC specs (opens in a new tab). For more informations regarding the current and upcoming releases please reffer to the Version section.

The primary functionality of a full node is to access the state of the network it synchronizes with. To facilitate this, Starknet has implemented a list of access methods that can be found in the official JSON-RPC specs (opens in a new tab). Currently, these methods fall into three categories:

  • Read-Only Access Methods: These methods provide access to network information in a read-only mode, meaning they do not alter the network's state. Some offer static access while others might trigger client execution calls.
  • Trace Generation Methods: These methods generate a trace from a transaction's execution to provide detailed information about state changes.
  • Write Methods: These methods aim to directly modify Starknet's state, for example by deploying a new contract or executing a transaction.
⚠

Warning: Write methods are not executed by full node clients themselves but are merely forwarded to the Sequencer, which is responsible for constructing the blocks and state or returning the corresponding error.

Each method adheres to a schema that may or may not contain parameters and may return a result or an error. A method is structured as follows:

{
    "name": "starknet_ followed by the name of your method",
    "summary": "Description summary of your method",
    "params?": [
        {
            "name": "Parameter A name",
            "description": "Description of Parameter A",
            "required": true or false,
            "schema": {
                "title": "Title of the parameter schema",
                "PARAMETER_A_TYPE"
            }
        },
        {
            "name": "Parameter B name",
            "description": "Description of Parameter B",
            "required": true or false,
            "schema": {
                "title": "Title of the parameter schema",
                "PARAMETER_B_TYPE"
            }
        }
    ],
    "result": {
        "name": "Result",
        "description": "Description of the result",
        "schema": {
            "title": "Title of the result schema",
            "oneOf?": [
                {
                    "title": "Expected output A",
                    "RESULT_A_TYPE"
                },
                {
                    "title": "Expected output B",
                    "RESULT_B_TYPE"
                }
            ]
        }
    },
    "errors": [
        {
            "ERROR_TYPE"
        }
    ]
}

Each method has its own specific features and schema. Detailed information on each call can be expanded upon for the following APIs:

⚠

Warning: Please refer to the official JSON-RPC specs (opens in a new tab) for up to date data.

ℹ️

Info: You can play with the Voyager playground (opens in a new tab) or the OPEN-RPC (opens in a new tab) interface to get more familiar with those methods.

Read API

starknet_specVersion

Returns the version of the Starknet JSON-RPC specification being used.

  • Params: None - Result: Semver of Starknet's JSON-RPC spec being used (type: string)

starknet_getBlockWithTxHashes

Get block information with transaction hashes given the block id.
  • Params:
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag (required)
  • Result: The resulting block information with transaction hashes
  • Errors:
    • BLOCK_NOT_FOUND: If the specified block does not exist

starknet_getBlockWithReceipts

Get block information with transaction hashes given the block id.
  • Params:
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag (required)
  • Result: The resulting block information with transaction hashes
  • Errors:
    • BLOCK_NOT_FOUND: If the specified block does not exist

starknet_getBlockWithTxs

Get block information with full transactions given the block id.
  • Params:
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag (required)
  • Result: The resulting block information with full transactions
  • Errors:
    • BLOCK_NOT_FOUND: If the specified block does not exist

starknet_getStateUpdate

Get the information about the result of executing the requested block.
  • Params:
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag (required)
  • Result: The information about the state update of the requested block
  • Errors:
    • BLOCK_NOT_FOUND: If the specified block does not exist

starknet_getStorageAt

Get the value of the storage at the given address and key.
  • Params:
    • contract_address: The address of the contract to read from (required)
    • key: The key to the storage value for the given contract (required)
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag (required)
  • Result: The value at the given key for the given contract. Returns 0 if no value is found.
  • Errors:
    • CONTRACT_NOT_FOUND: If the specified contract does not exist
    • BLOCK_NOT_FOUND: If the specified block does not exist

starknet_getTransactionStatus

Gets the transaction status, potentially indicating if the transaction is still in the mempool or has been dropped.
  • Params:
    • transaction_hash: The hash of the requested transaction (required)
  • Result:
    • finality_status: The finality status of the transaction
    • execution_status: The execution status of the transaction
  • Errors:
    • TXN_HASH_NOT_FOUND: If the transaction hash does not exist

starknet_getTransactionByHash

Retrieves the details and status of a submitted transaction.
  • Params:
    • transaction_hash: The hash of the requested transaction (required)
  • Result:
    • transaction: The details of the transaction including the transaction hash
  • Errors:
    • TXN_HASH_NOT_FOUND: If the transaction hash does not exist

starknet_getTransactionByBlockIdAndIndex

Obtains the details of a transaction by a specified block id and index within that block. If not found, returns null.
  • Params:
    • block_id: The hash, number (height), or tag of the requested block (required)
    • index: The index within the block to look for the transaction (required)
  • Result:
    • transactionResult: The details of the transaction if found
  • Errors:
    • BLOCK_NOT_FOUND: If the block does not exist
    • INVALID_TXN_INDEX: If the transaction index is invalid or does not exist in the block

starknet_getTransactionReceipt

Acquires the receipt of a transaction using its hash.
  • Params:
    • transaction_hash: The hash of the requested transaction (required)
  • Result:
    • result: The transaction receipt, or pending transaction receipt if applicable
  • Errors:
    • TXN_HASH_NOT_FOUND: If the transaction hash does not exist

starknet_getClass

Fetches the contract class definition within a given block associated with a specified hash.
  • Params:
    • block_id: The hash, number (height), or tag of the requested block (required)
    • class_hash: The hash of the requested contract class (required)
  • Result:
    • result: The contract class information, if available
  • Errors:
    • BLOCK_NOT_FOUND: If the block does not exist
    • CLASS_HASH_NOT_FOUND: If the contract class hash does not exist

starknet_getClassHashAt

Retrieves the class hash of a contract deployed at a specific address within a given block.
  • Params:
    • block_id: The hash, number (height), or tag of the requested block (required)
    • contract_address: The address of the contract (required)
  • Result:
    • result: The class hash of the specified contract
  • Errors:
    • BLOCK_NOT_FOUND: If the block does not exist
    • CONTRACT_NOT_FOUND: If the contract at the given address does not exist

starknet_getClassAt

Get the contract class definition in the given block at the given address.
  • Params:
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag (required)
    • contract_address: The address of the contract whose class definition will be returned (required)
  • Result:
    • result: The contract class, which may be a deprecated contract class or the current contract class
  • Errors:
    • BLOCK_NOT_FOUND: If the block does not exist
    • CONTRACT_NOT_FOUND: If the contract at the given address does not exist

starknet_getBlockTransactionCount

Get the number of transactions in a block given a block id.
  • Description: Returns the number of transactions in the designated block.
  • Params:
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag (required)
  • Result:
    • result: The number of transactions in the designated block
  • Errors:
    • BLOCK_NOT_FOUND: If the block does not exist

starknet_call

Call a StarkNet function without creating a StarkNet transaction.
  • Description: Calls a function in a contract and returns the return value. Using this call will not create a transaction; hence, will not change the state.
  • Params:
    • request: The details of the function call (required)
    • block_id: 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)
  • Result:
    • result: The function's return value, as defined in the Cairo output
  • Errors:
    • CONTRACT_NOT_FOUND: If the contract at the given address does not exist
    • CONTRACT_ERROR: If there is an error with the contract during the call
    • BLOCK_NOT_FOUND: If the block does not exist

starknet_estimateFee

Estimate the fee for StarkNet transactions.
  • Description: Estimates the resources required by transactions when applied on a given state.
  • Params:
    • request: The transaction to estimate, consisting of a sequence of transactions to estimate, running each transaction on the state resulting from applying all the previous ones (required)
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag, for the block referencing the state to call the transaction on (required)
  • Result:
    • result: The fee estimations, a sequence of fee estimations where the i'th estimate corresponds to the i'th transaction
  • Errors:
    • CONTRACT_NOT_FOUND: If the contract at the given address does not exist
    • CONTRACT_ERROR: If there is an error with the contract during the call
    • BLOCK_NOT_FOUND: If the block does not exist

starknet_estimateMessageFee

Estimate the L2 fee of a message sent on L1.
  • Params:
    • message: The message's parameters (required)
    • block_id: 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)
  • Result:
    • result: The fee estimation
  • Errors:
    • CONTRACT_NOT_FOUND: If the contract related to the message cannot be found
    • CONTRACT_ERROR: If there is an error with the contract during fee estimation
    • BLOCK_NOT_FOUND: If the block does not exist

starknet_blockNumber

Get the most recent accepted block number.
  • Result:
    • result: The latest block number
  • Errors:
    • NO_BLOCKS: If there are no blocks to reference

starknet_blockHashAndNumber

Get the most recent accepted block hash and number.
  • Result:
    • result: The latest block hash and number
  • Errors:
    • NO_BLOCKS: If there are no blocks to reference

starknet_chainId

Return the currently configured StarkNet chain id.
  • Result:
    • result: The chain id this node is connected to

starknet_syncing

Returns an object about the sync status, or false if the node is not synching.
  • Result:
    • syncing: The state of the synchronization, or false if the node is not synchronizing

starknet_getEvents

Returns all events matching the given filter.
  • Params:
    • filter: The conditions used to filter the returned events (required)
  • Result:
    • events: All the event objects matching the filter
  • Errors:
    • PAGE_SIZE_TOO_BIG: If the page size of the request is too large
    • INVALID_CONTINUATION_TOKEN: If the continuation token provided is invalid
    • BLOCK_NOT_FOUND: If the specified block does not exist
    • TOO_MANY_KEYS_IN_FILTER: If there are too many keys in the filter

starknet_getNonce

Get the nonce associated with the given address in the given block.
  • Params:
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag (required)
    • contract_address: The address of the contract whose nonce we're seeking (required)
  • Result:
    • result: The contract's nonce at the requested state
  • Errors:
    • BLOCK_NOT_FOUND: If the block does not exist
    • CONTRACT_NOT_FOUND: If the contract at the given address does not exist

Trace API

starknet_traceTransaction

For a given executed transaction, return the trace of its execution, including internal calls.
  • Params:
    • transaction_hash: The hash of the transaction to trace (required)
  • Result:
    • trace: The function call trace of the transaction designated by the given hash
  • Errors:
    • TXN_HASH_NOT_FOUND: If the transaction hash does not exist
    • NO_TRACE_AVAILABLE: If no trace is available for the transaction

starknet_simulateTransactions

Simulate a given sequence of transactions on the requested state, and generate the execution traces.
  • Params:
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag, for the block referencing the state to call the transaction on (required)
    • transactions: The transactions to simulate (required)
    • simulation_flags: Describes what parts of the transaction should be executed (required)
  • Result:
    • simulated_transactions: The execution trace and consumed resources of the required transactions
  • Errors:
    • BLOCK_NOT_FOUND: If the specified block does not exist
    • TRANSACTION_EXECUTION_ERROR: If a transaction simulation fails

starknet_traceBlockTransactions

Retrieve traces for all transactions in the given block.
  • Params:
    • block_id: The hash of the requested block, or number (height) of the requested block, or a block tag (required)
  • Result:
    • traces: The traces of all transactions in the block
  • Errors:
    • BLOCK_NOT_FOUND: If the block does not exist

Write API

starknet_addInvokeTransaction

Submit a new transaction to be added to the chain.
  • Params:
    • invoke_transaction: The information needed to invoke the function (or account, for version 1 transactions) (required)
  • Result:
    • result: Contains the hash of the invoke transaction
      • transaction_hash: The hash of the invoke transaction
  • Errors:
    • INSUFFICIENT_ACCOUNT_BALANCE: If the account balance is insufficient
    • INSUFFICIENT_MAX_FEE: If the provided max fee is insufficient
    • INVALID_TRANSACTION_NONCE: If the transaction nonce is invalid
    • VALIDATION_FAILURE: If the transaction fails validation checks
    • NON_ACCOUNT: If a non-account tries to execute an account-specific transaction
    • DUPLICATE_TX: If the transaction is a duplicate
    • UNSUPPORTED_TX_VERSION: If the transaction version is unsupported
    • UNEXPECTED_ERROR: In case of an unexpected error

starknet_addDeclareTransaction

Submit a new class declaration transaction.
  • Params:
    • declare_transaction: Declare transaction required to declare a new class on Starknet (required)
  • Result:
    • result: Contains the hash of the declare transaction and the hash of the declared class
      • transaction_hash: The hash of the declare transaction
      • class_hash: The hash of the declared class
  • Errors:
    • CLASS_ALREADY_DECLARED: If the class has already been declared
    • COMPILATION_FAILED: If the compilation of the class failed
    • COMPILED_CLASS_HASH_MISMATCH: If the compiled class hash does not match the declared one
    • INSUFFICIENT_ACCOUNT_BALANCE: If the account balance is insufficient
    • INSUFFICIENT_MAX_FEE: If the max fee provided is insufficient
    • INVALID_TRANSACTION_NONCE: If the transaction nonce is invalid
    • VALIDATION_FAILURE: If the transaction fails validation checks
    • NON_ACCOUNT: If a non-account tries to execute an account-specific transaction
    • DUPLICATE_TX: If the transaction is a duplicate
    • CONTRACT_CLASS_SIZE_IS_TOO_LARGE: If the declared contract class is too large
    • UNSUPPORTED_TX_VERSION: If the transaction version is unsupported
    • UNSUPPORTED_CONTRACT_CLASS_VERSION: If the contract class version is unsupported
    • UNEXPECTED_ERROR: In case of an unexpected error

starknet_addDeployAccountTransaction

Submit a new deploy account transaction.
  • Params:
    • deploy_account_transaction: The deploy account transaction (required)
  • Result:
    • result: Contains the hash of the deploy transaction and the address of the new contract
      • transaction_hash: The hash of the deploy transaction
      • contract_address: The address of the new contract
  • Errors:
    • INSUFFICIENT_ACCOUNT_BALANCE: If the account balance is insufficient
    • INSUFFICIENT_MAX_FEE: If the provided max fee is insufficient
    • INVALID_TRANSACTION_NONCE: If the transaction nonce is invalid
    • VALIDATION_FAILURE: If the transaction fails validation checks
    • NON_ACCOUNT: If a non-account tries to execute an account-specific transaction
    • CLASS_HASH_NOT_FOUND: If the class hash referred to by the transaction cannot be found
    • DUPLICATE_TX: If the transaction is a duplicate
    • UNSUPPORTED_TX_VERSION: If the transaction version is unsupported
    • UNEXPECTED_ERROR: In case of an unexpected error
ServerTelemetry