From 1a6d22ceb9198d024d3e8b14cd46bcca20b1374e Mon Sep 17 00:00:00 2001
From: CSDUMMI <31551856+CSDUMMI@users.noreply.github.com>
Date: Sun, 3 Oct 2021 23:30:37 +0200
Subject: [PATCH 1/5] Detailed documentation of the oplog entries.

---
 API.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/API.md b/API.md
index 8bec76e..5dd4e03 100644
--- a/API.md
+++ b/API.md
@@ -66,6 +66,18 @@ Read the **[GETTING STARTED](https://github.com/orbitdb/orbit-db/blob/master/GUI
   * [`peer`](#peer)
   * [`closed`](#closed)
   * [`peer.exchanged`](#peerexchanged)
+- [Oplog API](#oplog-api)
+  * [`oplog.values`](#oplogvalues)
+    + `hash`
+    + `id`
+    + `payload`
+    + `next`
+    + `refs`
+    + `v`
+    + `clock`
+    + `key`
+    + `identity`
+    + `sig`
 
 <!-- tocstop -->
 
@@ -656,3 +668,72 @@ db.events.on('peer.exchanged', (peer, address, heads) => ... )
 ```
 
 Emitted after heads have been exchanged with a peer for a specific database. This will be emitted after every exchange, even if no heads are received from the peer, or if all received heads are already present. (This is in contrast with the `replicated` event, which will only fire when new heads have been received.) Note that `heads` here contains heads *received* as part of the exchange, not heads sent.
+
+# Oplog API
+Oplog or IPFS-Log is the underlying data structure used by the OrbitDB Stores to store,
+replicate and add operations to any of their stores. 
+
+## `oplog.values`
+Each oplog entry contains these fields:
+```js
+ {
+    hash: 'zdpuAuARU9C1MXvHGozGxvpv3rvSzghQg7JmoLQLWbedJzcd7',
+    id: '/orbitdb/zdpuArEpCPwqpgQVMYrFSDQKhHLq5L6Es8HQkhWfhrad5oYdK/example',
+    payload: { op: 'PUT', key: 'abc', value: 'def' },
+    next: [ 'zdpuAzWC4phgt6eQeRPz58p33G1w1J5ciVnCwuoFa7szsDVP2' ],
+    refs: [ 'zdpuAxFR9miMinzetRdZKvy9mBaiZLJByA6DV715Wcmgi7dwx' ],
+    v: 2,
+    clock: LamportClock {
+      id: '04f75c96cb240d8b254df96fcc7d9d7a1260fd838cb0d085f009d2f0c78b74f7984c168da6afa1f0ee9400f5022952e70955c10798beb0c168966faf746c7202ad',
+      time: 3
+    },
+    key: '04f75c96cb240d8b254df96fcc7d9d7a1260fd838cb0d085f009d2f0c78b74f7984c168da6afa1f0ee9400f5022952e70955c10798beb0c168966faf746c7202ad',
+    identity: {
+      id: '0336124289bdb2384ef7f3f5991d25bb1e02bf2a98edb02f94b0bc9f292c41156b',
+      publicKey: '04f75c96cb240d8b254df96fcc7d9d7a1260fd838cb0d085f009d2f0c78b74f7984c168da6afa1f0ee9400f5022952e70955c10798beb0c168966faf746c7202ad',
+      signatures: [Object],
+      type: 'orbitdb'
+    },
+    sig: '3045022100e618887439bcaa8cffe0196d5655c710cc117af7de4390a313d137dd02a993a402205fb0b657600216944a0e7f68d2bb07854e8f47cc01a74d7cc632870ad7055758'
+  }
+```
+
+Let's got through each of them in turn:
+- [Oplog API](#oplog-api)
+  * [`oplog.values`](#oplogvalues)
+    + `hash`
+    + `id`
+    + `payload`
+    + `next`
+    + `refs`
+    + `v`
+    + `clock`
+    + `key`
+    + `identity`
+    + `sig`
+### `hash`
+Hash of the entry on IPFS. "zd...".
+
+### `id`
+Address of the oplog. (A.k.a. the OrbitDB Address)
+
+### `payload`
+Payload of the operation. Provided by the Store to `_addOperation`. 
+
+### `next`
+Array of hashes
+
+### `refs`
+**TBD**
+
+### `v`
+**TBD**
+
+## `key`
+Public key of the Identity that added this entry.
+
+### `identity`
+Identity that added this entry.
+
+### `sig`
+Signature of the entry.

From 01a1557ec2449715c880227f31f6e26fa1b5825f Mon Sep 17 00:00:00 2001
From: CSDUMMI <31551856+CSDUMMI@users.noreply.github.com>
Date: Sun, 3 Oct 2021 23:37:38 +0200
Subject: [PATCH 2/5] Documentation for clock field on oplog.values

---
 API.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/API.md b/API.md
index 5dd4e03..08072c9 100644
--- a/API.md
+++ b/API.md
@@ -729,6 +729,13 @@ Array of hashes
 ### `v`
 **TBD**
 
+### `clock`
+Lamport clock instance of the entry.
+A Lamport clock contains a `time`, an integer, 
+taht for all operations depending on each other increases.
+
+If Operation A depends on Operation B, B's time < A's time.
+
 ## `key`
 Public key of the Identity that added this entry.
 

From 4a448f69bf44a11252c6274e7445a8e9a0c7be54 Mon Sep 17 00:00:00 2001
From: CSDUMMI <31551856+CSDUMMI@users.noreply.github.com>
Date: Sun, 3 Oct 2021 23:41:00 +0200
Subject: [PATCH 3/5] Removed notes for structure.

And added note on the `sig` value.
---
 API.md | 14 ++------------
 1 file changed, 2 insertions(+), 12 deletions(-)

diff --git a/API.md b/API.md
index 08072c9..97532b8 100644
--- a/API.md
+++ b/API.md
@@ -699,18 +699,7 @@ Each oplog entry contains these fields:
 ```
 
 Let's got through each of them in turn:
-- [Oplog API](#oplog-api)
-  * [`oplog.values`](#oplogvalues)
-    + `hash`
-    + `id`
-    + `payload`
-    + `next`
-    + `refs`
-    + `v`
-    + `clock`
-    + `key`
-    + `identity`
-    + `sig`
+
 ### `hash`
 Hash of the entry on IPFS. "zd...".
 
@@ -744,3 +733,4 @@ Identity that added this entry.
 
 ### `sig`
 Signature of the entry.
+If the entry is in the oplog, the signature is valid.

From b1f2048103303d4740e1a6f787280af41f6ac090 Mon Sep 17 00:00:00 2001
From: CSDUMMI <31551856+CSDUMMI@users.noreply.github.com>
Date: Thu, 7 Oct 2021 20:22:12 +0200
Subject: [PATCH 4/5] More documentation of `next` fields

Thanks to @haadcode
---
 API.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/API.md b/API.md
index 97532b8..14fdbc6 100644
--- a/API.md
+++ b/API.md
@@ -710,7 +710,8 @@ Address of the oplog. (A.k.a. the OrbitDB Address)
 Payload of the operation. Provided by the Store to `_addOperation`. 
 
 ### `next`
-Array of hashes
+Array of hashes of the oplog entries that are before this entry 
+in the oplog and that this entry depends upon.
 
 ### `refs`
 **TBD**

From 8330fc01c8f2c80fcf47ebeac0e7336f63ccc4d2 Mon Sep 17 00:00:00 2001
From: CSDUMMI <31551856+CSDUMMI@users.noreply.github.com>
Date: Fri, 8 Oct 2021 10:28:17 +0200
Subject: [PATCH 5/5] Wikipedia Page on Lamport Timestamps linked.

---
 API.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/API.md b/API.md
index 14fdbc6..6ec37e1 100644
--- a/API.md
+++ b/API.md
@@ -710,8 +710,9 @@ Address of the oplog. (A.k.a. the OrbitDB Address)
 Payload of the operation. Provided by the Store to `_addOperation`. 
 
 ### `next`
-Array of hashes of the oplog entries that are before this entry 
-in the oplog and that this entry depends upon.
+Array of hashes of the oplog entries that happened before this one.
+
+
 
 ### `refs`
 **TBD**
@@ -722,10 +723,12 @@ in the oplog and that this entry depends upon.
 ### `clock`
 Lamport clock instance of the entry.
 A Lamport clock contains a `time`, an integer, 
-taht for all operations depending on each other increases.
+that for all operations depending on each other increases.
 
 If Operation A depends on Operation B, B's time < A's time.
 
+[See the Wikipedia description of Lamport Clocks for more details](https://en.wikipedia.org/wiki/Lamport_timestamp)
+
 ## `key`
 Public key of the Identity that added this entry.