Skip to content

Commit

Permalink
add staking validator guide (#2266)
Browse files Browse the repository at this point in the history 
* add staking validator guide

* release docs v0.12.4
  • Loading branch information
@LordGhostX
LordGhostX authored Nov 19, 2024
1 parent e29c217 commit 00524ad
Show file tree
Hide file tree
Showing 28 changed files with 1,553 additions and 383 deletions.
4 changes: 3 additions & 1 deletion docs/docs/_config-options.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,10 @@
| `cn-unverifiable-range` | `[]` | Custom network range of blocks to skip hash verifications (e.g. `0,100`) |
| `colour` | `true` | Use `--colour=false` command to disable colourized outputs (ANSI Escape Codes) |
| `config` | | The YAML configuration file |
| `db-cache-size` | `8` | Determines the amount of memory (in megabytes) allocated for caching data in the database |
| `db-cache-size` | `1024` | Determines the amount of memory (in megabytes) allocated for caching data in the database |
| `db-max-handles` | `1024` | A soft limit on the number of open files that can be used by the DB |
| `db-path` | `juno` | Location of the database files |
| `disable-l1-verification` | `false` | Disables L1 verification since an Ethereum node is not provided |
| `eth-node` | | WebSocket endpoint of the Ethereum node. To verify the correctness of the L2 chain, Juno must connect to an Ethereum node and parse events in the Starknet contract |
| `grpc` | `false` | Enable the HTTP gRPC server on the default port |
| `grpc-host` | `localhost` | The interface on which the gRPC server will listen for requests |
Expand All @@ -37,6 +38,7 @@
| `p2p-private-key` | | EXPERIMENTAL: Hexadecimal representation of a private key on the Ed25519 elliptic curve |
| `p2p-public-addr` | | EXPERIMENTAL: Specify p2p public address as multiaddr. Example: /ip4/35.243.XXX.XXX/tcp/7777 |
| `pending-poll-interval` | `5` | Sets how frequently pending block will be updated (0s will disable fetching of pending block) |
| `plugin-path` | | Path to the plugin .so file |
| `pprof` | `false` | Enables the pprof endpoint on the default port |
| `pprof-host` | `localhost` | The interface on which the pprof HTTP server will listen for requests |
| `pprof-port` | `6062` | The port on which the pprof HTTP server will listen for requests |
Expand Down
32 changes: 32 additions & 0 deletions docs/docs/staking-validator.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Become a Staking Validator

Staking on Starknet provides an opportunity to contribute to network security and earn rewards by becoming a validator. Check out the [Becoming a Validator](https://docs.starknet.io/staking/entering-staking/) guide to learn more about the validator process.

## Prerequisites

- **STRK Tokens**: At least 20,000 STRK is required for staking. For the latest details, check out the [Staking Protocol Details](https://docs.starknet.io/staking/overview/#protocol_details).
- **Node Setup**: The [latest version of Juno](updating) installed and running on your machine.
- **Starknet Wallet**: A compatible wallet, like [Braavos](https://braavos.app/wallet-features/ledger-on-braavos/) or [Argent](https://www.argent.xyz/blog/how-to-use-your-hardware-wallet-with-argent).
- **Access to CLI/Block Explorer**: Tools like [Voyager](https://voyager.online) for interacting with contracts.

## 1. Set up Juno

Juno is a reliable choice for running a Starknet node. Follow the [Running Juno](running-juno) guide to configure Juno using Docker, binaries, source builds, or Google Cloud Platform (GCP).

## 2. Stake STRK tokens

Register as a validator by staking STRK tokens through the Starknet staking contract. Check out the [Becoming a Validator](https://docs.starknet.io/staking/entering-staking/) guide for complete instructions. The staking process includes:

- **Pre-approving STRK Transfer**: Allow the staking contract to lock your tokens.
- **Calling the `stake` Function**: Register operational and reward addresses, set commission rates, and enable pooling if desired.

## 3. Finalising your validator

Once Juno is running and your STRK tokens are staked:

1. Monitor your validator's status via dashboards like [Voyager](https://voyager.online/).
2. Stay updated for future network requirements or configurations.

:::info
You're now a staking validator! With your node running and tokens staked, you support Starknet's security and earn rewards. The network manages most operations, though future updates may require additional setup.
:::
1 change: 1 addition & 0 deletions docs/sidebars.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ const sidebars = {
},
],
},
"staking-validator",
"monitoring",
"snapshots",
"faq",
Expand Down
52 changes: 52 additions & 0 deletions docs/versioned_docs/version-0.12.4/_config-options.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
<!-- This file is generated automatically. Any manual modifications will be overwritten. -->

| Config Option | Default Value | Description |
| - | - | - |
| `cn-core-contract-address` | | Custom network core contract address |
| `cn-feeder-url` | | Custom network feeder URL |
| `cn-gateway-url` | | Custom network gateway URL |
| `cn-l1-chain-id` | | Custom network L1 chain id |
| `cn-l2-chain-id` | | Custom network L2 chain id |
| `cn-name` | | Custom network name |
| `cn-unverifiable-range` | `[]` | Custom network range of blocks to skip hash verifications (e.g. `0,100`) |
| `colour` | `true` | Use `--colour=false` command to disable colourized outputs (ANSI Escape Codes) |
| `config` | | The YAML configuration file |
| `db-cache-size` | `1024` | Determines the amount of memory (in megabytes) allocated for caching data in the database |
| `db-max-handles` | `1024` | A soft limit on the number of open files that can be used by the DB |
| `db-path` | `juno` | Location of the database files |
| `disable-l1-verification` | `false` | Disables L1 verification since an Ethereum node is not provided |
| `eth-node` | | WebSocket endpoint of the Ethereum node. To verify the correctness of the L2 chain, Juno must connect to an Ethereum node and parse events in the Starknet contract |
| `grpc` | `false` | Enable the HTTP gRPC server on the default port |
| `grpc-host` | `localhost` | The interface on which the gRPC server will listen for requests |
| `grpc-port` | `6064` | The port on which the gRPC server will listen for requests |
| `gw-api-key` | | API key for gateway endpoints to avoid throttling |
| `gw-timeout` | `5` | Timeout for requests made to the gateway |
| `http` | `false` | Enables the HTTP RPC server on the default port and interface |
| `http-host` | `localhost` | The interface on which the HTTP RPC server will listen for requests |
| `http-port` | `6060` | The port on which the HTTP server will listen for requests |
| `log-level` | `info` | Options: trace, debug, info, warn, error |
| `max-vm-queue` | `2 * max-vms` | Maximum number for requests to queue after reaching max-vms before starting to reject incoming requests |
| `max-vms` | `3 * CPU Cores` | Maximum number for VM instances to be used for RPC calls concurrently |
| `metrics` | `false` | Enables the Prometheus metrics endpoint on the default port |
| `metrics-host` | `localhost` | The interface on which the Prometheus endpoint will listen for requests |
| `metrics-port` | `9090` | The port on which the Prometheus endpoint will listen for requests |
| `network` | `mainnet` | Options: mainnet, sepolia, sepolia-integration |
| `p2p` | `false` | EXPERIMENTAL: Enables p2p server |
| `p2p-addr` | | EXPERIMENTAL: Specify p2p listening source address as multiaddr. Example: /ip4/0.0.0.0/tcp/7777 |
| `p2p-feeder-node` | `false` | EXPERIMENTAL: Run juno as a feeder node which will only sync from feeder gateway and gossip the new blocks to the network |
| `p2p-peers` | | EXPERIMENTAL: Specify list of p2p peers split by a comma. These peers can be either Feeder or regular nodes |
| `p2p-private-key` | | EXPERIMENTAL: Hexadecimal representation of a private key on the Ed25519 elliptic curve |
| `p2p-public-addr` | | EXPERIMENTAL: Specify p2p public address as multiaddr. Example: /ip4/35.243.XXX.XXX/tcp/7777 |
| `pending-poll-interval` | `5` | Sets how frequently pending block will be updated (0s will disable fetching of pending block) |
| `plugin-path` | | Path to the plugin .so file |
| `pprof` | `false` | Enables the pprof endpoint on the default port |
| `pprof-host` | `localhost` | The interface on which the pprof HTTP server will listen for requests |
| `pprof-port` | `6062` | The port on which the pprof HTTP server will listen for requests |
| `remote-db` | | gRPC URL of a remote Juno node |
| `rpc-call-max-steps` | `4000000` | Maximum number of steps to be executed in starknet_call requests. The upper limit is 4 million steps, and any higher value will still be capped at 4 million |
| `rpc-cors-enable` | `false` | Enable CORS on RPC endpoints |
| `rpc-max-block-scan` | `18446744073709551615` | Maximum number of blocks scanned in single starknet_getEvents call |
| `versioned-constants-file` | | Use custom versioned constants from provided file |
| `ws` | `false` | Enables the WebSocket RPC server on the default port |
| `ws-host` | `localhost` | The interface on which the WebSocket RPC server will listen for requests |
| `ws-port` | `6061` | The port on which the WebSocket server will listen for requests |
125 changes: 125 additions & 0 deletions docs/versioned_docs/version-0.12.4/configuring.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
---
title: Configuring Juno
---

# Configuring Juno :gear:

Juno can be configured using several methods, with the following order of precedence:

1. [Command line parameters (flags)](#command-line-params)
2. [Environment variables](#environment-variables)
3. [Configuration file](#configuration-file)

## Command line params

Juno can be configured directly on the command line by prefixing `--` to each option name:

```bash
./build/juno --http --http-port 6060 --http-host 0.0.0.0
```

When using Docker, append the command line parameters after the image name to configure Juno:

```bash
docker run nethermind/juno --http --http-port 6060 --http-host 0.0.0.0
```

:::tip
Command line parameters override [environment variables](#environment-variables) and [configuration file](#configuration-file).
:::

## Environment variables

Juno can be configured through environment variables by prefixing the variable names with `JUNO_` and using the configuration options in [SCREAMING_SNAKE_CASE](https://en.wiktionary.org/wiki/screaming_snake_case) format.

To set the `http`, `http-port`, and `http-host` configurations, Juno should be run in this format:

```bash
JUNO_HTTP=true JUNO_HTTP_PORT=6060 JUNO_HTTP_HOST=0.0.0.0 ./build/juno
```

When using Docker, start Juno using the `-e` command option:

```bash
docker run \
-e "JUNO_HTTP=true JUNO_HTTP_PORT=6060 JUNO_HTTP_HOST=0.0.0.0" \
nethermind/juno
```

:::tip
Environment variables rank second in configuration precedence. [Command line parameters](#command-line-params) override environment variables.
:::

## Configuration file

Juno can be configured using a [YAML](https://en.wikipedia.org/wiki/YAML) file:

```yaml title="Sample YAML File" showLineNumbers
log-level: info
network: mainnet
http: true
http-port: 6060
metrics: true
metrics-port: 9090
```
To run Juno with a configuration file, use the `config` option to specify the path of the configuration file:

```bash
# Standalone binary
./build/juno --config <CONFIG FILE PATH>
# Docker container
docker run nethermind/juno --config <CONFIG FILE PATH>
```

:::info
By default, Juno looks for the configuration file in the `$XDG_CONFIG_HOME` directory.
:::

:::tip
Configuration file rank third in configuration precedence. [Command line parameters](#command-line-params) and [environment variables](#environment-variables) override configuration file.
:::

## Configuration options

To list all available command line options, you can use the `--help` parameter:

```bash
# Standalone binary
./build/juno --help
# Docker container
docker run nethermind/juno --help
```

Below is a list of all configuration options available in Juno, along with their default values and descriptions:

```mdx-code-block
import ConfigOptions from "./_config-options.md";
<ConfigOptions />
```

## Subcommands

Juno provides several subcommands to perform specific tasks or operations. Here are the available ones:

- `genp2pkeypair`: Generate a private key pair for p2p.
- `db`: Perform database-related operations
- `db info`: Retrieve information about the database.
- `db size`: Calculate database size information for each data type.
- `db revert`: Reverts the database to a specific block number.

To use a subcommand, append it when running Juno:

```bash
# Running a subcommand
./build/juno <subcommand>
# Running the genp2pkeypair subcommand
./build/juno genp2pkeypair
# Running the db info subcommand
./build/juno db info
```
125 changes: 125 additions & 0 deletions docs/versioned_docs/version-0.12.4/faq.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
---
title: Frequently Asked Questions
---

# Frequently Asked Questions :question:

<details>
<summary>What is Juno?</summary>

Juno is a Go implementation of a Starknet full-node client created by Nethermind to allow node operators to easily and reliably support the network and advance its decentralisation goals. Juno supports various node setups, from casual to production-grade indexers.

</details>

<details>
<summary>How can I run Juno?</summary>

Check out the [Running Juno](running-juno) guide to learn the simplest and fastest ways to run a Juno node. You can also check the [Running Juno on GCP](running-on-gcp) guide to learn how to run Juno on GCP.

</details>

<details>
<summary>What are the hardware requirements for running Juno?</summary>

We recommend running Juno with at least 4GB of RAM and 250GB of SSD storage. Check out the [Hardware Requirements](hardware-requirements) for more information.

</details>

<details>
<summary>How can I configure my Juno node?</summary>

You can configure Juno using [command line parameters](configuring#command-line-params), [environment variables](configuring#environment-variables), and a [YAML configuration file](configuring#configuration-file). Check out the [Configuring Juno](configuring) guide to learn their usage and precedence.

</details>

<details>
<summary>How can I update my Juno node?</summary>

Check out the [Updating Juno](updating) guide for instructions on updating your node to the latest version.

</details>

<details>
<summary>How can I interact with my Juno node?</summary>

You can interact with a running Juno node using the [JSON-RPC](json-rpc) and [WebSocket](websocket) interfaces.

</details>

<details>
<summary>How can I monitor my Juno node?</summary>

Juno captures metrics data using [Prometheus](https://prometheus.io), and you can visualise them using [Grafana](https://grafana.com). Check out the [Monitoring Juno](monitoring) guide to get started.

</details>

<details>
<summary>Do node operators receive any rewards, or is participation solely to support the network?</summary>

Presently, running a node does not come with direct rewards; its primary purpose is contributing to the network's functionality and stability. However, operating a node provides valuable educational benefits and deepens your knowledge of the network's operation.

</details>

<details>
<summary>How can I view Juno logs from Docker?</summary>

You can view logs from the Docker container using the following command:

```bash
docker logs -f juno
```

</details>

<details>
<summary>How can I get real-time updates of new blocks?</summary>

The [WebSocket](websocket#subscribe-to-newly-created-blocks) interface provides a `juno_subscribeNewHeads` method that emits an event when new blocks are added to the blockchain.

</details>

<details>
<summary>Does Juno provide snapshots to sync with Starknet quickly?</summary>

Yes, Juno provides snapshots for both the Starknet Mainnet and Sepolia networks. Check out the [Database Snapshots](snapshots) guide to get started.

</details>

<details>
<summary>How can I contribute to Juno?</summary>

You can contribute to Juno by running a node, starring on GitHub, reporting bugs, and suggesting new features. Check out the [Contributions and Partnerships](/#contributions-and-partnerships) page for more information.

</details>

<details>
<summary>I noticed a warning in my logs saying: **Failed storing Block \{"err": "unsupported block version"\}**. How should I proceed?</summary>

You can fix this problem by [updating to the latest version](updating) of Juno. Check for updates and install them to maintain compatibility with the latest block versions.

</details>

<details>
<summary>After updating Juno, I receive **error while migrating DB.** How should I proceed?</summary>

This error suggests your database is corrupted, likely due to the node being interrupted during migration. This can occur if there are insufficient system resources, such as RAM, to finish the process. The only solution is to resynchronise the node from the beginning. To avoid this issue in the future, ensure your system has adequate resources and that the node remains uninterrupted during upgrades.

</details>

<details>
<summary>I receive **Error: unable to verify latest block hash; are the database and --network option compatible?** while running Juno. How should I proceed?</summary>

To resolve this issue, ensure that the `eth-node` configuration aligns with the `network` option for the Starknet network.

</details>

<details>
<summary>I receive **process \<PID\> killed** and **./build/juno: invalid signature (code or signature have been modified)** while running the binary on macOS. How should I proceed?</summary>

You need to re-sign the binary to resolve this issue using the following command:

```bash
codesign --sign - ./build/juno
```

</details>
23 changes: 23 additions & 0 deletions docs/versioned_docs/version-0.12.4/hardware-requirements.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
---
title: Hardware Requirements
---

# Hardware Requirements :computer:

The following specifications outline the hardware required to run a Juno node. These specifications are categorised into minimal and recommended requirements for different usage scenarios.

## Minimal requirements

- **CPU**: At least 2 cores
- **RAM**: 4GB or more
- **Storage**: 250GB or more (SSD recommended; note: storage needs will grow over time)

## Recommended requirements

- **CPU**: High-performance CPU with 4 or more cores
- **RAM**: 8GB or more
- **Storage**: High-performance SSD with at least 250GB to accommodate future growth

:::tip
We intend the above specifications as a guideline. The minimal requirements support basic node operations, and the recommended settings ensure optimal performance and scalability for future needs.
:::
Loading

0 comments on commit 00524ad

Please sign in to comment.