aljaz/dlcspecs
1
0
Fork 0
mirror of https://github.com/aljazceru/dlcspecs.git synced 2025-12-17 06:14:23 +01:00
Code Issues Packages Projects Releases Wiki Activity

Move oracle related TLV info to Messaging.md (#162)

Browse Source
This commit is contained in:
Thibaut Le Guilly
2021-04-20 15:52:54 +09:00
committed by GitHub
parent e5aa4c0fc2
commit 08c781021b
2 changed files with 123 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

154
Messaging.md
View File

@@ -9,41 +9,43 @@ All data fields are unsigned big-endian unless otherwise specified.
## Table of Contents ## Table of Contents
* [Connection Handling and Multiplexing](#connection-handling-and-multiplexing) - [Connection Handling and Multiplexing](#connection-handling-and-multiplexing)
* [Message Format](#message-format) - [Message Format](#message-format)
* [Fundamental Types](#fundamental-types) - [Fundamental Types](#fundamental-types)
* [DLC Specific Types](#dlc-specific-types) - [DLC Specific Types](#dlc-specific-types)
* [The `contract_info` Type](#the-contract_info-type) - [The `contract_info` Type](#the-contract_info-type)
* [Version 0 `contract_info`](#version-0-contract_info) - [Version 0 `contract_info`](#version-0-contract_info)
* [Version 1 `contract_info`](#version-1-contract_info) - [Version 1 `contract_info`](#version-1-contract_info)
* [The `contract_descriptor` Type](#the-contract_descriptor-type) - [The `contract_descriptor` Type](#the-contract_descriptor-type)
* [Version 0 `contract_descriptor`](#version-0-contract_descriptor) - [Version 0 `contract_descriptor`](#version-0-contract_descriptor)
* [Version 1 `contract_descriptor`](#version-1-contract_descriptor) - [Version 1 `contract_descriptor`](#version-1-contract_descriptor)
* [The `oracle_info` Type](#the-oracle_info-type) - [The `oracle_info` Type](#the-oracle_info-type)
* [Version 0 `oracle_info`](#version-0-oracle_info) - [Version 0 `oracle_info`](#version-0-oracle_info)
* [Version 1 `oracle_info`](#version-1-oracle_info) - [Version 1 `oracle_info`](#version-1-oracle_info)
* [Version 2 `oracle_info`](#version-2-oracle_info) - [Version 2 `oracle_info`](#version-2-oracle_info)
* [The `oracle_params` Type](#the-oracle_params-type) - [The `oracle_params` Type](#the-oracle_params-type)
* [Version 0 `oracle_params`](#version-0-oracle_params) - [Version 0 `oracle_params`](#version-0-oracle_params)
* [The `negotiation_fields` Type](#the-negotiation_fields-type) - [The `negotiation_fields` Type](#the-negotiation_fields-type)
* [Version 0 `negotiation_fields`](#version-0-negotiation_fields) - [Version 0 `negotiation_fields`](#version-0-negotiation_fields)
* [Version 1 `negotiation_fields`](#version-1-negotiation_fields) - [Version 1 `negotiation_fields`](#version-1-negotiation_fields)
* [Version 2 `negotiation_fields`](#version-2-negotiation_fields) - [Version 2 `negotiation_fields`](#version-2-negotiation_fields)
* [The `funding_input` Type](#the-funding_input-type) - [The `funding_input` Type](#the-funding_input-type)
* [Version 0 `funding_input`](#version-0-funding_input) - [Version 0 `funding_input`](#version-0-funding_input)
* [The `cet_adaptor_signatures` Type](#the-cet_adaptor_signatures-type) - [The `cet_adaptor_signatures` Type](#the-cet_adaptor_signatures-type)
* [Version 0 `cet_adaptor_signatures`](#version-0-cet_adaptor_signatures) - [Version 0 `cet_adaptor_signatures`](#version-0-cet_adaptor_signatures)
* [The `funding_signatures` Type](#the-funding_signatures-type) - [The `funding_signatures` Type](#the-funding_signatures-type)
* [Version 0 `funding_signatures`](#version-0-funding_signatures) - [Version 0 `funding_signatures`](#version-0-funding_signatures)
* [The `event_descriptor` Type](#the-event_descriptor-type) - [The `event_descriptor` Type](#the-event_descriptor-type)
* [Version 0 `external_event_descriptor`](#version-0-external_event_descriptor) - [Version 0 `enum_event_descriptor`](#version-0-enum_event_descriptor)
* [Version 0 `enum_event_descriptor`](#version-0-enum_event_descriptor) - [Version 0 `digit_decomposition_event_descriptor`](#version-0-digit_decomposition_event_descriptor)
* [Version 0 `range_event_descriptor`](#version-0-range_event_descriptor) - [The `oracle_event` Type](#the-oracle_event-type)
* [The `oracle_event` Type](#the-oracle_event-type) - [Version 0 `oracle_event`](#version-0-oracle_event)
* [Version 0 `oracle_event`](#version-0-oracle_event) - [The `oracle_announcement` Type](#the-oracle_announcement-type)
* [The `oracle_announcement` Type](#the-oracle_announcement-type) - [Version 0 `oracle_announcement`](#version-0-oracle_announcement)
* [Version 0 `oracle_announcement`](#version-0-oracle_announcement) - [The `oracle_attestation` Type](#the-oracle_attestation-type)
* [Authors](#authors) - [Version 0 `oracle_attestation`](#version-0-oracle_attestation)
- [Authors](#authors)
## Connection Handling and Multiplexing ## Connection Handling and Multiplexing
@@ -183,7 +185,7 @@ This type of oracle info is for single-oracle events.
* [`u16`:`num_oracles`] * [`u16`:`num_oracles`]
* [`oracle_announcement`:`oracle_announcement_1`] * [`oracle_announcement`:`oracle_announcement_1`]
* ... * ...
* [`oracle_announcment`:`oracle_announcement_num_oracles`] * [`oracle_announcement`:`oracle_announcement_num_oracles`]
This type of oracle info is for multi-oracle events where all oracles are signing messages chosen This type of oracle info is for multi-oracle events where all oracles are signing messages chosen
from a set of messages that exactly corresponds to the set of messages being signed by the other oracles, from a set of messages that exactly corresponds to the set of messages being signed by the other oracles,
@@ -329,6 +331,86 @@ as every input must be Segwit. Witness elements should *not* include their lengt
Witnesses should be sorted by the `input_serial_id` sent in `funding_input` defining these inputs. Witnesses should be sorted by the `input_serial_id` sent in `funding_input` defining these inputs.
### The `event_descriptor` Type
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.
#### Version 0 `enum_event_descriptor`
1. type: 55302 (`enum_event_descriptor_v0`)
2. data:
* [`u16`:`num_outcomes`]
* [`string`:`outcome_1`]
* ...
* [`string`:`outcome_n`]
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.
#### Version 0 `digit_decomposition_event_descriptor`
1. type: 55306 (`digit_decomposition_event_descriptor_v0`)
2. data:
* [`bigsize`:`base`]
* [`bool`:`is_signed`]
* [`string`:`unit`]
* [`int32`:`precision`]
* [`u16`:`nb_digits`]
### 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.
#### Version 0 `oracle_event`
1. type: 55330 (`oracle_event_v0`)
2. data:
* [`u16`:`nb_nonces`]
* [`nb_nonces*x_point`:`oracle_nonces`]
* [`u32`:`event_maturity_epoch`]
* [`event_descriptor`:`event_descriptor`]
* [`string`:`event_id`]
### The `oracle_announcement` Type
This type contains an `oracle_event` and a signature certifying its origination.
See [the Oracle specifications](./Oracle.md#oracle-announcements) for more details.
#### Version 0 `oracle_announcement`
1. type: 55332 (`oracle_announcement`)
2. data:
* [`signature`:`annoucement_signature`]
* [`x_point`:`oracle_public_key`]
* [`oracle_event`:`oracle_event`]
where `signature` is a Schnorr signature over a sha256 hash of the serialized `oracle_event`, using the tag `announcement/v0`.
### The `oracle_attestation` Type
This type contains information about the outcome of an event and the signature(s) over its outcome value(s).
See [the Oracle specifications](./Oracle.md#oracle-attestations) for more details.
#### Version 0 `oracle_attestation`
1. type: 55400 (`oracle_attestation_v0`)
2. 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`.
The outcomes should be the message signed, ordered the same as the signatures.
## Authors ## Authors
Nadav Kohen <nadavk25@gmail.com> Nadav Kohen <nadavk25@gmail.com>

74
Oracle.md
View File

@@ -15,15 +15,11 @@ This necessary information is committed to in a so-called [_event descriptor_](#
- [Example: BTC/USD rate](#example-btcusd-rate) - [Example: BTC/USD rate](#example-btcusd-rate)
- [Serialization and signing of outcome values](#serialization-and-signing-of-outcome-values) - [Serialization and signing of outcome values](#serialization-and-signing-of-outcome-values)
- [Serialization of event descriptors](#serialization-of-event-descriptors) - [Serialization of event descriptors](#serialization-of-event-descriptors)
- [Version 0 `enum_event_descriptor`](#version-0-enum_event_descriptor)
- [Version 0 `digit_decomposition_event_descriptor`](#version-0-digit_decomposition_event_descriptor)
- [Oracle events](#oracle-events) - [Oracle events](#oracle-events)
- [Version 0 `oracle_event`](#version-0-oracle_event)
- [Oracle announcements](#oracle-announcements) - [Oracle announcements](#oracle-announcements)
- [Version 0 `oracle_announcement`](#version-0-oracle_announcement)
- [Oracle Attestations](#oracle-attestations) - [Oracle Attestations](#oracle-attestations)
- [Version 0 `oracle_attestation`](#version-0-oracle_attestation)
- [Signing Algorithm](#signing-algorithm) - [Signing Algorithm](#signing-algorithm)
- [Footnotes](#footnotes)
## Event descriptor ## Event descriptor
@@ -102,30 +98,7 @@ Signing should be done using the [signing algorithm](#Signing-Algorithm) using t
### Serialization of event descriptors ### Serialization of event descriptors
Event descriptors should be serialized using [TLV format](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md#type-length-value-format) as described bellow. Event descriptors should be serialized using [TLV format](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md#type-length-value-format) as described in [the Messaging specifications](./Messaging.md##the-event_descriptor-type).
#### Version 0 `enum_event_descriptor`
1. type: 55302 (`enum_event_descriptor_v0`)
2. data:
* [`u16`:`num_outcomes`]
* [`string`:`outcome_1`]
* ...
* [`string`:`outcome_n`]
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.
#### Version 0 `digit_decomposition_event_descriptor`
1. type: 55306 (`digit_decomposition_event_descriptor_v0`)
2. data:
* [`bigsize`:`base`]
* [`bool`:`is_signed`]
* [`string`:`unit`]
* [`int32`:`precision`]
* [`u16`:`nb_digits`]
### Oracle events ### Oracle events
@@ -136,17 +109,7 @@ Oracle events contain such information, which includes:
* the event descriptor, * the event descriptor,
* the event ID which can be a name or categorization associated with the event by the oracle. * the event ID which can be a name or categorization associated with the event by the oracle.
The TLV serialization for oracle events is as follow: The TLV serialization for oracle events is given in [the Messaging specifications](./Messaging.md#the-oracle_event-type).
#### Version 0 `oracle_event`
1. type: 55330 (`oracle_event_v0`)
2. data:
* [`u16`:`nb_nonces`]
* [`nb_nonces*x_point`:`oracle_nonces`]
* [`u32`:`event_maturity_epoch`]
* [`event_descriptor`:`event_descriptor`]
* [`string`:`event_id`]
## Oracle announcements ## Oracle announcements
@@ -155,41 +118,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. 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 as follow. The TLV serialization of oracle announcements is given in [the Messaging specifications](./Messaging.md#the-oracle_announcement-type).
#### Version 0 `oracle_announcement`
1. type: 55332 (`oracle_announcement`)
2. data:
* [`signature`:`annoucement_signature`]
* [`x_point`:`oracle_public_key`]
* [`oracle_event`:`oracle_event`]
where `signature` is a Schnorr signature over a sha256 hash of the serialized `oracle_event`, using the tag `announcement/v0`.
## Oracle Attestations ## Oracle Attestations
After an event occurs, and the oracle creates signatures to attest the outcome, it needs to give them to users. 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. An oracle can use an attestation tlv to give users this information.
The TLV serialization of oracle attestations is as follows. The TLV serialization of oracle attestations is given in [the Messaging specifications](./Messaging.md#the-oracle_attestation-type).
#### Version 0 `oracle_attestation`
1. type: 55400 (`oracle_attestation_v0`)
2. 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`.
The outcomes should be the message signed, ordered the same as the signatures.
## Signing Algorithm ## Signing Algorithm