Merge pull request #1 from conduition/dlcs

additional clarity around message content and tags

Author: benthecarman

88.md

@@ -19,10 +19,15 @@ a unique opportunity to use a different transport layer for DLCs. This NIP propo
 acts like a mailbox for DLC messages. The DLC messages are sent over nostr and available for the user the next time
 they open their wallet. This allows for a more mobile-friendly DLC experience.
 
+DLC protocol messages are binary-serialized messages described concretely in
+[this document](https://github.com/discreetlogcontracts/dlcspecs/blob/master/Messaging.md).
+Whenever embedding DLC messages inside Nostr events (which are encoded as JSON), we serialize those DLC messages in base64.
+
 ### `kind:8_888`
 
-Kind 8_888 is a simple message that contains a [NIP04](04.md) encrypted DLC message and it tagged with the recipient's
-public key with a `p` tag and if it is in reply to another event, that event should be tagged with an `e` tag.
+Kind 8_888 is a simple message that contains a [NIP04](04.md) encrypted DLC message and is tagged with the recipient's
+public key with a `p` tag and if it is in reply to another event, that event should be tagged with an `e` tag. The DLC
+message is first serialized in binary, and then encrypted with [NIP04](04.md).
 
 A DLC wallet should only process messages that are tagged with their public key and that are in reply to a message they
 sent unless it is an offer. This is to prevent spam and to prevent a malicious actor from sending a message to a user
@@ -58,14 +63,18 @@ offer.
 
 A parameterized replaceable event is used to allow the offerer to update the offer or remove it from the market. The `d`
 tag should be the Offer's id to allow replacement of the offer. If the user wishes to remove the offer from the market,
-they can replace the event with an expires tag that is in the past.
+they can replace the event with an `expires` tag that is in the past. The `relays` tag indicates the relays on which to
+contact the offerer.
+
+The `content` field must be the base64-encoding of a binary-serialized
+[`contract_info` object](https://github.com/discreetlogcontracts/dlcspecs/blob/master/Messaging.md#the-contract_info-type).
 
 ### `kind:30_088`
 
 ```jsonc
 {
   "kind": 30088,
-  "content": "base64 contract details",
+  "content": "base64 contract_info",
   "tags": [
     [
       "relays",
@@ -101,7 +110,7 @@ attestations respectively.
 ```jsonc
 {
   "kind": 88,
-  "content": "base64 oracle annoucement",
+  "content": "base64 oracle_annoucement",
   "tags": [
     [
       "relays", // the relays the oracle will publish attestations to
@@ -116,15 +125,18 @@ attestations respectively.
 }
 ```
 
+The `content` field must be the base64-encoding of a binary-serialized
+[`oracle_annoucement` object](https://github.com/discreetlogcontracts/dlcspecs/blob/master/Messaging.md#the-oracle_annoucement-type).
+
 ### `kind:89`
 
 ```jsonc
 {
   "kind": 89,
-  "content": "base64 oracle attestation",
+  "content": "base64 oracle_attestation",
     "tags": [
     [
-      "e", // the event id of the announcement
+      "e", // the Nostr event id of the announcement
       "30efed56a035b2549fcaeec0bf2c1595f9a9b3bb4b1a38abaf8ee9041c4b7d93",
     ],
   ],
@@ -135,6 +147,17 @@ attestations respectively.
 }
 ```
 
+The `content` field must be the base64-encoding of a binary-serialized
+[`oracle_attestation` object](https://github.com/discreetlogcontracts/dlcspecs/blob/master/Messaging.md#the-oracle_attestation-type).
+
+Note that the `e` tag is the _Nostr event identifier_ for the `kind:88` announcement event, which is distinct from the identifier
+embedded [in the announcement](https://github.com/discreetlogcontracts/dlcspecs/blob/master/Messaging.md#oracle_event) or
+[in the attestation itself](https://github.com/discreetlogcontracts/dlcspecs/blob/master/Messaging.md#oracle_attestation). The `e`
+tag is intended to be used to look up the corresponding announcement event.
+
+Upon receiving an attestation, clients _should_ validate that the `event_id` field inside the `oracle_announcement` object matches
+the `event_id` field in the `oracle_attestation` object.
+
 ## DLC Receipts
 
 DLCs can be fun, social events. This NIP proposes a `kind:90` event that can be used to publish the result of a DLC