docs: add documentation

book/book.toml

@@ -3,3 +3,8 @@ authors = ["Jonathan Lei"]
 language = "en"
 multilingual = false
 src = "src"
+title = "Starkli Book"
+
+[output.html]
+git-repository-url = "https://github.com/xJonathanLEI/starkli"
+no-section-label = true

book/src/SUMMARY.md

@@ -1,3 +1,25 @@
 # Summary
 
-[starkli](./title-page.md)
+[Introduction](./introduction.md)
+
+# Getting started
+
+- [Installation](./installation.md)
+- [Shell completions](./shell-completions.md)
+
+# Core concepts
+
+- [Providers](./providers.md)
+- [Signers](./signers.md)
+- [Accounts](./accounts.md)
+- [Argument resolution](./argument-resolution.md)
+
+# Cookbooks
+
+- [Declaring classes](./declaring-classes.md)
+- [Deploying contracts](./deploying-contracts.md)
+- [Invoking contracts](./invoking-contracts.md)
+
+# Reference
+
+- [Commands](./ref/commands.md)

book/src/accounts.md

@@ -0,0 +1,62 @@
+# Accounts
+
+Starkli sends out transactions through accounts. Starknet natively supports [account abstraction](https://ethereum.org/en/roadmap/account-abstraction/) and all accounts are smart contracts. Therefore, there are many "flavors" of accounts and Starkli supports the most popular ones. Starkli refers to these "flavors" as _variants_.
+
+Currently, the only supported variant is [OpenZeppelin's account contract implementation](https://github.com/OpenZeppelin/cairo-contracts/blob/70cbd05ed24ccd147f24b18c638dbd6e7fea88bb/src/openzeppelin/account/presets/Account.cairo), but many more are expected to be supported soon.
+
+Accounts can be created and managed through the `starkli account` command. Variant-specific commands are available under `starkli account <VARIANT>`.
+
+## Account creation
+
+Before creating an account, you must first decide on the _variant_ to use. As of this writing, the only supported variant is `oz`, the OpenZeppelin account contract.
+
+All variants come with an `init` subcommand that creates an account file ready to be deployed. For example, to create an `oz` account:
+
+```console
+starkli account oz init /path/to/account
+```
+
+> ℹ️ **Note**
+>
+> The `starkli account oz init <PATH>` command requires a signer. Starkli would complain that a signer is missing when running the command as shown, unless a keystore is specified via the `STARKNET_KEYSTORE` environment variable. See the [signers page](./signers.md) page for more details.
+
+## Account deployment
+
+Once you have an account file, you can deploy the account contract with the `starkli account deploy` command. This command sends a `DEPLOY_ACCOUNT` transaction, which requires the account to be funded with some `ETH` for paying for the transaction fee.
+
+For example, to deploy the account we just created:
+
+```console
+starkli account deploy /path/to/account
+```
+
+> ℹ️ **Note**
+>
+> This command also requires a signer. You must provide the same signer used for creating the account file in the first place.
+
+When run, the command shows the address where the contract will be deployed on, and instructs the user to fund the account before proceeding. Here's an example command output:
+
+```console
+The estimated account deployment fee is 0.000011483579723913 ETH. However, to avoid failure, fund at least:
+    0.000017225369585869 ETH
+to the following address:
+    0x01cf4d57ba01109f018dec3ea079a38fc08b789e03de4df937ddb9e8a0ff853a
+Press [ENTER] once you've funded the address.
+```
+
+Once the account deployment transaction is confirmed, the account file will be update to reflect the deployment status. It can then be used for commands where an account is expected.
+
+## Account fetching
+
+Account fetching allows recreating the account file from on-chain data alone. This could be helpful when:
+
+- the account file is lost; or
+- migrating an account from another tool/application.
+
+The `starkli account fetch` commands creates an account file using just the address provided:
+
+```console
+starkli account fetch <ADDRESS> --output /path/to/account
+```
+
+Running the command above creates the account file at `/path/to/account`.

book/src/argument-resolution.md

@@ -0,0 +1,46 @@
+# Argument resolution
+
+To make argument input easier and less error-prone, Starkli supports _argument resolution_, the process of expanding simple, human-readable input into actual field element arguments expected by the network.
+
+By default, arguments are only parsed as raw field elements, accepting both decimal and hexadecimal representations.
+
+To make arguments expandable, and thus trigger the resolution process, use the format `scheme:content`, where `scheme` is one of the supported [schemes](#schemes), and `content` is the scheme-specific content.
+
+## Schemes
+
+### `addr`
+
+The `addr` scheme resolves the address name provided as `content` into a full address using an _address book_ under the current network ID. As of this writing, the actual address book feature hasn't been implemented, and a hard-coded address book is used instead, which contains only one entry `eth` for the `ETH` token address.
+
+### `u256`
+
+The `u256` scheme interprets `content` as an unsigned 256-bit integer and resolves into _2_ field element arguments for the low and high 128 bits, respectively. This scheme is useful for working with contracts expecting `u256` arguments, such as the standard ERC20 contract.
+
+### `str`
+
+The `str` scheme encodes `content` as [Cairo short string](https://book.starknet.io/chapter_2/strings.html#working_with_short_strings).
+
+### `const`
+
+The `const` scheme uses `content` as the key to look up a hard-coded table to commonly used constant values. The current list of constants are:
+
+| Key        | Value                                                                    |
+| ---------- | ------------------------------------------------------------------------ |
+| `u256_max` | `0xffffffffffffffffffffffffffffffff, 0xffffffffffffffffffffffffffffffff` |
+| `felt_max` | `0x0800000000000011000000000000000000000000000000000000000000000000`     |
+
+## Scheme omission
+
+Normally, the `scheme:` prefix is required for opting in to argument resolution. However, there's one exception: the `addr:` prefix can be omitted when an address is expected.
+
+As an example, consider the `starkli invoke` command. To use the `addr` scheme, one would run:
+
+```console
+starkli invoke addr:eth ...
+```
+
+However, since the first positional argument for the `starkli invoke` is always expected to be an address, this command can be simplified into:
+
+```console
+starkli invoke eth ...
+```

book/src/declaring-classes.md

@@ -0,0 +1,40 @@
+# Declaring classes
+
+In Starknet, all deployed contracts are instances of certain declared classes. Therefore, the first step of deploying a contract is declaring a class, if it hasn't been declared already.
+
+With Starkli, this is done with the `starkli declare` command.
+
+> ℹ️ **Note**
+>
+> You need both a [signer](./signers.md) and an [account](./accounts.md) for this. The commands shown in this page omit the signer and account options for better readability, and assume you've properly configured the environment variables.
+
+You can declare the following types of contract artifacts:
+
+- Sierra classes: output of the `starknet-compile` command; and
+- _(Deprecated)_ Legacy Cairo 0 classes: output of the `starknet-compile-deprecated` command
+
+To declare any class, simply run:
+
+```console
+starkli declare /path/to/class/file
+```
+
+Starkli is capable of determining the type of class provided. There are no separate commands for Sierra and legacy classes.
+
+Once the declaration is successful, Starkli displays the class hash declared. The class hash is needed for [deploying contracts](./deploying-contracts.md).
+
+## Sierra class compilation
+
+When declaring Sierra classes, Starknet requires a so-called _CASM hash_ to be provided. This is important because as of this writing, the Sierra-to-CASM compilation process isn't proven by the OS. Should the _CASM hash_ not be provided and signed by the user, a malicious sequencer would be able to claim anything to be the CASM output, effectively deploying arbitrary code.
+
+To come up with the _CASM hash_, Starkli compiles the Sierra class provided under the hood. By default, it automatically chooses one of the compiler versions shipped with Starkli itself based on the network. Users can override the compiler version used by providing a `--compiler-version <VERSION>` option.
+
+> ℹ️ **Note**
+>
+> Unless you're working with custom networks where it's infeasible for Starkli to detect the right compiler version, you shouldn't need to manually choose a version with `--compiler-version`.
+>
+> If Starkli _does_ choose the wrong compiler version, try upgrading Starkli, or file a bug if you're already on the latest release.
+
+> ℹ️ **Note**
+>
+> For advanced users, it's possible to skip the Sierra-to-CASM compilation process by directly providing a `--casm-hash <CASM_HASH>`.

book/src/deploying-contracts.md

@@ -0,0 +1,23 @@
+# Deploying contracts
+
+Once you obtain a class hash by [declaring a class](./declaring-classes.md), it's possible to deploy instances of the class.
+
+With Starkli, this is done with the `starkli deploy` command.
+
+> ℹ️ **Note**
+>
+> You need both a [signer](./signers.md) and an [account](./accounts.md) for this. The commands shown in this page omit the signer and account options for better readability, and assume you've properly configured the environment variables.
+
+To deploy a contract with class hash `<CLAS_HASH>`, simply run:
+
+```console
+starkli deploy <CLASS_HASH> <CTOR_ARGS>
+```
+
+where `<CTOR_ARGS>` is the list of constructor arguments, if any.
+
+> 💡 **Tips**
+>
+> You might be able to leverage [argument resolution](./argument-resolution.md) to simplify the argument list input.
+
+Under the hood, Starkli sends an `INVOKE` transaction to the [Universal Deployer Contract](https://community.starknet.io/t/universal-deployer-contract-proposal/), as Starknet does not support native external contract deployment transactions.

book/src/installation.md

@@ -0,0 +1,53 @@
+# Installation
+
+The easiest way to install Starkli is to use `starkliup`, a portable script that downloads prebuilt binaries and manages shell configuration for you. However, it might not be available depending on your device's platform and/or architecture.
+
+Note that if you use any installation method other than `starkliup`, you will need to manually [set up shell completions](./shell-completions.md).
+
+## Using `starkliup`
+
+If you're on Linux/macOS/WSL, you can install `stakrliup` by running the following command:
+
+```console
+curl https://get.starkli.sh | sh
+```
+
+You might need to restart your shell session for the `starkliup` command to become available. Once it's available, run the `starkliup` command:
+
+```console
+starkliup
+```
+
+Running the commands installs `starkli` for you, and upgrades it to the latest release if it's already installed.
+
+`starkliup` detects your device's platform and automatically downloads the right prebuilt binary. It also sets up shell completions. You might need to restart your shell session for the completions to start working.
+
+> ℹ️ **Note**
+>
+> Over time, `starkliup` itself may change and require upgrading. To upgrade `starkliup` itself, run the `curl` command above again.
+
+## Prebuilt binaries
+
+Prebuilt binaries are available with [GitHub releases](https://github.com/xJonathanLEI/starkli/releases) for certain platforms.
+
+Prebuilt binaries are best managed with [`starkliup`](#using-starkliup). However, if you're on a platform where `starkliup` isn't available (e.g. using `starkli` on Windows natively), you can manually download the prebuilt binaries and make them available from `PATH`.
+
+## Install from source
+
+If you have [Rust](https://www.rust-lang.org/) installed, it's also possible to install `starkli` directly from source. Installing from source might be necessary if you want to use an unreleased feature, for example.
+
+> ℹ️ **Note**
+>
+> Shell completions would _not_ be configured when you install `starkli` from source. You need to manually [set up shell completions](./shell-completions.md) for it to work.
+
+To install from source from [crates.io](https://crates.io/crates/starkli):
+
+```console
+cargo install --locked starkli
+```
+
+Alternatively, to install from [GitHub](https://github.com/xJonathanLEI/starkli):
+
+```console
+cargo install --locked --git https://github.com/xJonathanLEI/starkli
+```

book/src/introduction.md

@@ -0,0 +1,5 @@
+# Welcome to Starkli
+
+Starkli is a command line tool for interacting with [Starknet](https://starknet.io/), powered by [starknet-rs](https://github.com/xJonathanLEI/starknet-rs).
+
+Starkli allows you to query Starknet and make transactions with ease. It's fast, easy to install, and intuitive to use.

book/src/invoking-contracts.md

@@ -0,0 +1,59 @@
+# Invoking contracts
+
+With Starkli, this is done with the `starkli invoke` command.
+
+> ℹ️ **Note**
+>
+> You need both a [signer](./signers.md) and an [account](./accounts.md) for this. The commands shown in this page omit the signer and account options for better readability, and assume you've properly configured the environment variables.
+
+The basic format of a `starkli invoke` command is the following:
+
+```console
+starkli invoke <ADDRESS> <SELECTOR> <ARGS>
+```
+
+For example, to transfer `100 Wei` of the `ETH` token to the address `0x1234`, one can run:
+
+```console
+starkli invoke 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7 transfer 0x1234 100 0
+```
+
+> ℹ️ **Note**
+>
+> The `transfer` function takes 2 parameters (i.e. `recipient` and `amount`) but we actually need to enter 3 (note the `0` at the end). This is because `amount` is of type `u256`, which consists of 2 raw field elements.
+>
+> See the [simplifying invoke commands](#simplifying-invoke-commands) section below for ways to make entering this command easier.
+
+## Simplifying invoke commands
+
+You might be able to simplify invoke commands by leveraging [argument resolution](./argument-resolution.md). In this section, we will take the `ETH` transfer command above and try to simplify it.
+
+First, since the `0x021074834d251687180a8d007c5ffc5819e3e68993de9d2d2c32a67d9f3091ff` address is a well-known address available on the built-in address book as the `eth` entry, we can replace it with the use of the [`addr` scheme](./argument-resolution.md#addr):
+
+```console
+starkli invoke addr:eth transfer 0x1234 100 0
+```
+
+Furthermore, as the `addr:eth` is the first positional argument in an `invoke` command, it's eligible for [scheme omission](./argument-resolution.md#scheme-omission), which means we can further simplify it by dropping the `addr:` prefix:
+
+```console
+starkli invoke eth transfer 0x1234 100 0
+```
+
+Manually entering `u256` values as 2 separate field element values is tedious and error-prone, especially with larger values. We can leverage the [`u256` scheme](./argument-resolution.md#u256) to have Starkli automatically split the values for us:
+
+```console
+starkli invoke eth transfer 0x1234 u256:100
+```
+
+For more information regarding argument resolution, check out the [argument resolution](./argument-resolution.md) page.
+
+## Multicall support
+
+Starkli has seamless support for multicall. To use more than 1 contract call in an `invoke` command, simply separate the calls with `/`.
+
+For example, to also approve the sending of `300 Wei` for address `0x4321` in the same transaction:
+
+```console
+starkli invoke eth transfer 0x1234 u256:100 / eth approve 0x4321 u256:300
+```