Merge branch 'master' into clarify-json-serialization

1 files changed, 21 insertions, 10 deletions

diff --git a/03.md b/03.md
index 3c5d764..74e010c 100644
--- a/03.md
+++ b/03.md
@@ -4,20 +4,31 @@ NIP-03
 OpenTimestamps Attestations for Events
 --------------------------------------
 
-`draft` `optional` `author:fiatjaf`
+`draft` `optional`
 
-When there is an OTS available it MAY be included in the existing event body under the `ots` key:
+This NIP defines an event with `kind:1040` that can contain an [OpenTimestamps](https://opentimestamps.org/) proof for any other event:
 
-```
+```json
 {
-  "id": ...,
-  "kind": ...,
-  ...,
-  ...,
-  "ots": <base64-encoded OTS file data>
+  "kind": 1040
+  "tags": [
+    ["e", <event-id>, <relay-url>],
+    ["alt", "opentimestamps attestation"]
+  ],
+  "content": <base64-encoded OTS file data>
 }
 ```
 
-The _event id_ MUST be used as the raw hash to be included in the OpenTimestamps merkle tree.
+- The OpenTimestamps proof MUST prove the referenced `e` event id as its digest.
+- The `content` MUST be the full content of an `.ots` file containing at least one Bitcoin attestation. This file SHOULD contain a **single** Bitcoin attestation (as not more than one valid attestation is necessary and less bytes is better than more) and no reference to "pending" attestations since they are useless in this context.
+
+### Example OpenTimestamps proof verification flow
 
-The attestation can be either provided by relays automatically (and the OTS binary contents just appended to the events it receives) or by clients themselves when they first upload the event to relays — and used by clients to show that an event is really "at least as old as [OTS date]".
+Using [`nak`](https://github.com/fiatjaf/nak), [`jq`](https://jqlang.github.io/jq/) and [`ots`](https://github.com/fiatjaf/ots):
+
+```bash
+~> nak req -i e71c6ea722987debdb60f81f9ea4f604b5ac0664120dd64fb9d23abc4ec7c323 wss://nostr-pub.wellorder.net | jq -r .content | ots verify
+> using an esplora server at https://blockstream.info/api
+- sequence ending on block 810391 is valid
+timestamp validated at block [810391]
+```