Skip to main content

Quickstart: Run an Agora node (and a validator)

Select a configuration​

Introduction​

Agora-cl is an implementation of the Ethereum proof-of-stake consensus specification for use in the Agora public blockchain network. In this quickstart, you’ll use Agora-cl to run consensus layer node and optionally a validator. This will let you stake 40,000 BOA using hardware that you manage.

This is a beginner-friendly guide. Familiarity with the command line is expected, but otherwise this guide makes no assumptions about your technical skills or prior knowledge.

At a high level, we'll walk through the following flow:

  1. Configure an Agora execution node using Agora-el, an execution-layer client.
  2. Configure an Agora consensus node using Agora-cl, a consensus-layer client.
  3. Configure an Agora validator and stake BOA using Agora-validator (optional).

Knowledge Check

Not familiar with nodes, networks, and related terminology? Consider reading Nodes and networks before proceeding.

Step 1: Review prerequisites and best practices​

Node typeBenefitsRequirements
Agora Execution + Agora Consensus
  • Contributes to the security of Agora's ecosystem.
  • Lets you access the Agora network directly without having to trust a third party service.
  • Lets you run a validator post-Merge.
  • Software: Execution client, Agora node client (instructions for clients below), curl
  • OS: 64-bit Linux, Mac OS X 10.14+, Windows 10+ 64-bit
  • CPU: 4+ cores @ 2.8+ GHz
  • Memory: 16GB+ RAM
  • Storage: SSD with at least 2TB free space
  • Network: 8 MBit/sec broadband
ValidatorLets you stake BOA, propose + validate blocks, earn staking rewards + transaction fee tips.
  • Everything above, plus...
  • Software: Validator client, browser-based crypto wallet (instructions below)
  • Hardware: (Recommended) A new machine that has never been connected to the internet that you can use to securely generate your mnemonic phrase and keypair
  • 40,000 BOA (Mainnet)
  • 40,000 testnet BOA (Testnets)

Best practices​

  • If you're staking BOA as a validator, try this guide on a testnet first, then mainnet.
  • Keep things simple. This guidance assumes all client software will run on a single machine.
  • Review the latest advisories for the network(s) that you're using: testnet, Mainnet.
  • Review all of our published security best practices.
  • Join the community - join the Bosagora Telegram for updates and support.

Step 2: Install Agora Configuration​

Install latest docker client for your OS following the instructions at https://docs.docker.com/engine/install/

Download an install network
mkdir agora-chain
cd agora-chain
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/bosagora/agora-chain/v0.x.x/agora.sh)"

This will result in the following folder structure:

📂 agora-chain
  ┣  📂 docs
  ┣  📂 networks
    ┣ 📂 devnet
    ┣ 📂 mainnet
    ┣ 📂 testnet

Change to mainnet network:

./agora.sh network mainnet

Step 3: Run an Agora execution client​

In this step, you'll install an execution-layer client that Agora's consensus client will connect to.

Run the following command to initialize and run the execution layer client:

./agora.sh el-node init
./agora.sh el-node run

Syncing can take a long time - from minutes to hours depending on your network and hardware specification. You can proceed to the next step while your execution node syncs.

Congratulations - you’re now running an execution node in Agora's execution layer.

Step 4: Run an Agora consensus layer client​

Run the following command to run the consensus layer client:

./agora.sh cl-node run
If you're running a validator, specifying a suggested-fee-recipient wallet address will allow you to earn what were previously miner transaction fee tips. See [How to configure Fee Recipient](/docs/execution-node/fee-recipient) for more information about this feature.

Your Agora node will now begin syncing. This could take minutes, hours or even days depending on your network and hardware specs.

Congratulations - you’re now running a full, Merge-ready Agora node. To check the status of your node see [Check node and validator status]('/docs/monitoring/checking-status').

Step 5: Run an Agora validator​

Download the latest stable version of the deposit client from the Agora Staking Deposit Client Releases page.

Run the following command to create your mnemonic phrase and keys:

./agora.sh deposit-cli new-mnemonic

Follow the CLI prompts to generate your keys. This will give you the following artifacts:

  1. A new mnemonic seed phrase. This is highly sensitive and should never be exposed to other people or networked hardware.
  2. A validator_keys folder. This folder will contain two files:
    1. deposit_data-*.json - contains deposit data that you’ll later upload to the Agora staking site.
    2. keystore-m_*.json - contains your public key and encrypted private key.

Copy the validator_keys folder to your primary machine's agora-chain-testnet/root/config/cl/validator_keys folder. Run the following command to import your keystores, replacing <YOUR_FOLDER_PATH> with the full path to your agora-chain-testnet/root/config/cl/validator_keys folder:

./agora.sh validator import <YOUR_FOLDER_PATH>

You’ll be prompted to specify a wallet directory twice. Provide the path to your agora-chain-testnet/root/config/cl/validator_keys folder for both prompts. You should see Successfully imported 1 accounts, view all of them by running accounts list when your account has been successfully imported into Agora-cl.

Next, go to the Agora Mainnet staking deposit data upload page and upload your deposit_data-*.json file. You’ll be prompted to connect your wallet.

You can then deposit 40,000 BOA into the Mainnet deposit contract via the staking launchpad page. Exercise extreme caution throughout this procedure. Finally, run the following command to start your validator, replacing <YOUR_FOLDER_PATH> with the full path to your root/config/cl folder:

./agora.sh validator import <YOUR_FOLDER_PATH>
Congratulations!

You’re now running a full Agora consensus node and a validator.

It can a long time (from days to months) for your validator to become fully activated as there are a limitied number of validators allowed to join each Epoch. See Check node and validator status for detailed status monitoring guidance.

You can leave your execution client, Agora node, and validator client terminal windows open and running. Once your validator is activated, it will automatically begin proposing and validating blocks.

Frequently asked questions​

Why do you recommend putting everything on a single machine?
Keeping all of your client software on a single machine keeps things simple, which aligns with our security best practices.

Can I use Agora-cl on a Mac M1 ARM chip?
Mac M1 ARM chips currently require users to run Agora-cl through Rosetta. See our open bug for details.

Do I need to configure JWT if I'm using IPC instead of HTTP?
No.

Do I need to configure my firewall?
We recommend closing TCP port 8545 to the internet and keeping TCP and UDP ports 30303 open to support other execution nodes.

Can you mix and match networks between execution layer and consensus layer?
No. See Nodes and networks for more information.

Can I stake with less than 40,000 BOA?
Yes! Pooled staking lets you stake with less than 40,000 BOA.

What should I do if I can't run a node using my own hardware?
You can delegate hardware management to staking as a service providers.

Can I use a light node with Agora-cl, or do I need to run a full execution node?
No - at this time, a full node is required.

Can I use an external SSD connected via USB?
Yes, but your USB connection introduces a possible point of failure. If you do this, avoid connecting your SSD to your computer through a USB hub - instead, connect it directly.

Can I use a light client as my local execution client so I don't have to download so much data?
No, a full execution node is needed.

Why do I need to run my own execution client?
The Merge introduces a new Engine API that allows consensus-layer clients to communicate with execution-layer clients. Teku docs contain a great explainer here: The Merge.

What happens if my execution client goes down? Will I be penalized?
Yes. Downtime penalties are minimal but we recommend having uptime and downtime alerts configured for your execution node, Agora node, and validator if possible.

My Agora node is taking a long time to sync. Is there any way I can speed it up?
Yes - you can use checkpoint sync to start your Agora node's synchronization from a checkpoint rather than from genesis. This is actually a more secure way to run your Agora node.

My proposals aren't working, but my attestations are. What's going on?
This is usually an indication that your validator isn't able to communicate with your Agora node, or your Agora node isn't able to connect to your execution node.

How long does it take for my validator to be selected to propose a new block?
At the time of this writing, a ballpark estimate is around a week. Every 12 seconds a new block is proposed, and your validator has a one in [total number of active validators] chance of being chosen, so this duration can vary significantly from one validator to the next.