Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

NIP-88: Discreet Log Contracts over Nostr #919

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
+181 −0
Draft

NIP-88: Discreet Log Contracts over Nostr #919

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ceaf163
NIP-88: Discreet Log Contracts over Nostr
benthecarman Dec 6, 2023
7089bf7
additional clarity around message content and tags
conduition Jul 15, 2024
9157321
Merge pull request #1 from conduition/dlcs
benthecarman Jul 15, 2024
083f112
add title and description tags to oracle announcement
conduition Aug 30, 2024
eb4f408
Merge pull request #2 from conduition/dlcs
benthecarman Aug 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 146 additions & 0 deletions 88.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
NIP-88
======

Discreet Log Contracts over nostr
-----------------

`draft` `optional`

This NIP describes a way to use Discreet Log Contracts (DLCs) over Nostr. This comes in four main
components: `kind:8_888` for sending DLC messages between wallets. `kind:30088` for posting DLC offers to the global
market. `kind:88` and `kind:89` for publishing DLC oracle announcements and attestations. And `kind:90` for a DLC
"receipt" that can publish the result of a DLC for social interaction.

## DLC Messages

DLCs typically use [BOLT 8](https://github.com/lightning/bolts/blob/master/08-transport.md) for sending messages but
this has various problems: it requires the ability to accept incoming connections and an always-on node. Nostr provides
a unique opportunity to use a different transport layer for DLCs. This NIP proposes a new `kind:8_888` message that
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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right here seems to be the perfect spot to insert a description of the DLC messages' structure and encoding. Assuming you meant it this way, we should add a link to the DLC specifications to be explicit about what the base64 contract details, or base64 oracle announcement concretely encode.

Suggested change
they open their wallet. This allows for a more mobile-friendly DLC experience.
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 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
Copy link

@conduition conduition Jul 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NIP04 describes how to encrypt text messages and assumes that text is UTF8-encoded already.

Since we're using base64(binary(dlc_message)) as event content elsewhere in this NIP, I think it would be wise to clarify exactly what encoding of the DLC message should be encrypted. Are we doing aes(key, binary(dlc_message)), or aes(key, base64(binary(dlc_message)))?

public key with a `p` tag and if it is in reply to another event, that event should be tagged with an `e` tag.
benthecarman marked this conversation as resolved.
Show resolved Hide resolved

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
that looks like it is from a different user.

```json
{
"kind": 8888,
"content": "TJob1dQrf2ndsmdbeGU+05HT5GMnBSx3fx8QdDY/g3NvCa7klfzgaQCmRZuo1d3WQjHDOjzSY1+MgTK5WjewFFumCcOZniWtOMSga9tJk1ky00tLoUUzyLnb1v9x95h/iT/KpkICJyAwUZ+LoJBUzLrK52wNTMt8M5jSLvCkRx8C0BmEwA/00pjOp4eRndy19H4WUUehhjfV2/VV/k4hMAjJ7Bb5Hp9xdmzmCLX9+64+MyeIQQjQAHPj8dkSsRahP7KS3MgMpjaF8nL48Bg5suZMxJayXGVp3BLtgRZx5z5nOk9xyrYk+71e2tnP9IDvSMkiSe76BcMct+m7kGVrRcavDI4n62goNNh25IpghT+a1OjjkpXt9me5wmaL7fxffV1pchdm+A7KJKIUU3kLC7QbUifF22EucRA9xiEyxETusNludBXN24O3llTbOy4vYFsq35BeZl4v1Cse7n2htZicVkItMz3wjzj1q1I1VqbnorNXFgllkRZn4/YXfTG/RMnoK/bDogRapOV+XToZ+IvsN0BqwKSUDx+ydKpci6htDRF2WDRkU+VQMqwM0CoLzy2H6A2cqyMMMD9SLRRzBg==?iv=S3rFeFr1gsYqmQA7bNnNTQ==",
"tags": [
[
"p",
"04c915daefee38317fa734444acee390a8269fe5810b2241e5e6dd343dfbecc9"
],
[
"e",
"9ae37aa68f48645127299e9453eb5d908a0cbb6058ff340d528ed4d37c8994fb"
]
],
"pubkey": "97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322",
"created_at": 1679673265,
"id": "30efed56a035b2549fcaeec0bf2c1595f9a9b3bb4b1a38abaf8ee9041c4b7d93",
"sig": "f2cb581a84ed10e4dc84937bd98e27acac71ab057255f6aa8dfa561808c981fe8870f4a03c1e3666784d82a9c802d3704e174371aa13d63e2aeaf24ff5374d9d"
}
```

## DLC Offers

DLCs are done between two parties and Nostr provides a unique opportunity to create a global market for DLCs. This
benthecarman marked this conversation as resolved.
Show resolved Hide resolved
market can be constructed with a simple list of DLC offers that can be filtered by the user's wallet. The user can then
select an offer and send a message to the offerer to begin the DLC process. `kind:30088` is an event that contains a DLC
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.

### `kind:30_088`

```jsonc
{
"kind": 30088,
"content": "base64 contract details",
"tags": [
[
"relays",
"wss://nostr.mutinywallet.com",
"wss://relay.damus.io"
],
[
"expires",
"1695327657"
],
[
"d",
"6423394a32f37a4f0590e74f9308f5aee06e59e14f50c4cd6d59365caed13cb7"
],
],
"pubkey": "97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322",
"created_at": 1679673265,
"id": "30efed56a035b2549fcaeec0bf2c1595f9a9b3bb4b1a38abaf8ee9041c4b7d93",
"sig": "f2cb581a84ed10e4dc84937bd98e27acac71ab057255f6aa8dfa561808c981fe8870f4a03c1e3666784d82a9c802d3704e174371aa13d63e2aeaf24ff5374d9d"
}
```

## DLC Oracle Gossip

DLCs require an oracle to attest to the outcome of real world events. This is done by the oracle signing a message
containing the outcome of the event. Before they attest to the outcome, they must create an announcement where they
publish the intent to sign the future event. This announcement is then used by the DLC participants to create the
contract. Here we define two events, `kind:88` and `kind:89` that are used to publish the oracle's announcement and
attestations respectively.

### `kind:88`

```jsonc
{
"kind": 88,
"content": "base64 oracle annoucement",
"tags": [
[
"relays", // the relays the oracle will publish attestations to
"wss://nostr.mutinywallet.com",
"wss://relay.damus.io"
],
],
"pubkey": "97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322",
"created_at": 1679673265,
"id": "30efed56a035b2549fcaeec0bf2c1595f9a9b3bb4b1a38abaf8ee9041c4b7d93",
"sig": "f2cb581a84ed10e4dc84937bd98e27acac71ab057255f6aa8dfa561808c981fe8870f4a03c1e3666784d82a9c802d3704e174371aa13d63e2aeaf24ff5374d9d"
}
```

### `kind:89`

```jsonc
{
"kind": 89,
"content": "base64 oracle attestation",
"tags": [
[
"e", // the event id of the announcement
"30efed56a035b2549fcaeec0bf2c1595f9a9b3bb4b1a38abaf8ee9041c4b7d93",
],
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oracle announcements also contain an event_id field, and so do oracle attestations. Announcement event IDs must be distinct from the Nostr kind:88 event IDs (due to the fact that the announcement is part of the preimage for the nostr event ID). This might cause some confusion.

Perhaps we should clarify that the e tag must be the Nostr event ID, not the announcement event ID, and that the e tag should be used to look up the Nostr event which embeds an oracle announcement.

One might want to enforce on the client that the oracle_attestation data embeds the same announcement event ID that you find by looking up the event indicated by the e tag. In pseudocode:

def validate_attestation_event(attestation_event):
  oracle_attestation = decode_attestation(attestation_event.content)
  announcement_event = nostr_event_lookup(attestation_event.tags.e)
  oracle_announcement = decode_announcement(announcement_event.content)
  assert oracle_announcement.event_id == oracle_attestation.event_id

],
"pubkey": "97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322",
"created_at": 1679673265,
"id": "30efed56a035b2549fcaeec0bf2c1595f9a9b3bb4b1a38abaf8ee9041c4b7d93",
"sig": "f2cb581a84ed10e4dc84937bd98e27acac71ab057255f6aa8dfa561808c981fe8870f4a03c1e3666784d82a9c802d3704e174371aa13d63e2aeaf24ff5374d9d"
}
```

## 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
contract. This event can be used to show off the result of a DLC to the user's followers, similar [Zaps](57.md) but for
DLC bets.

### `kind:90`

todo I still need to think about this one