Difference between revisions of "How-To: Claim neurons for seed participants"
(Typesetting fixes, remove reference to future release of Ledger app.) |
|||
(24 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | + | ''A guide for seed contributors to claim their ICP utility tokens as NNS neurons. For controlling the neurons after claiming see this [https://medium.com/dfinity/integrating-ledger-nano-with-the-nns-front-end-dapp-user-manual-9c5600925e16 tutorial] instead.'' | |
− | At Genesis Unlock your ICP were disbursed to you in the form of a basket of 49 voting [[Network Nervous System|neurons]]. These neurons already exist inside the [[Network Nervous System]]. Your neurons contain the | + | == Introduction == |
+ | You are a ''seed participant'' if you donated to the DFINITY foundation in February of 2017 to support the development of the Internet Computer. At that time, 30 tokens per Swiss Franc of value donated were allotted to your key. These tokens are now called "ICP utility tokens" or "ICP" for short. | ||
+ | |||
+ | At Genesis Unlock, your ICP were disbursed to you in the form of a basket of 49 voting [[Network Nervous System|neurons]]. These neurons already exist inside the [[Network Nervous System]]. Your neurons contain the tokens you have been awarded, which are staked inside. | ||
Your neurons have been configured to vote automatically and are already earning voting rewards for you. You do not need to do anything to initialize your neurons in order to continue earning voting rewards. | Your neurons have been configured to vote automatically and are already earning voting rewards for you. You do not need to do anything to initialize your neurons in order to continue earning voting rewards. | ||
− | The 49 neurons created for you have dissolve [[Network Nervous System|delays]] of 0 days, 30 days, 60 days, 90 days and so on. Apart from the first neuron which has a dissolve delay of 0 days (which can be dissolved immediately), the other dissolve delays may have a small random number of days | + | The 49 neurons created for you have dissolve [[Network Nervous System|delays]] of 0 days, 30 days, 60 days, 90 days and so on. Apart from the first neuron which has a dissolve delay of 0 days (which can be dissolved immediately), the other dissolve delays may have a small random number of days added to it. |
+ | |||
+ | Your neurons have also been pre-aged. At the moment of Genesis Unlock, their age was already set to 18 months old. This is important, because neuron age significantly increases your voting power and the voting rewards you receive. | ||
+ | |||
+ | To control your neurons, you must use the same secret key that you generated when the donation was made. It was recorded by you as a 12-word mnemonic phrase. In order to control your neurons you need to first ''claim'' your basket of neurons. There are two ways to claim which are explained below in this article: | ||
− | + | # Claiming with Ledger Nano device (recommended) | |
+ | # Claiming with an air-gapped computer + networked computer/smartphone | ||
− | + | After claiming, there are two ways to control your neurons: | |
+ | |||
+ | # The NNS dapp (GUI) as described in this [https://medium.com/dfinity/integrating-ledger-nano-with-the-nns-front-end-dapp-user-manual-9c5600925e16 tutorial] | ||
+ | # A command line tool ic-hardware-wallet-cli available on [https://github.com/dfinity/nns-dapp/tree/main/ic-hardware-wallet-cli github]. | ||
== Claiming with a Ledger Nano device == | == Claiming with a Ledger Nano device == | ||
− | + | === Prepare your Nano device === | |
+ | |||
+ | Connect your Ledger Nano device to USB power. On the Nano device, select "Set up with Recovery phrase" (as opposed to "Set up as new device"). Choose a PIN. Select "Recovery phrase with 12 words" (not 18 or 24 words). Enter the 12 word phrase the was generated by the Chrome extension during the seed donation phase. | ||
+ | |||
+ | On your computer, install Ledger Live from ledger.com and start it. If offered to upgrade to a newer version then do so. Connect the Nano device to USB and, if necessary, unlock it with the PIN. In Ledger Live, select "Manager" in the "Menu" column on the left. Confirm the access on the Nano device. | ||
+ | |||
+ | If offered to update the firmware of the Nano device then do so. Confirm the update on the Nano device. After an update you have to re-enter the PIN. If the previous firmware was very old then you even have to re-enter the 12-word phrase. Moreover, if the previous firmware was very old then you may not get to the latest firmware version in one step (multiple incremental updates will be needed). It is important that you get to the latest _available_ firmware on your Nano device. | ||
+ | |||
+ | From within the Ledger Live "Manager" install the app called "Internet computer (ICP)" version >=2.0.6 onto your Nano device. You can search for the app in the search bar by typing "ICP" or "internet". After the installation succeeded you can close Ledger Live. | ||
+ | |||
+ | === Install the CLI tool === | ||
+ | |||
+ | Install `node` from https://nodejs.org/en/download/. Follow the download or installation link for your operating system. | ||
+ | |||
+ | Open a terminal and run this command: | ||
+ | |||
+ | <code>npm install -g @dfinity/hardware-wallet-cli</code> | ||
+ | |||
+ | Depending on your OS you may have to put <code>sudo</code> in front of the command. | ||
+ | |||
+ | This will install the package https://www.npmjs.com/package/@dfinity/hardware-wallet-cli and build an executable called `ic-hardware-wallet`. To verify that the executable is accessible run the command: | ||
+ | |||
+ | <code>ic-hardware-wallet</code> | ||
+ | |||
+ | and you should see output like this: | ||
+ | |||
+ | |||
+ | Usage: ic-hardware-wallet [options] [command] | ||
+ | A CLI for the Ledger hardware wallet. | ||
+ | Options: | ||
+ | --network <network> The IC network to talk to. (default: "https://ic0.app", env: IC_NETWORK) | ||
+ | -h, --help display help for command | ||
+ | Commands: | ||
+ | info [options] Show the wallet's principal, address, and balance. | ||
+ | icp Commands for managing ICP. | ||
+ | neuron Commands for managing neurons. | ||
+ | help [command] display help for command | ||
+ | </code> | ||
+ | |||
+ | If you had already installed an older version of the package `@dfinity/hardware-wallet-cli` then install it again and make sure the version of the package is >= 0.2.1. You can check the installed version with the command: | ||
+ | |||
+ | <code> | ||
+ | npm list | ||
+ | </code> | ||
+ | |||
+ | === Claim with CLI === | ||
+ | |||
+ | Connect the Nano device to USB, unlock it with PIN and start the "ICP" app on it. | ||
+ | |||
+ | On your computer run the command: | ||
+ | |||
+ | <code>ic-hardware-wallet neuron claim</code> | ||
+ | |||
+ | You will have to approve twice on the Nano device. Once for the actual `claim` message and once for obtaining the result status. You should see output like this: | ||
+ | |||
+ | <code> | ||
+ | OK: Successfully claimed the following neurons: | ||
+ | </code> | ||
+ | |||
+ | followed by 49 numbers (the neuron ids). | ||
+ | |||
+ | Note: there is no risk of harm if your computer is compromised or infected with malware. The signed "claim" message cannot be abused. The worst that can happen is that it is not submitted to the IC. There is no harm in sending the "claim" message multiple times. If something went wrong in the process then you can simply retry. | ||
+ | |||
+ | === Claim with NNS UI === | ||
+ | Claiming through the NNS UI is an alternative method to claiming through the CLI for users who feel more comfortable using the NNS UI instead of command line interface. | ||
+ | |||
+ | * Visit <nowiki>https://nns.ic0.app/</nowiki> | ||
+ | * Login (create a new Internet Identity if you don’t already have one) | ||
+ | * Visit My Tokens in the left sidebar | ||
+ | * Click on the card “Add Account” | ||
+ | * Attach Hardware wallet. Follow instructions. | ||
+ | * When finished visit the wallet page. | ||
+ | * Click 6 times in the header “Account” of the Wallet page. | ||
+ | * A prompt will appear. | ||
+ | * Enter “cn” | ||
+ | * Congratulations, you have now claimed your seed round neurons through the NNS UI flow. If you haven't already done so, you will now need to complete the KYC process described [[Seed participant configuration with DFINITY Canister SDK#Step 3: Enable disbursal by passing the KYC process|here]] to control your neurons. | ||
== Claiming with an air-gapped computer == | == Claiming with an air-gapped computer == | ||
− | Claiming requires access to your secret mnemonic phrase and to secret keys derived from it. It is highly advised that you use an air-gapped computer for the purpose of claiming. | + | Claiming requires access to your secret mnemonic phrase and to secret keys derived from it. It is highly advised that you use an air-gapped computer for the purpose of claiming. As an air-gapped device you can use a Windows, Linux or MacOS machine. Linux includes Raspberry Pi. |
− | |||
− | As an air-gapped device you can use a Windows, Linux or MacOS machine. Linux includes Raspberry Pi. | ||
=== Download the tools === | === Download the tools === | ||
− | To download the tools you need a second, networked computer. The tools are called ''keysmith'' and ''quill.'' | + | To download the tools you need a second, networked computer. The tools are called ''keysmith'' and ''quill.'' This section describes how to find and download a binary for your architecture. Alternatively, you can compile the tools yourself from the source code available on github for [https://github.com/dfinity/keysmith keysmith] and [https://github.com/dfinity/quill quill]. |
Binaries are available for the following hardware architectures. Here, architecture refers to the air-gapped computer, not the networked computer. | Binaries are available for the following hardware architectures. Here, architecture refers to the air-gapped computer, not the networked computer. | ||
Line 57: | Line 141: | ||
==== Download keysmith ==== | ==== Download keysmith ==== | ||
− | Go to [https://github.com/dfinity/keysmith/releases/ keysmith], choose the latest release (currently v1.6.2) and fetch the .tar.gz file that matches the air-gapped machine's architecture in the table above. | + | Go to [https://github.com/dfinity/keysmith/releases/ keysmith], choose the latest release (currently v1.6.2) and fetch the <code>.tar.gz</code> file that matches the air-gapped machine's architecture in the table above. |
==== Download quill ==== | ==== Download quill ==== | ||
Line 65: | Line 149: | ||
=== Copy to air-gapped machine === | === Copy to air-gapped machine === | ||
− | Copy the keysmith .tar.gz file and the quill executable from the networked machine to the air-gapped machine. For example, you can do so with a USB drive. | + | Copy the keysmith <code>.tar.gz</code> file and the quill executable from the networked machine to the air-gapped machine. For example, you can do so with a USB drive. |
=== Verify the hashes === | === Verify the hashes === | ||
Line 96: | Line 180: | ||
For quill:<syntaxhighlight lang="bash"> | For quill:<syntaxhighlight lang="bash"> | ||
+ | mv quill-arm_32 quill | ||
sudo install quill /usr/local/bin | sudo install quill /usr/local/bin | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | == | + | == Produce the private key file with keysmith == |
− | <syntaxhighlight lang="bash"> | + | |
+ | === Test the installation === | ||
+ | On the air-gapped computer run:<syntaxhighlight lang="bash"> | ||
keysmith | keysmith | ||
</syntaxhighlight>You should see:<syntaxhighlight lang="bash"> | </syntaxhighlight>You should see:<syntaxhighlight lang="bash"> | ||
Line 116: | Line 203: | ||
x-private-key Derive your extended private key and write it to a file. | x-private-key Derive your extended private key and write it to a file. | ||
x-public-key Print your extended public key. | x-public-key Print your extended public key. | ||
− | </syntaxhighlight>If you are using macOS, | + | </syntaxhighlight>If you are using macOS, running <code>keysmith</code> for the first time might require you to grant permission under System Preferences > Security & Privacy > General. |
=== Enter your mnemonic phrase (aka "seed") === | === Enter your mnemonic phrase (aka "seed") === | ||
Line 148: | Line 235: | ||
This creates a file <code>identity.pem</code> containing your private key. | This creates a file <code>identity.pem</code> containing your private key. | ||
− | == Run quill == | + | ==== Optional: Store .pem file only in RAM ==== |
+ | The identity.pem file will later be wiped from the filesystem. There is however a remaining risk that the data could survive in the disk and later extracted despite it being wiped. It is more secure to create a RAM disk and store the .pem file only in the RAM disk. | ||
+ | |||
+ | ===== Create RAM disk on MacOS ===== | ||
+ | Run these commands<syntaxhighlight lang="bash" line="1"> | ||
+ | DISK=$(hdiutil attach -nomount ram://16384) | ||
+ | diskutil erasevolume HFS+ RD $DISK | ||
+ | cd /Volumes/RD | ||
+ | </syntaxhighlight>before running<syntaxhighlight lang="bash"> | ||
+ | echo $seed | keysmith private-key -f - | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | ===== Create RAM disk on Linux ===== | ||
+ | Run these commands<syntaxhighlight lang="bash" line="1"> | ||
+ | sudo mkdir /mnt/ramdisk | ||
+ | sudo mount -t ramfs keysmith /mnt/ramdisk | ||
+ | sudo mkdir /mnt/ramdisk/workspace | ||
+ | sudo chown $USER /mnt/ramdisk/workspace | ||
+ | cd /mnt/ramdisk/workspace | ||
+ | </syntaxhighlight>before running<syntaxhighlight lang="bash"> | ||
+ | echo $seed | keysmith private-key -f - | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | ===== Create RAM disk on Windows ===== | ||
+ | Todo | ||
+ | |||
+ | == Submit claim with quill == | ||
+ | |||
+ | === Test the installation === | ||
+ | On the air-gapped computer run: | ||
+ | quill | ||
+ | You should see:<syntaxhighlight lang="bash"> | ||
+ | quill 0.2.12 | ||
+ | |||
+ | Ledger & Governance ToolKit for cold wallets | ||
+ | |||
+ | USAGE: | ||
+ | quill [OPTIONS] <SUBCOMMAND> | ||
+ | |||
+ | OPTIONS: | ||
+ | -h, --help Print help information | ||
+ | --pem-file <PEM_FILE> Path to your PEM file (use "-" for STDIN) | ||
+ | -V, --version Print version information | ||
+ | |||
+ | SUBCOMMANDS: | ||
+ | account-balance Queries a ledger account balance | ||
+ | claim-neurons Claim seed neurons from the Genesis Token Canister | ||
+ | get-proposal-info | ||
+ | help Print this message or the help of the given subcommand(s) | ||
+ | list-neurons Signs the query for all neurons belonging to the signin principal | ||
+ | list-proposals | ||
+ | neuron-manage Signs a neuron configuration change | ||
+ | neuron-stake Signs topping up of a neuron (new or existing) | ||
+ | public-ids Prints the principal id and the account id | ||
+ | send Sends a signed message or a set of messages | ||
+ | transfer Signs an ICP transfer transaction | ||
+ | </syntaxhighlight>If you are using macOS, running <code>quill</code> for the first time might require you to grant permission under System Preferences > Security & Privacy > General. | ||
+ | |||
+ | === Sign the claim request === | ||
+ | |||
On the air-gapped computer run:<syntaxhighlight lang="bash"> | On the air-gapped computer run:<syntaxhighlight lang="bash"> | ||
quill --pem-file identity.pem claim-neurons >msg.json | quill --pem-file identity.pem claim-neurons >msg.json | ||
</syntaxhighlight> | </syntaxhighlight> | ||
+ | |||
+ | === Submit the claim to the IC === | ||
+ | |||
+ | ==== Option 1: With quill on the networked computer ==== | ||
+ | |||
Copy the resulting file `msg.json` back to the networked computer. On the networked computer, change into the directory where `msg.json` is and run:<syntaxhighlight lang="bash"> | Copy the resulting file `msg.json` back to the networked computer. On the networked computer, change into the directory where `msg.json` is and run:<syntaxhighlight lang="bash"> | ||
quill send msg.json | quill send msg.json | ||
</syntaxhighlight>Your neurons should now be claimed. | </syntaxhighlight>Your neurons should now be claimed. | ||
− | You can double-check if you claim was successful in the following way: Go to https://ic.rocks/genesis/2d89d96b10f7a9456a9154b2f5309ee70df5bce1 where you replace 2d89d96b10f7a9456a9154b2f5309ee70df5bce1 with your own DFN address. Under "Status" you should see "Claimed". | + | You can double-check if you claim was successful in the following way: Go to https://ic.rocks/genesis/2d89d96b10f7a9456a9154b2f5309ee70df5bce1 where you replace <code>2d89d96b10f7a9456a9154b2f5309ee70df5bce1</code> with your own DFN address. Under "Status" you should see "Claimed". |
+ | |||
+ | ==== Option 2: Use the QR scanner app ==== | ||
+ | |||
+ | * Install <code>qrencode</code> | ||
+ | * Run <code>cat msg.json | gzip -c | base64 | qrencode -o msg.png</code> | ||
+ | * Open <code>msg.png</code> in an image viewer | ||
+ | * Open scanner app in a browser on a phone: https://p5deo-6aaaa-aaaab-aaaxq-cai.raw.ic0.app | ||
+ | * Scan QR code and submit | ||
+ | |||
+ | === Clean up the air-gapped computer === | ||
− | If your claim was successful then do not forget to remove the .pem file on the air-gapped computer:<syntaxhighlight lang="bash"> | + | If your claim was successful then do not forget to remove the <code>.pem</code> file on the air-gapped computer:<syntaxhighlight lang="bash"> |
rm identity.pem | rm identity.pem | ||
</syntaxhighlight> | </syntaxhighlight> |
Latest revision as of 11:11, 20 November 2023
A guide for seed contributors to claim their ICP utility tokens as NNS neurons. For controlling the neurons after claiming see this tutorial instead.
Introduction
You are a seed participant if you donated to the DFINITY foundation in February of 2017 to support the development of the Internet Computer. At that time, 30 tokens per Swiss Franc of value donated were allotted to your key. These tokens are now called "ICP utility tokens" or "ICP" for short.
At Genesis Unlock, your ICP were disbursed to you in the form of a basket of 49 voting neurons. These neurons already exist inside the Network Nervous System. Your neurons contain the tokens you have been awarded, which are staked inside.
Your neurons have been configured to vote automatically and are already earning voting rewards for you. You do not need to do anything to initialize your neurons in order to continue earning voting rewards.
The 49 neurons created for you have dissolve delays of 0 days, 30 days, 60 days, 90 days and so on. Apart from the first neuron which has a dissolve delay of 0 days (which can be dissolved immediately), the other dissolve delays may have a small random number of days added to it.
Your neurons have also been pre-aged. At the moment of Genesis Unlock, their age was already set to 18 months old. This is important, because neuron age significantly increases your voting power and the voting rewards you receive.
To control your neurons, you must use the same secret key that you generated when the donation was made. It was recorded by you as a 12-word mnemonic phrase. In order to control your neurons you need to first claim your basket of neurons. There are two ways to claim which are explained below in this article:
- Claiming with Ledger Nano device (recommended)
- Claiming with an air-gapped computer + networked computer/smartphone
After claiming, there are two ways to control your neurons:
- The NNS dapp (GUI) as described in this tutorial
- A command line tool ic-hardware-wallet-cli available on github.
Claiming with a Ledger Nano device
Prepare your Nano device
Connect your Ledger Nano device to USB power. On the Nano device, select "Set up with Recovery phrase" (as opposed to "Set up as new device"). Choose a PIN. Select "Recovery phrase with 12 words" (not 18 or 24 words). Enter the 12 word phrase the was generated by the Chrome extension during the seed donation phase.
On your computer, install Ledger Live from ledger.com and start it. If offered to upgrade to a newer version then do so. Connect the Nano device to USB and, if necessary, unlock it with the PIN. In Ledger Live, select "Manager" in the "Menu" column on the left. Confirm the access on the Nano device.
If offered to update the firmware of the Nano device then do so. Confirm the update on the Nano device. After an update you have to re-enter the PIN. If the previous firmware was very old then you even have to re-enter the 12-word phrase. Moreover, if the previous firmware was very old then you may not get to the latest firmware version in one step (multiple incremental updates will be needed). It is important that you get to the latest _available_ firmware on your Nano device.
From within the Ledger Live "Manager" install the app called "Internet computer (ICP)" version >=2.0.6 onto your Nano device. You can search for the app in the search bar by typing "ICP" or "internet". After the installation succeeded you can close Ledger Live.
Install the CLI tool
Install `node` from https://nodejs.org/en/download/. Follow the download or installation link for your operating system.
Open a terminal and run this command:
npm install -g @dfinity/hardware-wallet-cli
Depending on your OS you may have to put sudo
in front of the command.
This will install the package https://www.npmjs.com/package/@dfinity/hardware-wallet-cli and build an executable called `ic-hardware-wallet`. To verify that the executable is accessible run the command:
ic-hardware-wallet
and you should see output like this:
Usage: ic-hardware-wallet [options] [command] A CLI for the Ledger hardware wallet. Options: --network <network> The IC network to talk to. (default: "https://ic0.app", env: IC_NETWORK) -h, --help display help for command Commands: info [options] Show the wallet's principal, address, and balance. icp Commands for managing ICP. neuron Commands for managing neurons. help [command] display help for command
If you had already installed an older version of the package `@dfinity/hardware-wallet-cli` then install it again and make sure the version of the package is >= 0.2.1. You can check the installed version with the command:
npm list
Claim with CLI
Connect the Nano device to USB, unlock it with PIN and start the "ICP" app on it.
On your computer run the command:
ic-hardware-wallet neuron claim
You will have to approve twice on the Nano device. Once for the actual `claim` message and once for obtaining the result status. You should see output like this:
OK: Successfully claimed the following neurons:
followed by 49 numbers (the neuron ids).
Note: there is no risk of harm if your computer is compromised or infected with malware. The signed "claim" message cannot be abused. The worst that can happen is that it is not submitted to the IC. There is no harm in sending the "claim" message multiple times. If something went wrong in the process then you can simply retry.
Claim with NNS UI
Claiming through the NNS UI is an alternative method to claiming through the CLI for users who feel more comfortable using the NNS UI instead of command line interface.
- Visit https://nns.ic0.app/
- Login (create a new Internet Identity if you don’t already have one)
- Visit My Tokens in the left sidebar
- Click on the card “Add Account”
- Attach Hardware wallet. Follow instructions.
- When finished visit the wallet page.
- Click 6 times in the header “Account” of the Wallet page.
- A prompt will appear.
- Enter “cn”
- Congratulations, you have now claimed your seed round neurons through the NNS UI flow. If you haven't already done so, you will now need to complete the KYC process described here to control your neurons.
Claiming with an air-gapped computer
Claiming requires access to your secret mnemonic phrase and to secret keys derived from it. It is highly advised that you use an air-gapped computer for the purpose of claiming. As an air-gapped device you can use a Windows, Linux or MacOS machine. Linux includes Raspberry Pi.
Download the tools
To download the tools you need a second, networked computer. The tools are called keysmith and quill. This section describes how to find and download a binary for your architecture. Alternatively, you can compile the tools yourself from the source code available on github for keysmith and quill.
Binaries are available for the following hardware architectures. Here, architecture refers to the air-gapped computer, not the networked computer.
Hardware | keysmith | quill |
---|---|---|
Mac, Intel silicon | darwin-amd64 | macos-x86_64 |
Mac, Apple silicon (M1) | darwin-arm64 | - |
Linux (x86) | linux-amd64 | linux-x86_64 |
Raspberry Pi | linux-arm32 | arm_32 |
Linux (arm) | linux-arm64 | - |
Windows | windows-amd64 | windows-x86_64 |
Download keysmith
Go to keysmith, choose the latest release (currently v1.6.2) and fetch the .tar.gz
file that matches the air-gapped machine's architecture in the table above.
Download quill
Go to quill , choose the latest release (must be >= 0.2.12) and fetch the executable file that matches the air-gapped machine's architecture in the table above.
Copy to air-gapped machine
Copy the keysmith .tar.gz
file and the quill executable from the networked machine to the air-gapped machine. For example, you can do so with a USB drive.
Verify the hashes
On the air-gapped machine, go to the terminal. Change the directory to the folder where the keysmith .tar.gz files and quill executables are. Compute the SHA256 hashes with the commands
openssl dgst -sha256 keysmith-*
and
openssl dgst -sha256 quill-*
The hashes should match the following entries:
SHA256(keysmith-darwin-amd64.tar.gz)= a53bad6fa36c1eb35cd36059ffe9cbf4c063b515e47ccf666b7e1c174a7d1088
SHA256(keysmith-darwin-arm64.tar.gz)= 47932452353fe7f921b4ac41828dd19530ae0c4bdb72bcbb016a0715ca80e879
SHA256(keysmith-linux-amd64.tar.gz)= cb283dac031d8676f25e72d19115be347d2b85c864a17dd563104bf496b14a06
SHA256(keysmith-linux-arm32.tar.gz)= b28670e2b3483ea9f9ba691e9f76f99df31b2678db33b69c888fb08b634de162
SHA256(keysmith-linux-arm64.tar.gz)= ebe9cde3cf440ebbfb53dd10bf7f412cbff8b089551100ee0fa48f3ac9bd66c3
SHA256(keysmith-windows-amd64.tar.gz)= 1ef9b77ccaae980aad4a227fe1a817821245da491a90f0e6ad323426b49ae40a
and
SHA256(quill-arm_32)= ebe2506e4dc4422e7670094e8b2b1d854a3b3c317b25c1c88990853d3d85c064
SHA256(quill-linux-x86_64)= 18fc671ee8c96b367875b39470073d68db78d32d242d14d4682025ef2a5d9ad4
SHA256(quill-macos-x86_64)= 97c373ab871be377ac784faff089ca26d23c37725230fb36d78f17d7a73b0867
SHA256(quill-windows-x86_64.exe)= 2542244c9ad3a9baf54bc2227e8c71ea8a8fb9f7e6065cc7a848c7b1cdce906e
Unpack and install
For keysmith:
tar -f keysmith-*.tar* -x
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. For quill:
mv quill-arm_32 quill
sudo install quill /usr/local/bin
Produce the private key file with keysmith
Test the installation
On the air-gapped computer run:
keysmith
You should see:
usage: keysmith <command> [<args>]
Available Commands:
account Print your account identifier.
generate Generate your mnemonic seed and write it to a file.
legacy-address Print your legacy address.
principal Print your principal identifier.
private-key Derive your private key and write it to a file.
public-key Print your public key.
shortlist Print the available commands.
version Print the version number.
x-private-key Derive your extended private key and write it to a file.
x-public-key Print your extended public key.
If you are using macOS, running keysmith
for the first time might require you to grant permission under System Preferences > Security & Privacy > General.
Enter your mnemonic phrase (aka "seed")
If you 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
Optional: check your legacy address and balance
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: Go to https://ic.rocks/principal/renrk-eyaaa-aaaaa-aaada-cai, look for "Canister interface" and the method "balance". There, paste your DFN address in to the field labeled "text" and click the button labeled "Query". Your ICP balance will appear below "nat32".
Create your private key (.pem file)
Derive your private key from your seed phrase.
echo $seed | keysmith private-key -f -
This creates a file identity.pem
containing your private key.
Optional: Store .pem file only in RAM
The identity.pem file will later be wiped from the filesystem. There is however a remaining risk that the data could survive in the disk and later extracted despite it being wiped. It is more secure to create a RAM disk and store the .pem file only in the RAM disk.
Create RAM disk on MacOS
Run these commands
1DISK=$(hdiutil attach -nomount ram://16384)
2diskutil erasevolume HFS+ RD $DISK
3cd /Volumes/RD
before running
echo $seed | keysmith private-key -f -
Create RAM disk on Linux
Run these commands
1sudo mkdir /mnt/ramdisk
2sudo mount -t ramfs keysmith /mnt/ramdisk
3sudo mkdir /mnt/ramdisk/workspace
4sudo chown $USER /mnt/ramdisk/workspace
5cd /mnt/ramdisk/workspace
before running
echo $seed | keysmith private-key -f -
Create RAM disk on Windows
Todo
Submit claim with quill
Test the installation
On the air-gapped computer run:
quill
You should see:
quill 0.2.12
Ledger & Governance ToolKit for cold wallets
USAGE:
quill [OPTIONS] <SUBCOMMAND>
OPTIONS:
-h, --help Print help information
--pem-file <PEM_FILE> Path to your PEM file (use "-" for STDIN)
-V, --version Print version information
SUBCOMMANDS:
account-balance Queries a ledger account balance
claim-neurons Claim seed neurons from the Genesis Token Canister
get-proposal-info
help Print this message or the help of the given subcommand(s)
list-neurons Signs the query for all neurons belonging to the signin principal
list-proposals
neuron-manage Signs a neuron configuration change
neuron-stake Signs topping up of a neuron (new or existing)
public-ids Prints the principal id and the account id
send Sends a signed message or a set of messages
transfer Signs an ICP transfer transaction
If you are using macOS, running quill
for the first time might require you to grant permission under System Preferences > Security & Privacy > General.
Sign the claim request
On the air-gapped computer run:
quill --pem-file identity.pem claim-neurons >msg.json
Submit the claim to the IC
Option 1: With quill on the networked computer
Copy the resulting file `msg.json` back to the networked computer. On the networked computer, change into the directory where `msg.json` is and run:
quill send msg.json
Your neurons should now be claimed.
You can double-check if you claim was successful in the following way: Go to https://ic.rocks/genesis/2d89d96b10f7a9456a9154b2f5309ee70df5bce1 where you replace 2d89d96b10f7a9456a9154b2f5309ee70df5bce1
with your own DFN address. Under "Status" you should see "Claimed".
Option 2: Use the QR scanner app
- Install
qrencode
- Run
cat msg.json | gzip -c | base64 | qrencode -o msg.png
- Open
msg.png
in an image viewer - Open scanner app in a browser on a phone: https://p5deo-6aaaa-aaaab-aaaxq-cai.raw.ic0.app
- Scan QR code and submit
Clean up the air-gapped computer
If your claim was successful then do not forget to remove the .pem
file on the air-gapped computer:
rm identity.pem