---
# System prepended metadata

title: Cryptographic Wallet Definitions and Languaging
tags: [article / in process]

---

---
robots: noindex, nofollow
---

# Cryptographic Wallet Definitions and Languaging
###### tags: `article / in process`

***(Shannon, I'd like you to do a quick edit pass tomorrow on this first, and consider as you revise other Fully Noded 2 documents making sure we move in this direction.)***

I start with a few notes on language. 

Most of these definitions do not need to be included the FullyNoded 2 docs, but I'm including them for our consistency and terminology clarity long-term. My goal with these is to address the following problems:

1. Our languaging in the bitcoin community is not consistent about wallets. In fact, in many cases the use of the word "wallet" is fundamentally incorrect, as real-world wallets contain multiple kinds of things, whereas in bitcoin "wallet" typically means the keys to fully control one or more bitcoin accounts.
1. In particular our language in the Bitcoin community has been driven by single signature scenarios, not the new scenarios of where the wallet holder can participates in multi-party multisig accounts and may also hold identity & authentication material, credentials, and bearer instruments such as pre-signed transactions and capabilities.
1. We also often make use of terms inconsistent with legal terms used by banks and regulators.
1. Many of these terms also should be useable in the future for non-digital asset wallets, such as digital identity (authentication data),  credentials (endorsement certificates), and capabilities (authorization vouchers)
1. In these definitions I trying to avoid as much as I can about the specific technology of keys, signatures, proofs, as well as what they authorize (funds, credentials, etc.) or any specifics like single signatures, multisignatures, Shamir shards, etc. Some are unavoidable.

[dual / mutual / control]

***General definitions:***

- A **party** is a person or institution that can legally consent to take **action**, or explicitly consent to participate in **actions** of other **parties**.
- A **party** would typically be a natural person but could be a group of people acting in concert together (atomically as a group) to explicity consent to take take action, for example as a family, organization, company or a smart contract algorithm that a group of people has delegated their implicit consent take **action** on their behalf.
- The **holder** is the primary party that can initiate an **action** and also can legally consent to take that **action** at this moment in time. They may be taking such **action** solely on behalf of themselves, or in concert with others in a **supportive** or **cooperative** capacity, a **mutual** capacity, or **custodial** or **fiduciary** capacity. They may not be able to take action in the future if **time-locks** are defined.
- An **action** is a cryptographic operation by the **holder** that once is completed with other parties creates a cryptograpic **capability** containing the instructions of its creators. Once a **capability** is shared and confirmed by the system (such as a shared ledger, distributed database or blockchain) the capability will change the state of data in that system. Typically these changes are not trivially deletable by the **holder**, they must be either be **reversed** with the participation of other parties, or other parties accept **revocation** of that action.
  - Future to be done: A **registered capability** makes solely fixed state changes to data as defined by the parties that created the instrument to a fixed set of third-parties. A **bearer capability** allows the possessor of the instrument to make state changes to the data on the possessors own behalf, without additional participation of the parties that created the **capability**. A **delegated capability** allows the possessor to make a subset of state changes to the data on the possessors own behalf, without additional participation of the parties that delegated or created it. It is possible for to have a **delegated bearer capability**.

*Definitions associated with wallets:*

- A **cryptographic** **wallet** is an application holding cryptographic material that allows **holders** to take action, or participate in the **action** of other **parties.**
- A **cryptographic** **wallet** is considered under the **control** of the holder if they exclusively have both the legal and cryptographic ability to consent to initiate an **action** even if it to complete the **action** also requires the **consent** of other parties.
- A **cryptographic** **wallet** is considered **compromised** if other parties gain **control** of the ability to take **action** without the consent of the **holder** and that such actions are indistinguishable from consent by the **holder**, and thus other **parties** are unable to know that proper consent was not given.

*Definitions associated with wallet templates*

- A **wallet template** is a series of decisions about how a **cryptographic wallet** is to be created, how the wallet can used by the **holder** (with or without the participation of other **parties**) to take **action**, how consent for such **action** is determined.
- A **wallet key** (sometimes known an "HD-derived key", BIP32 key, or xprv) is a secret that is used to create the cryptographic material that a single wallet needs for the **holder** to take **action**, or to participate in the **action** of other **parties**. Some **wallet templates** require multiple **wallet-keys**, some of which may not be under the control of the **holder**.
- A **watch-key** is a special key derived from the **wallet-key** (sometimes called a xpub), that does not allow a wallet to take action, but does allow devices or **parties** to watch or participate in an **action** by the **holder**.
- A **wallet-descriptor** is a wallet template that has been completely filled out with either **master-keys** or **watch-keys**. It comes in **public**, **recovery**, or **master** forms.
- A **public wallet-descriptor** is a wallet template that has been filled out with all the **watch-keys** required a particular wallet. It is unspendable without any **master-keys**, though the disclosure of a **public descriptor** does potentially allow others to know 
- A **recovery wallet-descriptor** is a wallet template that has been filled out with all the **watch-keys** required a particular wallet, as well as at least one **master-key**. It is unspendable until all **master-keys** are recovered. It is considered **"warm".**
- A **full wallet-descriptor** is a wallet template that has been filled out with all the **wallet-keys** required a particular wallet. It is considered "**hot**" and is immediately spendable.
- A **master-seed** is a special secret used that can be used to create multiple **wallet-keys.** However, without some form of **wallet descriptor** (**public**, **recovery**, or **master**) a **master-seed** may be insufficient to restore a wallet.
- A **master recovery archive** is a special recovery descriptor that includes a **full wallet-descriptor** but also includes the master-seed, path, birthday as well as all other metadata needed to fully restore a wallet.

*The following definitions are about the kinds of **cryptographic wallets**.* 

- A wallet is **live** if is able to take actions based on the consent of the holder.
- A wallet is **cold** if no one can take action until at least some information is restored from offline sources that do not reside any computer on the network. A wallet is **cool** if it can see a history of previous **cold** actions and can watch for new **cold** actions.
- A **hot** wallet is one that is **live**, and everything required for a **holder** to take **action** resides on a single device. A **warm** wallet is also **live**, but some of the information required to take **action** resides on other devices under the exclusive control of the **holder**.
- A wallet is **mutual** if it requires another party to consent to approve the **holder** to take action. In effect, a **mutual wallet** joins the parties into a single party for purposes of consent. It is possible for **mutual wallets** to be also **cold** or **cool** but never **hot** or **warm**.

*The following definitions are about the recovery of a **cryptographic wallet**:* 

- A wallet requires **recovery** if the **holder** loses exclusive **control** of a **wallet** in case of damage, loss or **compromise.**
- A **recovery template** describes how the **holder** may be restored to the exclusive **control** of a wallet.
- A wallet is considered **self-sovereign** if it can be recovered without the participation of other **parties**.
- A wallet is considered **supported** if other **parties** can participate in the recovery of the wallet, but the participation of such **supportive parties** is not exclusively required, and thus **self-sovereign** recovery without their participation is still possible.
- A wallet is considered **collaborative** if it requires the participation of other parties to recover the **control** of the wallet to the **holder**, but no single party can recover the wallet without the consent of the **holder** or some participation by all or some threshold of additional **collaborative parties**.
- A wallet is considered **custodial** if single party can restore wallet without the explicit consent of the **holder** to take action, in particular, if they have the right to do so for the **custodial parties'** benefit rather than that of the holder.
- A wallet is considered **fiduciary** if it is **custodial** but that the **fiduciary party** has a strong legal requirement and incentive to solely act on the behalf of the **holder**, even if it harms the **fiduciary party**.

Some other wallet definitions

- A wallet is considered **time-locked** if at some future time, based on rules set by the **holder**, another **party** can take **action** without **control** of the **holder's** wallet. Such action is considered to be consented to by the **holder**, as the rules of the time-lock were originally established exclusively by the **holder**.
- An **offline backup** is storage of sufficient **wallet-descriptors** in locations other than that of your primary device to allow recovery of your wallet.
- An **offline archive** is not only an **offline backup** of your **wallet-descriptors** but also includes **master-seeds** and other metadata about your wallet, such as paths, birthday, invoice and payment notes, etc.

Given these definitions, here is the (i) info text for the two FullyNoded2 wallet and recovery templates we currently support. Note that I don't use all the terms above, and even when I do I have only **highlighted** a few key terms that I believe FullyNoded2 users should learn early.

**Hot Self-Sovereign Wallet (for amounts under $1K)** 

(info text) This **wallet template** is best as a purse for smaller amounts of Bitcoin, for learning about how to use Bitcoin, and for learning about the features this Fully Noded 2 application. It will create a **live** spendable single-signature wallet (aka a **hot** wallet), You can recover control of this wallet without any assistance of others, thus recovery is considered **self-sovereign**.

This template creates a new **master seed** (bip39) which then used to derive a single **wallet key** (bip32) which is encrypted on your iPhone and iCloud using the native segwit (bip84) standard. Once you have backed up your wallet for recovery, this **master seed** will be deleted and only the **wallet key** will exist on your phone.

To recover your wallet, this template will offer you three **offline backup** options. 

- You can backup a **master recovery archive** for your wallet to the ***QR-Vault\*** app on another device or print it on waterproof paper. You can use this **master recovery archive** to fully recover or sweep not only your wallet and all its metadata (such as invoice and payment notes), but this archive also includes the **master seed** to generate additional **wallet-keys** that can used to create new wallets or used with others to create new collaborative multi-signature wallets.
- You can backup your **master wallet-descriptor** (which includes your **wallet-key** but not your **master seed**) for use with a ***QR-Vault\*** app on another device, or to print on waterproof paper. You can use this backup to recover your wallet in case of loss or damage to your iPhone or sweep the funds associated with this wallet to new wallet if you believe it has been compromised. However, you will not be able to restore any metadata such as invoice and payment notes, or use it to create new wallets. 
- You can print an offline **public wallet-descriptor** ideally on waterproof paper, along with a 12-word **master seed** to be stored on waterproof paper, or more ideally on steel or titanium as described in the #SmartCustody book. With both of these you to restore your wallet in case of loss or damage to your iPhone or sweep the funds associated with this wallet to new wallet if you believe it has been compromised, but you will not be able to restore any metadata such as invoice and payment notes. In this form, your **master seed** is also available for use by other wallets so that you only have to scribe, punch or etch on titanium or steel one time.

Using this wallet template, if you lose possession of your full node, it can't be used to steal your funds as it does not have any keys to spend your funds. If you lose possession of your iPhone, it can't be used by someone else to steal your funds as your iPhone's **wallet-key** as is protected by both biometric (TouchID or FaceID) and by two-factor authentication (Log in with Apple). You can recover your funds safely by restoring a new iPhone from iCloud. If both your iPhone and iCloud have become compromised you could also lose your funds, thus you'll need to have access to your **offline backup** to sweep them to a new account before any attacker in order to restore control of your funds.