SCP-002: Datastore P2P interface

scps/SCP-002.md

@@ -0,0 +1,75 @@
+## SCP-002: Datastore P2P interface
+
+This proposal is a system that allows stores to create custom p2p channels to other peers interested in a common orbitdb datastore.
+
+**Definitions**:
+* Asking peer: The peer initiating the connection
+* Responding peer: The peer responding to the initiation.
+* The network: Cloud of peers all interconnected interested in the datastore in question
+* Broadcast channel: Global pubsub channel of the corresponding datastore.
+* Application specific P2P API: Interface diagrammed by higher level code implementing `orbit-db-store`; Defined by the store type.
+
+### Hypothetical model N1
+> Note all p2p traffic is over IPFS pubsub
+
+**Flow**:
+
+1. Asking peer joins store broadcast channel. (Example: Asking peer is just starting up and gets connected to the network)
+2. Responding peer broadcasts a small message to all the other peers containing information regarding what diagrams/protocol it supports. Including Public key for encryption, if needed, and a forwarding pubsub channel ID (a channel where asking peers can send messages directly to the responding peer, derived from the peerId). The forwarding channel isn't designed to be a back and forth between a responding peer and an asking peer.  Only a temporary channel for negotiating a direct peer-to-peer connection.
+3. Asking peer sends an establishment request to the forwarding channel, containing the necessary information to determine a direct p2p channel ID.
+4. In the newly created pubsub channel, protocol handshakes are done, encryption is established, exchange of supported p2p application specific API calls, Secondary application specific handshakes completed. The rest of the process is diagrammed by the application specific API.
+
+**Advantages**
+* Relies on a technology already used in orbitdb.
+* Pubsub relays can help with routing packets to peers behind a firewall.
+* Does not require a separate libp2p daemon. Can use IPFS daemon directly.
+
+**Disadvantages**
+* No P2P transport security out of the box. Higher chance of an adversory capturing P2P messages
+* Potential packet size limitiations. No out of the box streaming capabilities
+* Peer discovery/rendezvous might be an issue.
+* Requires building custom systems to accomplish the same level of functionality as Model N2.
+
+### Hypothetical model N2
+> Uses a global pubsub channel for finding peers interested in a datastore. Maintaines an up-to-date list of possible peer connections. 
+Broadcasts peer metadata routinely to global pubsub channel. Keeping other peers up to date.
+
+**Flow**:
+
+1. Asking peer joins store broadcast channel. (Example: Asking peer is just starting up and gets connected to the network)
+2. Asking peer broadcasts a small chunk of metadata descripting what P2P operations it supports.
+Occasionally redoing this step either when metadata has changed or on a timed basis for peers that do not have a copy yet.
+3. Responding peer stores copy of peer metadata, verifying signature in the process.
+
+NOTE: Step 2 and 3 can happen on asking and responding peer sides.
+
+4. Asking peer decides to contact another peer. Asking peer retrieves peer metadata from local store. Can be initiated by user, or built in functionality.
+5. Asking peer dials responding peer through libp2p. 
+6. Responding peer receives libp2p dial request and establishes the connection. 
+In the process doing a double check to ensure both listener and dialer speak the same operations. Libp2p duplex stream is established between the two entities.
+7. P2P exchange commences. At this point most of the functionality is left up to store implemention.
+
+**Advantages**:
+* Async iterable support out of the box.
+* Encrypted and signed connection out of the box.
+
+**Disadvantages**:
+* Significantly more complicated out of the box.
+
+### **What does this accomplish**
+By exposing some type of peer to peer API to store types, stores can implement custom authentication methods, and side channel non essential actions not included in the oplog.
+The following is possible. 
+* Secondary authentication channels to peers trusted cryptographically through orbit-db-access-controller; 
+Allows peers to be granted write authority via other none cryptographic manners such oauth2. 
+Still relying on all peers to have a public/private key for the oplog entry signing.
+* Querying other peers instead of searching local store.
+
+Further discussion and comments is appreciated.
+
+### Notes
+[[1](https://github.com/vaultec81/js-libp2p-template)]: `https://github.com/vaultec81/js-libp2p-template` Basic libp2p listener and dialer template with support for async iterables and packet based messages. Includes handling of errors and exceptions.
+
+[[2](https://github.com/ipfs-shipyard/ipfs-pubsub-1on1/)]: `https://github.com/ipfs-shipyard/ipfs-pubsub-1on1/` ipfs-pubsub-1on1 is a 1-to-1 communication channel over IPFS Pubsub. It enables two peers to exchange messages between each other. Note that the channel is currently not authenticated nor encrypted!
+
+[[3](https://github.com/ipfs-shipyard/ipfs-pubsub-peer-monitor/)]: `https://github.com/ipfs-shipyard/ipfs-pubsub-peer-monitor/` ipfs-pubsub-peer-monitor listens on a IPFS PubSub topic and emits an event when a peer joins or leaves the topic.
+This module is based on ipfs-pubsub-room that can provide the same functionality. It contains extra features that are not necessary for purely wanting to know joins/leaves, so this module was created to do that and only that.