Introduction to Securing Bitcoin Keys

Using your Bitcoin keys

Mastering BTC Pay Server

Using your Bitcoin keys

BTCPay Server Wallet
Transactions
How to Send
RBF (Replace-By-Fee)
Coin Selection
How to Receive
BTCPay Server Wallet settings
Example
Example: Writing down a seed phrase
Example: Storing a seed phrase on a Hardware Wallet
Skill Summary
Knowledge Assessment Practical Review

BTCPay Server Wallet

BTCPay Server consists of the following standard wallet features:

Transactions
Send
Receive
Rescan
Pull Payments
Payouts
PSBT
General settings

Transactions

Administrators can see the incoming and outgoing transactions for the on-chain wallet connected to this specific store in the transactions view. Each transaction has a distinction between the received and sent amounts. Received will be green, and outgoing transactions will be red. Within the BTCPay Server transaction view, administrators will also see a set of standard labels.

Transaction Type	Description
App	Payment was received through an app-created invoice
invoice	Payment was received through an invoice
payjoin	Not paid, invoice timer still has not expired
payjoin-exposed	UTXO was exposed through an invoice payjoin proposal
payment-request	Payment was received through a payment request
payout	Payment was sent through a payout or refund

How to Send

BTCPay server’s send function sends transactions from your BTCPay Server on-chain wallet. BTCPay Server allows for multiple ways of signing your transactions to spend funds. A transaction can be signed with;

Hardware Wallet
Wallets supporting PSBT
HD private key or recovery seeds.
Hot Wallet

Hardware wallet

BTCPay Server has built-in hardware wallet support, allowing you to use your hardware wallet with BTCPay Vault without leaking information to third-party apps or servers. The hardware wallet integration within BTCPay Server enables you to import your hardware wallet and spend incoming funds with a simple confirmation on your device. Your private keys never leave the device, and all funds are validated against your full node, ensuring no data leakage.

Signing with a wallet supporting PSBT

PSBT (Partially Signed Bitcoin Transactions) is an interchange format for Bitcoin transactions still need to be fully signed. PSBT is supported in BTCPay Server and can be signed with compatible hardware and software wallets.

The construction of a fully signed Bitcoin transaction goes through the following steps:

A PSBT gets constructed with specific inputs and outputs, but no signatures
The exported PSBT can be imported by a wallet that supports this format
The transaction data can be inspected and signed using the wallet
The signed PSBT file gets exported from the wallet and imported with BTCPay Server
BTCPay Server produces the final Bitcoin transaction
You verify the result and broadcast it to the network

Signing with HD Private Key or mnemonic seed

If you have created a wallet before using BTCPay Server, you can spend the funds by inputting your private key into an appropriate field. Set a proper "AccountKeyPath" in wallet> Settings; otherwise, you cannot spend.

Signing with a hot wallet

If you created a new wallet when setting up your store and enabled it as a hot wallet, it will automatically use the seed stored on a server to sign.

RBF (Replace-By-Fee)

Replace-By-Fee (RBF) is a Bitcoin protocol feature that allows you to replace a previously broadcast transaction (while still unconfirmed). This allows randomizing your wallet’s transaction fingerprint or replacing it with a higher fee rate to move the transaction higher in the queue of confirmation (mining) priority. This will effectively replace the original transaction as the higher fee rate will be prioritized, and once confirmed, it will invalidate the original one (no double spend).

Press the "Advanced Settings" button to view the RBF options.

Randomize for higher privacy, allows the transaction to be replaced automatically for randomization of the transaction fingerprint.
Yes, flag transaction for RBF and be replaced explicitly (Not replaced by default, only by input)
No, do not allow the transaction to be replaced.

Coin Selection

Coin selection is an advanced privacy-enhancing feature that allows you to select coins you want to spend when crafting a transaction. For example, paying with coins that are fresh from a conjoin mix.

Coin selection works natively with the wallet labels feature. This lets you label incoming funds for smoother UTXO management and spending.

BTCPay Server supports BIP-329 for label management. If you transfer from a wallet that supports BIP-329 and have set labels, BTCPay Server will recognize and import them automatically. When migrating servers, this information can also be exported and imported into the new environment.

How to Receive

When clicking on the receive button in BTCPay Server, it generates an unused address that can be used to receive payments. Administrators may also generate a new address by creating a new “Invoice.”

BTCPay Server will always prompt you to generate the following available address to prevent address reuse. After clicking “Generate next available BTC Address,” BTCPay Server generated a new address and QR. It also allows you to directly set a Label to the address for better management of your addresses.

Re-scan

The Rescan feature relies on Bitcoin Core 0.17.0’s “Scantxoutset” to scan the current state of the blockchain (called UTXO Set) for coins belonging to the configured derivation scheme. A wallet rescan addresses two common issues that BTCPay Server users frequently encounter.

Gap limit problem - Most third-party wallets are light wallets that share a node between many users. Light and full node-reliant wallets limit the number (typically 20) of addresses without a balance they track on the blockchain to prevent performance issues. BTCPay Server generates a new address for every invoice. With the above in mind, after BTCPay Server generates 20 consecutive unpaid invoices, the external wallet stops fetching the transactions, assuming no new transactions occurred. Your external wallet won’t show them once invoices are paid on the 21st, 22nd, etc. On the other hand, internally, the BTCPay Server wallet tracks any address it generates, along with a significantly higher gap limit. It does not rely on a third party and can always show a correct balance.
The gap limit solution - If your external/existing wallet allows gap-limit configuration, the easy fix is to increase it. However, the majority of wallets do not allow this. The only wallets that currently support gap-limit configuration that we are aware of are Electrum, Wasabi, and Sparrow Wallet. Unfortunately, you are likely to encounter a problem with many other wallets. For the best user experience and privacy, consider using the BTCPay Server's internal wallet instead of external wallets.

BTCPay Server uses “mempoolfullrbf=1”

BTCPay Server uses “mempoolfullrbf=1”; we have added this as the default to your BTCPay Server setup. However, we have also made it a feature you can disable yourself. Without “mempoolfullrbf=1,” if a customer double-spends a payment with a transaction not signaling RBF, the Merchant would only know after confirmation.

An administrator may want to opt out of this setting. By the following string, you can change the default setting.

BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCL UDE_FRAGMENTS;opt-mempoolfullrbf"
. btcpay-setup.sh -i

BTCPay Server Wallet settings

Wallet settings within BTCPay Server provide a clear and concise overview of your wallet's general settings. All these settings are pre-filled if the wallet was created with BTCPay Server.

Wallet settings within BTCPay Server provide a clear and concise overview of your wallet's general settings. All these settings are pre-filled if the wallet was created with BTCPay Server. BTCPay Server’s wallet settings start with the wallet status. Is it a Watch-only or a Hot wallet? Depending on the wallet type, actions may vary, including rescanning the wallet for missing transactions, pruning old transactions from the history, registering the wallet for payment links, or replacing and deleting the current wallet attached to the store. In BTCPay Server’s wallet settings, administrators may set a Label for the wallet for better wallet management. Here, the Administrator will also be able to see the Derivation Scheme, account key (xpub), Fingerprint, and Keypath. Payments in wallet settings have only two main settings. Payment is invalid if the transaction fails to confirm within (set minutes) after invoice expiration. Consider the invoice confirmed when the payment transaction has X amount of confirmations. Administrators can also set a toggle to display recommended fees at the payment screen or set a manual confirmation target in the number of blocks.

!Note!

If you follow this course independently, creating this account would likely be done on a third-party host. Therefore, we again suggest that these should not be used as production environments, but rather for training purposes only.

Example

Set up a Bitcoin Wallet in BTCPay Server

BTCPay Server offers two methods for setting up a wallet. One way is to import an existing Bitcoin wallet. The import can be done by connecting a hardware wallet, importing a Wallet file, entering an Extended public key, scanning a wallet’s QR code, or, least favorably, entering a previously created Wallet recovery seed by hand. In BTCPay Server, it is also possible to create a new wallet. There are two possible ways of configuring BTCPay Server when generating a new wallet.

The hot wallet option in BTCPay Server enables features such as 'Payjoin' or 'Liquid'. There is, however, a drawback: the recovery seed generated for this Wallet will be stored on the server, where anyone with admin control could fetch it. As your private key is derived from your recovery seed, a malicious actor could gain access to your current and future funds!

To mitigate this risk in BTCPay Server, an Admin can set the value in Server Settings > Policies > "Allow non-admins to create hot wallets for their stores" to "no", as it is the default value. To enhance the security of those Hot wallets, the server administrator should enable 2FA authentication on accounts that are allowed to have hot wallets. Storing private keys on a public server is a dangerous practice and carries significant risks. Some are similar to Lightning Network risks (see the next chapter for Lightning Network risks).

The second option BTCPay Server offers in generating a new wallet is by creating a Watch-Only wallet. BTCPay Server will generate your private keys once. After the user confirms to have written down their Seed Phrase, BTCPay Server will wipe the private keys from the server. As a result, your store now has a Watch-only wallet connected to it. To spend the funds received on your watch-only Wallet, see chapter How to Send, either by using BTCPay Server Vault, PSBT (partially signed bitcoin transaction), or, least recommended, manually providing your seed phrase.

You created a new 'Store' in the last part. The installation wizard will continue by asking to "Set up a wallet" or "Set up a Lightning node". In this example, you will follow the "Set up a wallet" wizard process (1).

After clicking "Set up a wallet", the wizard will continue by requesting how you want to continue; BTCPay Server now offers the option to connect an existing Bitcoin wallet to your new store. If you don't have a wallet, BTCPay Server suggests creating a new one. This example will follow the steps for “create a new wallet” (2). Follow the steps to learn how to "Connect an existing wallet (1).

!Note!

If you take this course in a classroom, please note that the current example and seed we have generated are for educational purposes only. There should never be any substantial amount other than required throughout the exercises on these addresses.

(1) Continue the “New wallet” wizard by clicking on the "Create a new wallet" button.

(2) After clicking “Create a new wallet,” the next window in the wizard will give the options “Hot wallet” and “Watch-only wallet.” If you follow along with an instructor, your environment is a shared Demo, and you can only create a Watch-only wallet. Notice the difference between the two figures below. As you are in the Demo environment, following along with the instructor, create a "Watch-only wallet" and continue with the "New Wallet" wizard.

(3) Continuing the new wallet wizard, you are now in the Create BTC watch-only wallet section. Here, we get to set the wallet's "Address type." BTCPay Server allows you to pick your preferred Address type; as of the writing of this course, it is still recommended to use bech32 addresses. You can learn more in detail about addresses in the first chapter of this part.

SegWit (bech32)
- Native SegWit addresses start with bc1q.
- Example: bc1qXXXXXXXXXXXXXXXXXXXXXX
Legacy
- Legacy addresses are addresses that start with the number 1.
- Example: 15e15hXXXXXXXXXXXXXXXXXXXX
Taproot (For advanced users)
- Taproot addresses start with bc1p.
- Example: bc1pXXXXXXXXXXXXXXXXXXXXXXXX
SegWit wrapped
- SegWit-wrapped addresses start with 3.
- Example: 37BBXXXXXXXXXXXXXXX

Choose SegWit (recommended) as your preferred wallet address type.

(4) When setting the parameter for the Wallet, BTCPay Server allows the users to set an optional passphrase through BIP39; be sure to confirm your password.

(5) After setting the Wallet’s Address type and possibly setting some advanced options, click Create, and BTCPay Server will generate your new Wallet. Note that this is the last step before generating your Seed phrase. Ensure you only do this in an environment where someone might not be able to steal the seed phrase by looking at your screen.

(6) In the following screen of the wizard, BTCPay Server shows you the Recovery seed phrase for your newly generated Wallet; these are the keys to recovering your Wallet and signing transactions. BTCPay Server generates a seed phrase of 12 words. These words will be erased from the server after this setup screen. This Wallet is specifically a Watch-only wallet. It is advised not to store this seed phrase digitally or by photographic image. Users may only go further in the wizard if they actively acknowledge that they wrote down their seed phrase.

(7) After clicking Done and securing the newly generated Bitcoin seed phrase, BTCPay Server will update your store with the attached new Wallet and is ready to receive payments. In the User Interface, in the left navigation menu, notice how Bitcoin is now highlighted and activated under Wallet.

Example: Writing down a seed phrase

This is a particularly secure moment to use Bitcoin. As mentioned before, only you should have access to or knowledge about your seed phrase. As you follow along with an instructor and classroom, the seed generated should only be used in this course. Too many factors, including prying eyes from classmates, insecure systems, and others, make these keys only educational and untrustworthy. However, the keys generated should still be stored for course examples.

The first method we will use in this situation, which is also the least secure, is writing down the seed phrase in the proper order. A Seed phrase card is included in the course material provided to the student or can be found on the BTCPay Server GitHub. We will use this card to write down the words generated in the prior step. Make sure to write them down in the correct order. After you have written them down, check them against what was given by the software to make sure you wrote them down in the correct order. Once you have written it down, click the checkbox stating you have written down your seed phrase properly.

Example: Storing a seed phrase on a Hardware Wallet

In this course, we touch on storing a seed phrase on a hardware wallet. Following this course with an instructor might sometimes include such a device. In the course, the guide materials have compiled a list of hardware wallets that would be suitable for this exercise.

We will use BTCPay Server vault and a Blockstream Jade hardware wallet in this example.

Download BTCPay Server Vault: https://github.com/btcpayserver/BTCPayServer.Vault/releases

Make sure you download the correct files for your specific system. Windows users should download the BTCPayServerVault-2.0.5-setup.exe package, Mac users download the BTCPayServerVault-osx-x64-2.0.5.dmg, and Linux users should download BTCPayServerVault-Linux-2.0.5.tar.gz

After installing BTCPay Server Vault, start the software by clicking the icon on your Desktop. When BTCPay Server Vault is installed properly and started for the first time, it will ask permission to be used with Web Applications. It will ask to grant access to the specific BTCPay Server you work with. Accept these conditions. BTCPay Server Vault will now search for the Hardware device. Once the device is found, BTCPay Server will recognize that Vault is running and has fetched your device.

!Note!

Don't give your SSH keys or server admin account to anyone else apart from administrators when using a hot wallet. Anyone with access to these accounts will have access to the funds in the Hot Wallet.

Skill Summary

In this section, you learned the following:

The transaction view of the Bitcoin wallet and its various categorizations.
Various options are available when sending from a Bitcoin wallet, from hardware to hot wallets.
The gap limit problem faced when using most wallets, and how to correct this.
How to generate a new Bitcoin wallet within BTCPay Server, including storing the keys in a hardware wallet and backing up the recovery phrase.

In this objective, you have learned how to generate a new Bitcoin wallet within BTCPay Server. We have not yet gone into how to secure or use those keys. In a quick overview of this objective, you have learned how to set up the first store. You have learned how to generate a Bitcoin Recovery Seed phrase.

Knowledge Assessment Practical Review

Describe a method for generating keys and a scheme for securing them, along with the trade-offs/risks of the security scheme.