This specification describes a portable, extensible, JSON-LD wallet, supporting digital currencies and credentials.

This document is experimental and is undergoing heavy development. It is inadvisable to implement the specification in its current form. An experimental implementation is available.

Introduction

Traditional physical wallets are used to store a variety of personal assets such as cash, credit cards, driver license, health insurance, and business cards. Today we also have a wide variety of digital wallets to store and access digital versions of these same assets, with more options coming into the market every day. However, each wallet represents data and capabilities differently, sometimes intentionally to facilitate vendor lock in.

Imagine you had to carry a dozen different wallets with you at all times, and to use each one independently based on the situation. The wallets are disconnected, and the burden is on either the holder or the verifier to request all required information for each transaction. The result is a cumbersome user experience (not dissimilar to account and password management today) and expensive business implementation to support different wallets. What is missing is a standardized structure - a universal wallet - that can effectively point to and comprehend each digital asset in its current location. This universal wallet not only offers a convenient access point for people and machines to organize their assets (akin to a traditional physical wallet), but it also enables awareness and relationships between those assets as needed for real-world use.

The purpose of this specification is to design an abstract data model and set of interfaces that approximate a physical wallet system and its common uses.

There are many existing software systems which manage subsets or supersets of the information represented in digital wallets. This specification aims to be compatible with those systems, by allowing them to continue to manage the information and inferfaces, so long as they can be adequately described at both a data model, and interface level.

The property of representing data and interfaces as they exist, where they exist today, is a critical component of this specification. We fully expect this specification to live or die by its ability to achieve this property.

Guidance

Several organizations have published guidance on digital wallets.

EUDI

European Digital Identity (EUDI) Wallet Solution

Wallet Architecture and Reference Framework

ESI

Electronic Signatures and Infrastructures (ESI)

JAdES digital signatures

SVIP

Department of Homeland Security (DHS) Science and Technology Directorate (S&T) Silicon Valley Innovation Program (SVIP)

DRAFT: DHS Implementation Profile of W3C VCs and W3C DIDs

Scaling Interoperability

OWF

The mission of the OWF is to develop an open source engine to enable secure and interoperable multi-purpose wallets anyone can use to build solutions.

The OWF aims to set best practices for digital wallet technology through collaboration on open source code for use as a starting point for anyone who strives to build interoperable, secure, and privacy-protecting wallets.

Open Wallet Foundation

Wallet Types

There are many different kinds of digital wallet. This section describes a few distinguishable categories.

Progressive Web Applications

Progressive web applications (PWAs) are a kind of offline capable website.

You can read more about them here.

PWAs don't require users to install an app through an app store, but are limited by browser API support in ways that native mobile applications are not.

PWAs can access camera, WebRTC, NFC, Bluetooth, and other browser APIs. They can connect to remote apis to facilitate discovery and messaging.

Native Mobile Applications

Native Mobile Applications (NMAs) are software a user installs on a mobile OS, like Android or iOS.

NMAs have access to APIs supported by the mobile OS, such as filesystem, network, phone, or camera APIs, among others.

NMAs might implement support for hardware backed secret or key management via the OS. This and better biometric authentication support make them attractive to high security applications.

Cloud Wallets

Cloud Wallets are software services hosted on the internet, typically exposed over HTTP or gRPC.

Cloud Wallets offer some of the security benefits of centralization, such as logging and dynamic scaling.

Cloud wallets can also be "always online", in cases where a mobile wallet might lose connectivity.

Cloud wallets and message based APIs are generally an easier integration target for legacy systems.

Cold Storage Wallets

Cold Storage Wallets (CSWs) are non-networked, long-term storage for digital assets.

Cold storage is typically reserved for very sensitive information, such as keys that control large amounts of crypto currency, or root certificate signing keys.

CSWs may be implemented as either isolated hardware or physical paper.

Terminology

The following terms are used to describe concepts involved in the universal wallet.

wallet
A wallet is a small, flat case that can be used to carry such small personal items as paper currency, credit cards, and identification documents. See Wallet.
cryptocurrency
A digital asset designed to work as a medium of exchange wherein individual coin ownership records are stored in a digital ledger or computerized database using strong cryptography to secure transaction record entries, to control the creation of additional digital coin records. See Cryptocurrency.
verifiable credential
A data model for conveying claims made by an issuer about a subject. See [[vc-data-model]].
secret
Information controlled by an identity. MAY be used to derive keys.
key
A mechanism for granting or restricing access to something. MAY be used to issue and prove verifiable credentials. MAY be used to transfer and controll cryptocurrency. See Key_(cryptography).
card
A thin rectangular object used to store information graphically or digitally. MAY be used to represent any wallet content type.
meta data
Information about other information. MAY be used to describe the context in which information is used, or attributes of other information.
identity
A unique entity. Typically represented with a unique identifier.
controller
The entity that has the ability to make changes to an identity, cryptocurrency or verifiable credential. See DID controller, [[vc-data-model]].
issue
The process of creating a verifiable credential. MAY require the use of a key. See [[vc-data-model]].
prove
The process of presenting a verifiable credential. MAY require the use of a key. See [[vc-data-model]].
transfer
The process of changing the controller of a cryptocurrency, identity or verifiable credential. MAY require the use of a key.
agent
A representative for an identity. MAY require the use of a wallet. MAY support transfer,issue, prove.
collection
A collection is a named bucket for grouping wallet content.
entropy
Unpredictable information. Often used as a secret or as input to a key generation algorithm. Entropy_(information_theory).
correlation
An identifier used to indicate that external parties have observed how wallet contents are related. For example, when a public key is reused in multiple DIDs, it conveys that some common entity is controlling both identifiers. Tracking correlation allows for software to warn when some new information might be about to be exposed, for example: "Looks like you are about to send crypo currency, from an account you frequently use to a new account you just created."
Representation may need to be refactored for scaling / performance.
tags
Human friendly text labels for organizing information.
note
Text note about wallet content.
target
The target of a wallet content. Used for representing directed associations.
quorum
Number of controllers needed to make a valid transaction.
universal wallet
A digital wallet that supports cryptocurrency, verifiable credentials and cards.
multibase
Multibase is a protocol for disambiguating the encoding of base-encoded (e.g., base32, base36, base64, base58, etc.) binary appearing in text.
hdPath
A standard way of pointing to a key generated by a single mnemonic. See

Integration

The following sections describe how a wallet controller can define relationships with external systems.

HD Wallets

HD Wallets are a popular mechanism for managing many keys, addresess and accounts across multiple crypto currency ledgers.

Using a Meta Data object applied to a Secret, a user instruct an application to discover cryptocurrency that is controlled by a Secret.

See EIP84 for examples of how this is done in the ethereum community.

Because HD Wallet arose from blockchain applications, there is some ambiguity regarding their applications to DIDs.

We recommend using the Bitcoin HD path by default when generating key material for a DID Method that does not provide a specific recommendation for working with HD Paths.

      mnemonic "sell antenna drama rule twenty cement mad deliver you push derive hybrid"
      hd path "m/44'/0'/0'/0/0" 
      key type "Ed25519" 
      yields 'did:key:z6MktiSzqF9kqwdU8VkdBKx56EYzXfpgnNPUAGznpicNiWfn'.
      

It is not recommended to use the same root key for multiple key types, so a different mnemonic and/or HD path combination should be used when generating a secp256k1 "did:key".

OpenPGP Keyring

OpenPGP Keyring

Keys can be exported from keyring and imported into wallets. Some transformation may be necessary.

          gpg --armor --export you@example.com > publicKey.asc
        

Mobile Wallets

Android Keychain

KeyChain keystore

Apple Wallet

Keychain Acccess wallet.apple.com

Google Wallet

wallet.google.com

Microsoft Wallet

wallet.microsoft.com

Cloud Secret Managers

Software services that support secret or key management are useful building blocks for cloud wallets.

Some services combine secret and key operations under the umbrella term "Key Management Service". Wallets may use both managed asymmetric and symmetric key operations, as well as managed and versioned secrets.

Acknowledgements

Portions of the work on this specification have been funded by the United States Department of Homeland Security's (US DHS) Silicon Valley Innovation Program under contracts 70RSAT20T00000003, and 70RSAT20T00000033. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.