docs: add Profiles page to book

xJonathanLEI · Dec 28, 2023 · 04998f6 · 04998f6
1 parent 3a3b42f
commit 04998f6
Show file tree

Hide file tree

Showing 3 changed files with 102 additions and 2 deletions.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -10,6 +10,7 @@
 # Core concepts
 
 - [Providers](./providers.md)
+- [Profiles](./profiles.md)
 - [Signers](./signers.md)
 - [Accounts](./accounts.md)
 - [Transaction fees](./transaction-fees.md)

diff --git a/book/src/profiles.md b/book/src/profiles.md
@@ -0,0 +1,99 @@
+# Profiles
+
+Starkli supports profiles, where custom networks can be defined.
+
+> ℹ️ **Note**
+>
+> Profiles only allow defining custom networks at the moment. More features will be added soon.
+
+> ℹ️ **Note**
+>
+> Currently, only one profile `default` is supported. Defining additional profiles results in an error.
+
+## The profiles file
+
+Depending on what operating system you're using, the profiles file are located at:
+
+- Linux and Mac: `~/.config/starkli/profiles.toml`
+- Windows: `%AppData%\starkli\profiles.toml`
+
+> 💡 **Tips**
+>
+> The profiles file is created automatically the first time you use a [free RPC vendor](./providers.md#free-rpc-vendors). You can take the automatically generated file as a starting point for adding new networks.
+
+## Defining custom networks
+
+Custom networks can be defined as `<PROFILE_ID>.networks.<NETWORK_ID>`. Since only the `default` profile is supported at the moment, networks should be defined as `default.networks.<NETWORK_ID>`.
+
+Each network contains the following properties:
+
+| Field      | Mandatory | Type              | Description                                       |
+| ---------- | --------- | ----------------- | ------------------------------------------------- |
+| `name`     | No        | `String`          | Human-readable network name, currently unused     |
+| `chain_id` | Yes       | `String`          | String representation of the chain ID             |
+| `provider` | Yes       | `String`/`Object` | [Provider configuration](#provider-configuration) |
+
+### Provider configuration
+
+The `provider` field can be either a `String` or an `Object`. When the `provider` value is an `Object`, it must contain a `type` field, whose value must be one of the following:
+
+| Value                            | Description                                              |
+| -------------------------------- | -------------------------------------------------------- |
+| [`rpc`](#rpc-provider-variant)   | Use the JSON-RPC provider by specifying an endpoint URL  |
+| [`free`](#free-provider-variant) | Use a [free RPC vendor](./providers.md#free-rpc-vendors) |
+
+#### `rpc` provider variant
+
+| Field  | Mandatory | Type     | Description                  |
+| ------ | --------- | -------- | ---------------------------- |
+| `type` | Yes       | `String` | Value must be `rpc`          |
+| `url`  | Yes       | `String` | URL to the JSON-RPC endpoint |
+
+#### `free` provider variant
+
+| Field    | Mandatory | Type     | Description                             |
+| -------- | --------- | -------- | --------------------------------------- |
+| `type`   | Yes       | `String` | Value must be `free`                    |
+| `vendor` | Yes       | `String` | Must be one of `blast` and `nethermind` |
+
+#### `rpc` provider shorthand
+
+The `provider` value can also be a `String`. When this is the case, it's used as a shorthand for the [`rpc` variant](#rpc-provider-variant). So this value:
+
+```toml
+provider = "https://example.com/"
+```
+
+is the same as this:
+
+```toml
+provider = { type = "rpc", url = "https://example.com/" }
+```
+
+### Example network configurations
+
+This section contains a few example network configurations.
+
+#### Network with the RPC provider
+
+```toml
+[default.networks.mainnet]
+chain_id = "SN_MAIN"
+provider = { type = "rpc", url = "https://example.com/" }
+```
+
+#### Network with the RPC provider shorthand
+
+```toml
+[default.networks.mainnet]
+chain_id = "SN_MAIN"
+provider = "https://example.com/"
+```
+
+#### Network with the free RPC vendor
+
+```toml
+[default.networks.mainnet]
+chain_id = "SN_MAIN"
+provider = { type = "free", vendor = "blast" }
+```
diff --git a/book/src/providers.md b/book/src/providers.md
@@ -53,7 +53,7 @@ which is the same as the running with the `--rpc` option.
 
 ## Using a predefined network
 
-Networks can be defined in profiles. Each network is uniquely identified by an identifier within a profile. When the `--network` option, or the `STARKNET_NETWORK` environment variable, is used, Starkli looks up the network identifier in the current active profile, and uses its provider settings to connect to the network. See the profiles page for details on defining networks.
+Networks can be defined in [profiles](./profiles.md). Each network is uniquely identified by an identifier within a profile. When the `--network` option, or the `STARKNET_NETWORK` environment variable, is used, Starkli looks up the network identifier in the current active profile, and uses its provider settings to connect to the network. See the [profiles page](./profiles.md) for details on defining networks.
 
 If the supplied network identifier is not found, Starkli terminates with an error, **unless the network is eligible for [free RPC vendors](#free-rpc-vendors)**, in which case Starkli automatically creates the network and persists it into the profile.
 
@@ -100,4 +100,4 @@ Once selected, the vendor choice is persisted in the profile. A message is print
 
 > 💡 **Tips**
 >
-> You can always change the automatically assigned free RPC vendor for a network by editing the profiles.
+> You can always change the automatically assigned free RPC vendor for a network by [editing the profiles](./profiles.md).