go-ethereum/test/TEST_REWARDS.md

Testing Whitelist Extra Rewards

This guide shows you how to verify that whitelisted validators receive double block rewards.

Prerequisites

You can test this in two ways:

1. Manual devnet setup (recommended for functional testing):
   Run two local geth processes (node1 + node2) with block production enabled.
2. Docker setup (for structure / integration):
   Spin up two nodes via docker-compose.

Manual Devnet Setup (no Docker)

These commands assume you are in a separate checkout of geth v1.11.6 in a directory like ~/Desktop/go-ethereum-v1.11, and that you have a genesis.json configured with the three accounts used in this test.

0. Clone and build geth v1.11.6 (one-time)

cd ~/Desktop
git clone https://github.com/ethereum/go-ethereum.git go-ethereum-v1.11
cd go-ethereum-v1.11
git checkout v1.11.6
make geth

1. Start node1 (whitelisted validator)

./build/bin/geth --datadir node1 init genesis.json

./build/bin/geth --datadir node1 \
  --networkid 1234 --nodiscover \
  --http --http.addr 0.0.0.0 --http.port 8545 \
  --port 30303 \
  --http.api eth,net,web3,admin,miner \
  --mine --miner.threads 1 \
  --miner.etherbase 0xca6b49ee60cdd276ab503fbd6fb80a3cfbc06ffc

2. Start node2 (non-whitelisted validator)

./build/bin/geth --datadir node2 init genesis.json

./build/bin/geth --datadir node2 \
  --networkid 1234 --nodiscover \
  --http --http.addr 0.0.0.0 --http.port 8546 \
  --port 30304 \
  --http.api eth,net,web3,admin,miner \
  --mine --miner.threads 1 \
  --miner.etherbase 0xab52b2c71f61cd9447a932c0cb55d1752571dab8

3. Verify blocks are being produced

./build/bin/geth attach --exec "eth.blockNumber" http://localhost:8545

The block number should increase over time.

4. (Optional) Connect the two nodes explicitly

Get node1's enode:

./build/bin/geth attach --exec "admin.nodeInfo.enode" http://localhost:8545

Then on node2:

./build/bin/geth attach --exec "admin.addPeer('ENODE_HERE')" http://localhost:8546

Verify from node1:

./build/bin/geth attach --exec "admin.peers" http://localhost:8545

Once blocks are moving, you can run the Go test scripts from this repo (see below).

Step-by-Step Testing

Step 1: Check Initial State

First, let's see the current balances before whitelisting:

# Run the test script (this will show balances and wait for blocks)
go run ./test/test_rewards/test_rewards.go

This will show:

• Current block number
• Miner1 (Node1) balance
• Miner2 (Node2) balance
• Then wait for 10 blocks and show the results

Expected before whitelisting: Both miners should earn roughly the same per-block reward.

Step 2: Whitelist Node1's Miner

Now, add Node1's miner address to the whitelist:

go run ./test/whitelist_validator/whitelist_tx.go

You should see:

Whitelisting transaction sent: 0x...

Wait for this transaction to be mined (check logs or wait ~15 seconds).

Step 3: Verify Extra Rewards

Run the test script again:

go run ./test/test_rewards/test_rewards.go

Expected after whitelisting:

• Miner1 (whitelisted) should earn ~2x the reward per block
• Miner2 (not whitelisted) should earn normal reward
• The ratio should be approximately 2.0x (or close to it)

Step 4: Manual Verification (Alternative Method)

If you want to verify manually using geth attach:

# Attach to node1
docker exec -it geth-node1 geth attach http://localhost:8545

In the JavaScript console:

// Miner addresses
var miner1 = "0x26357d0353bEA3f89B654b14ccdc610720753F5E"; // Node1
var miner2 = "0xa6d864bb0D1F25EDD958c48E202F7a51b3E93424"; // Node2

// Check current balances
web3.fromWei(eth.getBalance(miner1), "ether");
web3.fromWei(eth.getBalance(miner2), "ether");

// Get current block number
eth.blockNumber;

// Wait for 5-10 blocks, then check again
// Miner1 should have increased by ~2x more than Miner2

Step 5: Check Block Miners

To see which node mined which blocks:

// Check last 10 blocks
for (var i = 0; i < 10; i++) {
    var block = eth.getBlock(eth.blockNumber - i);
    console.log("Block " + block.number + ": mined by " + block.miner);
}

Expected Results

Before Whitelisting:

• Miner1 per-block reward: ~5 ETH (Frontier reward)
• Miner2 per-block reward: ~5 ETH (Frontier reward)
• Ratio: ~1.0x

After Whitelisting:

• Miner1 per-block reward: ~10 ETH (Frontier reward × 2)
• Miner2 per-block reward: ~5 ETH (Frontier reward)
• Ratio: ~2.0x ✅

Troubleshooting

If Miner1 is not getting extra rewards:

1. Check if whitelist transaction was mined:

   docker logs geth-node1 --tail 50 | grep -i "whitelist\|0x0100"
   

2. Verify the precompile is registered:

   • Check core/vm/contracts.go - should have whitelist precompile at 0x0100

3. Check consensus code:

   • Verify consensus/ethash/consensus.go has the whitelist check in accumulateRewards

4. Rebuild Docker images:

   docker compose build --no-cache
   docker compose down
   docker compose up -d
   

If both miners get the same reward:

• Make sure you ran go run ./test/whitelist_validator/whitelist_tx.go after starting the nodes
• Check that the transaction was successfully mined (look for the tx hash in logs)
• Verify Node1 is actually mining blocks (check docker logs geth-node1)

Understanding the Reward Logic

The extra reward logic is in consensus/ethash/consensus.go:

1. During block creation, accumulateRewards() is called
2. It checks if the block's coinbase (miner) is whitelisted by calling the precompile at 0x0100
3. If whitelisted, it adds one extra block reward on top of the normal reward
4. Result: whitelisted miners get 2× the base block reward