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.
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.
Several organizations have published guidance on digital wallets.
European Digital Identity (EUDI) Wallet Solution
Electronic Signatures and Infrastructures (ESI)
Department of Homeland Security (DHS) Science and Technology Directorate (S&T) Silicon Valley Innovation Program (SVIP)
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.
There are many different kinds of digital wallet. This section describes a few distinguishable categories.
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 (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 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 (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.
The following terms are used to describe concepts involved in the universal wallet.
The following sections describe how a wallet controller can define relationships with external systems.
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".
Keys can be exported from keyring and imported into wallets. Some transformation may be necessary.
gpg --armor --export you@example.com > publicKey.asc
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.
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.