Skip to content
Create a gist now

Instantly share code, notes, and snippets.

"Shared" wallets : design straw-man


Make it easy for end-users to use multi-signature transactions to more securely spend and store their bitcoins.

Identify what infrastructure needs to be built, what existing infrastructure can be re-used, and agree on an interoperable standard so users running different Bitcoin clients can cooperate to create multi-signature wallets and create multi-signature transactions.

User experience

I've created a mockup of a GUI for two use cases:

  1. A corporate wallet controlled by more than one person, that requires multiple approvals for spending.

  2. An individual's wallet that requires second-device authorization on their smart phone for any spending.

Before reading further, please visit to see the GUI mockup.

Creating a Shared Wallet

The first step is to create a shared wallet, specifying who will be involved and how many signatures are required to spend from the wallet.

Is "Shared Wallet" the right metaphor?

I use the term "shared wallet" to mean: one or more multisignature bitcoin addresses that can receive funds and whose private keys are distributed to more than one person or device.

Perhaps "joint account" or some other banking term would be better.

Participant identity

Identifying who is involved in the transaction is a key piece of the GUI. I've used email addresses throughout the mockup, which I think are the most obvious way of identifying users.

I think other possible unique identifier (e.g. GPG key fingerprint or mobile phone number or bitcoin address) is either too esoteric or too difficult for users to recognize.

Participant messaging infrastructure

I assume that participants (people or devices) are not constantly connected to the network. That implies there must be some kind of messaging infrastructure that stores messages and delivers them to participants when they are online.

There are at least three separate (but related) design issues:

  1. How are messages stored and delivered?
  2. How are messages encoded?
  3. What is the set of messages?

Message storage and delivery

Perhaps the biggest design decision is whether to extend the Bitcoin peer-to-peer network protocol to support storage and delivery of messages, or to use something else.

I'm proposing that we use something else: the email system that is already universally deployed and that we all use every day. Pros and cons of the alternatives follow:

XMPP (Personal Eventing), AMQP, STOMP, FreeNet, etc

These are all messaging standards that could be used. AMQP is big, complicated, and XML-based. XMPP is big, complicated, XML-based, and focused more on real-time messaging than the "anytime in the next couple of minutes" messaging that will suffice for shared wallets.

Minimizing the amount of code pulled in to a bitcoin client to support shared wallets is a high priority.

STOMP is nice and simple, but fairly new and not widely adopted. It might not be around in a few years.

Extend the Bitcoin p2p protocol

Creating a p2p solution that runs over the Bitcoin protocol is appealing, but designing a robust p2p messaging system is hard if you assume that attackers will try to flood it with messages, might mount a Sybil attack to drop or delay messages, etc. And even assuming that the DoS issues can be addressed, if we are relying on Bitcoin network nodes to store messages for nodes that are not currently online, we have to worry about incentives for nodes to store the messages (are they paid somehow?), total message capacity across the network and reliability if not all nodes try to store all messages.

At this point in time, designing such a system feels like a great research project, not a solution ready to be used.


Good old-fashioned email has well-defined standards (SMTP, POP, IMAP) and a worldwide, well-supported messaging infrastructure already in place. Every programming language already has libraries available for dealing with email, and it is not hard to find programmers who know how to write code to fetch or send email.

If we required consistent delivery of messages in less than 60 seconds then email would be the wrong choice, because email servers are not designed for instant communication.

The only other major issue I see with using email as the communication mechanism is a practical one: if we send messages via the user's main email address, then machine-to-machine communications might clutter up their inbox, and we might open up a security hole if the machines fetching or sending email have access to the rest of the user's email messages.

Both of these issues can be solved with bitcoin-communication-dedicated email addreses, although I think in the short term users will simply trust their bitcoin wallet to have access to their inbox and will use filters so shared wallet messages are shunted into their own folder that the user will ignore.

(Note: there is a proposed IMAP standard for authorizing access to only certain email folders, which combined with auto-filtering would also be a good "least authority" solution).

Message encoding

Deciding on a message encoding is basically a religious decision; any encoding could work. Likely candidates:

Bitcoin network serialization : Advantages: all bitcoin clients already have code to encode/decode, and it minimizes data size. Disadvantages: harder to debug (because it is binary), non-standard outside the Bitcoin world.

JSON : Advantages: most bitcoin clients already use JSON for something, libraries for reading/writing available in every programming language, human-readable and simple. Disadvantages: larger message size.

Protocol buffers : Advantages: minimizes data size, easily extensible, "the specification is the code". Disadvantages: harder to debug, not an Official Standard, added dependencies (or more compiled-in code) to encode/decode.

PKIX text encoding : Advantages: X.509 certificates and other security-related stuff are already encoded this way. Disadvantages: Not an Official Standard yet, introduces another way to encode data (base64).

I plan to prototype a shared wallet using JSON.


Plan: create another document with detailed spec for messages needed to support the workflow in the GUI mockup.

Discuss bigger issues here, like "must add participant be done before create shared wallet", or "once a transaction approval has been sent, does the initiator have a chance to cancel it?"


Security Discussion

How much can we or should we rely on the existing messaging infrastructure (email) to provide some security?

Example: if '' gets a message from '' (which is hosted by Google Apps on the gmail infrastructure), I can be very close to 100% confident that the message has not been tampered with by a man-in-the-middle (because I am very close to 100% confident that Google does not have a rogue employee tampering with internal email messages).

Even so, it is very possible somebody managed to compromise the '' email account and/or the associated wallet keys.

The risk is not that a man-in-the-middle sends bogus transaction signing requests; the risk is that a request to spend sends funds to an attacker instead of to where they are supposed to be sent.

Therefore, it is critical that when funds are sent users have some way of verifying that they are actually being sent to the correct place. Bitcoin addresses are not a good way to verify that funds are going to the correct place, but they are all we have right now. In the short term, warning users to double-check the addresses of large transactions (via phone call or SMS or some other, non-email channel that you can assume an attacker has not compromised) is a reasonable solution.

In the medium term we need a new, widely supported payment protocol that supports authentication of addresses (that is, verify that a bitcoin address belongs to some human-recognizable identifier like "Bitcoin Foundation "). That is another specification.

evbogue commented Nov 17, 2012

For messaging is 0mq what you might be looking for?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.