Skip to content

Commit 5ae9306

Browse files
sauliusgrigaitissauliusgrigaitis
committed
Moved Grandine book to this repo
1 parent 3cfefca commit 5ae9306

15 files changed

+348
-0
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,5 @@
33
cobertura.xml
44

55
/target/
6+
book/book
7+
book/deploy

‎book/book.toml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[book]
2+
authors = ["Saulius Grigaitis"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "Grandine"
7+
8+
[output.html]
9+
default-theme = "ayu"

‎book/src/SUMMARY.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Summary
2+
3+
- [Beacon Node API](./beacon_node_api.md)
4+
- [Builder API and MEV](./builder_api_and_mev.md)
5+
- [Checkpoint Sync](./checkpoint_sync.md)
6+
- [CLI Options](./cli_options.md)
7+
- [Downloads](./downloads.md)
8+
- [Metrics](./metrics.md)
9+
- [Slashing Protection](./slashing_protection.md)
10+
- [Storage](./storage.md)
11+
- [Subcommands](./subcommands.md)
12+
- [Validator Client](./validator_client.md)
13+
- [Web3Signer](./web3signer.md)
14+
- [Support](./support.md)

‎book/src/beacon_node_api.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## Beacon Node API
2+
3+
Grandine supports standard [Beacon Node API](https://ethereum.github.io/beacon-APIs/). This API is extensively tested against other CL validator clients and other Beacon Node API consumers such as [Vouch](https://github.com/attestantio/vouch). API is enabled by default. An example of running Grandine Beacon Node with API enabled by default:
4+
5+
```
6+
docker run \
7+
-p 9000:9000/tcp \
8+
-p 9000:9000/udp \
9+
-v $HOME/.grandine:/root/.grandine \
10+
-v $HOME/.grandine/jwtsecret:/root/.grandine/jwtsecret \
11+
sifrai/grandine:unstable grandine \
12+
--checkpoint-sync-url CHECKPOINT-SYNC-URL \
13+
--eth1-rpc-urls ETH1-RPC-URL \
14+
--jwt-secret JWT-SECRET-PATH
15+
```
16+
17+
### Relevant command line options:
18+
19+
* `--http-port` - sets API listen port (default: `5052`);
20+
* `--http-address` - sets API listen address (default: `127.0.0.1`);
21+
* `--timeout` - sets API timeout in miliseconds (default: `10000`).

‎book/src/builder_api_and_mev.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Builder API and MEV
2+
3+
Grandine supports [Builder API](https://github.com/ethereum/builder-specs) for stakers that use MEV. Only a single builder URL can be passed to Grandine. Multiple builders can be used via relay such as [mev-boost](https://github.com/flashbots/mev-boost) or [mev-rs](https://github.com/ralexstokes/mev-rs). Grandine provides a configurable circuit breaker that disables external block building in certain conditions.
4+
5+
### Relevant command line options:
6+
7+
* `--builder-api-url` - external block builder URL (default: does not use any external builder);
8+
* `--builder-disable-checks` - always specified external block builder without checking for circuit breaker conditions (default: disabled);
9+
* `--builder-max-skipped-slots` - number of consecutive missing blocks to trigger circuit breaker condition and switch to a local execution engine for payload construction (default: `3`);
10+
* `--builder-max-skipped-slots-per-epoch` - number of missing blocks in the last rolling epoch to trigger circuit breaker condition and switch to a local execution engine for payload construction (default: `5`).

‎book/src/checkpoint_sync.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## Checkpoint Sync
2+
3+
Grandine supports checkpoint sync. Currently, it's the preferred way to sync the chain. By default, back-syncing is disabled, so no historical blocks are fetched and no historical states are reconstructed. This default behavior is sufficient for staking, however, for other use cases (such as historical data access via Beacon Node API) back-syncing must be enabled.
4+
5+
### Relevant command line options
6+
7+
* `--checkpoint-sync-url` - Beacon Node API URL to load a recent finalized checkpoint and sync from it (default: disabled)
8+
* `--back-sync` - enables back-syncing blocks and reconstructing states (default: disabled)

‎book/src/cli_options.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
## CLI options
2+
3+
The list of command line options:
4+
5+
```
6+
--network <NETWORK>
7+
Name of the Eth2 network to connect to [default: mainnet] [possible values: mainnet, goerli, custom]
8+
--configuration-file <YAML_FILE>
9+
Load configuration from YAML_FILE
10+
--configuration-directory <DIRECTORY>
11+
Load configuration from directory
12+
--verify-phase0-preset-file <YAML_FILE>
13+
Verify that Phase 0 variables in preset match YAML_FILE
14+
--verify-altair-preset-file <YAML_FILE>
15+
Verify that Altair variables in preset match YAML_FILE
16+
--verify-bellatrix-preset-file <YAML_FILE>
17+
Verify that Bellatrix variables in preset match YAML_FILE
18+
--verify-capella-preset-file <YAML_FILE>
19+
Verify that Capella variables in preset match YAML_FILE
20+
--verify-configuration-file <YAML_FILE>
21+
Verify that configuration matches YAML_FILE
22+
--terminal-total-difficulty-override <DIFFICULTY>
23+
Override TERMINAL_TOTAL_DIFFICULTY
24+
--terminal-block-hash-override <BLOCK_HASH>
25+
Override TERMINAL_BLOCK_HASH
26+
--terminal-block-hash-activation-epoch-override <EPOCH>
27+
Override TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH
28+
--deposit-contract-starting-block <BLOCK_NUMBER>
29+
Start tracking deposit contract from BLOCK_NUMBER
30+
--genesis-state-file <SSZ_FILE>
31+
Load genesis state from SSZ_FILE
32+
--max-empty-slots <MAX_EMPTY_SLOTS>
33+
[default: 32]
34+
--checkpoint-sync-url <CHECKPOINT_SYNC_URL>
35+
Beacon node API URL to load recent finalized checkpoint and sync from it [default: None]
36+
--force-checkpoint-sync
37+
Force checkpoint sync. Requires --checkpoint-sync-url [default: disabled]
38+
--eth1-rpc-urls <ETH1_RPC_URLS>...
39+
List of Eth1 RPC URLs
40+
--data-dir <DATA_DIR>
41+
Parent directory for application data files [default: $HOME/.grandine/{network}]
42+
--store-directory <STORE_DIRECTORY>
43+
Directory to store application data files [default: {data_dir}/beacon]
44+
--network-dir <NETWORK_DIR>
45+
Directory to store application network files [default: {data_dir}/network]
46+
--archival-epoch-interval <ARCHIVAL_EPOCH_INTERVAL>
47+
[default: 32]
48+
--prune-storage
49+
Enable prune mode where only single checkpoint state & block are stored in the DB [default: disabled]
50+
--unfinalized-states-in-memory <UNFINALIZED_STATES_IN_MEMORY>
51+
Number of unfinalized states to keep in memory. Specifying this number enables unfinalized state pruning. By default all unfinalized states are kept in memory. [default: None]
52+
--database-size <DATABASE_SIZE>
53+
Max size of the Eth2 database [default: "274.9 GB"]
54+
--eth1-database-size <ETH1_DATABASE_SIZE>
55+
Max size of the Eth1 database [default: "17.2 GB"]
56+
--request-timeout <REQUEST_TIMEOUT>
57+
Default global request timeout for various services in milliseconds [default: 30000]
58+
--http-address <HTTP_ADDRESS>
59+
HTTP API address [default: 127.0.0.1]
60+
--http-port <HTTP_PORT>
61+
HTTP API port [default: 5052]
62+
--state-slot <STATE_SLOT>
63+
State slot [default: None]
64+
--disable-block-verification-pool
65+
Disable block signature verification pool [default: enabled]
66+
--subscribe-all-subnets
67+
Subscribe to all subnets
68+
--suggested-fee-recipient <EXECUTION_ADDRESS>
69+
Suggested value for the feeRecipient field of the new payload
70+
--jwt-id <JWT_ID>
71+
Optional CL unique identifier to send to EL in the JWT token claim [default: None]
72+
--jwt-secret <JWT_SECRET>
73+
Path to a file containing the hex-encoded 256 bit secret key to be used for verifying/generating JWT tokens
74+
--jwt-version <JWT_VERSION>
75+
Optional CL node type/version to send to EL in the JWT token claim [default: None]
76+
--back-sync
77+
Enable syncing historical data [default: disabled]
78+
--metrics
79+
Collect Prometheus metrics
80+
--metrics-address <METRICS_ADDRESS>
81+
Metrics address for metrics endpoint [default: 127.0.0.1]
82+
--metrics-port <METRICS_PORT>
83+
Listen port for metrics endpoint [default: 5054]
84+
--remote-metrics-url <REMOTE_METRICS_URL>
85+
Optional remote metrics URL that Grandine will periodically send metrics to
86+
--track-liveness
87+
Enable validator liveness tracking [default: disabled]
88+
--max-events <MAX_EVENTS>
89+
Max number of events stored in a single channel for HTTP API /events api call [default: 100]
90+
--timeout <TIMEOUT>
91+
HTTP API timeout in milliseconds [default: 10000]
92+
--listen-address <LISTEN_ADDRESS>
93+
Listen IPv4 address [default: 0.0.0.0]
94+
--listen-address-ipv6 <LISTEN_ADDRESS_IPV6>
95+
Listen IPv6 address [default: None]
96+
--libp2p-port <LIBP2P_PORT>
97+
libp2p IPv4 port [default: 9000]
98+
--libp2p-port-ipv6 <LIBP2P_PORT_IPV6>
99+
libp2p IPv6 port [default: 9050]
100+
--disable-peer-scoring
101+
Disable peer scoring
102+
--disable-upnp
103+
Disable NAT traversal via UPnP [default: enabled]
104+
--discovery-port <DISCOVERY_PORT>
105+
discv5 IPv4 port [default: 9000]
106+
--discovery-port-ipv6 <DISCOVERY_PORT_IPV6>
107+
discv5 IPv6 port [default: 9050]
108+
--enr-address <ENR_ADDRESS>
109+
ENR IPv4 address
110+
--enr-address-ipv6 <ENR_ADDRESS_IPV6>
111+
ENR IPv6 address
112+
--enr-tcp-port <ENR_TCP_PORT>
113+
ENR TCP IPv4 port
114+
--enr-tcp-port-ipv6 <ENR_TCP_PORT_IPV6>
115+
ENR TCP IPv6 port
116+
--enr-udp-port <ENR_UDP_PORT>
117+
ENR UDP IPv4 port
118+
--enr-udp-port-ipv6 <ENR_UDP_PORT_IPV6>
119+
ENR UDP IPv6 port
120+
--boot-nodes <BOOT_NODES>
121+
List of ENR boot node addresses
122+
--libp2p-nodes <LIBP2P_NODES>
123+
List of Multiaddr node addresses
124+
--target-peers <TARGET_PEERS>
125+
Target number of network peers [default: 80]
126+
--trusted-peers <TRUSTED_PEERS>
127+
List of trusted peers
128+
--slashing-enabled
129+
Enable slasher [default: disabled]
130+
--slashing-history-limit <SLASHING_HISTORY_LIMIT>
131+
Number of epochs for slasher to search for violations [default: 54000]
132+
--keystore-dir <KEYSTORE_DIR>
133+
Path to a directory containing EIP-2335 keystore files
134+
--keystore-password-dir <KEYSTORE_PASSWORD_DIR>
135+
Path to a directory containing passwords for keystore files
136+
--keystore-password-file <KEYSTORE_PASSWORD_FILE>
137+
Path to a file containing password for keystore files
138+
--pack-extra-attestations
139+
Pack extra singular attestations to proposed block
140+
--builder-api-url <BUILDER_API_URL>
141+
External block builder API URL
142+
--builder-disable-checks
143+
Always use specified external block builder without checking for circuit breaker conditions
144+
--builder-max-skipped-slots <BUILDER_MAX_SKIPPED_SLOTS>
145+
Max allowed consecutive missing blocks to trigger circuit breaker condition and switch to local execution engine for payload construction [default: 3]
146+
--builder-max-skipped-slots-per-epoch <BUILDER_MAX_SKIPPED_SLOTS_PER_EPOCH>
147+
Max allowed missing blocks in the last rolling epoch to trigger circuit breaker condition and switch to local execution engine for payload construction [default: 5]
148+
--web3signer-api-urls <WEB3SIGNER_API_URLS>...
149+
List of Web3Signer API URLs
150+
--use-validator-key-cache
151+
Use validator key cache for faster startup
152+
--graffiti <GRAFFITI>
153+
154+
--features <FEATURES>
155+
List of optional runtime features to enable
156+
-h, --help
157+
Print help
158+
-V, --version
159+
Print version
160+
```

‎book/src/downloads.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## Downloads
2+
3+
### Docker
4+
5+
Docker [images](https://hub.docker.com/r/sifrai/grandine/tags) is the best way to get the latest versions of Grandine. We provide multi-platform images supporting `linux/amd64` and `linux/arm64`. Available tags:
6+
7+
* `latest` - latest stable version for `linux/amd64` and `linux/arm64`;
8+
* `latest-amd64` - latest stable version for `linux/amd64`;
9+
* `latest-arm64` - latest stable version for `linux/arm64`;
10+
* `unstable` - latest unstable version `linux/amd64` and `linux/arm64`;
11+
* `unstable-amd64` - latest unstable version for `linux/amd64`;
12+
* `unstable-arm64` - latest unstable version for `linux/arm64`.
13+
14+
### Binary
15+
16+
The latest stable binaries are provided on [Github](https://github.com/sifraitech/grandine/tags). Unstable binary builds are not released to Github.

‎book/src/metrics.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## Metrics
2+
3+
### Beacon Node metrics
4+
5+
Grandine provides a set of Beacon Node metrics that are suitable to be consumed by [Prometheus](https://github.com/prometheus/prometheus) and visualized via [Grafana](https://github.com/grafana/grafana) dashboards.
6+
7+
### Remote Metrics
8+
9+
Grandine can to push metrics to a remote endpoint every 60 seconds. This option is useful for services such as [beaconcha.in](https://kb.beaconcha.in/beaconcha.in-explorer/mobile-app-less-than-greater-than-beacon-node).
10+
11+
### Relevant command line options:
12+
13+
* `--metrics` - enables metrics (default: disabled);
14+
* `--metrics-address` - address for metrics endpoint (default: `127.0.0.1`);
15+
* `--metrics-port` - port for metrics endpoint (default: `5054`);
16+
* `--remote-metrics-url` - remote metrics URL that Grandine will periodically send metrics to (default: disabled).

‎book/src/slashing_protection.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
## Slashing Protection
2+
3+
Grandine supports the [Slashing Protection Interchange Format](https://eips.ethereum.org/EIPS/eip-3076). It's a must to migrate slashing protection data if you are switching validators between clients or servers.
4+
5+
Import Slashing Protection history to Grandine:
6+
7+
```
8+
./grandine --network goerli interchange export slashing_protection.json
9+
```
10+
11+
Export Slashing Protection history from Grandine:
12+
13+
```
14+
./grandine --network goerli interchange export slashing_protection.json
15+
```
16+
17+
We highly recommend waiting for a few epochs before starting validators after migration.

0 commit comments

Comments
 (0)