Update katana section

dojoengine · Aug 14, 2023 · ce3aaf4 · ce3aaf4
1 parent 434e6d3
commit ce3aaf4
Show file tree

Hide file tree

Showing 2 changed files with 85 additions and 33 deletions.
diff --git a/src/toolchain/katana/overview.md b/src/toolchain/katana/overview.md
@@ -5,14 +5,15 @@
 ### Features
 
 -   [Starknet JSON-RPC v0.3.0](https://github.com/starkware-libs/starknet-specs/tree/v0.3.0) support
+-   Custom methods for manipulating the blockchain states
 
 ## Installation
 
 `katana` binary is available via [`dojoup`](../../getting-started/quick-start.md).
 
 ### Installing from source
 
-```bash
+```sh
 git clone https://github.com/dojoengine/dojo
 cd dojo
 cargo install --path ./crates/katana --locked --force
@@ -37,13 +38,18 @@ $ katana
 PREFUNDED ACCOUNTS
 ==================
 
-| Account address |  0x06f62894bfd81d2e396ce266b2ad0f21e0668d604e5bb1077337b6d570a54aea
-| Private key     |  0x07230b49615d175307d580c33d6fda61fc7b9aec91df0f5c1a5ebe3b8cbfee02
-| Public key      |  0x078e6e3e4a50285be0f6e8d0b8a61044033e24023df6eb95979ae4073f159ae6
+| Account address |  0x3ee9e18edc71a6df30ac3aca2e0b02a198fbce19b7480a63a0d71cbd76652e0
+| Private key     |  0x300001800000000300000180000000000030000000000003006001800006600
+| Public key      |  0x1b7b37a580d91bc3ad4f9933ed61f3a395e0e51c9dd5553323b8ca3942bb44e
 
-| Account address |  0x04b352538f61697825af242c9c451df02a40cca99391a47054489dee82138008
-| Private key     |  0x0326b6d921c2d9c9b76bb641c433c94b030cf57d48803dc742729704ffdd0fc6
-| Public key      |  0x0564a13ba4d4cf95a60f78ca05fc04ff6845736e2f04b3c6703283cdf65e2615
+| Account address |  0x33c627a3e5213790e246a917770ce23d7e562baa5b4d2917c23b1be6d91961c
+| Private key     |  0x333803103001800039980190300d206608b0070db0012135bd1fb5f6282170b
+| Public key      |  0x4486e2308ef3513531042acb8ead377b887af16bd4cdd8149812dfef1ba924d
+
+
+ACCOUNTS SEED
+=============
+0
 
 
 🚀 JSON-RPC server started: http://127.0.0.1:5050
@@ -53,4 +59,4 @@ PREFUNDED ACCOUNTS
 
 > 📚 **Reference**
 >
-> See the [`katana` Reference](./reference.md) for in full reference.
+> See the [`katana` Reference](./reference.md) for an in depth reference and documentation on Katana.
diff --git a/src/toolchain/katana/reference.md b/src/toolchain/katana/reference.md
@@ -4,21 +4,23 @@
 
 katana - Create a local testnet node for deploying and testing Starknet smart contracts.
 
-### SYNOPSIS
+### USAGE
 
-`katana` [*options*]
+```sh
+katana [OPTIONS]
+```
 
 ### DESCRIPTION
 
-Create a local testnet node for deploying and testing Starknet smart contracts. Katana supports deployment and execution of version 0 and 1 of Cairo contracts.
+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
 
-Mining modes refer to how frequent blocks are mined using Katana. By default, it automatically generates a new block as soon as a transaction is submitted.
+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 change this setting to interval mining if you will, which means that a new block will be generated in a given period of time selected by the user. If you want to go for this type of mining, you can do it by adding the `--block-time <block-time-in-seconds>` flag, like in the following example.
+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 <SECONDS>` flag, as demonstrated in the following example.
 
 ```sh
 # Produces a new block every 10 seconds
@@ -83,76 +85,120 @@ Katana supports version **v0.3.0** of the Starknet JSON-RPC specifications. The
 Katana provides a convenient set of custom RPC methods to quickly and easily configure the node to suit your testing environment.
 
 `katana_generateBlock`  
-Mine a new block which includes all currently pending transactions
+Mine a new block which includes all currently pending transactions.
 
 `katana_nextBlockTimestamp`  
-Get the time for the next block
+Get the time for the next block.
 
 `katana_increaseNextBlockTimestamp`  
-Increase the time for the block by a given amount of time, in seconds
+Increase the time for the block by a given amount of time, in seconds.
 
 `katana_setNextBlockTimestamp`  
-Similar to `katana_increaseNextBlockTimestamp` but takes the exact timestamp that you want in the next block
+Similar to `katana_increaseNextBlockTimestamp` but takes the exact timestamp that you want in the next block.
 
 `katana_predeployedAccounts`  
-Get the info for all of the predeployed accounts
+Get the info for all of the predeployed accounts.
+
+`katana_setStorageAt`  
+Set an exact value of a contract's storage slot.
 
 ### OPTIONS
 
 #### General Options
 
 `--silent`  
-&nbsp;&nbsp;&nbsp;&nbsp; Don't print anything on startup
+&nbsp;&nbsp;&nbsp;&nbsp; Don't print anything on startup.
 
 `--no-mining`  
-&nbsp;&nbsp;&nbsp;&nbsp; Disable auto and interval mining, and mine on demand instead
+&nbsp;&nbsp;&nbsp;&nbsp; Disable auto and interval mining, and mine on demand instead.
 
 `-b, --block-time <SECONDS>`  
-&nbsp;&nbsp;&nbsp;&nbsp; Block time in seconds for interval mining
+&nbsp;&nbsp;&nbsp;&nbsp; Block time in seconds for interval mining.
+
+`--dump-state <PATH>`  
+&nbsp;&nbsp;&nbsp;&nbsp; Dump the state of chain on exit to the given file.  
+&nbsp;&nbsp;&nbsp;&nbsp; If the value is a directory, the state will be written to `<PATH>/state.bin`.
+
+`--load-state <PATH>`  
+&nbsp;&nbsp;&nbsp;&nbsp; Initialize the chain from a previously saved state snapshot.
 
 `-h, --help`  
-&nbsp;&nbsp;&nbsp;&nbsp; Print help (see a summary with '-h')
+&nbsp;&nbsp;&nbsp;&nbsp; Print help (see a summary with '-h').
 
 `-V, --version`  
-&nbsp;&nbsp;&nbsp;&nbsp; Print version information
+&nbsp;&nbsp;&nbsp;&nbsp; Print version information.
 
 #### Server Options
 
 `-p, --port <PORT>`  
-&nbsp;&nbsp;&nbsp;&nbsp; Port number to listen on [default: 5050]
+&nbsp;&nbsp;&nbsp;&nbsp; Port number to listen on. [default: 5050]
 
 `--host <HOST>`  
-&nbsp;&nbsp;&nbsp;&nbsp; The IP address the server will listen on
+&nbsp;&nbsp;&nbsp;&nbsp; The IP address the server will listen on.
 
 #### Starknet Options
 
 `--seed <SEED>`  
-&nbsp;&nbsp;&nbsp;&nbsp; Specify the seed for randomness of accounts to be predeployed
+&nbsp;&nbsp;&nbsp;&nbsp; Specify the seed for randomness of accounts to be predeployed.
 
 `--accounts <NUM>`  
-&nbsp;&nbsp;&nbsp;&nbsp; Number of pre-funded accounts to generate [default: 10]
+&nbsp;&nbsp;&nbsp;&nbsp; Number of pre-funded accounts to generate. [default: 10]
 
-`--allow-zero-max-fee`  
-&nbsp;&nbsp;&nbsp;&nbsp; Allow transaction max fee to be zero
+`--disable-fee`  
+&nbsp;&nbsp;&nbsp;&nbsp; Disable charging fee for transactions.
 
 #### Environment Options
 
 `--chain-id <CHAIN_ID>`  
-&nbsp;&nbsp;&nbsp;&nbsp; The chain ID [default: KATANA]
+&nbsp;&nbsp;&nbsp;&nbsp; The chain ID. [default: KATANA]
 
 `--gas-price <GAS_PRICE>`  
-&nbsp;&nbsp;&nbsp;&nbsp; The gas price
+&nbsp;&nbsp;&nbsp;&nbsp; The gas price.
+
+`--validate-max-steps <VALIDATE_MAX_STEPS>`  
+&nbsp;&nbsp;&nbsp;&nbsp; The maximum number of steps available for the account validation logic.
+
+`--invoke-max-steps <INVOKE_MAX_STEPS>`  
+&nbsp;&nbsp;&nbsp;&nbsp; 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
+
+#### EXAMPLES
+
+Generate shell completions script for `bash` and appends it to a `.bashrc` file:
+
+```bash
+katana completions bash >> ~/.bashrc
+```
 
 ### EXAMPLES
 
-1. Set the number of accounts to 15 and allow zero fee transaction
+1. Create 15 dev accounts and disable transaction fee mechanism
 
 ```sh
 katana --accounts 15 --disable-fee
 ```
 
-2. Set the chain id SN_GOERLI and run the server on port 8545
+2. Set the chain id to `SN_GOERLI` and run the server on port 8545
 
 ```sh
 katana --chain-id SN_GOERLI --port 8545
 ```
+
+3. Load previously stored state and dump the state of this session to a file on shutdown
+
+```sh
+katana --load-state ./dump-state.bin --dump-state ./dump-state.bin
+```