starknet-devnet 0.1.18

A local testnet for Starknet

Introduction

A Flask wrapper of Starknet state. Similar in purpose to Ganache.

Aims to mimic Starknet's Alpha testnet, but with simplified functionality.

Contents

• Install
• Disclaimer
• Run
• Interaction
• Dumping and Loading
• Hardhat integration
• L1-L2 Postman communication
• Block explorer
• Development

Install

pip install starknet-devnet

Requirements

Works with Python versions <=3.9.10.

On Ubuntu/Debian, first run:

sudo apt install -y libgmp3-dev

On Mac, you can use brew:

brew install gmp

Disclaimer

• Devnet should not be used as a replacement for Alpha testnet. After testing on Devnet, be sure to test on testnet!
• Specifying a block by its hash/number is not supported. All interaction is done with the latest block.
• Read more in interaction.

Run

Installing the package adds the starknet-devnet command.

usage: starknet-devnet [-h] [-v] [--host HOST] [--port PORT]

Run a local instance of Starknet Devnet

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         Print the version
  --host HOST           Specify the address to listen at; defaults to localhost (use the address the program outputs on start)
  --port PORT, -p PORT  Specify the port to listen at; defaults to 5000
  --load-path LOAD_PATH
                        Specify the path from which the state is loaded on
                        startup
  --dump-path DUMP_PATH
                        Specify the path to dump to
  --dump-on DUMP_ON     Specify when to dump; can dump on: exit, transaction

Run with Docker

Devnet is available as a Docker container (shardlabs/starknet-devnet):

docker pull shardlabs/starknet-devnet

The server inside the container listens to the port 5000, which you need to publish to a desired <PORT> on your host machine:

docker run -it -p [HOST:]<PORT>:5000 shardlabs/starknet-devnet

E.g. if you want to use your host machine's 127.0.0.1:5000, you need to run:

docker run -it -p 127.0.0.1:5000:5000 shardlabs/starknet-devnet

You may ignore any address-related output logged on container startup (e.g. Running on all addresses or Running on http://172.17.0.2:5000). What you will use is what you specified with the -p argument.

If you don't specify the HOST part, the server will indeed be available on all of your host machine's addresses (localhost, local network IP, etc.), which may present a security issue if you don't want anyone from the local network to access your Devnet instance.

Interaction

• Interact with Devnet as you would with the official Starknet Alpha testnet.
• The exact underlying API is not exposed for the same reason Alpha testnet does not expose it.
• To use Devnet with Starknet CLI, provide Devnet's URL to the --gateway_url and --feeder_gateway_url options of Starknet CLI commands.
• The following Starknet CLI commands are supported:
  • call
  • deploy
  • get_block
  • get_code
  • get_storage_at
  • get_transaction
  • invoke
  • tx_status
  • get_transaction_receipt
  • get_full_contract
• The following Starknet CLI commands are not supported:
  • get_contract_addresses
  • get_state_update

Hardhat integration

• If you're using the Hardhat plugin, see here on how to edit its config file to integrate Devnet.

Postman integration

Postman is a Starknet utility that allows testing L1 <> L2 interactions. To utilize functionality, you can use starknet-hardhat-plugin, as witnessed in this example. Or you can directly interact with the two Postman-specific endpoints:

• Load a StarknetMockMessaging contract. The address in the body is optional. If provided, the StarknetMockMessaging contract will be fetched from that address, otherwise a new one will be deployed:

  • POST "/postman/load_l1_messaging_contract"
  • body: { "networkUrl":"http://localhost:5005", "address":"0x83D76591560d9CD02CE16c060c92118d19F996b3" }

• Flush. This will go through the new enqueued messages sent from L1 and send them to L2. This has to be done manually for L1 -> L2, but for L2 -> L1, it is done automatically:

  • POST "/postman/flush"
  • no body

This method of L1 <> L2 communication testing differs from Starknet Alpha networks. Taking the L1L2Example.sol contract in the starknet documentation:

constructor(IStarknetCore starknetCore_) public {
        starknetCore = starknetCore_;
}

The constructor takes an IStarknetCore contract as argument, however for devnet L1 <> L2 communication testing, this will have to be replaced with the MockStarknetMessaging.sol contract:

constructor(MockStarknetMessaging mockStarknetMessaging_) public {
    starknetCore = mockStarknetMessaging_;
}

Dumping

To preserve your Devnet instance for future use, there are several options:

• Dumping on exit (handles Ctrl+C, i.e. SIGINT, doesn't handle SIGKILL):

starknet-devnet --dump-on exit --dump-path <PATH>

• Dumping after each transaction (done in background, doesn't block):

starknet-devnet --dump-on transaction --dump-path <PATH>

• Dumping on request (replace <HOST>, <PORT> and <PATH> with your own):

curl -X POST http://<HOST>:<PORT>/dump -d '{ "path": <PATH> }' -H "Content-Type: application/json"

Loading

To load a preserved Devnet instance, run:

starknet-devnet --load-path <PATH>

Enabling dumping and loading with Docker

To enable dumping and loading if running Devnet in a Docker container, you must bind the container path with the path on your host machine.

This example:

• Relies on Docker bind mount; try Docker volume instead.
• Assumes that /actual/dumpdir exists. If unsure, use absolute paths.
• Assumes you are listening on 127.0.0.1:5000. However, leave the --host 0.0.0.0 part as it is.

If there is dump.pkl inside /actual/dumpdir, you can load it with:

docker run -it \
  -p 127.0.0.1:5000:5000 \
  --mount type=bind,source=/actual/dumpdir,target=/dumpdir \
  shardlabs/starknet-devnet \
  poetry run starknet-devnet \
  --host 0.0.0.0 --port 5000 \
  --load-path /dumpdir/dump.pkl

To dump to /actual/dumpdir/dump.pkl on Devnet shutdown, run:

docker run -it \
  -p 127.0.0.1:5000:5000 \
  --mount type=bind,source=/actual/dumpdir,target=/dumpdir \
  shardlabs/starknet-devnet \
  poetry run starknet-devnet \
  --host 0.0.0.0 --port 5000 \
  --dump-on exit --dump-path /dumpdir/dump.pkl

Block explorer

To see how to setup a local block explorer (Voyager) check this post.

Development

If you're a developer willing to contribute, be sure to have installed Poetry.

Development - Run

poetry run starknet-devnet

Development - Test

When running tests locally, do it from the project root.

Setup an example project by running:

./scripts/setup_example.sh

To see if Devnet can interact with starknet CLI commands, run:

python3 -m test.test_cli
python3 -m test.test_cli_auth

To see if Devnet can interact with the Hardhat plugin, set environment variables HARDHAT_CONFIG_FILE and TEST_FILE and run:

./test/test_plugin.sh

Other tests in the test directory use pytest, so run them with:

poetry run pytest <TEST_FILE>

Development - Build

You don't need to build anything to be able to run locally, but if you need the *.whl or *.tar.gz artifacts, run

poetry build