All Issues - Wallet Documentation

This issue is part of a series to demonstrate the wallets features.

Choosing Notaries

Wallet Howto 10 Choosing Notaries A5023d27b0e3fce3ee0b12b79e7e337ce 2014-11-06 10:39:50

So far we can verify the wallet by simply trying that the advertised logic works as expected. This could be enough to use it. In this issue we learn how to assert that there are no bad surprises lurking.

The wallet's balance (and other state) is kept in a simple SQL table. Without additional safeguards a single individual could tamper with it.

A consensus protocol is needed to assure both peers the other will not cheat, and to avoid having to route the transaction and trust fallible third parties with data.

Consensus Protocol

A popular coherence protocol these days is Bitcoin. The Bitcoin protocol ensures that C=everyone can verify the exchange. This makes it rather hard (though not completely impossible) to cheat. Unfortunately it's slow, expensive, requires an ever growing so called block chain and maybe A+B don't really need this much followers on their private business.

The better alternative is to mimic double entry bookkeeping.

Using pen and paper Alice and Bob would each keep their own books. Both Alice and Bob actively replicate the calculation: they archive their receipts and maintain their own idea of the balance. To avoid an ever growing archive they periodically verify consensus about the current balance. At this point old receipts can be safely thrown away. Thus Alice and Bob can reach consensus without having to trust any other party.

That's what we do. Just the verification period we use is rather short: just one transaction. The wallet will hold on receipts longer than technically required: until the user actually requests their disposal.

We need to introduce some terms here: The electronic equivalent the "pen and paper" is a device, e.g., a users smart phone including a software stack. We term it the "notary device", for short "notary", here. Alice and Bob's individual wallets are applications of the notary devices. Notaries can be designated and authorized to to broadcast input from a user. Notaries in this special role are called "representative devices" for that user.

Both Alice representative and Bobs representative maintain the whole wallet's SQL database for both their wallets (so in practice this might be just the wallet Alice uses to send to Bob and vise versa). They will allow Alice's representative to control Alice's wallet and Bobs representative to control Bobs wallet only.

As long as Aice and Bob continue to act benevolent it should be possible to agree that both know precisely who owns how much of the asset.

Except that is is not that easy. If the connection is gone, you can't send your order. The scientist in you might dive deeper into the topic to learn: this leads to cases which can not be resolved without human intervention. Adding that notary devices may not follow high security standards, factoring in honest mistakes and assuming benevolence and veracity may not be given we skip a few steps for laziness and learn: we need at least five notaries to reliably audit the balance. The solution is known under the name "byzantine fault tolerance" thanks to Leslie Lamport's work. (Remark: byzantine consensus itself requires only four notaries for one faulty; but groups of four degrade badly on the second failing.)

Commissioning Notaries

Users express their preference wrt. trust, privacy and reliability by adjusting the set of notaries commissioned to audit their wallets.

The wallet's menu has an entry Notaries which has two sections. (Tab the titles to open them.)

Note: At the time of writing this tab is seen as subject to further development. Please bear with me. The screen shots look terrible.

Notaries are identified by the license to use the device; see also "social support contracts".

The first section allows to attach human readable nick names to the OID's of notaries. This is pure convenience for the wallets user and has no technical use.

screen shot

The second section lists all notaries commissioned to the wallet and enables two operations:

  1. Enable one more: enter the OID and submit.
  2. Switch one off: push the Off button next to the entry.

screen shot

Note that the "wallet skin" should notify the user that expansion of the notary set is not allowed when the wallet has a positive balance for any asset. This restriction was introduces to enforce the check against sybil attacks. See below.

Users learn about usable notaries usually from the audit record in messages and contracts. This is a manual process for now and normally includes additional conversation to inform the user about the security assumptions for the device.

What Is Sybil?

A sybil attack is an attempt to cheat on a group of notaries by providing fake evidence approved by a large enough group of "sock puppet" - notaries under control of the attacker.

This is not an issue for our wallets. As we've seen it is precisely clear which notaries audit which wallet.

When a message is sent from Alice to Bob, her wallet will commission the all notaries of her wallet and all of Bobs wallet to her it. This assures that those message will be deliverable to all relevant notaries but no others.

But what if there is in incoming order claiming a large set of notaries having audited it but Bob does not trust any of them? Bob does not want to accept it.

The underlying replication protocol in BALL can not simply reject such messages since the decision depends on the application semantics.

Therefore the wallet must account for this case. Beware: currently it will reject all possibly sybil orders.

The predicate we are currently using might not be the final one: we classify as possibly sybil according to the relationship to the applicable ricardian contract since the latter is supposed to define the instrument and the managing parties. If size of the notary set of the incoming message exceeds double the size of notary set commissioned to audit the asset, it is possibly sybil. This leaves control of the notary set to 50% into the hands of the issuer. Enough to block fraudulent orders but not enough to create them.

Nevertheless will obviously lead to situations where Bob does not share enough notaries with an instrument to receive an order. The only way to transfer a value among them in this situation is to create an intermediate wallet acting like an exchange. This intermediate would hold the foreign instrument and issue derived instrument within a notary set compatible to Bob.


  1. A0cd6168e9408c9c095f700d7c6ec3224
  2. Abb8999dd38524dcc113f977d378a9ee0
  3. A0cd6168e9408c9c095f700d7c6ec3224
  4. Abb3867b74214ac915c93f1b9f5a0dd10
  5. Aa46397453362cbdab9c90582a315a03b

Don't care too much about typos etc. in these memos: those can not be updated anyway.