Release v0.0.6 (#473)

.github/CONTRIBUTING.md

@@ -167,10 +167,10 @@ The documentation website content has [its own readme](../website/README.md).
 
 To release a new version, follow these steps:
 
-1. Increment the semver in Cargo.toml of those Devnet crates that have changed. Use `scripts/check_crate_changes.sh` for this. Preferably create a separate PR for the increment, such as [this one](https://github.com/0xSpaceShard/starknet-devnet-rs/pull/398). In your PR, also add a documentation entry for the incoming version by running:
+1. Increment the semver in Cargo.toml of those Devnet crates that have changed. Use `scripts/check_crate_changes.sh` for this. Preferably create a separate PR for the increment, such as [this one](https://github.com/0xSpaceShard/starknet-devnet-rs/pull/473). In your PR, add a documentation entry for the incoming version by running:
 
    ```
-   npm run docusaurus docs: version <VERSION>
+   npm run docusaurus docs:version <VERSION>
    ```
 
 2. The publishing of crates and Docker images is done automatically in CI when merged into the main branch.

Cargo.toml

@@ -15,10 +15,10 @@ authors = ["Mario"]
 edition = "2021"
 repository = "https://github.com/0xSpaceShard/starknet-devnet-rs"
 license-file = "LICENSE"
-homepage = "https://github.com/0xSpaceShard/starknet-devnet-rs"
+homepage = "https://0xspaceshard.github.io/starknet-devnet-rs"
 description = "A local testnet for Starknet"
 readme = "README.md"
-documentation = "https://github.com/0xSpaceShard/starknet-devnet-rs"
+documentation = "https://0xspaceshard.github.io/starknet-devnet-rs/docs/intro"
 
 exclude = [".github/**", ".devcontainer/**", ".circleci/**"]
 
@@ -92,9 +92,9 @@ cairo-lang-syntax = "=2.6.0"
 cairo-lang-utils = "=2.6.0"
 
 # Inner dependencies
-starknet-types = { version = "0.0.4", path = "crates/starknet-devnet-types", package = "starknet-devnet-types" }
-starknet-core = { version = "0.0.5", path = "crates/starknet-devnet-core", package = "starknet-devnet-core" }
-server = { version = "0.0.5", path = "crates/starknet-devnet-server", package = "starknet-devnet-server" }
+starknet-types = { version = "0.0.5", path = "crates/starknet-devnet-types", package = "starknet-devnet-types" }
+starknet-core = { version = "0.0.6", path = "crates/starknet-devnet-core", package = "starknet-devnet-core" }
+server = { version = "0.0.6", path = "crates/starknet-devnet-server", package = "starknet-devnet-server" }
 
 # Dependabot alerts
 zerocopy = "0.7.31"

crates/starknet-devnet-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "starknet-devnet-core"
-version = "0.0.5"
+version = "0.0.6"
 edition.workspace = true
 repository.workspace = true
 license-file.workspace = true

crates/starknet-devnet-server/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "starknet-devnet-server"
-version = "0.0.5"
+version = "0.0.6"
 edition = "2021"
 repository.workspace = true
 license-file.workspace = true

crates/starknet-devnet-types/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "starknet-devnet-types"
-version = "0.0.4"
+version = "0.0.5"
 edition = "2021"
 description = "Starknet types for the devnet"
 repository.workspace = true

crates/starknet-devnet/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "starknet-devnet"
-version = "0.0.5"
+version = "0.0.6"
 edition = "2021"
 repository.workspace = true
 license-file.workspace = true

website/versioned_docs/version-0.0.6/account-impersonation.md

@@ -0,0 +1,73 @@
+# Account impersonation
+
+Devnet allows you to use impersonated account from mainnet/testnet. This means that a transaction sent from an impersonated account will not fail with an invalid signature error. In the general case, a transaction sent with an account that is not in the local state fails with the aforementioned error. For impersonation to work, Devnet needs to be run in [forking mode](./forking.md).
+
+:::warning Caveat
+
+- Only `INVOKE` and `DECLARE` transactions are supported. `DEPLOY_ACCOUNT` transaction is not supported, but you can create an `INVOKE` transaction to UDC.
+- Overall fee, for transactions sent with an impersonated account, will be lower compared to normal transactions. The reason is that validation part is skipped.
+- The most common way of sending a transaction is via starknet-rs/starknet.js or starkli. Trying to send with an account that **does not** exist even in the origin network will return an error:
+  - In transaction construction, if account nonce is not hardcoded, Devnet is queried and returns `ContractNotFound`.
+  - Otherwise the nonce fetching part is skipped and `InsufficientAccountBalance` is returned.
+
+:::
+
+## API
+
+Account impersonation follows JSON-RPC method specification. Each method returns an empty response:
+
+### devnet_impersonateAccount
+
+Impersonates a specific account address nonexistent in the local state.
+
+```js
+{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "devnet_impersonateAccount",
+    "params": {
+        "account_address": "0x49D36570D4E46F48E99674BD3FCC84644DDD6B96F7C741B1562B82F9E004DC7"
+    }
+}
+```
+
+### devnet_stopImpersonateAccount
+
+Stops the impersonation of an account previously marked for impersonation.
+
+```js
+{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "devnet_stopImpersonateAccount",
+    "params": {
+        "account_address": "0x49D36570D4E46F48E99674BD3FCC84644DDD6B96F7C741B1562B82F9E004DC7"
+    }
+}
+```
+
+### devnet_autoImpersonate
+
+Enables automatic account impersonation. Every account that does not exist in the local state will be impersonated.
+
+```js
+{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "devnet_autoImpersonate",
+    "params": {}
+}
+```
+
+### devnet_stopAutoImpersonate
+
+Stops the effect of [automatic impersonation](#devnet_autoimpersonate).
+
+```js
+{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "devnet_stopAutoImpersonate",
+    "params": {}
+}
+```

website/versioned_docs/version-0.0.6/api.md

@@ -0,0 +1,45 @@
+# API
+
+## Starknet API
+
+Unlike Pythonic Devnet, which also supported Starknet's gateway and feeder gateway API, Devnet in Rust supports Starknet's JSON-RPC API. Since JSON-RPC v0.6.0, to find out which JSON-RPC version is supported by which Devnet version, check out the [releases page](https://github.com/0xspaceshard/starknet-devnet-rs/releases).
+
+The JSON-RPC API is reachable via `/rpc` and `/` (e.g. if spawning Devnet with default settings, these URLs are functionally equivalent: `http://127.0.0.1:5050/rpc` and `http://127.0.0.1:5050/`)
+
+## Devnet API
+
+Devnet has many other functional features which are available via their own endpoints, which are all mentioned throughout the documentation.
+
+## Config API
+
+To retrieve the current configuration of Devnet, send a `GET` request to `/config`. Example response is attached below. It can be interpreted as a JSON mapping of CLI input parameters, both specified and default ones, with some irrelevant parameters omitted. So use `starknet-devnet --help` to better understand the meaning of each value, though keep in mind that some of the parameters have slightly modified names.
+
+```json
+{
+  "seed": 4063802897,
+  "total_accounts": 10,
+  "account_contract_class_hash": "0x61dac032f228abef9c6626f995015233097ae253a7f72d68552db02f2971b8f",
+  "predeployed_accounts_initial_balance": "1000000000000000000000",
+  "start_time": null,
+  "gas_price_wei": 100000000000,
+  "gas_price_strk": 100000000000,
+  "data_gas_price_wei": 100000000000,
+  "data_gas_price_strk": 100000000000,
+  "chain_id": "SN_SEPOLIA",
+  "dump_on": "exit",
+  "dump_path": "dump_path.json",
+  "state_archive": "none",
+  "fork_config": {
+    "url": "http://rpc.pathfinder.equilibrium.co/integration-sepolia/rpc/v0_7",
+    "block_number": 26429
+  },
+  "server_config": {
+    "host": "127.0.0.1",
+    "port": 5050,
+    "timeout": 120,
+    "request_body_size_limit": 2000000
+  },
+  "blocks_on_demand": false,
+  "lite_mode": false
+}
+```

website/versioned_docs/version-0.0.6/balance.md

@@ -0,0 +1,41 @@
+# Account balance
+
+Other than using prefunded predeployed accounts, you can also add funds to an account that you deployed yourself.
+
+Separate tokens use separate ERC20 contracts for minting and charging fees. These are the token contracts predeployed by Devnet and the addresses where they are located:
+
+- ETH: `0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7`
+- STRK: `0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d`
+
+## Mint token - Local faucet
+
+By sending a `POST` request to `/mint` for a token, you initiate a transaction on that token's ERC20 contract. The response contains the hash of this transaction, as well as the new balance after minting. The token is specified by providing the unit, and defaults to `WEI`.
+
+The value of `amount` is in WEI and needs to be an integer (or a float whose fractional part is 0, e.g. `1000.0` or `1e21`)
+
+```
+POST /mint
+{
+    "address": "0x6e3205f...",
+    "amount": 500000,
+    "unit": "WEI" | "FRI"
+}
+```
+
+Response:
+
+```
+{
+    "new_balance": 500000,
+    "unit": "WEI" | "FRI",
+    "tx_hash": "0xa24f23..."
+}
+```
+
+## Check balance
+
+Check the balance of an address by sending a `GET` request to `/account_balance`. The address should be a 0x-prefixed hex string; `unit` defaults to `WEI` and `block_tag` to `latest`.
+
+```
+GET /account_balance?address=<ADDRESS>[&unit=<FRI|WEI>][&block_tag=<latest|pending>]
+```

website/versioned_docs/version-0.0.6/blocks.md

@@ -0,0 +1,66 @@
+# Blocks
+
+Devnet starts with a genesis block (with a block number equal to 0). In forking mode, the genesis block number will be equal to forked block number plus one.
+
+A new block is generated with each new transaction, and you can create an empty block by yourself.
+
+## Creating blocks on demand
+
+If you start Devnet with the `--blocks-on-demand` CLI option, all valid transactions will be stored in a pending block (targetable via block tag `"pending"`).
+
+To create a block on demand, send a `POST` request to `/create_block`. This will convert the pending block to the latest block (targetable via block tag `"latest"`), giving it a block hash and a block number. All subsequent transactions will be stored in a new pending block.
+
+In case of demanding block creation with no pending transactions, a new empty block will be generated.
+
+The creation of the genesis block is not affected by this feature.
+
+```
+POST /create_block
+```
+
+Response:
+
+```
+{'block_hash': '0x115e1b390cafa7942b6ab141ab85040defe7dee9bef3bc31d8b5b3d01cc9c67'}
+```
+
+## Create an empty block
+
+To create an empty block without transactions, `POST` a request to /create_block:
+
+```
+POST /create_block
+```
+
+Response:
+
+```
+{"block_hash": "0x115e1b390cafa7942b6ab141ab85040defe7dee9bef3bc31d8b5b3d01cc9c67"}
+```
+
+## Abort blocks
+
+This functionality allows to simulate block abortion that can occur on mainnet.
+
+You can abort blocks and revert transactions from the specified block to the currently latest block. Newly created blocks after the abortion will have accepted status and will continue with numbering where the last accepted block left off.
+
+The state of Devnet will be reverted to the state of the last accepted block.
+
+E.g. assume there are 3 accepted blocks numbered 1, 2 and 3. Upon receiving a request to abort blocks starting with block 2, the blocks numbered 2 and 3 are aborted and their transactions reverted. The state of network will be as it was in block 1. Once a new block is mined, it will be accepted and it will have number 2.
+
+Aborted blocks can only be queried by block hash. Aborting the blocks in forking origin and already aborted blocks is not supported and results in an error.
+
+```
+POST /abort_blocks
+{
+    "starting_block_hash": BLOCK_HASH
+}
+```
+
+Response:
+
+```
+{
+    "aborted": [BLOCK_HASH_0, BLOCK_HASH_1, ...]
+}
+```

website/versioned_docs/version-0.0.6/dump-load-restart.md

@@ -0,0 +1,54 @@
+# Dump, load, restart
+
+## Dumping
+
+To preserve your Devnet instance for future use, these are the 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 block:
+
+```
+$ starknet-devnet --dump-on block --dump-path <PATH>
+```
+
+- Dumping on request requires providing --dump-on mode on the startup. Example usage in `exit` mode (replace `<HOST>`, `<PORT>` and `<PATH>` with your own):
+
+```
+$ starknet-devnet --dump-on exit --dump-path <PATH>
+$ curl -X POST http://<HOST>:<PORT>/dump -d '{ "path": <PATH> }' -H "Content-Type: application/json"
+```
+
+## Loading
+
+To load a preserved Devnet instance, the options are:
+
+- Loading on startup (note the argument name is not `--load-path` as it was in Devnet-py):
+
+```
+$ starknet-devnet --dump-path <PATH>
+```
+
+- Loading on request:
+
+```
+curl -X POST http://<HOST>:<PORT>/load -d '{ "path": <PATH> }' -H "Content-Type: application/json"
+```
+
+Currently, dumping produces a list of received transactions that is stored on disk. Conversely, loading is implemented as the re-execution of transactions from a dump. This means that timestamps of `StarknetBlock` will be different on each load.
+
+### Loading disclaimer
+
+Dumping and loading are not guaranteed to work across versions. I.e. if you dumped one version of Devnet, do not expect it to be loadable with a different version.
+
+If you dumped a Devnet utilizing one class for account predeployment (e.g. `--account-class cairo0`), you should use the same option when loading. The same applies for dumping a Devnet in `--blocks-on-demand` mode.
+
+## Restarting
+
+Devnet can be restarted by making a `POST /restart` request (no body required). All of the deployed contracts (including predeployed), blocks and storage updates will be restarted to the original state, without the transactions and requests that may have been loaded from a dump file on startup.
+
+If you're using [**the Hardhat plugin**](https://github.com/0xSpaceShard/starknet-hardhat-plugin#restart), restart with `starknet.devnet.restart()`.