Skip to content

Updates for 2.0.0 and 2.0.3 #99

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 27, 2025
Merged

Updates for 2.0.0 and 2.0.3 #99

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
77f787b
Merge pull request #88 from casper-network/dev
devendran-m Jun 19, 2025
2db9146
Merge pull request #90 from casper-network/dev
mrkara Jul 5, 2025
9953cd3
Merge pull request #94 from casper-network/dev
mrkara Jul 21, 2025
a24030f
Updated old information on installing node.
sacherjj Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions versioned_docs/version-2.0.0/operators/setup/basic-node-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 6 additions & 2 deletions versioned_docs/version-2.0.0/operators/setup/hardware.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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}
Expand Down
83 changes: 36 additions & 47 deletions versioned_docs/version-2.0.0/operators/setup/install-node.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -85,7 +65,7 @@ It defaults to `bash` but can be changed with the `--shell` argument:
--shell <STRING> 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:
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand Down
114 changes: 25 additions & 89 deletions versioned_docs/version-2.0.0/operators/setup/joining.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<details>
<summary>Sample output of the <code>/status</code> endpoint</summary>

```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"
}
```
</details>

## 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.
19 changes: 15 additions & 4 deletions versioned_docs/version-2.0.0/operators/setup/node-endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand All @@ -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}

Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-2.0.0/operators/setup/node-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down