User Tools

Site Tools


This is an old revision of the document!


Rhizome is the resilient file distribution system developed by The Serval Project. It forms the basis of all non-connection-oriented services provided by Serval Mesh, such as text messaging, file sharing, voice mail, and automatic software upgrades.

Purpose and features

  • Rhizome is a store and forward service for transporting units of data called payloads (“files”) between applications running on nodes in a digital telecommunications network
  • Rhizome is designed for wireless mesh networks such as MDP in the Serval Mesh, but can also be used within a fixed network infrastructure
  • Rhizome guarantees that payloads will remain intact wherever they are transported
  • Rhizome makes no guarantees about delivery time or eventual arrival
  • Rhizome makes its best effort to transport payloads to wherever they are wanted, subject to the constraints of the network (topology, bandwidth) and its nodes (storage, battery), without favouring any payloads above others of equal kind
  • Rhizome is neutral with respect to originating and receiving nodes, applications, and payload content
  • Rhizome uses cryptography to preserve the integrity and privacy of payloads
  • Rhizome protects anonymous senders by not storing or transmitting information that may allow senders to be traced, even on the originating device
  • Rhizome functions without centralised infrastructure such as well-known servers or a persistent network connection
  • Rhizome can be configured to use central servers to improve efficiency and reach

Rhizome applications

  • Users do not use Rhizome directly, but indirectly via applications which use Rhizome as their data transport
  • Current Rhizome applications:
    • MeshMS, the simple text messaging service of the Serval Mesh app for Android
    • Serval Maps, an Android app produced by the Serval Project, uses Rhizome to share geo-tagged data like photos and documents
    • the Serval Mesh app for Android uses Rhizome to distribute software upgrades
    • the file sharing service of the Serval Mesh app for Android is a simple UI for sharing, browsing and saving/viewing non-MeshMS content in Rhizome
    • Serval SAM is a crowd survey app for Android that allows the user to fill in an Open Data Kit form and uses Rhizome to transport completed forms to a central collection server
    • Sensor Logger, an Android app produced by the Serval Project, uses Rhizome to send continuous accelerometer logs to the Serval HQ central collection server
  • Future applications may include:
    • voice mail
    • disaster response situational awareness
    • medical or environmental sensor data collection
    • collaborative text editing and whiteboarding
    • distributed document management
    • citizen journalism
    • classroom and remote teaching tools
    • group chat
    • Wikipedia caching
  • Applications inject data into Rhizome by supplying a payload and some meta data
  • Applications extract data from Rhizome, receiving the payload and all meta data

Rhizome's data model

Every Rhizome payload (“file”) is accompanied by some structured meta data called a manifest:

  • some meta data is supplied by the originating application to accompany the payload, but is not used by Rhizome, eg, File name, Content MIME type
  • some meta data is created and used by Rhizome to identify, prioritise, route and expire the payload, eg, Bundle ID, Bundle Version, Payload size, Payload hash (digest)
  • some meta data is supplied by the originating application and is used by Rhizome to prioritise, route and expire the payload, eg, sender and recipient Serval Identities, Journal head, Bounding circle, Lifetime

A Rhizome bundle = manifest + payload

Rhizome manifest

The Rhizome manifest is a set of key-value pairs called fields, A manifest is stored and transmitted in either text or binary representation:

  • The text manifest is the original implementation
  • The original text format used US-ASCII character encoding and may be upgraded to Unicode UTF-8 when needed
  • The binary manifest is not yet implemented
  • Here are some sample (historical) implementations of the text manifest from Serval Mesh release 0.90 "Shiny":
  • An example of a text manifest:
  • Every manifest contains one or more cryptographic signatures to prevent tampering
    • Rhizome nodes will reject manifests with no signature or a signature that does not verify
    • Only the original creator (author) of the manifest may possess the signing key, so is the only party able to modify the manifest (publish newer Bundle Versions with the same Bundle ID)
Backward and forward compatibility

Both Rhizome manifest representations (text and binary) are designed to allow upgrades.

Forward compatibility arises from an extensible manifest data format that allows unrecognised fields to be skipped:

  • The text manifest uses a special field delimiter (newline) that cannot appear in any field value
  • The binary manifest stores the length of every field
  • Every Rhizome node uses only the manifest fields it recognises and successfully parses, and ignores any it does not (possibly logging a warning)
  • Every Rhizome node always stores and transmits the manifest intact, without modification, including any unrecognised fields

Backward compatibility is done using a standard replace/deprecate/delete process:

  • The format and meaning of existing fields is never changed
  • Software upgrades may introduce a new field that can coexist with the older field(s) it supercedes
  • For a while, software upgrades create manifests containing the deprecated field and the newer field
  • Eventually a software release and all following releases cease to insert the deprecated field
  • This provides a time window during which the automatic field upgrade has a chance to upgrade all the Rhizome software in the field
Sender and recipient
  • If a bundle does not indicate the Serval Identity of its intended recipient, it is for general consumption (broadcast)
  • If a bundle does not indicate the Serval Identity of its sender, then it is of unknown origin (anonymous)

Put these points somewhere else

  • A manifest may be present on many nodes at a time
  • A payload may be present on many nodes at a time
  • A manifest may persist for any length of time on any node
  • A payload may persist for any length of time on any node
  • Rhizome does not modify any manifest once it is created
  • Rhizome does not modify any payload

Rhizome nodes

  • A Rhizome node is any network node (device) that is running the Rhizome software
  • Payloads and manifests are copied directly from node to node using network transfers
  • Payloads and manifests are stored on nodes using volatile (RAM) or non-volatile (Flash, disk) local storage
  • Each Rhizome node actively transmits its recently acquired manifests to its neighbours
  • Each Rhizome node records all received manifests in a sorted list called the rank
  • Each Rhizome node attempts to acquire the payloads of its highest ranked manifests from neighbouring nodes
  • Each Rhizome node recovers local storage space by evicting its lowest ranked payloads and manifests


  • Rhizome interprets meta data uniformly, regardless of the originating or receiving application
  • Rhizome ranks (prioritises) payloads using uniform rules that do not depend on the originating or receiving application
  • Rhizome software does not encapsulate any application-specific logic
  • Rhizome does not record the originating or transited nodes of any payload, so nodes cannot rank (prioritise) payloads based on point of origin, only on available meta data
  • Rhizome does not rank (prioritise) based on the content of payloads

Bundle integrity

  • Rhizome creates a random 256-bit Elliptic Curve private key for every bundle, called the Bundle Secret or BS
  • The 256-bit public key derived from the Bundle Secret is called the Bundle ID or BID
  • Rhizome does not reveal the Bundle Secret to any other application or node
  • Rhizome computes the 512-bit SHA512 hash of the payload, called the Payload Hash or PH (also File Hash or FH)
  • At injection, Rhizome inserts the Payload Hash into the bundle's manifest
  • Rhizome signs every complete manifest using the Bundle Secret
  • Rhizome nodes will only store and transmit manifests with valid signatures
  • Only an application possessing the original Bundle Secret can alter the manifest or payload

The net result of Rhizome's crytpo system is that:

  • any party may create a new bundle (with a new Bundle ID)
  • only the originating party may modify the manifest or payload of an existing bundle (keeping the same Bundle ID)
  • thus, once a bundle is created, all new payloads with the same Bundle ID are guaranteed to be from the same original sender

Payload security

  • Rhizome can optionally encrypt a payload during injection with a one-way asymmetric cipher using the recipient's Serval ID public key
  • Rhizome can optionally encrypt a payload during injection with a two-way session cipher constructed using the sender's and recipient's Serval ID public keys
  • Rhizome will decrypt an encrypted payload during extraction if the node possesses the recipient's Serval ID secret key
  • The Payload Hash of an encrypted payload is the SHA512 hash of the encrypted form, not the clear text form

User intervention

  • Users may improve the local capacity of Rhizome by operating nodes with high storage capacity
  • Users may improve the reach of Rhizome by periodically moving a node between distant locations

Network connections

  • Rhizome nodes may communicate using network layer connections over established networks, eg, TCP or UDP or HTTP over public Internet or cellular GSM
  • Adjacent Rhizome nodes may communicate over data link layer connections, eg, MDP to Serval Mesh devices within Fi-Fi range


Rhizome is currently implemented as part of the Serval DNA daemon.

The name "Rhizome"

Once a file is inserted into Rhizome, it can be notoriously difficult to eradicate. This is analogous to a biological process of vegetative reproduction: a rhizome is an underground plant stem with the ability to send out shoots which develop into new plants. If a rhizome is cut into smaller pieces, each piece can grow into a new organism. Anybody who has battled the incursion of couch grass into their garden knows how obstinate a rhizome can be.

Curiously (but not coincidentally) some of the principles of the rhizomatic philosophy of thought also describe the behaviour of the Rhizome file distribution system.

content/tech/rhizome.1365398974.txt.gz · Last modified: 07/04/2013 22:29 by Andrew Bettison