# Run Your Starknet Node Workshop: All You Need To Get Started

## What is a Node?
- A node is a computer running Ethereum software often referred to as a 'client'
- This software (client) downloads a copy of the Ethereum blockchain and verifies the validity of every block, then keeps it up-to-date with new blocks and transactions, and helps others download and update their own copies.

## Why Run a Node?
- Censorship Resistance: There's possibility for 3rd-party nodes to reject transactions from specific IP addresses, or transactions that involve specific accounts, potentially blocking you from using the network when you need it. With your own node, there's guarantees that your submitted transaction is broadcasted to the rest of the peer-to-peer network at any time.
Eg: [In March 2022, Infura, MetaMask's default Remote Procedure Call (RPC) provider in a bid to comply with U.S. sanctions, implemented access restrictions for users in certain regions, including Venezuela, thus making users in such regions not to be able to access Ethereum via MetaMask](https://x.com/infura_io/status/1499446960725512202). [Details here]( https://www.coindesk.com/business/2022/03/04/crypto-industrys-sanctions-woes-on-full-display-in-metamasks-venezuela-hiccup)
- Privacy and Security - When sending transactions using public nodes, personal information can be leaked to these third-party services such as your IP address and which Ethereum addresses you own. By pointing compatible wallets to your own node you can use your wallet to privately and securely interact with the blockchain.
- Promotes the decentralization promise of blockchains - Network resilience is achieved with more nodes, in geographically diverse locations, operated by more people of diverse backgrounds. As more people run their own node, reliance on centralized points of failure diminishes, making the network stronger. resists centralized points of failure. Centralized cloud servers can provide a lot of computing power, but they provide a target for nation-states or attackers looking to disrupt the network. A diverse set of nodes is important for Ethereum’s health, security and operational resiliency.
- Sovereignty: Most Ethereum wallets like Metamask, etc typically reach out to a 3rd-party node, such as Infura or Alchemy, when looking up your balances. Running your own node allows you to have your own copy of the Ethereum blockchain. An Ethereum wallet allows you to take full custody and control of your digital assets by holding the private keys to your addresses, but those keys don't tell you the current state of the blockchain, such as your wallet balance.

- Public RPC - you can provide your own custom RPC endpoints publicly to the community to help them avoid big centralized providers

## Categeries of Ethereum Clients
- Execution client
- Consensus client

## Execution Client:
- A software implementing the specification for the Execution Layer as it tracks network upgrades and implements core methods like `apply_fork`, `get_last_256_block_hashes`, `state_transition` - apply a block to an existing block chain
- The Engine JSON-RPC API is a collection of methods that all execution clients implement. This interface allows the communication between consensus and execution layers of the two-component post-Merge Ethereum Client.
- The execution client creates execution payloads:
- the list of transactions
- updated state trie
- and other execution-related data.

- Examples of Execution clients:
- [Go-Ethereum (GETH)](https://github.com/ethereum/go-ethereum) - Go implementaion
- [Nethermind](https://github.com/NethermindEth/nethermind) - C# implementation
- [Erigon](https://github.com/erigontech/erigon) - Go implementation
- [Reth](https://github.com/paradigmxyz/reth) - Rust
- [Besu](https://github.com/hyperledger/besu) - Java implementation

## Transition to Proof-of-Stake (PoS)
- On September 15, 2022, Ethereum transitioned from Proof-of-Work to Proof-of-Stake.
- The Beacon Chain now manages validator coordination and consensus.

## Consensus Client:
- A software implementing core consensus specs
- Core specifications for Ethereum proof-of-stake clients which are divided into features
- These features are researched and developed in parallel, and then consolidated into sequential upgrades when ready:

| Seq | CodeName | Fork Epoch |
| --- | --------- | ---------- |
| 0 | Phase0 | 0 |
| 1 | Altair | 74240 |
| 2 | Bellatrix | 144896 |
| 3 | Capella | 194048 |
| 4 | Deneb | 269568 |
| 5 | Electra | 364032 |

- Additional standards outside of requisite client functionality include:
- Beacon APIs
- Engine APIs
- Beacon Metrics
- Builder Specs

- The consensus client is further divided into:
- beacon node (BN)
- peer to peer node
- responsible for networking, state transition, message validation, state storage
- validator client (VC)
- responsible for validator key management and duties
- not required unless staking
- interfaces with a beacon node via http

- Examples of consensus clients:
- [Lighthouse]( https://github.com/sigp/lighthouse.git) - Rust implementaion
- [Prysm](https://github.com/prysmaticlabs/prysm) - Go
- [Lodestar](https://github.com/prysmaticlabs/prysm) - Typescript implementation
- [Teku](https://github.com/Consensys/teku) - Java implementation
- [Nimbus](https://github.com/status-im/nimbus-eth2) - Nim implementation
- [Grandine](https://github.com/grandinetech/grandine) - Rust

## Consensus and Execution

| **Execution Client** | **Consensus Client** | **Validator** |
| -------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------- |
| Gossips transactions over its P2P network | Gossips blocks and attestations over its P2P network | Proposes blocks |
| Executes/re-executes transactions | Runs the fork choice algorithm | Accrues rewards/penalties |
| Verifies incoming state changes | Keeps track of the head of the chain | Makes attestations |
| Manages state and receipts tries | Manages the Beacon state (contains consensus and execution info) | Requires 32 ETH to be staked |
| Creates execution payload | Keeps track of accumulated randomness in RANDAO | Can be slashed |
| Exposes JSON-RPC API for interacting with Ethereum | Keeps track of justification and finalization | |

## Hardware Requirements: Recommended specifications
- Fast CPU with 4+ cores
- 16 GB+ RAM (Min of 8GB)
- Fast SSD with 2+TB
*NB: The Execution client relies heavily on IOPS, or "operations per second";
recommendations:
15k Read IOPS, and 5k Write IOPS In practice, this means that:
- HDD (spinning platter) drives will not work
- SATA or external USB 3.0+ SSDs can work
- NVMe SSD drives are preferred
If you already have an SSD you want to use and want to be sure it has sufficient performance for node operation.*
Get a TLC-based NVMe SSD with DRAM cache and high endurance (TBW ≥ 600TB).
- 25+ MBit/s bandwidth
- Tabular comparison between NVme & SATA
| Interface | Speed (typical) |
| --------- | --------------- |
| SATA | \~500 MB/s |
| NVMe | 3,500+ MB/s |

---
# 🛠️ Setting up an L1 Ethereum Node from Source
- For easy navigation, create an `eth_node` folder in your machine.
- Create 2 sub folders, thus:
- execution
- consensus
- In the `eth_node` folder, create a JWT secret file. This JWT secret file serves as a secure communication between the execution client and the consensus client:

`openssl rand -hex 32 | tr -d "\n" | tee jwt.hex`
- You should have the following folder structure:

.
├── consensus/
├── execution/
└── jwt.hex

### Execution Client Setup (Reth)
- First, install Rust using rustup：
`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
`

- Install the following Ubuntu packages:

sudo apt update && sudo apt install -y git gcc g++ make cmake pkg-config llvm-dev libclang-dev clang

- `cd` into your `execution` folder `~/eth_node/execution`
- Clone `reth` repo:

git clone https://github.com/paradigmxyz/reth
cd reth

- Then, install Reth into your PATH directly via:
`cargo install --locked --path bin/reth --bin reth`

- After installing `reth`, make sure the binary exists by running `which reth` or `reth --version`
- Now that we have `reth` installed, it's time to run our `reth` execution client; open another terminal and run:

reth node --chain sepolia --authrpc.jwtsecret ~/eth_node/jwt.hex --authrpc.addr 127.0.0.1 --authrpc.port 8551 --http --http.addr 0.0.0.0 --http.port 8545 --ws --ws.addr 0.0.0.0 --ws.port 8546

### Consensus Client Setup (Lighthouse)
- First, make sure you have rust installed. You can follow the guide for installing rust while configuring your machine for `reth` as described above
`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
`

- Install the following Ubuntu packages:

sudo apt update && sudo apt install -y git gcc g++ make cmake pkg-config llvm-dev libclang-dev clang

- `cd` into your `consensus` folder `~/eth_node/consensus`
- Clone the lighthouse repo:

git clone https://github.com/sigp/lighthouse.git
cd lighthouse
make

- After [installing `ligthouse`](https://lighthouse-book.sigmaprime.io/installation.html), make sure the binary exists by running `which lighthouse` or `lighthouse --version`

- To run the beacon node of the lighthouse consensus client, use this command:

lighthouse bn --network sepolia --execution-endpoint http://localhost:8551 --execution-jwt ~/eth_node/jwt.hex --checkpoint-sync-url https://sepolia.beaconstate.info --http --http-address 0.0.0.0 --disable-deposit-contract-sync

- With these, we have our L1 Ethereum full node running

### FAQ: Can I share an execution node between multiple beacon nodes (many:1)?
It is not possible to connect more than one beacon node to the same execution engine. There must be a 1:1 relationship between beacon nodes and execution nodes. The beacon node controls the execution node via the engine API, telling it which block is the current head of the chain. If multiple beacon nodes were to connect to a single execution node they could set conflicting head blocks, leading to frequent re-orgs on the execution node.In the future, there will be HTTP proxies available which allow node operators to nominate a single controlling beacon node, while allowing consistent updates from other beacon nodes.

# 🛠️ Running Your L2 Starknet Juno Node from Source
- Our Juno full node will run as a separate service on the existing L1 full node.
- Juno connects to our execution client at port `8546`
- This guide helps you build and run a [Juno](https://github.com/NethermindEth/juno) node from source, including all prerequisites and step-by-step instructions.

---

### ⚙️ Prerequisites
You need a fully synced L1 full node

Ensure your system has the following installed:

- **Go** [1.23 or later](sudo apt update
sudo apt install golang-go) via
- **Rust** (via [rustup.rs](https://rustup.rs))
- **C compiler** (`gcc` or `clang`)
- **jemalloc** memory allocator `sudo apt-get install -y libjemalloc-dev`

#### On Ubuntu:

sudo apt-get update
sudo apt-get install -y build-essential libjemalloc-dev

> ⚠️ **Important:** Install `libjemalloc-dev` **before** building the project, or the build will fail.

---

### 📦 Step 1: Clone the Repository
- Create a folder called `stark_node` with 2 sub folders, thus:
- juno
- staking-validator

- You should the following structure in your `stark_node` folder

.
├── juno /
├── staking-validator /

- `cd` into `juno` and clone the juno repo and run this command:

git clone https://github.com/NethermindEth/juno.git
cd juno

---

### 🛠️ Step 2: Build the Binary

make build

The binary will be available at: `./build/juno`

---

### 📁 Step 3: Prepare the Snapshots Directory

Create a directory to store the chain database:

mkdir -p $HOME/snapshots/juno_sepolia

---

### 🚀 Step 4: Run the Node

./build/juno \
  --http \
  --http-port 6060 \
  --http-host 0.0.0.0 \
  --db-path $HOME/snapshots/juno_sepolia \
  --eth-node <ws://YOUR-EXECUTION-CLIENT-IP:8546>

Alternatively, you can create a config `run.yml` file with this this config:

log-level: info
network: mainnet
http: true
http-port: 6060
http-host: 0.0.0.0
eth-node: ws://127.0.0.1:8546
metrics: true
metrics-port: 26660

1. `log-level` - type of details to be logged while running juno. Either trace, debug, info, warn, error logs
2. `network` - the selected network to run Juno on whether mainnet, sepolia, sepolia-integration
3. `http` - enables the HTTP RPC server on the default port and interface
4. `http-port` - the port on which the HTTP server will listen for requests
5. `http-host` - interface on which the HTTP RPC server will listen for requests
6. `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
7. `metrics` - enables the Prometheus metrics endpoint on the default port
8. `metrics-port` - the port on which the Prometheus endpoint will listen for requests. Default port is 9090. However, you may need to specify a different port like `26660` if port is already in use by Prometheus service
- To run Juno with this config:
`./build/juno --config run.yml`

> 🧠 Note: Juno requires a WebSocket-based execution client (e.g. Geth or Nethermind, or Reth).
Make sure you have WS enabled and it is reachable at the provided address.

--eth-node ws://127.0.0.1:8546

---

### 🧪 Step 5: Monitor the Logs

If you're running it directly, logs will print to your terminal.

---

### To retrieve the latest Starknet block, run:

curl --location 'http://localhost:6060' --header 'Content-Type: application/json' --data '{
    "jsonrpc": "2.0",
    "method": "starknet_blockNumber",
    "params": [],
    "id": 1
}' | jq

---

# Updating Juno (Standalone binary)

- Pull the latest updates to the codebase
`git pull`

---

- Rebuild the binary:
`make juno`

---

- Verify the updated version
`cd build && ./juno --version`


---

# Setting Up A Validator
- At the time of writing this documentation, Starknet sequencer is currently still centralized - [Starkware Sequencer](https://github.com/starkware-libs/sequencer/)
- It is gradually moving towards employing a staking protocol, handing over the responsibilities of producing, attesting, and proving blocks to validators.

- The process of becoming a validator involves three main steps:
- Running a Juno node: Ensure you have the latest version properly configured with adequate resources
- Acquiring STRK tokens: A minimum of 20,000 STRK is required for staking on mainnet (1 STRK is required for staking on Sepolia testnet), like a security deposit that ensures validators have "skin in the game"
- Staking tokens: Register as a validator through the Starknet staking contract
- Pre-approve STRK transfer to the staking contract
- Call the stake function with your operational and reward addresses
- Set commission rates and enable pooling if desired

Starknet’s staking protocol features two options for participation:

- Staking directly as validators: Staking a minimum of 20,000 STRK for mainnet (1 STRK for sepolia testnet) and earning rewards by handling any responsibilities the protocol requires

- Staking indirectly as delegators: Delegating STRKs to validators who allow delegation and sharing in their rewards without handling any of their responsibilities

### Installation of `sncast` CLI
- It's time to make network requests to Starknet via `sncast` CLI.
- Using `sncast` CLI is only possible if you have `starknet-foundry` installed; this can be installed directly using [starkup](https://github.com/software-mansion/starkup) by running this this command:

curl --proto '=https' --tlsv1.2 -sSf https://sh.starkup.sh | sh

Then run`starkup`; this command unpacks all the required binaries to run starknet-foundry including `sncast`
- Verify that you have `sncast` by running:
`which sncast` or `sncast --version`

- To become a Starknet validator, you need:
- a Starknet account
- 20000 STRK tokens (for Mainnet) or 1 STRK (for Sepolia) to successfully stake.

- If you have an existing account, you'll need the private key of such account, otherwise you can create a new directly from your CLI using `sncast`:

sncast \
    account create \
    --url http://localhost:6060 \
    --name validator_account

- The above command automatically creates an OpenZepellin-Standard account on Starknet's Sepolia testnet
##### NB - The private key of this created account will be used to configure our validator. Please keep it safe

- This newly created account must be funded via https://starknet-faucet.vercel.app/
- With the now account funded, next, we deploy this account:

sncast \
    account deploy \
    --url http://localhost:6060 \
    --name validator_account

- You can now access the metadata of this account any time from your machine by running:
`cat ~/.starknet_accounts/starknet_open_zeppelin_accounts.json`
- The above command outputs relevant details of the account housed in this json file like so:

 "validator_account": {
      "address": "Your-address",
      "class_hash": "0x61dac032f228abef9c6626f995015233097ae253a7f72d68552db02f2971b8f",
      "deployed": true,
      "legacy": false,
      "private_key": "Your-private-key",
      "public_key": "Your-public-key",
      "salt": "Your-salt"
    }

- Make sure NEVER TO:
- expose your private key
- modify this json file.

### Approve and Stake `STRK` tokens
- We are done with creating and funding our account
- To become a validator, you must grant `Starknet Staking` [contract](https://sepolia.starkscan.co/contract/0x03745ab04a431fc02871a139be6b93d9260b0ff3e779ad9c8b377183b23109f1) permission by calling the `approve` method on the `STRK` token contract:

sncast --account workshop_account invoke --url http://localhost:6060 --contract-address 0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d --function "approve" --arguments '0x03745ab04a431fc02871a139be6b93d9260b0ff3e779ad9c8b377183b23109f1, 1'

- Then stake your STRK tokens to register as a validator:

sncast --account workshop_account invoke --url http://localhost:6060 --contract-address 0x03745ab04a431fc02871a139be6b93d9260b0ff3e779ad9c8b377183b23109f1 --function "stake" --arguments 'Your-validator-address, Your-validator-address, 1000000000000000000, true, 500'

### Staking Validator Installation
With our Juno up and running & our STRK tokens staked, it's time to install and run our validator client.
- Netherminds's `Starknet-Staking-v2` is a validator software that enables users to participate in Phase 2 of Starknet's staking protocol by performing block attestation.
- Validators attest to randomly assigned blocks during each epoch to prove they are actively tracking the network, which is essential preparation for future phases where validators will have full consensus responsibilities.
- We will be setting up this tool by building from source:
- `cd` into the `staking-validator` sub-folder within your `stark_node` folder and clone the `starknet-staking-v2` thus:

git clone https://github.com/NethermindEth/starknet-staking-v2.git
cd starknet-staking-v2

- Build the validator: `make validator` - the binary will be available at `./build/validator`

- Verify the installation: `./build/validator --help`

### Create validator config
In your machine create a config file, called `config.json`, with the following config:

{
  "provider": {
      "http": "http://localhost:6060/v0_8",
      "ws": "ws://localhost:6061/v0_8"
  },
  "signer": {
      "operationalAddress": "Your-validator-address",
      "privateKey": "Your-Private-Key"
  }
}

---

### Running Your Staking Validator
- You’re now ready to begin your attestation duties as a validator on Starknet. On another terminal, start your validator with the following command:

`./build/validator --config config.json --log-level trace`

- If this runs successfully, you'll see logs of blocks received,`block_header` metadata containing details of `block_hash`, `parent_hash`, `block_number`, `new_root`, `timestamp`, `sequencer_address`, attestation window capturing `start` and `end` blocks to be attested.
- There will be periodic attest transactions to be executed by your validator account. Make sure your validator account has enough gas to pay for such transactions.
- After a given attestation, you will find the status of the attestation, and relevant metadata of this transaction including `transaction_hash`, `finality_status` and `execution_status`
### Running Multiple Validators on a Single Juno Full Node
Juno allows you to run multiple validator accounts on a single full node. To do this:

- Define a separate configuration file (.json) - Eg `validator_2.json`, `validator_3.json` - for each validator account, specifying a unique provider and signer in each config.
- Ensure that each account has staked the required amount of STRK tokens and that the corresponding private key is correctly included in its configuration file.

- Once set up, each configured validator account will independently perform attestation duties through the same full node; Meaning on a different terminal within your `~/stark_node/staking-validator/starknet-staking-v2` folder, you can run the following command to start your 2nd validator:

./build/validator --config validator_2.json --log-level trace