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

v0 Oracle Changes #167

Open
wants to merge 23 commits into
base: master
Choose a base branch
from
Open

v0 Oracle Changes #167

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
44f904c
Made breaking changes to oracle announcement message
nkohen Jun 8, 2021
b369642
Updated announcement signature hash
nkohen Jun 8, 2021
df6f714
Responded to review
nkohen Jun 11, 2021
fe53767
Added timestamp and ToC entry
nkohen Jun 14, 2021
6b1a02b
Responded to review
nkohen Sep 9, 2021
67376f9
Changes responding to review from Lloyd in spec meeting (and Matt on …
nkohen Nov 9, 2021
9d2e6b8
Restructured oracle metadata signatures and such
nkohen Nov 10, 2021
0151ab5
Update TOC
Tibo-lg Jun 9, 2022
bbe3f6b
Update serialization and enable multiple attestation schemes
Tibo-lg Jun 9, 2022
cba6535
Rename oracle_keys to oracle_metadata
Tibo-lg Jun 14, 2022
2c7fa3b
Update test vectors
Tibo-lg Jun 16, 2022
dcdc1e3
Change type of base in digit event desc
Tibo-lg Jun 16, 2022
47b1f49
Add proof of knowledge using regular Schnorr signatures
Tibo-lg Jun 23, 2022
cb72177
Add missing attestation scheme
Tibo-lg Aug 7, 2022
7969fba
Clarify verification key for announcement signature
Tibo-lg Aug 7, 2022
e98808b
Fix test vectors with good announcement type
Tibo-lg Aug 8, 2022
db54f76
Fix test vectors with good announcement type
Tibo-lg Aug 8, 2022
5176f01
Remove extensibility of attestation scheme
Tibo-lg Aug 10, 2022
6b09bdd
Fixes
Tibo-lg Aug 13, 2022
9ea6ce0
Remove type prefix from announcement in offer
Tibo-lg Aug 16, 2022
9cef39a
Update local to offer + remove subtype from attestation
Tibo-lg Aug 29, 2022
aba655b
ordered nonces in test vectors
Tibo-lg Sep 30, 2022
930f119
Add ordered nonce requirement
Tibo-lg Oct 5, 2022
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
181 changes: 136 additions & 45 deletions Messaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ All data fields are unsigned big-endian unless otherwise specified.

## Table of Contents

- [Connection Handling and Multiplexing](#connection-handling-and-multiplexing)
- [Message Format](#message-format)
- [Wire Messages](#wire-messages)
- [Type-Length-Value](#type-length-value)
Expand Down Expand Up @@ -42,12 +41,23 @@ All data fields are unsigned big-endian unless otherwise specified.
- [The `event_descriptor` Type](#the-event_descriptor-type)
- [`enum_event_descriptor`](#enum_event_descriptor)
- [`digit_decomposition_event_descriptor`](#digit_decomposition_event_descriptor)
- [The `oracle_event_timestamp` Type](#the-oracle_event_timestamp-type)
- [`fixed_oracle_event_timestamp`](#fixed_oracle_event_timestamp)
- [`range_oracle_event_timestamp`](#range_oracle_event_timestamp)
- [The `oracle_event` Type](#the-oracle_event-type)
- [`oracle_event`](#oracle_event)
- [The `oracle_metadata` Type](#the-oracle_metadata-type)
- [`oracle_metadata`](#oracle_metadata)
- [Rationale](#rationale)
- [Requirements](#requirements)
- [The `schnorr_proof_of_knowledge` type](#the-schnorr_proof_of_knowledge-type)
- [The `schnorr_attestation_scheme` Type](#the-schnorr_attestation_scheme-type)
- [Requirements](#requirements-1)
- [Rationale](#rationale-1)
- [The `oracle_announcement` Type](#the-oracle_announcement-type)
- [`oracle_announcement`](#oracle_announcement)
- [The `oracle_attestation` Type](#the-oracle_attestation-type)
- [`oracle_attestation`](#oracle_attestation)
- [Requirements](#requirements-2)
- [The `schnorr_attestation` Type](#the-schnorr_attestation-type)
- [Authors](#authors)

## Connection Handling and Multiplexing
Expand Down Expand Up @@ -202,7 +212,7 @@ This type represents an enumerated outcome contract.
1. implements: `contract_descriptor`
1. type: 1
1. data:
* [`u16`:`num_digits`]
* [`bigsize`:`num_digits`]
* [`payout_function`:`payout_function`]
* [`rounding_intervals`:`rounding_intervals`]

Expand All @@ -214,6 +224,7 @@ The type `rounding_intervals` is defined [here](NumericOutcome.md#rounding-inter
### The `oracle_info` Type

This type contains information about the oracles to be used in executing a DLC.
Note that all `oracle_announcements` are serialized with their `u16` type prefixes to match their wire serialization.

#### `single_oracle_info`

Expand Down Expand Up @@ -363,91 +374,171 @@ Witnesses should be sorted by the `input_serial_id` sent in `funding_input` defi
This type contains information about an event on which a contract is based.
Two types of events are described, see [the oracle specification](./Oracle.md#event-descriptor) for more details.

**For backward compatibility reasons, this type is currently serialized as a TLV and uses u16 for collection prefix. It is expected to be changed to the new serialization format in a near future.**

#### `enum_event_descriptor`

1. implements: `event_descriptor`
1. type: 55302
1. type: 0
1. data:
* [`u16`:`num_outcomes`]
* [`string`:`outcome_1`]
* ...
* [`string`:`outcome_n`]
* [`bigsize`:`num_outcomes`]
* [`num_outcomes*string`:`outcomes`]

This type of event descriptor is a simple enumeration where the value `n` is the number of outcomes in the event.

Note that `outcome_i` is the outcome value itself and not its hash that will be signed by the oracle.
Note that `outcomes[i]` is the outcome value itself and not its hash that will be signed by the oracle.

#### `digit_decomposition_event_descriptor`

1. implements: `event_descriptor`
1. type: 55306
1. type: 1
1. data:
* [`bigsize`:`base`]
* [`u8`:`base`]
* [`bool`:`is_signed`]
* [`string`:`unit`]
* [`int32`:`precision`]
* [`u16`:`nb_digits`]

### The `oracle_event_timestamp` Type

This type contains timestamp information about when an `oracle_event` is to happen.

There are two kinds of `oracle_event_timestamps`: fixed timestamps for events with a
known (expected) epoch time at which the event will occur, and range for events whose
time is not known ahead of time and also for events which may occur at any time in the
specified range.

When using an `oracle_event_timestamp_range` for events which may occur at any time,
the `earliest_expected_time_epoch` should correspond to the time at which the oracle
announcement was created and `latest_expected_time_epoch` should correspond to the
latest time for which the oracle will be responsible for attesting to the event's occurence.
Note that it is possible to have functionally open-ended events through the use of very large
`latest_expected_time_epoch` timestamps.

#### `fixed_oracle_event_timestamp`

1. implements: `oracle_event_timestamp`
1. type: 0
1. data:
* [`u32`:`expected_time_epoch`]

#### `range_oracle_event_timestamp`

1. implements: `oracle_event_timestamp`
1. type: 1
1. data:
* [`u32`:`earliest_expected_time_epoch`]
* [`u32`:`latest_expected_time_epoch`]

### The `oracle_event` Type

This type contains information provided by an oracle on an event that it will attest to.
See [the Oracle specifications](./Oracle.md#oracle-event) for more details.

**For backward compatibility reasons, this type is currently serialized as a TLV and uses u16 for collection prefix. It is expected to be changed to the new serialization format in a near future.**

#### `oracle_event`

1. type: 55330
1. data:
* [`u16`:`nb_nonces`]
* [`nb_nonces*x_point`:`oracle_nonces`]
* [`u32`:`event_maturity_epoch`]
* [`oracle_event_timestamp`:`timestamp`]
* [`event_descriptor`:`event_descriptor`]
* [`string`:`event_id`]

### The `oracle_metadata` Type

This type contains static oracle information and can be used to import trusted oracles into wallets.
This information should be saved by DLC nodes.

#### `oracle_metadata`

1. data:
* [`x_point`:`announcement_public_key`]
* [`string`:`oracle_name`]
* [`string`:`oracle_description`]
* [`u32`:`timestamp`]
Copy link
Member

Choose a reason for hiding this comment

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

@nkohen what is the use for this field? I think it'd be nice to have it explained somewhere.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I figured this would just be nice to have in case some oracle going as oracle_name publishes a new public key they use now and now when the user imports the new message, they can see that this is a newer one by looking at the timestamp. Open to changing this, but the idea was to have this be the time at which the oracle first announced this pubkey.

Copy link
Member

Choose a reason for hiding this comment

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

Mmmm ok thanks, I'll at least add the explanation and maybe we can discuss it next time.

Copy link
Member

Choose a reason for hiding this comment

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

I was wondering, what prevents anybody to just releasing a new struct with the name of an existing oracle but changing the public key (and using a newer timestamp)? How do you ensure that it is indeed the correct oracle?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think the idea is that one way or another people need to get the oracle public key in a good way (e.g. authenticated channel)

* [`schnorr_attestation_scheme`:`attestation_scheme`]
* [`signature`:`oracle_metadata_signature`]
Copy link
Member

Choose a reason for hiding this comment

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

@nkohen why is there a signature here and then one on the announcement? Isn't it redundant?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

So as it stands this message is static and can be imported by a wallet independently of an oracle announcement right? In this case it is important that the oracle metadata is what the oracle put down. If the keys are what you expect but someone takes the message and re-writes something about the scheme or description or such, this could be bad for wallet impls

Copy link
Member

Choose a reason for hiding this comment

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

If it is supposed to be a standalone message, does it make sense to include it in every single announcement? I'll go ahead with that for now but I feel it's also worth discussing.


where the `oracle_metadata_signature` is a Schnorr signature by the `announcement_public_key` using the tag `oraclemetadata/v0` of the sha256 hash of the serialized `oracle_metadata` message omitting the `announcement_public_key` and of course the the `oracle_metadata_signature`.

#### Rationale

Separate public keys are required for announcement and attestation because the attestation scheme
used in the current DLC spec reduces the security of non-attestation Schnorr signatures issued by the
Copy link
Contributor

Choose a reason for hiding this comment

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

Any citation/reason why it degrades security? It seems we state this as truth without some sort of reason why.

attestation keys and hence a separate announcement key is required.

The `oracle_metadata_signature` is used to link all data in this message to the `announcement_public_key`.

#### Requirements

A node

* SHOULD save this information in persistent storage.
* MUST reject if `announcement_public_key == attestation_public_key`.

### The `schnorr_proof_of_knowledge` type

A proof of knowledge is used to prove that oracles know the pre-images of the nonces they are using to prevent cancellation attacks in multi-oracle settings.
The `schnorr_proof_of_knowledge` uses Schnorr signatures to achieve this.

1. data:
* [`signature`:`attestation_public_key_proof`]
* [`nb_signatures`:`bigsize`]
* [`nb_signatures*signature`:`nonce_proofs`]

where each signature is generated over the message `dlcoraclepok`.

### The `schnorr_attestation_scheme` Type

The `schnorr_attestation_scheme` provides the information required to anticipate the attestation signatures of an oracle, as well as guaranteeing that the oracle knows the pre-images of the nonce point that it provides.

1. data:
* [`x_point`:`attestation_public_key`]
* [`bigsize`:`nb_nonces`]
* [`nb_nonces*x_point`:`oracle_nonces`]
* [`schnorr_proof_of_knowledge`:`proof_of_knowledge`]

where `proof_of_knowledge` ensures that the oracle knows the pre-image of the `attestation_public_key` and all `oracle_nonce`.
To be valid, an oracle MUST order the serialized nonces lexicographically.

#### Requirements

A node *MUST* validate the proof of knowledge in the case of multi oracle contracts.
A node *MUST* discard any announcement failing this verification.

#### Rationale

While using an aggregate signature increases the complexity of oracle implementation and management, providing a signature per nonce would lead to a large number of signatures in particular for oracle attesting to numerical event.

### The `oracle_announcement` Type

This type contains an `oracle_event` and a signature certifying its origination.
As oracle announcements can be broadcast directly, they are encoded as [wire messages](#wire-messages).
See [the Oracle specifications](./Oracle.md#oracle-announcements) for more details.

**For backward compatibility reasons, this type is currently serialized as a TLV and uses u16 for collection prefix. It is expected to be changed to the new serialization format in a near future.**

#### `oracle_announcement`

1. type: 55332
1. data:
* [`signature`:`annoucement_signature`]
* [`x_point`:`oracle_public_key`]
1. type: 55354 (`oracle_announcement`)
2. data:
* [`signature`:`announcement_signature`]
* [`oracle_metadata`:`oracle_metadata`]
* [`oracle_event`:`oracle_event`]

where `signature` is a Schnorr signature over a sha256 hash of the serialized `oracle_event`, using the tag `announcement/v0`.
where both the `announcement_signature` is a Schnorr signature over a sha256 hash of the serialized `oracle_event`, using the tag `announcement/v1`, that should be verified using the `oracle_announcement_public_key`.

### The `oracle_attestation` Type
#### Requirements

This type contains information about the outcome of an event and the signature(s) over its outcome value(s).
As oracle attestations can be broadcast directly, they are encoded as [wire messages](#wire-messages).
See [the Oracle specifications](./Oracle.md#oracle-attestations) for more details.
Clients SHOULD check the `oracle_attestation_public_key` has been signed by the `oracle_announcement_public_key` in a known `oracle_metadata` message and SHOULD abort if the attestation key is not recognized.

**For backward compatibility reasons, this type is currently serialized as a TLV and uses u16 for collection prefix. It is expected to be changed to the new serialization format in a near future.**
### The `schnorr_attestation` Type

#### `oracle_attestation`
The `schnorr_attestation` type provides signatures over an event outcome result values.

1. type: 55400
1. type: 55356
1. data:
* [`string`:`event_id`]
* [`x_point`:`oracle_public_key`]
* [`u16`: `nb_signatures`]
* [`signature`:`signature_1`]
* ...
* [`signature`:`signature_n`]
* [`string`:`outcome_1`]
* ...
* [`string`:`outcome_n`]

Where the signatures are ordered the same as the nonces in their original `oracle_event`.
* [`string`:`event_id`]
* [`x_point`:`oracle_attestation_public_key`]
* [`bigsize`: `nb_signatures`]
* [`nb_signatures`:`signatures`]
* [`bigsize`: `nb_outcomes`]
* [`nb_outcomes`:`signatures`]
Where the signatures are ordered the same as the nonces in their original `schnorr_attestation_scheme`.
The outcomes should be the message signed, ordered the same as the signatures.

## Authors
Expand Down
9 changes: 6 additions & 3 deletions Oracle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ For the purpose of these specifications, an event is a digital representation of
An [oracle](./Introduction.md#Oracle) is an entity that commits to publishing one or more signatures over a (number of) event outcome(s) ahead of time by releasing one or more [R-values](./Introduction.md#R-value) as well as necessary information for two parties to build a set of [CETs](./Introduction.md#Contract-Execution-Transaction-(CET)).
This necessary information is committed to in a so-called [_event descriptor_](#Event-descriptor) that will be further detailed in this document.

Before an oracle makes any announcements or attestations, it should first publish an [`oracle_keys`](Messaging.md#the-oracle_keys-type) message for
clients to be able to import a new oracle (or new oracle attestation keys) into their trusted keychain.

## Table of Contents

- [Event descriptor](#event-descriptor)
Expand Down Expand Up @@ -109,7 +112,7 @@ Oracle events contain such information, which includes:
* the event descriptor,
* the event ID which can be a name or categorization associated with the event by the oracle.

The TLV serialization for oracle events is given in [the Messaging specifications](./Messaging.md#the-oracle_event-type).
The serialization for oracle events is given in [the Messaging specifications](./Messaging.md#the-oracle_event-type).

## Oracle announcements

Expand All @@ -118,14 +121,14 @@ This proof is given in a so-called oracle announcement, which contains an oracle

This also makes it possible for users to obtain oracle event information from an un-trusted peer while being guaranteed that it originates from a given oracle.

The TLV serialization of oracle announcements is given in [the Messaging specifications](./Messaging.md#the-oracle_announcement-type).
The serialization of oracle announcements is given in [the Messaging specifications](./Messaging.md#the-oracle_announcement-type).

## Oracle Attestations

After an event occurs, and the oracle creates signatures to attest the outcome, it needs to give them to users.
An oracle can use an attestation tlv to give users this information.

The TLV serialization of oracle attestations is given in [the Messaging specifications](./Messaging.md#the-oracle_attestation-type).
The TLV serialization of oracle attestations is given in [the Messaging specifications](./Messaging.md#the-schnorr_attestation-type).

## Signing Algorithm

Expand Down
Loading