Into Eth 2 – Eth 1 and the Deposit Contract

Adrian Sutton

I’ve started a little side-project to setup a “private beacon chain”. The aim is to better understand how the beacon chain works and start to discover some of the things still required to be built or fixed in clients before it can officially launch.

So what is a private beacon chain? It’s intended to be an entirely self-contained, runs-on-my-laptop instance of the beacon chain, run as a small-scale simulation of how the real beacon chain will be fired up.

I’ve collected all the various scripts and config together in a git repo so you follow along from home if you like. Be warned, there is absolutely no polish and not even a lot of thought about organisation in there.

Step 1 – An Ethereum 1 Chain

First of all we need an Ethereum 1 chain that will be the source of our deposits for beacon chain validators. That’s pretty easy with Pantheon, but let’s complicate matters a little by using Docker. First we’re going to need a network which will eventually (hopefully) hold a whole bevy of different Eth 2 clients all happily interoperating on our beacon chain. So:

docker network create beacontest

Then we need a genesis config for our private Eth 1 chain. I’ve copied the genesis Pantheon uses by default in dev mode with a couple of tweaks I’ll explain later. Here’s the full file. There are a few accounts that have been allocated lots of ETH and the private keys are included in the config so it’s easy to import to MetaMask or other tools (don’t use these keys for anything real!).

Finally there’s a simple little script to run Pantheon using that file, in our docker network, exposing a bunch of ports and generally being setup to be useful for what we want to do.

Step 2 – Deposit Funds

Our beacon chain can’t become active until we have enough people who have deposited funds into the beacon chain contract to become validators. Obviously, that means we’ll need a beacon chain contract.

Step 2.1 Deploy the Deposit Contract

It turns out, the beacon chain contract has changed a bunch of times in different versions of the spec. This is painfully confusing because docs or examples you read usually don’t mention which version of the spec and you can waste many hours trying to interact with the wrong contract.

We will be using version 0.7.1 of the spec. Here’s that version of the deposit contract spec and the deposit contract code.

To make life simpler, I’ve taken the runtime byte code for that contract and added it into the genesis config at the fixed address 0xdddddddddddddddddddddddddddddddddddddddd. Note when including contracts in the genesis config you need the runtime byte code, not the constructor byte code you’d normally send as transaction data. Remix makes this easy with it’s “Runtime Bytecode” tab.

Step 2.2 Deposit Some ETH

The deposit contract spec helpfully tells us that there’s a deposit method we need to call which takes three arguments: pubkey: bytes[48], withdrawal_credentials: bytes[32], signature: bytes[96]

Unhelpfully it gives us almost no clue what those parameters actually mean or how to generate them.

I haven’t yet found a nice stand-alone way to generate the required parameters, so I wound up shoving an extra class into my local checkout of the Artemis codebase – GenerateKeys.java right next to the existing Artemis.java which has the main method. There are three key steps:

  1. Generate two BLS key pairs. One for the validator to use and one for the ETH 2 account that our funds will be sent to if we choose to leave the validator pool.
    • The withdrawal keys can be kept offline until you actually withdraw the funds whereas the validator keys need to be online so the validator can sign things and do its job.
  2. Encode the public key of the validator key pair using the compressed form with big endian encoding.
    • This will be the first argument – pubKey.
    • Don’t ask me why it’s called compressed encoding when it appears to be exactly the same length as the uncompressed form. UPDATE: Ben Edgington helpfully points out that an uncompressed key is actually 96 bytes – I’d been misled by a well-meaning error message when the real problem was I was using little endian instead of big.
  3. Calculate the SHA256 hash of the public key of the withdrawal key pair, in big endian encoding. Replace the first byte with 0 (the BLS_WITHDRAWAL_PREFIX_BYTE).
    • This will be the withdrawal commitment
  4. Calculate the signature. This requires serialising the DepositData object that will ultimately be created by Eth2 clients in response to our deposit in SSZ with hash trees and stuff. Don’t ask me, I just called the existing Artemis code… That then gets signed using the validator’s private key.
    • This proves you actually have the private key matching the public key you’re trying to register as a validator.
    • WARNING: This signature is not checked by the deposit contract, only be Eth2 clients. So if you get it or the public key wrong your deposit will be ignored by the beacon chain and you won’t get your ETH back.

Now that we know what parameters we need to pass, we just need to create a transaction with the required 32 ETH and those parameters encoded as a call to the deposit method. I wrote an especially ugly bit of JavaScript to do that. You’ll need to install the npm dependencies first with:

npm install

and can then send our deposit with:

node index.js

At this point, if we actually had an ETH2 client, it would recognise that deposit as creating our first validator. Setting up our ETH2 client will be step 3 but I’m not writing that up today. And, spoiler alert, we’re actually going to need another 65535 validators before the beacon chain will actually start, but that’s a problem for another day.