Skip to content
twostacktwostacktwostack

Overlay networks

A full-history wallet holds the Transactions of one user. But many applications need to share Transactions between many users: the current state of a token, the hosts that offer a service, the listings in a marketplace. In the old model we would have asked an indexer. In this section we will look at how an index-free application does it instead: with an overlay network of domain-specific nodes, and with services that help wallets at the edge find and talk to each other.

Domain-specific nodes

Section titled “Domain-specific nodes”

Recall the Application-Specific API servers from 2020. They stored only the Transactions an application cared about, which was the right instinct. An overlay network takes that instinct further. It is a federation of nodes, run by different parties, that each keep the Transactions of one domain, and only those.

The BSV Association’s overlay services define how such a node behaves:

  • A topic manager (BRC-22) decides which Transactions belong to its topic. An application submits a Transaction to the overlay, and each topic manager admits the Outputs that follow its rules, e.g. “a valid message box host advertisement”.
  • A lookup service (BRC-24) answers questions about the admitted Outputs, e.g. “which host holds the message box for this identity key?”. The answer comes back with the Transactions themselves, so the application can check them.
  • SHIP and SLAP (BRC-88) let the nodes find each other. A node advertises which topics it hosts (SHIP) and which lookup services it offers (SLAP), as Transactions on the overlay itself. A client finds the hosts for what it needs by asking a SLAP tracker.
Above, an application asks SHIP and SLAP trackers which hosts serve a topic, submits a Transaction to one domain node and looks up from another; the domain nodes of one topic keep each other in sync. Below, Alice’s wallet leaves a BEEF on a Ricochet or MessageBox server, and Bob’s wallet collects it; the server offers mailboxes, documents, presence and relay.Overlay network: one topicCoordinating wallets at the edgeApplicationSHIP / SLAP trackersdomain nodedomain nodedomain nodeAliceBobRicochet orMessageBoxtopic manager, lookuptopic manager, lookuptopic manager, lookupmailboxes, documents, presence, relaywhich hosts?submit (BRC-22)look up (BRC-24)syncsyncleave BEEFcollect
Figure 1: An overlay network for one topic, and a coordination server between two wallets

There are a few interesting things to note about this model:

  1. Nobody holds everything. Each node holds only its topic’s Transactions, so running one is cheap, and anyone with an interest in the domain can run one.
  2. Nothing has to be taken on trust. A lookup answer carries the Transactions themselves, so the application checks them by SPV, as it would check a payment.
  3. The data sits at the edge, close to the applications that use it, instead of in one provider’s index of the whole blockchain.

Our libtokensv library includes an overlay client that finds hosts through SHIP and SLAP, looks up Outputs, and submits Transactions. SpiffyVault uses it to advertise its users’ message boxes, as PushDrop tokens on the tm_messagebox topic.

Transactions that prove themselves

Section titled “Transactions that prove themselves”

Some domains need even less than an overlay. A token whose Script checks the Transaction that spends it (a covenant, see Bitcoin Script) carries its own rules forward from one owner to the next. The lineage tokens in libtokensv work this way: a single Transaction at the tip proves the token’s whole history back to its issuance. The payee checks the token without asking any node about its past.

Coordinating wallets at the edge

Section titled “Coordinating wallets at the edge”

Full-history wallets live on phones, and phones go offline, change networks, and sit behind NAT routers. Wallets need somewhere to leave each other messages, publish small documents, and find out who is online. We use two kinds of store-and-forward server for this.

Ricochet

Section titled “Ricochet”

go-ricochet is our store-and-forward server for peer-to-peer applications, built on libp2p. It is modelled on email: messages are submitted, routed and delivered into mailboxes, and held there until the recipient comes online to collect them. A Ricochet server offers:

  • Mailboxes, private, shared or public, with access control, and end-to-end encryption between peers.
  • A document store, readable by any peer, for small documents such as profiles and payment anchors.
  • Feeds and collections, for append-only and keyed data.
  • Presence, so a wallet can tell whether a peer is online.
  • A relay, so two phones behind NAT routers can still reach each other, and connect directly where their routers allow it.
  • Discovery: servers announce themselves over GossipSub, so clients can find one.

SpiffyVault and OverNode use Ricochet to coordinate their wallets. A payee publishes a signed payment anchor as a document; a payer checks presence to choose between a live and an offline payment; a live payment travels through the relay when the two phones can’t reach each other directly; and an offline payment waits, encrypted, in the payee’s mailbox. You can read about these flows in Paying peer to peer.

MessageBox

Section titled “MessageBox”

MessageBox (BRC-33) is the BSV Association’s store-and-forward server for BRC-100 wallets. A wallet authenticates with its identity key, leaves messages in another identity’s message box, and collects its own. BRC-100 wallets use it to deliver PeerPay payments, and its hosts are found through the tm_messagebox overlay described above.

Ricochet and MessageBox play the same role, for two different families of wallets. Ricochet gives us the relay, presence and documents that phone-to-phone applications need, and MessageBox lets our wallets exchange payments with the wider BRC-100 ecosystem. SpiffyVault speaks both.