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

Oracle JSON format proposal #150

Closed
wants to merge 1 commit into from
Closed

Oracle JSON format proposal #150

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
83 changes: 83 additions & 0 deletions Oracle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,89 @@ The algorithm `Sign(sk, message, tag)` is defined as:
* Let `m` = H(`message`)
* Return `BIP340_sign(sk, m)`

## JSON Serialization
Copy link
Contributor

Choose a reason for hiding this comment

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

The introduction of this option means that a field must be added to the TLV format in front of oracle_signature specifying what the oracle has signed (TLV vs. JSON vs. other) as the client will have to reconstruct that message from the TLV.

Copy link
Member Author

Choose a reason for hiding this comment

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

To answer to both your questions, it's a good point that I hadn't specified this. My thinking was that it would be the same signature as the TLV version. It could be nice and practical to allow signature of JSON messages, but JSON being non canonical it's not trivial to do. We would need to adopt a specification for that or make a custom one which feels cumbersome.
Also (as you mention here) we would need clients to at the end probably support both signing format. I feel instead it is better to have oralce implement TLV signing which compared to the client TLV is not that hard to implement IMHO.

Copy link
Contributor

Choose a reason for hiding this comment

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

Note that JSON messages being non canonical does not make it difficult to sign them. It is of course very difficult if you are trying to embed the JSON that is signed along side the signature. The most straightforward way is to encode the json in a string inside the outer json.

curl -sL https://h00.ooo/time/2021-06-02T01:00:00?occur | jq
{
  "announcement": {
    "oracle_event": {
      "encoding": "json",
      "data": "{\"id\":\"/time/2021-06-02T01:00:00?occur\",\"expected_outcome_time\":\"2021-06-02T01:00:00\",\"descriptor\":{\"type\":\"enum\",\"outcomes\":[\"true\"]},\"nonces\":[\"0c2f40112642c09db886e5ce24ed94687ea022e0616990e1cfc0104348dc7a43\"]}"
    },
    "signature": "4c4861d830e9914351b59daacbb58b17d62865319163f732e399f2102e1080273729ecef419f7d04e536ca9e730e8d16793df56e8c3c716e7e28dba6c9a0df02"
  },
  "attestation": null
}

Then after verifying the signature you decode the announcement:

curl -sL https://h00.ooo/time/2021-06-02T01:00:00?occur | jq .announcement.oracle_event.data -r | jq
{
  "id": "/time/2021-06-02T01:00:00?occur",
  "expected_outcome_time": "2021-06-02T01:00:00",
  "descriptor": {
    "type": "enum",
    "outcomes": [
      "true"
    ]
  },
  "nonces": [
    "0c2f40112642c09db886e5ce24ed94687ea022e0616990e1cfc0104348dc7a43"
  ]
}

Copy link
Member Author

Choose a reason for hiding this comment

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

Yeah so that's one way. We would need to define how we encode the string as well. But what doesn't work very well is if we want to pass along announcements to counter parties. Of course we could embed the string again as well, but I feel it becomes complicated personally (and quite inefficient).


In addition to the previously define TLVs, we also provide recommendation on JSON serialization of oracle messages, in order to facilitate interoperability between oracle and clients using this format.

### Announcements

The following example describe JSON serialization of oracle announcements:

```json
{
"announcementSignature": "464410ffd8be04249a6ea6a646fd07a05d8afbd8f6a96a6a6339ed66f799383b464410ffd8be04249a6ea6a646fd07a05d8afbd8f6a96a6a6339ed66f799383b",
"publicKey": "ce4b7ad2b45de01f0897aa716f67b4c2f596e54506431e693f898712fe7e9bf3",
"event":{
"nonces":[
"5ebf5cdbcafe17b7b419b728e68cde1d7035618bab4e4732971149b4a1c7ecd8",
],
"maturity":"2021-01-14T07:20:00Z",
"descriptor":{
...
},
"eventId": "btcusd1610608800"
}
}
```

where:
`anouncementSignature` is a hex string of length 128 representing a BIP340 Schnorr signature,
Copy link
Contributor

Choose a reason for hiding this comment

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

of what? Presumably a serialization of this JSON string without the signature field or something like that?

`publicKey` is a hex string of length 64 representing an x-only public key,
`nonces` is an array of string of length 64 representing x-only public keys,
`maturity` is a string representing a date formatted following ISO-8601,
`descriptor` is one of the descriptor type defined below,
`eventId` is a string.

#### Simple Enumeration decomposition descriptor

For simple enumeration events, the JSON format is as shown in the following example:

```json
{
"outcomes": [
"sunny", "rainy", "cloudy",
]
}
```

#### Digit decomposition descriptor

For digit decomposition events, the JSON format is as shown in the following example:

```json
{
"base": 2,
"isSigned": false,
"unit": "btc/usd",
"precision": 0
}
```

where:
`base` is a number,
`isSigned` is a boolean,
`unit` is a string,
`precision` is a number,

### Attestations

```json
{
"eventId":"btcusd1610608800",
"signatures":[
"5ebf5cdbcafe17b7b419b728e68cde1d7035618bab4e4732971149b4a1c7ecd859dfe812973cda8c71e977e8efed97f381de4db3c7223b4fcf89be5e34d07d9a",
],
"values":[
"0",
]
}
```

where:
`eventId` is a string,
`signatures` is an array of hex strings,
`values` is an array of strings representing the event outcomes.

## Footnotes

<b id="f1">1</b>: More complex constructions where considered to handle these.
Expand Down