A local testnet for Starknet
Project description
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.8.9.
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 -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 -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_full_contract
get_state_update
get_storage_at
get_transaction_receipt
get_transaction_trace
get_transaction
invoke
tx_status
- The following Starknet CLI commands are not supported:
get_contract_addresses
estimate_fee
(currently always returning 0)get_transaction_trace
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. Theaddress
in the body is optional. If provided, theStarknetMockMessaging
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
.
If there is dump.pkl
inside /actual/dumpdir
, you can load it with:
docker run \
-p 127.0.0.1:5000:5000 \
--mount type=bind,source=/actual/dumpdir,target=/dumpdir \
shardlabs/starknet-devnet \
--load-path /dumpdir/dump.pkl
To dump to /actual/dumpdir/dump.pkl
on Devnet shutdown, run:
docker run \
-p 127.0.0.1:5000:5000 \
--mount type=bind,source=/actual/dumpdir,target=/dumpdir \
shardlabs/starknet-devnet \
--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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for starknet_devnet-0.1.19-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ac24c130f584efd0c33603fdd70db480e6870da98322a4ca16e6b986637d1dac |
|
MD5 | 111dd94766ae49cdf8e2a132a7325e84 |
|
BLAKE2b-256 | 1687a90434a38a30a8f6ba3fc86b624ed67191f19c900470bf201a11adc09ab9 |