Multisig transactions with MMS and CLI wallet

Diese Seite ist noch nicht übersetzt. Wenn du uns mit Übersetzungen unterstützen möchtest, schau bitte hier README.

Multisig Transactions with MMS and CLI Wallet


This manual describes the Multisig Messaging System, abbreviated as MMS. It's a system that aims to simplify multisig transactions for Monero and similar CrypoNote-based cryptocurrencies by making it easy to exchange info like key sets and sync data between wallets and by offering some "workflow support" guiding you through the various steps.

The MMS so far presents itself to the user as a set of new commands in the CLI wallet. This is not surprising, as currently the CLI wallet is the only way to do multisig transactions interactively anyway. Hopefully this will be extended in the future; the MMS was designed with other wallets like e.g. the Monero GUI wallet in mind.

This manual has some tutorial-like aspects and is intended to be read in sequential fashion, best without skipping any chapter before chapter The Commands in Detail.

If you have high requirements regarding security and are not sure whether using the MMS is acceptable for you in the first place, you may read the chapter Security first.

This first version of the manual was written around year-end 2018 by René Brunner (rbrunner7), the original author of the MMS.

Monero Multisig in a Nutshell

Probably it will be pretty hard to understand the MMS without at least a basic grasp of how Monero multisig transactions work in principle. Here a short overview together with info about the terminology that this manual uses; for more details and more technical explanations you will have to look elsewhere.

Multisig means that a transaction needs multiple signatures before it can be submitted to the Monero network and executed. Instead of one Monero wallet creating, signing, and submitting transactions all on its own, you will have a whole group of wallets and collaboration between them to transact.

In this manual those wallets, or if you prefer, the people controlling them, are called authorized signers. Depending on the type of multisig used, not all authorized signers need to sign before a transaction becomes valid, but only a subset of them. The corresponding number (which is equal to or smaller than the number of authorized signers) is called required signers.

The usual notation in use here is M/N, with M standing for the number of required signers, and N standing for the total number of authorized signers. For example, probably the most useful and most popular type of multisig is written as 2/3: Out of a total of three authorized signers, any two are needed to make a transaction valid.

For technically "simple" coins like Bitcoin and its forks doing multisig transactions consists of the following steps:

  • Configure the multisig wallets and establish the multisig address
  • Fund the multisig wallets / the multisig address so there is something to spend in the first place
  • Do as many multisig transactions as you like

Monero adds one more type of step, necessary for internal bookkeeping so to speak. Simply told all the mechanisms that make Monero transactions truly private complicate things and lead to a necessity to exchange information between wallets to enable them to correctly process transactions, both incoming and outgoing.

The MMS uses the term syncing for the process to making wallets ready to transact again after sending or receiving transactions, and multisig sync data or simply sync data for the information that has to be exchanged to achieve that.

So the steps for Monero multisig look like that:

  • Configure the multisig wallets and establish the multisig address
  • Fund the multisig wallets / the multisig address so there is something to spend in the first place
  • Sync the wallets for a first time
  • Do 1 multisig transaction
  • Sync the wallets again
  • Do another multisig transaction and/or receive more funds
  • Sync the wallets yet again

The "value" of the MMS is making it easy and painless to exchange all those data packets between the wallets, and telling the signers at which point of the "workflow" they currently are and what has to be the next action in order to proceed.

The Architecture of the MMS

The MMS basically has 3 parts:

  • A set of new commands in the CLI wallet
  • A running instance of PyBitmessage reachable from the computer running the CLI wallet, doing message transport on behalf of the wallet
  • Internal code extensions to wallet code managing a new .mms file per wallet with the messages in it and interfacing with PyBitmessage

PyBitmessage is currently the only supported program for message transport, the MMS won't "speak" to any other system. You can't use e-mail nor any other of the myriad of communication programs out there. If you don't like PyBitmessage or can't run it for any reason you won't be able to use the current version of the MMS.

The author of the MMS hopes that you will give it a try: PyBitmessage is fully open source, is under continued development, has enough users to almost assure message transport at any time, and takes privacy very seriously - just like Monero.

Hopefully a future MMS will build on Monero's "native" private communication system, Kovri, but we are probably still quite some time away from a Kovri release ready for broad use.

MMS communications should be safe: The Bitmessage system is considered safe as it's completely invisible who sends messages to whom, and all traffic is encrypted. For additional safety the MMS encrypts any message contents itself as well: Nobody except the receiver of an MMS message can decrypt and use its content, and the messages are signed, meaning the receiver can be sure they come from the right sender.

The MMS User Experience

To see the "user experience" of multisig in the CLI wallet without MMS you can e.g. check here and here.

Those pages are also useful to familiarize yourself with the steps for multisig transactions in general, as the MMS will not change the order of the steps or make any of them superfluous, but will just make execution considerably easier, and the MMS will be able to tell you the next step in order automatically in most cases.

A Messaging System

The general approach of the MMS is very similar to e-mail: You send messages around, with the MMS command set in the CLI wallet playing the part of your e-mail client, allowing you to send messages, receive messages and manage a list of stored messages, something like a combined inbox and outbox.

The contents of those messages are of course all those things that must be transported between the wallets of the signers: key sets, wallet sync data, transactions to sign and/or submit to the network.

PyBitmessage is used for the actual message transport and thus plays the part of your e-mail server. Once configuration is done sending and receiving messages is fully automatic i.e. needs no manual intervention.

You don't use e-mail addresses, but Monero addresses to tell where messages should go, and you only ever send messages to other authorized signers: E.g. with 2/3 multisig you only have 2 partners to send something to.

Like with e-mail people don't have to be online at the same time for message transport to work: PyBitmessage will keep messages for up to 2 days, giving you time to fetch them.

The approach is in general quite flexbile and robust: If you need messages from several signers to proceed the MMS will wait until it finds all of them in the list of received messages, and the order of reception does not matter either, which results in a quite unstressed experience.

If another signer tells you that a particular message did not arrive or was lost somehow you can send it again anytime, picking it from the message list, like you would re-send an e-mail in a similar situation.

Signers and Messages

So, where a "normal" Monero wallet without MMS simply told manages three types of data (addresses, accounts and transactions), the MMS adds two more: Signers and messages.

The MMS manages, for each multisig wallet separately, a list of authorized signers. With 2/3 multisig that list has three entries. On a technical level, each entry represents a Monero wallet containing keys that can be used to sign multisig transactions. On a conceptual level it's easier to imagine a group of 3 people, i.e. yourself and 2 partners, as those "authorized signers". (Often there will be indeed 3 distinct people controlling the 3 wallets, but not always of course.)

The MMS also manages a single list of messages per wallet: All messages you send, plus all messages you receive. While the list of authorized signers is the same in all involved wallets, those messages of course differ. The more authorized signers there are to send you messages, and the longer you transact, the more messages will accumulate.

Getting the MMS

Right now, at the time of writing this manual (year-end 2018), the MMS is only available as part of the latest Monero code (master branch on Monero's GitHub repository). To use it, you have to check out that source code and compile it yourself. Doing so is easiest on a Linux system.

With the next hardfork in Spring 2019 the MMS will become an integral standard part of the Monero software: You install Monero, you have it.

A word of caution: At the time of writing using the latest development Monero version does not lead to conflicts and complications with any regular Monero release software and downloaded blockchain on the same system, but that may change between now and the hardfork, especially near the hardfork.

Installing and Configuring PyBitmessage

Installing PyBitmessage is easy enough: You find links to downloads and install instructions from the Bitmessage Wiki homepage. There are versions for all the major OS that Monero also supports: Linux, Windows, and macOS.

After installing run it, configure a Bitmessage address for you and note it, as you will later need it to configure your multisig wallet.

Don't worry right away if PyBitmessage does not seem to connect to the Bitmessage network when you run it the first time: Due to the decentral nature of that network it can take quite some time for your initial connect. It seems this often takes half an hour.

Likewise sending the very first message to a brand-new Bitmessage address can take time because there is a key exchange involved, sometimes another half of an hour. Once the key exchange is done messages are typically delivered within a few minutes however, sometimes within seconds.

You don't need to configure more than one Bitmessage address for you. You can run several multisig wallets over a single address without any problems because the MMS will be able to pick the right messages for the right wallets. You can even continue to use the same address for "normal" messages; those won't disturb the MMS, it will simply ignore any messages not intended for it.

Out of the box your PyBitmessage installation is not yet ready for use with the MMS because it does not allow other programs to use its API per default, you have to enable this explicitely (which makes sense, of course, for security reasons).

You find instructions how to enable the API on the Bitmessage wiki API reference page. You will use the user name and the password you choose here later as command-line parameters for the CLI wallet so that the MMS will be able to log in to PyBitmessage.

Further PyBitmessage Tweaks

The current official release version has a Dandelion++ protocol extension built-in that hardens the network further against attacks that try to track message flow to find out who sends messages to whom. Unfortunately it seems that it has still a bug somewhere that can lead to wildly differing and very long message transmission times which is quite unfortunate when using the MMS.

There is a way to switch off Dandelion++ which, in general, is not recommended of course, but useful for using the MMS as of now:

  • Locate PyBitmessage's config file keys.dat
  • Make a new section there named [network]
  • Add the following line to this new section: dandelion = 0
  • Restart PyBitmessage

As a "good citizen" you may consider to open your PC for access from other Bitmessage nodes to your node from the outside by opening port 8444. You find background info about that in their FAQ. It's not strictly necessary however for your client to function.

MMS Command Overview

There is only one new command in the CLI wallet that gives access to the MMS, sensibly called mms. That command has however quite a number of subcommands to handle all the various functions of the MMS. Here a list of the commands; for details each command has its own chapter later in the manual:

init        Initialize and configure the MMS
info        Display current MMS configuration
signer      Define a signer by giving a single-word label, a transport address, and a Monero address, or list all defined signers
list        List all messages
next        Evaluate the next possible multisig-related action(s) according to wallet state, and execute or offer for choice
sync        Force generation of multisig sync data regardless of wallet state, to recover from special situations like "stale data" errors
transfer    Initiate transfer with MMS support; arguments identical to normal 'transfer' command arguments, for info see there
delete      Delete a single message by giving its id, or delete all messages by using 'all'
send        Send a single message by giving its id, or send all waiting messages
receive     Check right away for new messages to receive
note        Send a one-line note message to a signer, identified by its label, or show all unread notes
show        Show detailed info about a single message
export      Export the content of a message to file
set         Set options, 'auto-send' being the only one so far

start_auto_config   Start the auto-config process at the auto-config manager's wallet by creating new tokens
auto_config         Start auto-config by using the token received from the auto-config manager
stop_auto_config    Delete any tokens and abort an auto-config process
send_signer_config  Send your complete signer configuration to all other signers

You get the list of commands by issuing help mms, and help for a particular subcommand by using help mms <subcommand>, e.g. help mms next. You can alternatively use mms help <subcommand> if that feels more natural.

Configuring a Wallet for Use with the MMS

Addresses and Labels

First for better understanding some basic facts about addressing and referring to signers (or their wallets respectively) in the MMS:

If you create a new wallet it gets (of course) its own, unique public Monero address. If you later configure the wallet for multisig, the wallet changes its public address to the common multisig address that you share with all the other authorized signers.

The MMS uses the first, "original" public Monero address over the whole wallet lifetime for addressing, before and after "going multisig". It may be a little confusing that a wallet should have two public addresses somehow, but once you got the original address into your signer configuration you can more or less forget about it.

The MMS uses labels that allow you to name yourself and the other signers, and that the MMS commands use when referring to signers. (Using Monero addresses or Bitmessage addresses in such commands would be quite cumbersome.)

Labels must be one word, and they must be unique within a single wallet. The example later on in this manual uses the labels alice and bob for a case of 2/2 multisig.

Running CLI Wallet

When you start the CLI wallet for use with the MMS there are the following two new (optional) command line parameters for connecting to PyBitmessage:

--bitmessage-address	Use PyBitmessage instance at URL <arg>
--bitmessage-login		Specify <arg> as username:password for PyBitmessage API

If you have PyBitmessage running on the same machine as the CLI wallet the default for the first parameter will do, and you should not need to set anything different. If it does not seem to find it despite running locally try to use http://localhost or as argument for the first parameter.

Beside that, you need of course either --testnet or --stagenet to connect to the right network. Also using --log-level 0 could be useful: This instructs the wallet to write detailed info into its logfile that might help to find bugs or problems with the MMS.

So a complete command line for the CLI wallet could look like this:

./monero-wallet-cli --testnet --bitmessage-login mmstest:p4ssw0rd --log-level 0

Initializing the MMS

After creating a new wallet you have to initialize it for use with the MMS; without that crucial first step you won't be able to use any MMS features. The command to do so is mms init:

mms init <required_signers>/<authorized_signers> <own_label> <own_transport_address>

own_transport_address is the Bitmessage address that you configured in your own PyBitmessage program. A full init command could look like this:

mms init 2/2 alice BM-2cUVEbbb3H6ojddYQziK3RafJ5GPcFQv7e

Use that init command only once: Executing it a second time will completely re-initialize the MMS by deleting any signer info and any messages, which you don't want except in special circumstances.

If you want to go through a MMS test as fast as possible you can instruct the wallet to ask for the password only when strictly necessary for technical reasons, and tell the MMS to send any generated message right away instead of prompting before doing so:

set ask-password 0
mms set auto-send 1

(Both those settings are active during the 2/2 multisig example shown in this manual.)

Configuring Signers

About each signer the MMS needs to know three things:

  • The one-word label that you will use to refer to that signer
  • The transport address which currently means their Bitmessage address as long as this is the only supported message transport system
  • The Monero address i.e. the "original" Monero address of their wallet

(See also above chapter Addresses and Labels.)

You don't have to create signers; after the mms init command they are already all "there", although without any info yet with the exception of yourself. The commands for setting signer information refer to them by number, 1 up to the total number of authorized signers, so 1 and 2 in the following 2/2 multisig example with signers named Alice and Bob and thus with the labels alice and bob.

After the above sample init command the list of signers looks like that:

 # Label                Transport Address
   Auto-Config Token    Monero Address
 1 alice                BM-2cUVEbbb3H6ojddYQziK3RafJ5GPcFQv7e

 2 <not set>            <not set>
                        <not set>

Note that signer #1 is always "me" i.e. your own label, transport address and Monero address. So in Alice's signer list #1 will be Alice and #2 will be Bob, while in Bob's wallet it will be exactly the other way round.

There are three ways to complete signer information: You can enter it manually, or you can use the auto-config mechanism that the MMS offers, which has a second, "semi-automatic" variant. With 2/2 there is hardly a difference in effort, but with higher numbers of signers auto-config is easier and more reliable. In any case, one advantage of auto-config is a secure transport of addresses because PyBitmessage is used.

So pick one method from the three following chapters Manually Configuring Signers, Auto-Config and Sending Signer Information:

Manually Configuring Signers

The command to manually enter signer info and display the list of signers is mms signer:

mms signer [<number> <label> [<transport_address> [<monero_address>]]]

Without any argument the command displays the list of signers. With at least a number and a label you can set or change info about a particular signer. A full command to set everything about signer #2 could look like this:

mms signer 2 bob BM-2cStcTfCx8D3McrMcmGZYZcF4csKcQT2pa 9yXKZ6UUdd8NnNN5UyK34oXV7zp7gjgZ4WTKHk8KzWsAAuyksfqoeRMLLkdWur85vnc1YL5E2rrMdPMHunA8WzUS9EL3Uoj

A command to later change only the label of signer #2 could be:

mms signer 2 bob-the-builder

With this manual method it's up to the signers how they all get to know each other's addresses.

Be careful while entering signer information: Any mistakes like wrong Bitmessage addresses will probably make it impossible to correctly transact later on.

Before you go out and start to exchange signer information over insecure channels like IRC or plain unencrypted e-mail, please note that there are certain dangers in doing so. If somebody can e.g. intercept your e-mails and get hold of your addresses that you send to a signer that person can then impersonate the signer.

There is also the danger that in a 2/3 multisig scenario for escrow signer Bob can set up a second wallet for the trusted third-party Trent beside his own and trick Alice into sending everything to that wallet instead of Trent's. After this Bob will be able to transact alone and steal coins from Alice.

You find a more detailed explanation of this second danger in chapter Security towards the end of the manual or here. Auto-config mitigates this danger to quite some extent.

Alice's complete signer list looks like this:

 # Label                Transport Address
   Auto-Config Token    Monero Address
 1 alice                BM-2cUVEbbb3H6ojddYQziK3RafJ5GPcFQv7e

 2 bob                  BM-2cStcTfCx8D3McrMcmGZYZcF4csKcQT2pa


MMS auto-config is based on so-called auto-config tokens. Such tokens are always 11 characters long, the fixed string "mms" followed by 8 hexadecimal digits. Examples for such tokens are mms561832e3eb and mms62cb2b87e2.

The basic trick: Unlike Bitmessage addresses and Monero addresses those tokens are short enough to type them easily and e.g. use reasonably safe smartphone messenger apps or SMS to transmit them, or dictate them over the phone, again not perfectly safe, but still much safer than plain e-mail or IRC.

The workflow is as follows - it's simpler than it looks at first sight, go once through it in practice and it makes sense:

  • One signer takes on the job to lead and organize configuration, furthermore called manager
  • The manager assigns a label to each signer and enters all labels into the signer configuration, either using mms signer commands or giving them as arguments of the mms start_auto_config command in the next step
  • The manager uses the command mms start_auto_config to generate auto-config tokens for all other signers, one distinct token per signer
  • The manager transmits the tokens to their respective signers outside of the MMS
  • All other signers enter their token with mms auto_config <token>
  • Their wallets will generate messages that send their addresses to the manager's wallet, already using PyBitmessage
  • As soon as all those messages arrive there the manager can in turn send messages to all other signers containing the complete signer information by doing mms next
  • The other signers process those messages to complete their signer information with mms next

Several points are noteworthy here. Manual configuration with e.g. 5 signers could mean 5 times 4 = 20 initial manual information transfers, if each of the 5 signers sends addresses to 4 others. Even a more clever approach with someone collecting all addresses first and sending the complete list to all others then would take 4 plus 4 = 8 information transfers. With auto-config there are only 4 such manual transfers - 4 tokens from the manager out to the other signers; after that point it's already messages over PyBitmessage.

You may wonder how the other signers' wallets can send their Bitmessage addresses back to the manager by using PyBitmessage. Doesn't this snake bite its own tail? The solution: A temporary, "throw-away" Bitmessage address is derived from each token and used just for this transfer, and temporary keys are derived as well for encrypting message content.

Part of the increased safety of the auto-config process is the fact that each signer gets its own, distinct token. In 2/3 multisig, just make sure Bob cannot get hold of Trent's own token, and already Bob has no way to "play" Trent and set up a second wallet to be able to sign transactions all on his own.

Sending Signer Configuration

Beside full auto-config there is a second, alternative way to make configuration easier, based on a command called send_signer_config. It's less "automatic", but you may prefer it because it's more transparent what happens.

Here the workflow is as follows:

  • One signer takes on the job to lead and organize configuration, furthermore called manager
  • The manager receives from all other signers their addresses over channels outside the MMS, e.g. encrypted and signed e-mail
  • The manager enters complete signer information into their wallet, using mms member commands
  • The manager uses the mms send_signer_config command to send the completed information to all other signers
  • The other signers process the messages containing signer information with mms next

For all signers except the manager this is nearly as comfortable as auto-config. Note however that the security of the scheme depends on securing the sending of info to the manager: If some signer can posit as not only themselves, but as other signers as well, they will be able to control several wallets and undermine the whole signing process. (See also chapter Manually Configuring Signers for more about such dangers.)

Establishing the Multisig Address

In general, there are no MMS commands to execute particular steps regarding multisig transactions (with the exception of starting a transfer using mms transfer and force sync with mms sync). You just use the mms next command, and the MMS will do whatever is next in the "multisig workflow", and if nothing is ready, e.g. because some messages are still missing, will tell you the reason why nothing is "next" yet.

So, after you completed the info about all signers, either manually or through auto-config, you just issue a mms next command, and the MMS will start with the first step needed to establish the multisig address: Calculate key sets for all coalition members and set up messages to send those to them. The whole scene might look like this for Alice:

[wallet A1VRwm]: mms next
Send this multisig info to all other participants, then use make_multisig <threshold> <info1> [<info2>...] with others' multisig info
This includes the PRIVATE view key, so needs to be disclosed only to that multisig wallet's participants 
  Id I/O  Authorized Signer              Message Type           Height   R Message State   Since                                   
   1 out  bob: BM-2cStcTfCx8D3McrMcmGZ.. key set                     0   0 ready to send   2018-12-26 07:46:21, 1 seconds ago      
Queued for sending.

The prepare_multisig output there is a hint that the MMS works by putting something like a "wrapper" about the CLI wallet pepare_multisig command, it even displays the MultisigV1 string for confirmation. Now you don't have to send that manually to the other signer somehow: The MMS prepares a message for that and sends it in a fully automatic way.

After Alice receives Bob's key set, another mms next command will process it and establish the multisig address:

[wallet A1VRwm]: mms next
Wallet password: 
2/2 multisig address: 9uWY5Kq6XocGGqUByp22ty4HYxj4CfjCXdRrZ24EKvYW2U7fudSzCvTRRT35tMNx5heQfqKmVmFjahWUZ1BENnzH8UvyVF7

The wallet may be "out of sync" after this step; if yes, just do a quick refresh.

In the case of non-symmetrical M/N multisig, with M different from N, like e.g. in 2/3, it's not enough that each signer sends one key set to every other signer: There will be several rounds of key set exchanges. However the MMS knows about this and will automatically take care of almost everything: For a particular wallet it waits until the key sets of all other signers have arrived before going on. If there is another key exchange round necessary, mms next will then start a new one. If not, the command will process the last key set(s) and establish the multisig address.

It's possible that a future enhanced version of the MMS will do this in a fully automatic way, i.e. sending all necessary key sets around without further intervention until the multisig address is configured. For now however you have to push things along yourself by issuing mms next commands.

Funding the Multisig Wallet

With the multisig address established the wallet is now ready to receive funds. Here the MMS plays no role, nor does multisig in general: Just transfer some coins to the address, to have something to transfer out later, and wait until they arrive.

Syncing Wallets

Every time after receiving or sending coins multisig wallets must exchange some info with each other to get "into sync" again. That's the case whenever the CLI wallet tells you about partial key images like in this balance command output:

[wallet 9uWY5K]: balance
Currently selected account: [0] Primary account
Tag: (No tag assigned)
Balance: 7.000000000000, unlocked balance: 7.000000000000 (Some owned outputs have partial key images - import_multisig_info needed)

That "import_multisig_info needed" thing is perhaps the single most tiresome aspect of CryptoNote multisig transactions and quite some work e.g. in the case of 3/3 or 2/3 multisig where already a total of six pieces of information must be passed around each time, only to finalize reception of some coins and/or being able to transfer again after a transfer.

At least, with the MMS, it's only a case of issuing mms next commands until all sync data is sent and received and the wallets get into sync again: It guides you automatically through the necessary export_multisig_info and import_multisig_info commands. Here again how