Skip to content

katana reference


katana - Create a local testnet node for deploying and testing Starknet smart contracts.


katana [OPTIONS]


Create a local testnet node for deploying and testing Starknet smart contracts. Katana supports deployment and execution of the new as well as the legacy (Cairo 0) Cairo contracts.

This section covers an extensive list of information about Mining Modes, Supported RPC Methods, Katana flags and their usages. You can run multiple flags at the same time.

Mining Modes

In Katana, mining modes determine how frequent blocks are mined. By default, a new block is automatically mined as soon as a transaction is submitted.

You can switch from the default mining behaviour to interval mining, where a new block is created at a fixed time interval selected by the user. To enable this mode of mining, use the --block-time <MILLISECONDS> flag, as demonstrated in the following example.

# Produces a new block every 10 seconds
katana --block-time 10000


Katana supports forking from a Starknet RPC provider. You can configure your node to enable the forking feature by providing a valid RPC provider using the --rpc-url <URL> flag., which would initiate Katana to fork the latest block of the provided network. If you would like to fork from a specific block, you can do so using --fork-block-number <BLOCK_NUMBER>.

NOTE: This does not allow fetching of historical blocks but only blocks that are mined by Katana. However, support for fetching historical blocks will be added in the future.

# Forks the network at block 1200
katana --rpc-url --fork-block-number 1200


Katana also allows users to perform L1 <-> L2 integration using the messaging feature. There are two types of messaging service supported by Katana:

  1. Ethereum
  2. Starknet (experimental)

If configured to Ethereum messaging, Katana will listen/send messages on an Ethereum chain. This type of messaging behaves similar to the canonical Starknet sequencer with the exception that messages from L2 -> L1 will be sent directly to the settlement chain for consumption, instead of having to wait for the corresponding blocks of the messages to be proven on the settlement chain (which in reality would be a very time consuming process).

The Starknet messaging, however, is an experimental feature that allows Katana to listen/send messages on a Starknet chain. It attempts to replicate the behaviour of Ethereum messaging but with a Starknet chain as the settlement layer. This is achieved by having Katana listen to the Starknet chain for new blocks and then sending the messages to the settlement chain for consumption. This is an experimental and opinionated feature, and is not recommended for production use.

katana --messaging path/to/messaging/config.json

The messaging config file is a JSON file that contains the following fields:

  /// The type of messaging service to use. Can be either "ethereum" or "starknet".
  "chain": "ethereum",
  /// The RPC-URL of the settlement chain.
  "rpc_url": "",
  /// The messaging-contract address on the settlement chain.
  "contract_address": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
  /// The address to use for settling messages. It should be a valid address that
  /// can be used to send a transaction on the settlement chain.
  "sender_address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  /// The private key associated to `sender_address`.
  "private_key": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
  /// The interval, in seconds, at which the messaging service will fetch and settle messages
  /// from/to the settlement chain.
  "interval": 2,
  /// The block on settlement chain from where Katana will start fetching messages.
  "from_block": 0

Supported Transport Layers

Only HTTP connection is supported at the moment. The server listens on port 5050 by default, but it can be changed by running the following command:

katana --port <PORT>

Starknet Feature Compatibility

Supported Transaction Type

Supported RPC Methods

Starknet Methods

Katana supports version v0.3.0 of the Starknet JSON-RPC specifications. The standard methods are based on this reference.

  • starknet_blockNumber

  • starknet_blockHashAndNumber

  • starknet_getBlockWithTxs

  • starknet_getBlockWithTxHashes

  • starknet_getBlockTransactionCount

  • starknet_getTransactionByHash

  • starknet_getTransactionByBlockIdAndIndex

  • starknet_getTransactionReceipt

  • starknet_pendingTransactions

  • starknet_getStateUpdate

  • starknet_call

  • starknet_estimateFee

  • starknet_chainId

  • starknet_getNonce

  • starknet_getEvents

  • starknet_getStorageAt

  • starknet_getClassHashAt

  • starknet_getClass

  • starknet_getClassAt
  • starknet_addInvokeTransaction

  • starknet_addDeclareTransaction

  • starknet_addDeployAccountTransaction

Custom Methods

Katana provides a convenient set of custom RPC methods to quickly and easily configure the node to suit your testing environment.

Mine a new block which includes all currently pending transactions.

Get the time for the next block.

Increase the time for the block by a given amount of time, in seconds.

Similar to katana_increaseNextBlockTimestamp but takes the exact timestamp that you want in the next block.

Get the info for all of the predeployed accounts.

Set an exact value of a contract's storage slot.


General Options

     Don't print anything on startup.

     Disable auto and interval mining, and mine on demand instead.

-b, --block-time <MILLISECONDS>
     Block time in milliseconds for interval mining.

--dump-state <PATH>
     Dump the state of chain on exit to the given file.
     If the value is a directory, the state will be written to <PATH>/state.bin.

--rpc-url <URL>
     The Starknet RPC provider to fork the network from.

     Output logs in JSON format.

--fork-block-number <BLOCK_NUMBER>
     Fork the network at a specific block.

--messaging <PATH>
     Configure the messaging service to allow Katana to listen/send messages on a settlement chain that can be either Ethereum or another Starknet sequencer (experimental).

-h, --help
     Print help (see a summary with '-h').

-V, --version
     Print version information.

Server Options

-p, --port <PORT>
     Port number to listen on. [default: 5050]

--host <HOST>
     The IP address the server will listen on.

Starknet Options

--seed <SEED>
     Specify the seed for randomness of accounts to be predeployed.

--accounts <NUM>
     Number of pre-funded accounts to generate. [default: 10]

     Disable charging fee for transactions.

Environment Options

--chain-id <CHAIN_ID>
     The chain ID. [default: KATANA]

--gas-price <GAS_PRICE>
     The gas price.

--validate-max-steps <VALIDATE_MAX_STEPS>
     The maximum number of steps available for the account validation logic.

--invoke-max-steps <INVOKE_MAX_STEPS>
     The maximum number of steps available for the account execution logic.

Shell Completions

katana completions shell

Generates a shell completions script for the given shell.

Supported shells are:

  • bash
  • elvish
  • fish
  • powershell
  • zsh


Generate shell completions script for bash and appends it to a .bashrc file:

katana completions bash >> ~/.bashrc


  1. Create 15 dev accounts and disable transaction fee mechanism
katana --accounts 15 --disable-fee
  1. Set the chain id to SN_GOERLI and run the server on port 8545
katana --chain-id SN_GOERLI --port 8545
  1. Load previously stored state and dump the state of this session to a file on shutdown
katana --load-state ./dump-state.bin --dump-state ./dump-state.bin