Seed participant configuration with DFINITY Canister SDK

Introduction

Steps to configure a neuron using the DFINITY Canistr SDK.

Warning

This process is not currently possible on macOS computers with M1 chips. You can only install the DFINITY Canister SDK dfx and the Candid compiler didc on Intel-based macOS and Linux computers.

Step 1: Derive a native Internet Computer principal from your Ethereum seed

As an early contributor or seed donor, Seed participants wrote down a 12-word mnemonic seed phrase that was generated by the DFINITY Chrome extension. To create an identity, seed participants must derive a private key from their seed phrase and import that private key into the DFINITY Canister SDK. This step is required before seed participants can take control of their neurons.

Step 1a: Secure your environment

The safety and security of the seed participant's private key is their responsibility and there is no substitute for planning ahead, bringing the right equipment, having the right skills, and using good judgment. It is strongly recommended they proceed using an air-gapped computer to reduce the risk of having their private key compromised. Depending on the hardware available, they might want to physically remove the network controller, microphone, speakers, and other components, or disable them in their BIOS. Covert channels can be established through a variety of different mediums, including sound, light, radio-frequency, and physical media. Be sure to evaluate the capabilities of your system before settling on a configuration that makes sense for you. If one is unsure, one should consult with a computer security expert. Do not contact the DFINITY Foundation for help with securing your environment.

Step 1b: Install Keysmith

You need Keysmith to derive your private/public key pair from the seed phrase.

To install Keysmith, there are two options:

a. Fetch the release binary

b. Build Keysmith from source.

Option A: Fetch the release binary

If you want to download the Keysmith release binary, keep in mind that you must perform this action on a computer with a network connection. If you are using an air-gapped computer, then you must copy the release binary from your networked computer to your air-gapped computer. How you do this will depend on your configuration.

To download the Keysmith release binary, fetch release v1.5.0 from Github.

Keysmith supports the following operating systems and architectures:

• Darwin / AMD64 – for macOS models with an Intel chip ([how to check])

• Darwin / ARM64 – for newer macOS models with an M1 chip ([how to check])

• Linux / AMD64

• Linux / ARM32

• Linux / ARM64

• Windows / AMD64

Download the .tar.gz file matching your architecture and operating system. If you have a newer M1-based macOS, download keysmith-darwin-arm64.tar.gz. Although you can install keysmith on macOS computers with an M1 chip, you can only install the DFINITY Canister SDK dfx command-line interface on Intel-based macOS computers. For an Intel-based macOS, download keysmith-darwin-amd64.tar.gz.

Verify the SHA256 checksum of your download

Open a terminal and change to the download directory. On a Mac this is

$ cd ~/Downloads

Compute the SHA256 checksum of your download.

$ openssl dgst -sha256 keysmith-*.tar*

Make sure the output matches one of the following lines:

SHA256(keysmith-darwin-amd64.tar.gz)= ad7383d60bced19580fa37b77e133b1e80416b482e4c5326ac2fd17a7710a318
SHA256(keysmith-darwin-arm64.tar.gz)= da1a4ac5ae04b85d4c5b0a3deb6442fb7c456dcf97cbd6ff8153316c5dbb29a9
SHA256(keysmith-linux-amd64.tar.gz)= 7901c3a23aef298f930d1dddf8eee23bc51a55ffda670accfd7b9e37748913d8
SHA256(keysmith-linux-arm32.tar.gz)= 0ab44e74cc502aa653dcb28962bcada5cbefb9e0ec41853a03fb4745c5cd51a9
SHA256(keysmith-linux-arm64.tar.gz)= 635c0bf98dd15f27b302ec0ea793f75c797441009c74500bd9d0a5df26092264
SHA256(keysmith-windows-amd64.tar.gz)= cb398c39583b81d5170dd0a9539d902715317572f6a640b45d3d2db01946b8fa

If your browser already unzipped the .tar.gz for you and you have a file ending in .tar then make sure the output of openssl matches one of the following lines:

SHA256(keysmith-darwin-amd64.tar)= 97b8048f00e75d6adc8651aac1aa77d9bd9c150b0dbc0b0f6409f0d6bdbb24a4
SHA256(keysmith-darwin-arm64.tar)= 07e296fbf33b0c06bd04a8ead30487762aa30ca2daf7e19948d74a96f2c34067
SHA256(keysmith-linux-amd64.tar)= 1d2d986a971f8c7ef0eeb4b01624f023ef8dc9c71d2f0127f21fcc99aebdc99a
SHA256(keysmith-linux-arm32.tar)= 8eb8efecd9182822326f2e60fcff32c0b1541cce206a12b3f2e94547c66dfe63
SHA256(keysmith-linux-arm64.tar)= 82264487e83cbfdd758c1227375758b7d1f0c864adb555775777e7d3afa19e08
SHA256(keysmith-windows-amd64.tar)= b85224d4e9807b8335295193c12dd0cab22bd38881d14c1f1c21479801ace17d

Unpack and install keysmith

To extract the executable from the tarball, enter the following command into your terminal:

$ tar -f keysmith-*.tar* -x

Next, add the executable to your PATH by entering the commands below:

$sudo install -d /usr/local/bin
$sudo install keysmith /usr/local/bin

You will be prompted to enter your laptop password. The password itself will not appear, simply type it and press enter.

Run it

$ keysmith

You should see:

usage: keysmith <command> [<args>]

Available Commands:
    account             Print your account identifier.
    generate            Generate your mnemonic seed.
    legacy-address      Print your legacy address.
    principal           Print your principal identifier.
    private-key         Write your private key to a file.
    public-key          Print your public key.
    version             Print the version number.
    x-public-key        Print your extended public key.

If you are using macOS, making the keysmith binary executable might require you to change a permission setting using System Preferences > Security & Privacy > General.

Option B: Build Keysmith from source

f you want to build the Keysmith from source, keep in mind that you must perform this action on a computer with a network connection. If you are using an air-gapped computer, then you must copy the target binary from your networked computer to your air-gapped computer. How you do this will depend on your configuration.

Keysmith is written in Go, so if you choose to build it from source, then you must first download and install Go, verify that go is in your PATH, and configure your GOPATH and GOBIN environment variables.

Run the following command to build Keysmith from source.

$ go get github.com/dfinity/keysmith

Step 1c: Install the DFINITY Canister SDK

You can install the DFINITY Canister SDK by fetching the v0.7.0 release binary from our website. It is not yet possible to build the DFINITY Canister SDK from source. Note that this action can only be performed on a networked computer. If you are using an air-gapped computer, then you must copy the release binary from your networked computer to your air-gapped computer. How you do this will depend on your configuration.

Run the following command to install the DFINITY Canister SDK.

$ sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"

Warning: Note that dfx will currently not install on M1-based Macs.

Step 1d: Set your seed phrase for use with keysmith

Once you have installed Keysmith and the DFINITY Canister SDK, and you are confident that your environment is secure, then you are ready to enter your seed for use with keysmith. For the duration of your session, you store your seed phrase in an environment variable. It will be eliminated from your system when you turn your computer off.

$ read seed

Enter your seed phrase and finish with Return.

If you prefer to not have your seed phrase displayed as you type then use this command instead:

$ read -s seed

Step 1e: Check your legacy address and balance (optional)

At this point you can already verify your legacy address and ICPT balance. The legacy address matches to what was formerly called "DFN address" in the Dfinity Chrome extension. You may have copied it from the Chrome extension for your records back when you used the extension.

echo $seed | keysmith legacy-address -f -

The output is a 40 character hex string. It looks something like this:

2d89d96b10f7a9456a9154b2f5309ee70df5bce1

You can check your ICPT balance as follows:

echo {} > dfx.json
GTC=renrk-eyaaa-aaaaa-aaada-cai
ADDR=$(echo $seed | keysmith legacy-address -f -)
dfx canister --network=https://ic0.app --no-wallet call $GTC balance '("'$ADDR'")'

The output is the number of ICPT associated with your address.

If you are an early contributor then you may have multiple addresses, all derived from your one seed phrase. To check the balance in each of them you do the following commands:

GTC=renrk-eyaaa-aaaaa-aaada-cai
ADDR=$(echo $seed | keysmith legacy-address -f - -i 0)
dfx canister --network=https://ic0.app --no-wallet call $GTC balance '("'$ADDR'")'

Then you repeat the last two lines with -i 1, -i 2, etc.

Step 1f: Derive and import your private key

Derive your private key from your seed phrase.

$ echo $seed | keysmith private-key -f -

This creates a file identity.pem containing your private key. Import your private key(s) into the DFINITY Canister SDK and then remove it from the filesystem.

$ dfx identity import <name> identity.pem
$ rm identity.pem

Here, <name> is an alias that you can choose arbitrarily for your identity, e.g. "jane". The command above displays output similar to the following:

Creating identity: "jane".
Created identity: "jane".

Make your new identity the currently-active one.

$ dfx identity use <name>

The command above displays output similar to the following:

Using identity: "jane".

At any time, you can list all available identities with

$ dfx identity list

Step 2: Take control of your neurons

You will receive your tokens inside a set of neurons that have been pre-created for you. The number of neurons will total 31 or 49 depending on whether you are an early contributor or seed donor, respectively. Your tokens are disbursed equally over these neurons. Claiming your neurons is the process of obtaining control over your neurons. It is done for all neurons at once.

Your neurons differ by their dissolve delay. For an explanation of dissolve delay see Instruct the neurons you wish to unstake to dissolve below.

To claim your neurons, you need to sign and send a message to the Genesis Token Canister. You can accomplish this in one step on a networked computer using dfx canister call, or as two separate steps, one on an air-gapped computer using dfx canister sign, and another on a networked computer using dfx canister send. We strongly recommend the latter approach to reduce the risk of having your private key compromised.

Regardless of which method you choose, you will need to download and install didc, the Candid compiler, on your networked computer. You can find the latest release here. Note that the binaries are suffixed by the operating systems they run on, didc-linux64 and didc-macos. Be sure to download the correct one. Below are commands to install didc on macos. If your’re using Linux, simply use the linux64 suffix instead.

$ sudo install -d /usr/local/bin
$ sudo install -m 0755 ~/Downloads/didc-macos /usr/local/bin/didc

Regardless of which method you choose, you will also need to download and extract the NNS canister interfaces on your networked computer. You can find the latest release here. Below are commands to extract the NNS canister interfaces.

pushd ~/Downloads
tar -f nns-ifaces-0.8.0.tar.gz -x
popd

Additionally, you will need to have dfx.json file available in the directory from which you are running dfx commands. You can create an empty dfx.json file in your current directory by running the following command.

$ echo {} > dfx.json

Note that if you’re using an air-gapped computer, then you’ll need to repeat this step since you’ll be running dfx commands in both places.

After downloading and installing didc, downloading and extracting the NNS canister interfaces, and creating your dfx.json file(s), you can Claim in one step (not recommended) or Claim in two steps.