Skip to main content

Creating a Wallet

To operate a stake pool, you need to create the following addresses for a wallet:

  • Payment Address—Used to store, receive and send money
  • Stake Address—Used to store and withdraw rewards, as well as to define the stake pool owner, rewards accounts and stake pool delegation

You can create a wallet for your stake pool using key pairs or a seed phrase. While creating a wallet using keys is simpler, using a seed phrase offers the convenience of accessing the rewards account holding the pledge for your stake pool using an online, Desktop or Mobile wallet.

Note
Note

Pledge is the stake that you delegate to the pool that you operate, serving as a security measure and indicating your commitment to the Cardano ecosystem.

If you create a wallet using a seed phrase, then you can generate the keys for the wallet. If you create a wallet using keys, then generating the seed phrase for the wallet is NOT possible.

For security, generate key pairs, addresses and the optional seed phrase using your air-gapped, offline computer.

Note
Note

Cardano CLI commands throughout the How to Set Up a Cardano Stake Pool guide may use the ‑‑mainnet option. If you are working in a Testnet environment, then remember to replace each instance of the ‑‑mainnet option with ‑‑testnet‑magic <MagicNumber> where <MagicNumber> is the network magic number for the Testnet that you use.

Using Keys

To create a new wallet using a terminal window on your air-gapped, offline computer:

  1. To generate a new payment address key pair using the file names payment.vkey and payment.skey type:
    cd $NODE_HOME
    cardano-cli conway address key-gen \
    --verification-key-file payment.vkey \
    --signing-key-file payment.skey

    Note
    Note

    You copied the Cardano CLI binary when Configuring an Air-gapped, Offline Computer.

  2. To generate a new stake address key pair using the file names stake.vkey and stake.skey type:
    cardano-cli conway stake-address key-gen \
    --verification-key-file stake.vkey \
    --signing-key-file stake.skey
  3. To generate a stake address using the file name stake.addr type:
    cardano-cli conway stake-address build \
    --stake-verification-key-file stake.vkey \
    --out-file stake.addr \
    --mainnet
  4. To generate a payment address using the file name payment.addr that is associated with the stake address you created in step 3, type:
    cardano-cli conway address build \
    --payment-verification-key-file payment.vkey \
    --stake-verification-key-file stake.vkey \
    --out-file payment.addr \
    --mainnet
  5. Carefully back up the files containing the payment address and stake address as well as the corresponding public verification and secret keys using a secure and comprehensive backup strategy.
  6. Using removable media, copy the stake.vkey, stake.addr and payment.addr files to the $NODE_HOME folder on your block-producing node.

Using a Seed Phrase

To create a new wallet using a seed phrase:

  1. Using a terminal window on the computer designated as the block-producing node in your stake pool configuration, type the following commands to download the latest release of Cardano Wallet:
    cd $NODE_HOME
    RELEASETAG=$(curl -s https://api.github.com/repos/cardano-foundation/cardano-wallet/releases/latest | jq -r .tag_name)
    wget https://github.com/cardano-foundation/cardano-wallet/releases/download/${RELEASETAG}/cardano-wallet-${RELEASETAG}-linux64.tar.gz
  2. Using removable media, copy the TAR.GZ archive that you downloaded in step 1 to the $NODE_HOME folder on your air-gapped, offline computer, and then type the following command using a terminal window to extract the contents of the archive, where <ArchiveName> is the name of the file containing Cardano Wallet:
    tar -xvzf <ArchiveName>
  3. To copy the shelley-genesis.json file for the environment that you use, type the following command where <ArchiveFolder> is the name of the folder where you extracted Cardano Wallet in step 2, and <EnvironmentName> is the name of the environment:
    cp ./<ArchiveFolder>/configs/<EnvironmentName>/shelley-genesis.json $NODE_HOME
  4. To add Cardano Wallet as well as bundled Cardano CLI binaries to the PATH environment variable temporarily, and then generate a 24-word seed phrase, type:
    export PATH="$(pwd)/cardano-wallet-${RELEASETAG}-linux64:$PATH"
    cardano-wallet recovery-phrase generate --size 24 > seed-phrase.dat
  5. Using a text editor, create a new file named $NODE_HOME/createWallet.sh, and then paste the following script into the file:
    #!/bin/bash

    #
    # To run the createWallet.sh script, type the following command where <Index> is 0 or 1
    # indicating the payment key path for the wallet, <OutputFolder> is the location where
    # you want the script to save keys and addresses, and <SeedPhrase> is the 24-word seed
    # phrase that you want the script to use:
    #
    # createWallet.sh <Index> <OutputFolder> <SeedPhrase>
    #
    # For example, type:
    #
    # ./createWallet.sh 0 wallet-keys $(cat seed-phrase.dat)
    #
    # Keys used in Cardano transactions are five derivations away from the seed phrase,
    # using the derivation path 1852H/1815H/<x>H/<y>/<z> where:
    #
    # - 1852 is the coin ID for ADA
    # - 1815 is an extra, unused path
    # - <x> is the wallet index number
    # - <y> is 0 or 1 indicating the payment key path for wallet <x>, or 2 indicating the
    # staking key path
    # - <z> is the key number
    #
    # NOTE: An extended key may derive a hierarchy of other keys. Normal keys represent a
    # single, standalone key pair.
    #
    # NOTE: An enterprise address is a payment address that cannot participate in staking.
    #
    # For more details on Cardano Wallet, see https://cardano-foundation.github.io/cardano-wallet/
    #
    # For more details on using the cardano-address binary, to access built-in help type:
    #
    # cardano-address --help
    #

    #
    # Assign paths to required binaries to variables
    #
    CADDR=${CADDR:=$(which cardano-address)}
    [[ -z "$CADDR" ]] && { echo "cardano-address is not available. Exiting..." >&2 ; exit 1; }

    CCLI=${CCLI:=$(which cardano-cli)}
    [[ -z "$CCLI" ]] && { echo "cardano-cli is not available. Exiting..." >&2 ; exit 1; }

    BECH32=${BECH32:=$(which bech32)}
    [[ -z "$BECH32" ]] && { echo "bech32 is not available. Exiting..." >&2 ; exit 1; }

    #
    # Parse arguments passed to the script
    #

    # Only support 24-word seed phrases
    [[ "$#" -ne 26 ]] && {
    echo "usage: $(basename $0) Arguments passed to the script are incorrect. Only 24-word seed phrases are supported." >&2
    exit 1
    }

    IDX=$1
    shift

    OUT_DIR="$1"
    [[ -e "$OUT_DIR" ]] && {
    echo "The folder $OUT_DIR already exists. Please delete the folder, and then run the createWallet.sh script again." >&2
    exit 1
    } || mkdir -p "$OUT_DIR" && pushd "$OUT_DIR" >/dev/null

    shift
    SEEDPHRASE="$*"

    #
    # If the Shelley Genesis file exists, then query to retrieve required values
    #
    GEN_FILE=${GEN_FILE:="../shelley-genesis.json"}
    [[ ! -f "$GEN_FILE" ]] && { echo "Shelley genesis file is not available. Exiting..." >&2 ; exit 1; }

    NW_ID=$(jq '.networkMagic' -r "$GEN_FILE")

    MAGIC="--testnet-magic $NW_ID"

    case $NW_ID in
    1)
    NETWORK="preprod"
    ;;
    2)
    NETWORK="preview"
    ;;
    *)
    NETWORK="mainnet"
    MAGIC="--mainnet"
    ;;
    esac

    #
    # Derive keys and addresses
    #

    echo
    echo "Generating wallet in the $NETWORK environment..."
    echo

    # Convert the seed phrase into the master key
    echo "$SEEDPHRASE" | "$CADDR" key from-recovery-phrase Shelley > root.prv

    # Using the master key, derive the extended private stake address key
    cat root.prv | "$CADDR" key child 1852H/1815H/0H/2/0 > stake.xprv

    # Using the master key, derive the extended private payment address key
    cat root.prv | "$CADDR" key child 1852H/1815H/0H/$IDX/0 > payment.xprv

    # Using the extended private keys, derive the extended public keys
    # as well as the enterprise address and payment address
    cat payment.xprv \
    | "$CADDR" key public --with-chain-code \
    | tee payment.xpub \
    | "$CADDR" address payment --network-tag $NETWORK \
    | tee enterprise.addr_candidate \
    | "$CADDR" address delegation $(cat stake.xprv | "$CADDR" key public --with-chain-code | tee stake.xpub) \
    | tee payment.addr_candidate \
    | "$CADDR" address inspect

    echo
    echo "Wallet generated using derivation path 1852H/1815H/0H/$IDX/0"
    echo

    # Using Cardano CLI, convert extended private keys to the corresponding Shelley-format secret signing key
    "$CCLI" conway key convert-cardano-address-key --shelley-payment-key --signing-key-file payment.xprv --out-file payment.skey
    "$CCLI" conway key convert-cardano-address-key --shelley-stake-key --signing-key-file stake.xprv --out-file stake.skey

    # Using secret signing keys, get extended public verification keys
    "$CCLI" conway key verification-key --signing-key-file payment.skey --verification-key-file payment.evkey
    "$CCLI" conway key verification-key --signing-key-file stake.skey --verification-key-file stake.evkey

    # Using extended public verification keys, get normal public verification keys
    "$CCLI" conway key non-extended-key --extended-verification-key-file payment.evkey --verification-key-file payment.vkey
    "$CCLI" conway key non-extended-key --extended-verification-key-file stake.evkey --verification-key-file stake.vkey

    # Using the stake address public verification key, generate the stake address
    "$CCLI" conway stake-address build --stake-verification-key-file stake.vkey $MAGIC --out-file stake.addr

    # Using the payment address public verification key, generate the enterprise address
    "$CCLI" conway address build --payment-verification-key-file payment.vkey $MAGIC --out-file enterprise.addr

    # Using the payment address and stake address public verification keys, generate the payment address
    # associated with the stake address
    "$CCLI" conway address build \
    --payment-verification-key-file payment.vkey \
    --stake-verification-key-file stake.vkey \
    $MAGIC \
    --out-file payment.addr

    echo "WARNING: If the address in the payment.addr file Cardano CLI generates does NOT match the address in the payment.addr_candidate file"
    echo " Cardano Wallet generates, then do NOT use the wallet:"
    echo
    echo " payment.addr: $(cat payment.addr)"
    echo "payment.addr_candidate: $(cat payment.addr_candidate)"
    echo
    diff -s payment.addr payment.addr_candidate
    echo

    popd > /dev/null

    Credit
    Credit

    Thanks to Geld Tiger, den-is and ilap for preparing the original script.

  6. Save and close the createWallet.sh file, and then type the following command to grant file permissions for executing the script:
    chmod +x createWallet.sh
  7. To generate keys and addresses for your wallet, type:
    ./createWallet.sh 0 wallet-keys $(cat seed-phrase.dat)
  8. To prevent overwriting your seed phrase, type the following command to remove Cardano Wallet binaries where <ArchiveFolder> is the name of the folder where you extracted Cardano Wallet in step 2:
    rm -r $NODE_HOME/<ArchiveFolder>
  9. To protect your seed phrase, type the following command to clear history:
    history -c && history -w
  10. Close the terminal window that you used to create your wallet, and then open a new terminal window if needed.
  11. Carefully back up the $NODE_HOME/seed-phrase.dat file, as well as all files in the $NODE_HOME/wallet-keys/ folder, using a secure and comprehensive backup strategy.
  12. Using removable media, from the $NODE_HOME/wallet-keys/ folder copy the stake.vkey, stake.addr and payment.addr files to the $NODE_HOME folder on the computer designated as the block-producing node in your stake pool configuration.

Funding Your Payment Address

Using a wallet, send funds that you want to pledge to your stake pool from another account you control to the new payment address.

To fund the new payment address:

  1. To display the new payment address, using a terminal window type:
    cat $NODE_HOME/payment.addr
  2. For a Mainnet payment address, use a wallet of your choice to send funds that you want to pledge to the address that displays in step 1
    OR
    For a payment address in a Testnet environment, request funds using the Testnets Faucet.

    Challenge
    Challenge

    Using Cardano CLI, create a transaction Sending Funds to the new payment address.

  3. Wait a few moments for the transaction to complete. To verify the transaction, type the following command using a terminal window on the block-producing node to display the list of Unspent Transaction Output (UTXOs) available for the new payment address, and then find the UTXO for the funds that you sent in step 2:
    cardano-cli conway query utxo --output-json \
    --address $(cat $NODE_HOME/payment.addr) \
    --mainnet

The UTXO query displays JSON output similar to the following—where the key is the transaction hash, followed by a hash (#) character, and then followed by the transaction index—displaying the value of the UTXO in Lovelace:

{
"4f26e87038f6657ea9429732685c43525685506816420dc5f0e50c692d3387e6#0": {
"address": "addr_test1qzkdq88knvkrycp40zv9mtdejqqjqwklvzcjmvlj8erjgx5q628ecngj4yjr4dmtfqwj76qcqrwclgwvn39hm4hcy9eqcsza02",
"datum": null,
"datumhash": null,
"inlineDatum": null,
"inlineDatumRaw": null,
"referenceScript": null,
"value": {
"lovelace": 9997654786
}
}
}

Note
Note

Named after the English mathematician and writer Ada Lovelace, the currency symbol for ADA is ₳ and the sub-unit is the Lovelace. ₳1 is comprised of 1,000,000 Lovelace.