diff --git a/versioned_docs/version-2.0.0/operators/setup/basic-node-configuration.md b/versioned_docs/version-2.0.0/operators/setup/basic-node-configuration.md index dacf212f3..a472ec872 100644 --- a/versioned_docs/version-2.0.0/operators/setup/basic-node-configuration.md +++ b/versioned_docs/version-2.0.0/operators/setup/basic-node-configuration.md @@ -23,6 +23,8 @@ sudo apt install casper-node-launcher You can also build [from source](https://github.com/casper-network/casper-node-launcher). However, all the setup and pull of casper-node releases will be manual. +`casper-node-util` is a helper script for managing a `casper-node` and installed as a debian package dependency of `casper-node-launcher` + :::note The `casper-sidecar` component is also typically installed alongside the node to provide additional APIs and event streaming. For more information, see the [Sidecar Setup](./casper-sidecar.md) page. diff --git a/versioned_docs/version-2.0.0/operators/setup/hardware.md b/versioned_docs/version-2.0.0/operators/setup/hardware.md index 0904c7d43..c099edc43 100644 --- a/versioned_docs/version-2.0.0/operators/setup/hardware.md +++ b/versioned_docs/version-2.0.0/operators/setup/hardware.md @@ -10,8 +10,11 @@ The following hardware specifications are recommended for the Casper [Mainnet](h - 4 Cores - 32 GB Ram -- 2 TB SSD -- Linux machine running Ubuntu 20.04 +- Storage (SSD) + - 2 TB (Archival Nodes) + - 500 GB (TTL Nodes) +- Linux machine running Ubuntu 22.04, 24.04 or Debian 13 + - Binaries are build on 22.04 and will run on Linux having same or higher Clib version. :::note Notes @@ -20,6 +23,7 @@ The following hardware specifications are recommended for the Casper [Mainnet](h - For non-archival nodes, current disc usage is significantly lower (e.g., ~500 GB is sufficient for at least 1 year). It is safe to start with lower capacity and scale up as needed. +- LMDB is a memory backed database. More RAM than recommended will help read performance after data is cached. ::: ### CPU Requirements {#cpu-requirements} diff --git a/versioned_docs/version-2.0.0/operators/setup/install-node.md b/versioned_docs/version-2.0.0/operators/setup/install-node.md index 66fcc0652..5f5b9f4eb 100644 --- a/versioned_docs/version-2.0.0/operators/setup/install-node.md +++ b/versioned_docs/version-2.0.0/operators/setup/install-node.md @@ -18,28 +18,8 @@ The following ports are used by the node: Of these `35000` is the only port required to be open for your node to function, however, opening `8888` will allow others to know general network health. For more details, see the additional information on [Node Endpoints](./node-endpoints.md). ## Operating System Requirements -The recommended OS version is Ubuntu 20.04. - -### Using Ubuntu 22.04 or 24.04 - -Installing using Ubuntu 22.04 or 24.04 follows the same instructions as 20.04 with one exception: - -If you try to install packages, you will receive: - -``` -casper-client : Depends: libssl1.1 (>= 1.1.0) but it is not installable -``` - -This message is due to the default `openssl` moving to 3.* with Ubuntu 22.04. You need to install OpenSSL 1.* for prior versions of Ubuntu to use the Casper binaries with the following command: - -``` -curl -f -JLO http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb -sudo apt install ./libssl1.1_1.1.1f-1ubuntu2_amd64.deb -``` - -## Required Number of Open Files - -Before beginning, [update the maximum open files limit](./open-files.md) for your system. Specifically, update the node's `/etc/security/limits.conf` file as described [here](./open-files.md#updating-limits-conf), to ensure proper node operation. +The recommended OS version is Ubuntu 22.04, Ubuntu 24.04 or Debian 13. +The current binary build OS is Ubuntu 22.04 and a Debian based system with Clib equal to or newer than the build system will work. ## Required Clean Up @@ -63,10 +43,10 @@ The following commands will set up the Casper repository for packages: ```bash sudo mkdir -m 0755 -p /etc/apt/keyrings/ sudo curl https://repo.casper.network/casper-repo-pubkey.gpg --output /etc/apt/keyrings/casper-repo-pubkey.gpg -echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/casper-repo-pubkey.gpg] https://repo.casper.network/releases focal main" | sudo tee -a /etc/apt/sources.list.d/casper.list +echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/casper-repo-pubkey.gpg] https://repo.casper.network/releases jammy main" | sudo tee -a /etc/apt/sources.list.d/casper.list sudo apt update ``` -We are creating /etc/apt/keyrings if needed, so we don't have the issue with this key being trusted by all APT requests if stored in /etc/apt/trusted.gpg.d. +We are creating `/etc/apt/keyrings` if needed, so we don't have the issue with this key being trusted by all APT requests if stored in `/etc/apt/trusted.gpg.d`. ## Required Tools @@ -85,7 +65,7 @@ It defaults to `bash` but can be changed with the `--shell` argument: --shell The type of shell to generate the completion script for [default: bash] [possible values: zsh, bash, fish, powershell, elvish] -sudo casper-client generate-completion --shell powershell +sudo casper-client generate-completion --shell bash ``` You need to source the new auto completion script or log out and log in again to activate it for the current shell: @@ -95,18 +75,22 @@ source /usr/share/bash-completion/completions/casper-client Now you can use `casper-client` and press the `tab` key to get auto completion for your commands. +## Required Number of Open Files + +Before beginning, [update the maximum open files limit](./open-files.md) for your system. Specifically, update the node's `/etc/security/limits.conf` file as described [here](./open-files.md#updating-limits-conf), to ensure proper node operation. + ## Installing All Protocols On **Mainnet**, run: ```bash -sudo -u casper /etc/casper/node_util.py stage_protocols casper.conf +sudo -u casper casper-node-util stage_protocols casper.conf ``` On **Testnet**, run: ```bash -sudo -u casper /etc/casper/node_util.py stage_protocols casper-test.conf +sudo -u casper casper-node-util stage_protocols casper-test.conf ``` ## Validator Keys @@ -163,44 +147,48 @@ If you are using the node for historical data and want to query back to genesis, sync_handling = genesis ``` +DB archives are made of networks and if you are launching an archival node, requesting these from Casper will make node setup much faster. Historical block syncing is the lowest priority in network operation and take more time as the chain grows. + ## Starting the Node Start the node using the following commands: ```bash -sudo /etc/casper/node_util.py rotate_logs -sudo /etc/casper/node_util.py start -``` +sudo casper_node_util start +``` ### Monitoring the Synchronization Process The following command will display the node synchronization details: ```bash -/etc/casper/node_util.py watch +casper_node_util watch ``` -When you first run the watch command, you may see the message `RPC: Not Ready`. Once the node is synchronized, the status will change to `RPC: Ready` and a similar output: - ```bash -Last Block: 630151 (Era: 4153) -Peer Count: 297 -Uptime: 4days 6h 40m 18s 553ms -Build: 1.4.5-a7f6a648d-casper-mainnet -Key: 0147b4cae09d64ab6acd02dd0868722be9a9bcc355c2fdff7c2c244cbfcd30f158 +Last Block: 5473886 (Era: 19015) +Peer Count: 125 +Uptime: 7days 15h 52m 32s +Build: 2.0.3-4c7068d +Key: 01b08d9184ec9daed7f1d2766674746d6cd8460ca6e0274fa48d01c3ded165da4c Next Upgrade: None -RPC: Ready +Reactor State: KeepUp +Available Block Range - Low: 0 High: 5473886 ● casper-node-launcher.service - Casper Node Launcher - Loaded: loaded (/lib/systemd/system/casper-node-launcher.service; enabled; vendor preset: enabled) - Active: active (running) since Wed 2022-03-16 21:08:50 UTC; 4 days ago - Docs: https://docs.casper.network - Main PID: 2934 (casper-node-lau) - Tasks: 12 (limit: 4915) - CGroup: /system.slice/casper-node-launcher.service - ├─ 2934 /usr/bin/casper-node-launcher - └─16842 /var/lib/casper/bin/1_4_5/casper-node validator /etc/casper/1_4_5/config.toml + Loaded: loaded (/usr/lib/systemd/system/casper-node-launcher.service; enabled; preset: enabled) + Active: active (running) since Wed 2025-08-13 20:41:05 UTC; 1 week 0 days ago + Docs: https://docs.casper.network + Main PID: 76968 (casper-node-lau) + Tasks: 8 (limit: 18921) + Memory: 10.2G (peak: 11.0G) + CPU: 1d 17h 2min 43.802s + CGroup: /system.slice/casper-node-launcher.service + ├─76968 /usr/bin/casper-node-launcher + └─76971 /var/lib/casper/bin/2_0_3/casper-node validator /etc/casper/2_0_3/config.toml + +Aug 13 20:41:05 ip-10-0-5-211 systemd[1]: Started casper-node-launcher.service - Casper Node Launcher. ``` The reactor state will be in CatchUp mode until it acquires the full tip state, at which point it will shift to KeepUp mode. If you left `sync_to_genesis` as `true`, it will begin syncing back history at this time. @@ -224,6 +212,7 @@ trie_or_chunk_timeouts 0 ``` If the node is not showing active (running) status, it is either stopped or in the process of restarting. +Indexing of the DB on startup can take some time if the node is archival. ### Monitoring the Running Node diff --git a/versioned_docs/version-2.0.0/operators/setup/joining.md b/versioned_docs/version-2.0.0/operators/setup/joining.md index b3d40106f..bc887b763 100644 --- a/versioned_docs/version-2.0.0/operators/setup/joining.md +++ b/versioned_docs/version-2.0.0/operators/setup/joining.md @@ -14,111 +14,47 @@ Visit the [Hardware Specifications](./hardware.md) section and provision your no Follow the instructions on the [Node Setup](./install-node.md) page. -## Step 3: Building the Required Contracts {#step-3-build-contracts} +## Step 3: Creating and Fund Keys for Bonding {#step-3-create--fund-keys-for-bonding} -Use the commands below to build all the necessary contracts for bonding, retrieving rewards, and unbonding. +See the [Node Setup](./basic-node-configuration.md#create-fund-keys) instructions if you have not generated a validator key. This lives in `/etc/casper/validator_keys`. +This will need funded to allow bonding. -1. Clone the casper-node repository. +## Step 4: Updating the Trusted Hash {#step-5-update-the-trusted-hash} -```bash -git clone https://github.com/casper-network/casper-node -``` +The node's `config.toml` needs to be updated with a recent trusted hash. -2. Install these prerequisites, which are also listed [here](https://github.com/casper-network/casper-node#pre-requisites-for-building). +See the [Trusted Hash for Synchronizing](./basic-node-configuration.md#trusted-hash-for-synchronizing) instructions if you have not set up a trusted hash during node installation. -- [Rust](../../developers/writing-onchain-code/getting-started.md#installing-rust) -- [CMake](https://cgold.readthedocs.io/en/latest/first-step/installation.html) -- `pkg-config` - On Ubuntu, use `sudo apt-get install pkg-config` -- `openssl` - On Ubuntu, use `sudo apt-get install openssl` -- `libssl-dev` - On Ubuntu, use `sudo apt-get install libssl-dev` +## Step 5: Setting sync mode -3. Install the [Rust casper-client](../../developers/prerequisites.md#install-casper-client) and fund the [keys](../setup/basic-node-configuration.md#create-fund-keys) you will use for bonding. +The default mode in config for sync is `ttl`. Available options are listed as comments in the `config.toml`. The only sync modes for an operating node are `nosync`, `ttl`, or `genesis`. -4. Use the following commands to build the contracts in release mode. Make sure you have [installed Rust](../../developers/writing-onchain-code/getting-started.md#installing-rust). +`ttl` syncs the Time To Live data, which is the minimum history needed to operate as a validator. `nosync` would need to wait for the ttl period to get this history until possible to transition into `Validate`. -```bash -cd casper-node -make setup-rs -make build-client-contracts -``` +The sync condition needs to be met before it is possible to transition from `KeepUp` to `Validate`. There are two reasons why `ttl` is recommended for a validator. -These commands will build all the necessary Wasm contracts for operating as a validator: -- `activate_bid.wasm` - Reactivates an ejected validator -- `add_bid.wasm` - Enables bonding for validator stake -- `delegate.wasm` - Delegates stake -- `undelegate.wasm` - Undelegates stake -- `withdraw_bid.wasm` - Enables unbonding for validator stake +### Improved performance of caching -## Step 4: Creating and Fund Keys for Bonding {#step-4-create--fund-keys-for-bonding} +`ttl` sync reduces disk space drastically compared to a `genesis` sync archive mode. This improves performance of LMDB DB as it is memory cached and gives higher probablity of cache hits. -See the [Node Setup](./basic-node-configuration.md#create-fund-keys) instructions if you have not generated and funded your validator keys. +### Dangers of `genesis` sync archival validators -## Step 5: Updating the Trusted Hash {#step-5-update-the-trusted-hash} +A node must sync to the tip of the chain and be in `KeepUp` state before transitioning to `Validate` state. However, prior to this transition, the historical sync operation must complete. -The node's `config.toml` needs to be updated with a recent trusted hash. +With a `ttl` node this is the minimum state required to operate as a validator. Even if a node has been shut down for some time, acquiring this data is generally fast. -See the [Trusted Hash for Synchronizing](./basic-node-configuration.md#trusted-hash-for-synchronizing) instructions if you have not set up a trusted hash during node installation. +If a node is in `genesis` sync mode, the historical state required is all the way back to the highest block previously synced. The node cannot transition to `Validate` mode until the full historical sync is complete. Historical sync is deprioritized, so this can cause a considerable delay in getting back operational as a validator after prolonged downtime. -## Step 6: Starting the Node {#step-6-start-the-node} - -Start the node with the `casper-node-launcher`: - -```bash -sudo systemctl start casper-node-launcher -``` - -The above Debian package installs a casper-node service for systemd. - -For more information, visit [GitHub](https://github.com/casper-network/casper-node/wiki#node-operators). - -## Step 7: Confirming the Node is Synchronized {#step-7-confirm-the-node-is-synchronized} - -While the node is synchronizing, the `/status` endpoint is available. You will be able to compare this to another node's status endpoint `era_id` and `height` to determine if you are caught up. You will not be able to perform any `casper-client` calls to your `7777` RPC port until your node is fully caught up. - -Towards the end of the following output, notice the `era_id` and `height` that you can use to determine if your node has completed synchronizing. - -
-Sample output of the /status endpoint - -```json -{ - "api_version": "1.4.3", - "chainspec_name": "casper-test", - "starting_state_root_hash": "e2218b6bdb8137a178f242e9de24ef5db06af7925e8e4c65fa82d41df38f4576", - "peers": [ - { - "node_id": "tls:0097..b253", - "address": "18.163.249.168:35000" - }, - ... - ... - ... - { - "node_id": "tls:ff95..c014", - "address": "93.186.201.14:35000" - } - ], - "last_added_block_info": { - "hash": "8280de05cb34071f276fbe7c69a07cb325ddd373f685877911238b614bdcc5b1", - "timestamp": "2022-01-04T15:33:08.224Z", - "era_id": 3240, - "height": 430162, - "state_root_hash": "ec4ff5c4d0a9021984b56e2b6de4a57188101c24e09b765c3fee740353690076", - "creator": "01ace6578907bfe6eba3a618e863bbe7274284c88e405e2857be80dd094726a223" - }, - "our_public_signing_key": "01cb41ee07d1827e243588711d45040fe46402bf3901fb550abfd08d1341700270", - "round_length": null, - "next_upgrade": null, - "build_version": "1.4.3-a44bed1fd-casper-mainnet", - "uptime": "25days 1h 48m 22s 47ms" -} -``` -
- -## Step 8: Sending the Bonding Request {#step-7-send-the-bonding-request} +## Step 5: Confirming the Node is Synchronized {#step-5-confirm-the-node-is-synchronized} -You can submit a [bonding request](../becoming-a-validator/bonding.md) to change your synchronized node to a validating node. +The `casper-node-util watch` command gives display of current node status. And example output is given on the [Node Setup](./basic-node-configuration.md#create-fund-keys) page. -The bonding request must be sent after the node has synchronized the protocol state and linear blockchain to avoid being ejected for liveness failures. +The node has a reactor state machine displayed as `Reactor State:` in the `watch` command. This is coming from the `localhost:8888/status` endpoint. + +Full status endpoint output can be seen with: `curl localhost:8888/status | jq`. We are piping to `jq` for clean `json` output. +## Step 6: Sending the Bonding Request {#step-6-send-the-bonding-request} +You can submit a [bonding request](../becoming-a-validator/bonding.md) to change your synchronized node to a validating node. + +The bonding request must be sent after the node has synchronized the protocol state and linear blockchain to avoid being ejected for liveness failures. diff --git a/versioned_docs/version-2.0.0/operators/setup/node-endpoints.md b/versioned_docs/version-2.0.0/operators/setup/node-endpoints.md index fae06b053..db7a55304 100644 --- a/versioned_docs/version-2.0.0/operators/setup/node-endpoints.md +++ b/versioned_docs/version-2.0.0/operators/setup/node-endpoints.md @@ -17,6 +17,9 @@ Node operators can modify a node's configuration options, including the port set The default endpoints for Mainnet and Testnet are open by default and are described below in more detail. If the node connects to a different network, the ports may differ depending on how the network was set up. +## Default IP bonding + +On all defaults given in `config-example.toml` which generates `config.toml` have the bond all interfaces `0.0.0.0` address. If you wish to restrict interfaces, provide the correct IP for these config locations. ## Default Networking Port: 35000 {#35000} @@ -28,17 +31,24 @@ bind_address = '0.0.0.0:35000' If the networking port is closed, the node becomes unreachable, and the node won't be discoverable in the network. If this is a validator, it will face eviction. A read-only node will be considered to be offline. - ## Default JSON-RPC HTTP Server Port: 7777 {#7777} -The configuration options for the JSON-RPC HTTP server are under the `rpc_server` section in the `config.toml` file. The `address` using port 7777 is the listening address for JSON-RPC HTTP server. +The configuration options for the JSON-RPC HTTP server is now in `/etc/casper-sidecar/config.toml`, as the RPC service has moved outside of the node. ```md -address = '0.0.0.0:7777' +ip_address = '0.0.0.0' +port = 7777 ``` -DApps would use this address to [interact with the Casper JSON-RPC API](../../developers/json-rpc/index.md). Users would use this address to [interact with the network using CLI](../../developers/cli/index.md). Validators would use this address to [bond](../becoming-a-validator/bonding.md#example-bonding-transaction) or [unbond](../becoming-a-validator/unbonding.md). If this port is closed, the requests coming to this port will not be served, but the node remains unaffected. +DApps would use this address to [interact with the Casper JSON-RPC API](../../developers/json-rpc/index.md). Users would use this address to [interact with the network using CLI](../../developers/cli/index.md). Validators would use this address to [bond](../becoming-a-validator/bonding.md#example-bonding-transaction) or [unbond](../becoming-a-validator/unbonding.md). If this port is closed or the `casper-sidecar` is not installed, the requests coming to this port will not be served, but the node remains unaffected. + +## Default Binary-RPC HTTP Server Port: 7779 {#7779} +The node RPC moved to the `casper-sidecar` and was replaced with the binary RPC interface. This can be exposed externally if desired for direct calling to node in binary format, which is more efficient than JSON-RPC. However, single RPC calls can involve multiple binary port calls to build up expected data. + +```md +address = '0.0.0.0:7779' +``` ## Default REST HTTP Server Port: 8888 {#8888} @@ -52,6 +62,7 @@ Opening port 8888 is recommended but not required. This port allows the node to One may use this port to [get a trusted hash](./basic-node-configuration.md#trusted-hash-for-synchronizing), [verify successful staging](../maintenance/upgrade.md#verifying-successful-staging) during an upgrade, or to [confirm that the node is synchronized](./joining.md#step-7-confirm-the-node-is-synchronized). +If restricting port 8888, it is requested that access is allowed from `3.21.239.186` for the casper-network-monitor to track overall health of the network. ### Example usage diff --git a/versioned_docs/version-2.0.0/operators/setup/node-events.md b/versioned_docs/version-2.0.0/operators/setup/node-events.md index 87f9a26b8..89d50fdcb 100644 --- a/versioned_docs/version-2.0.0/operators/setup/node-events.md +++ b/versioned_docs/version-2.0.0/operators/setup/node-events.md @@ -30,7 +30,7 @@ curl -sN http://HOST:PORT/events?start_from=ID **Example:** ```bash -curl -sN http://65.21.235.219:9999/events?start_from=29267508 +curl -sN http://localhost:9999/events?start_from=29267508 ``` :::note