How to Secure Pledge with Hardware Wallet
This guide describes the process of adding a hardware wallet as a stake pool owner. That way you can secure your pledge and rewards with a hardware wallet like Trezor or Ledger Nano S+/X
Last updated
This guide describes the process of adding a hardware wallet as a stake pool owner. That way you can secure your pledge and rewards with a hardware wallet like Trezor or Ledger Nano S+/X
Last updated
Updated: 1/11/25 - updated to use Conway commands
Credits to Apex Cardano Pool and Earn Coin Pool for documenting the procedure.
There are basically 3 main things we need to do in order to add hardware wallet: 1) Install cardano-hw-cli on air gapped machine to generate keys. 2) Generate new Pool Registration Certificate and build transaction. 3) Witness and Submit transaction for new Pool Registration Certificate to the blockchain
Good to know: The scripts were tested with a Ledger hardware wallet and using the cardano-hw-cli version 1.16.0-rc.1 (latest available at the time of writing this guide). They should also work with Trezor wallets.
The new owner becomes active after 2 full epochs, the initial owner of the stake pool cannot be replaced with the new one immediately (unless each of the wallets has enough ADA in it to cover the pledge).
After the second owner and its delegation to the stake pool become active, the pledge can be moved from the initial wallet to the hardware wallet and if desired the first wallet can be removed from the stake pool owners. Removing it is optional. Please note that you can't use your hardware wallet as payment wallet yet, so you may want to keep your original pledge wallet to use as payment for pool updates.
First step is to make sure you delegate you hardware wallet which will be your 2nd pool owner, to your stake pool with Daedalus or Yoroi or Eternl or so on.
Remember you will need at least 4 ADA on your hardware wallet in order to delegate to your pool.
For this guide we will be downloading cardano-hw-cli_1.16.0-rc.1-1.deb. For other distributions than Ubuntu or Debian, download the .tar.gz. extract it and copy cardano-hw-cli somewhere in the PATH (in /usr/local/bin or where cardano-cli is) on your air gapped machine.
Download files can be found here: https://github.com/vacuumlabs/cardano-hw-cli/releases/tag/v1.16.0-rc.1 Reference: https://github.com/vacuumlabs/cardano-hw-cli/blob/develop/docs/installation.md
For this guide we use ledger, The first time you connect your hardware wallet you may need to add the udev rules. (If your device is on and connect but you get an error that your device isn't connected, then you need add_udev_rules.sh)
For Linux copy the following file to your USB:
https://raw.githubusercontent.com/LedgerHQ/udev-rules/master/add_udev_rules.sh
#Referrence: https://support.ledger.com/hc/en-us/articles/115005165269-Fix-USB-connection-issues-with-Ledger-Live
and
https://github.com/LedgerHQ/udev-rules
Copy cardano-hw-cli install file and add_udev_rules.sh to air gapped machine.
For this guide we copied the .deb file and add_udev_rules.sh to our $NODE_HOME.
Copy cardano-hw-cli install files to air gapped machine.
To Install run the following commands:
Check install version, run:
Good to Know: to find location of cardano-hw-cli run: which cardano-hw-cli
Or If you wish to uninstall cardano-hw-cli, run:
sudo dpkg --remove cardano-hw-cli
Now add udev rules by running the following command:
We will now use cardano-hw-cli to extract two files from the hardware wallet:
1) The stake key verification key hw-stake.vkey (".vkey")
The hw-stake.vkey file will be required when creating the new stake pool registration certificate.
and
2) The hardware signing file hw-stake.hwsfile (".hwsfile")
The hw-stake.hwsfile file will be required for witnessing transactions with the hardware wallet.
hw-stake.vkey is not sensitive and may be shared publicly. hw-stake.hwsfile does NOT contain the raw private key.
This script must be executed with the hardware wallet connected to the computer and unlocked, and with the Cardano application started. It will be required to confirm the key export on the hardware wallet.
To generate the verification key and hardware wallet signing file, type:
In order to add a new owner to the stake pool, a new stake pool registration certificate needs to be created. This will secure both your pool pledge account and pool reward account with a hardware wallet.
Since we need to create a new stake pool registration certificate we are going to walk through how to create an env file that contains our pool information and a script to generate a new certificate. This will allow us to make future pool changes easier and help avoid errors.
If you want to skip this step you can see an example command to create new stake pool registration certificate with hardware wallet under the "Standard Method" tab below.
ON Air Gapped Machine
Notice the pool-reward-account and additional pool-ownerstake-verification-key-file lines point to hw-stake.vkey.
1) First let's start by creating a pool-scripts folder in our $NODE_HOME.
2) Let's create an env file for our pool in the pool-scripts folder:
Edit all the values to match your data. Paths are based on normal coincashew install, please update paths as necessary. The usual values for port are 3001 or 6000, but any valid port can be used.
It is also possible to use IP Addresses
3) Create pool-registration.sh script in the pool-scripts folder:
If you are using IP Addresses instead of hostnames for the registered relays, replace --single-host-pool-relay with --pool-relay-ipv4 in the script.
You can register as many relays as you want (one or more). You just have to repeat the --single-host-pool-relay and --pool-relay-port parameters for each of them.
The pledge wallet and the rewards wallet are the same one in this case. But it is possible to create and set different wallets for them. Paths are based on normal coincashew install, please update paths as necessary.
Next:
Add execute permissions to the pool-registration script.
⚠️The script must be executed in order to generate the new stake pool registration certificate, which will need to be submitted with a transaction.
Run pool-registration script with:
In order to finish adding the hardware wallet as stake pool owner, we must submit Certificate to the blockchain with transactions.
Now let's double check that we have the correct values for our pool.cert
To double check that we have the correct values for our pool.cert run:
The transaction for submitting the new stake pool registration certificate needs to be signed with 4 signing keys:
Witness cold key (node.skey)
Witness payment key -to pay the transaction fees (payment.skey)
Witness of the first stake pool owner stake key (stake.skey)
the hardware wallet stake key -the new pool owner (hw-stake.hwsfile)
When not using a hardware wallet, the transaction to submit a stake pool registration certificate can be signed with one command.
However due to the way the hardware wallet can sign transactions, the transaction must be witnessed by all 4 signing key, and then all the witness files must be combined into a signed transaction file, which will be submitted to the blockchain.
Now we need to do our 4 witnesses. To do so we need to move back to our air gapped machine. Copy your tx.raw file to you air gapped machine. For this guide we will put it in $NODE_HOME
Now on air gapped let's create first witness with cold key
Still on air gapped machine let's create our 2nd witness with payment key.
As of now you can't use your hardware wallet as payment address so you will need to use any other payment address and use it's payment key below.
If you are able in the future to use your hardware wallet as payment wallet you can export the payment key on your air gapped machine by running the following command. When executing this command, the hardware wallet will need to be connected to the computer and unlocked, and with the Cardano application started. It will be required to confirm the export.
Still on air gapped machine let's create our 3nd witness with the stake key of the first pool owner.
When executing this command, the hardware wallet will need to be connected to the computer and unlocked, and with the Cardano application started. It will be required to confirm the witness.
Still on air gapped machine let's create our 4nd and final witness with the hw-stake key of the second pool owner.
Now we will create the signed transaction file, which needs to be submitted to the blockchain. Still on air gapped machine assemble transaction by running the following command:
Copy your tx.multisign from air gapped machine to your node in hot environment.
Submit transaction to blockchain with this command:
Wait a few minutes for transaction to reach chain, then you can go to https://cardanoscan.io/ and search your pool. Then scroll down and click on pool updates tab.
Then click on transaction and scroll down to Pool Certificates tab. Here you can confirm the data submitted.
Remember to clean up files and delete files like tx.raw, tx.multisign and pool.cert from your node.
Also a great time to do another backup!
The new owner becomes active after 2 full epochs
So Remember to wait 2 Epochs before transferring funds between wallets so that your pledge is met.
You can use cexplorer.io to verify when your pool certificate changes will be active.
Go to cexplorer.io and search for your pool and go to your pool page. Then scroll down on your pool page and click on "About" tab.
Now scroll down to Pool Certificates. Here it will show what epoch your changes will be active. You can also see the updates to your Owner Addresses and Reward Address here.
Next time you want to update your Pool Registration for example to adjust min fee, margin or pledge you will simply nano your env file on your air gapped machine with the updated info you want to use. Use command:
Sample env file:
Then run Steps 6 through Step 15 again and you are all set!
If you need or want to update relays you will need to nano changes to env file and pool-registration.sh from Step 6
Thanks to the following pools for helping to put together these guides. Please consider delegating to their pools to support them. Are you a pool? Consider buying them a coffee
