diff --git a/remote-log.md b/remote-log.md new file mode 100644 index 00000000..9f0f0f4d --- /dev/null +++ b/remote-log.md @@ -0,0 +1,216 @@ +# Remote log specification + +> Version: 0.1.0 (Draft) +> +> Authors: Oskar Thorén oskar@status.im, Dean Eigenmann dean@status.im + +## Table of Contents + +- [Abstract](#abstract) +- [Definitions](#definitions) +- [Wire Protocol](#wire-protocol) + - [Secure Transport, storage, and name system](#secure-transport-storage-and-name-system) + - [Payloads](#payloads) +- [Synchronization](#synchronization) + - [Roles](#roles) + - [Flow](#flow) + - [Remote log](#remote-log) + - [Next page semantics](#next-page-semantics) + - [Interaction with MVDS](#interaction-with-mvds) +- [Footnotes](#footnotes) +- [Acknowledgements](#acknowledgements) + +## Abstract + +A remote log is a replication of a local log. This means a node can read data from a node that is offline. + +This specification is complemented by a proof of concept implementation 1. + +## Definitions + +| Term | Definition | +| ----------- | -------------------------------------------------------------------------------------- | +| CAS | Content-addressed storage. Stores data that can be addressed by its hash. | +| NS | Name system. Associates mutable data to a name. | +| Remote log | Replication of a local log at a different location. | + +## Wire Protocol + +### Secure Transport, storage, and name system + +This specification does not define anything related to to: secure transport, +content addressed storage, or the name system. It is assumed these capabilities +are abstracted away in such a way that any such protocol can easily be +implemented. + + + +### Payloads + +Payloads are implemented using [protocol buffers v3](https://developers.google.com/protocol-buffers/). + +**CAS service**: + +```protobuf +package vac.cas; + +service CAS { + rpc Add(Content) returns (Address) {} + rpc Get(Address) returns (Content) {} +} + +message Address { + bytes id = 1; +} + +message Content { + bytes data = 1; +} +``` + + + +**NS service**: + +```protobuf +service NS { + rpc Update(NameUpdate) returns (Response) {} + rpc Fetch(Query) returns (Content) {} +} + +message NameUpdate { + string name = 1; + bytes content = 2; +} + +message Query { + string name = 1; +} + +message Content { + bytes data = 1; +} + +message Response { + bytes data = 1; +} +``` + + + + +**Remote log:** + +```protobuf +message RemoteLog { + repeated Pair pair = 1; + bytes tail = 2; + + message Pair { + bytes remoteHash = 1; + bytes localHash = 2; + bytes data = 3; + } +} +``` + + + + + +## Synchronization + + + +### Roles + +There are four fundamental roles: + +1. Alice +2. Bob +2. Name system (NS) +3. Content-addressed storage (CAS) + +The *remote log* protobuf is what is stored at the Name system. + +"Bob" can represents anything from 0 to N participants. Unlike Alice, Bob only needs read-only access to NS and CAS. + +### Flow + + + +
+
+
+ Figure 1: Remote log data synchronization.
+