From 08c781021b52cf2a729bec5222c08efe3386fe3a Mon Sep 17 00:00:00 2001 From: Thibaut Le Guilly Date: Tue, 20 Apr 2021 15:52:54 +0900 Subject: [PATCH] Move oracle related TLV info to Messaging.md (#162) --- Messaging.md | 154 +++++++++++++++++++++++++++++++++++++++------------ Oracle.md | 74 ++----------------------- 2 files changed, 123 insertions(+), 105 deletions(-) diff --git a/Messaging.md b/Messaging.md index e4d0dd5..77def64 100644 --- a/Messaging.md +++ b/Messaging.md @@ -9,41 +9,43 @@ 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) - * [Fundamental Types](#fundamental-types) - * [DLC Specific Types](#dlc-specific-types) - * [The `contract_info` Type](#the-contract_info-type) - * [Version 0 `contract_info`](#version-0-contract_info) - * [Version 1 `contract_info`](#version-1-contract_info) - * [The `contract_descriptor` Type](#the-contract_descriptor-type) - * [Version 0 `contract_descriptor`](#version-0-contract_descriptor) - * [Version 1 `contract_descriptor`](#version-1-contract_descriptor) - * [The `oracle_info` Type](#the-oracle_info-type) - * [Version 0 `oracle_info`](#version-0-oracle_info) - * [Version 1 `oracle_info`](#version-1-oracle_info) - * [Version 2 `oracle_info`](#version-2-oracle_info) - * [The `oracle_params` Type](#the-oracle_params-type) - * [Version 0 `oracle_params`](#version-0-oracle_params) - * [The `negotiation_fields` Type](#the-negotiation_fields-type) - * [Version 0 `negotiation_fields`](#version-0-negotiation_fields) - * [Version 1 `negotiation_fields`](#version-1-negotiation_fields) - * [Version 2 `negotiation_fields`](#version-2-negotiation_fields) - * [The `funding_input` Type](#the-funding_input-type) - * [Version 0 `funding_input`](#version-0-funding_input) - * [The `cet_adaptor_signatures` Type](#the-cet_adaptor_signatures-type) - * [Version 0 `cet_adaptor_signatures`](#version-0-cet_adaptor_signatures) - * [The `funding_signatures` Type](#the-funding_signatures-type) - * [Version 0 `funding_signatures`](#version-0-funding_signatures) - * [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 `range_event_descriptor`](#version-0-range_event_descriptor) - * [The `oracle_event` Type](#the-oracle_event-type) - * [Version 0 `oracle_event`](#version-0-oracle_event) - * [The `oracle_announcement` Type](#the-oracle_announcement-type) - * [Version 0 `oracle_announcement`](#version-0-oracle_announcement) -* [Authors](#authors) +- [Connection Handling and Multiplexing](#connection-handling-and-multiplexing) +- [Message Format](#message-format) +- [Fundamental Types](#fundamental-types) +- [DLC Specific Types](#dlc-specific-types) + - [The `contract_info` Type](#the-contract_info-type) + - [Version 0 `contract_info`](#version-0-contract_info) + - [Version 1 `contract_info`](#version-1-contract_info) + - [The `contract_descriptor` Type](#the-contract_descriptor-type) + - [Version 0 `contract_descriptor`](#version-0-contract_descriptor) + - [Version 1 `contract_descriptor`](#version-1-contract_descriptor) + - [The `oracle_info` Type](#the-oracle_info-type) + - [Version 0 `oracle_info`](#version-0-oracle_info) + - [Version 1 `oracle_info`](#version-1-oracle_info) + - [Version 2 `oracle_info`](#version-2-oracle_info) + - [The `oracle_params` Type](#the-oracle_params-type) + - [Version 0 `oracle_params`](#version-0-oracle_params) + - [The `negotiation_fields` Type](#the-negotiation_fields-type) + - [Version 0 `negotiation_fields`](#version-0-negotiation_fields) + - [Version 1 `negotiation_fields`](#version-1-negotiation_fields) + - [Version 2 `negotiation_fields`](#version-2-negotiation_fields) + - [The `funding_input` Type](#the-funding_input-type) + - [Version 0 `funding_input`](#version-0-funding_input) + - [The `cet_adaptor_signatures` Type](#the-cet_adaptor_signatures-type) + - [Version 0 `cet_adaptor_signatures`](#version-0-cet_adaptor_signatures) + - [The `funding_signatures` Type](#the-funding_signatures-type) + - [Version 0 `funding_signatures`](#version-0-funding_signatures) + - [The `event_descriptor` Type](#the-event_descriptor-type) + - [Version 0 `enum_event_descriptor`](#version-0-enum_event_descriptor) + - [Version 0 `digit_decomposition_event_descriptor`](#version-0-digit_decomposition_event_descriptor) + - [The `oracle_event` Type](#the-oracle_event-type) + - [Version 0 `oracle_event`](#version-0-oracle_event) + - [The `oracle_announcement` Type](#the-oracle_announcement-type) + - [Version 0 `oracle_announcement`](#version-0-oracle_announcement) + - [The `oracle_attestation` Type](#the-oracle_attestation-type) + - [Version 0 `oracle_attestation`](#version-0-oracle_attestation) +- [Authors](#authors) + ## Connection Handling and Multiplexing @@ -183,7 +185,7 @@ This type of oracle info is for single-oracle events. * [`u16`:`num_oracles`] * [`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 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. +### 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 Nadav Kohen diff --git a/Oracle.md b/Oracle.md index 79759a2..6fb543e 100644 --- a/Oracle.md +++ b/Oracle.md @@ -15,15 +15,11 @@ This necessary information is committed to in a so-called [_event descriptor_](# - [Example: BTC/USD rate](#example-btcusd-rate) - [Serialization and signing of outcome values](#serialization-and-signing-of-outcome-values) - [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) - - [Version 0 `oracle_event`](#version-0-oracle_event) - [Oracle announcements](#oracle-announcements) - - [Version 0 `oracle_announcement`](#version-0-oracle_announcement) - [Oracle Attestations](#oracle-attestations) - - [Version 0 `oracle_attestation`](#version-0-oracle_attestation) - [Signing Algorithm](#signing-algorithm) +- [Footnotes](#footnotes) ## Event descriptor @@ -102,30 +98,7 @@ Signing should be done using the [signing algorithm](#Signing-Algorithm) using t ### 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. - -#### 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`] +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). ### Oracle events @@ -136,17 +109,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 as follow: - -#### 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 TLV serialization for oracle events is given in [the Messaging specifications](./Messaging.md#the-oracle_event-type). ## 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. -The TLV serialization of oracle announcements is as follow. - -#### 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 TLV 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 as follows. - -#### 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. +The TLV serialization of oracle attestations is given in [the Messaging specifications](./Messaging.md#the-oracle_attestation-type). ## Signing Algorithm