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

Generalized contract_info TLV #130

Merged
merged 4 commits into from
Feb 16, 2021
Merged

Generalized contract_info TLV #130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7d59db4
Updated TLVs to allow support for numeric outcome and multiple oracle…
nkohen Jan 12, 2021
6df0830
Added threshold field to multi-oracle oracle_infos
nkohen Jan 13, 2021
2fda0dd
Responded to review
nkohen Feb 15, 2021
4ed7fda
Some more review
nkohen Feb 16, 2021
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
131 changes: 119 additions & 12 deletions Messaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,18 @@ All data fields are unsigned big-endian unless otherwise specified.
* [DLC Specific Types](#dlc-specific-types)
* [The `contract_info` Type](#the-contract_info-type)
* [Version 0 `contract_info`](#version-0-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)
* [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)
Expand Down Expand Up @@ -87,33 +97,130 @@ The following DLC-specific types are used throughout the specification. All type

### The `contract_info` Type

This type contains information about a contracts outcomes and their corresponding payouts. To save space, only one side's POV is included in this message as the other can be derived using `remote_payout = total_collateral - local_payout`.
This type contains information about a contract's outcomes, their corresponding payouts, and the oracles to be used.

#### Version 0 `contract_info`

1. type: 42768 (`contract_info_v0`)
1. type: 55342 (`contract_info_v0`)
2. data:
* [`bigsize`:`nb_outcomes`]
* [`sha256`:`outcome_1`]
* [`u64`:`outcome_1_local_payout`]
* [`u64`:`total_collateral`]
* [`contract_descriptor`:`contract_descriptor`]
* [`oracle_info`:`oracle_info`]

`total_collateral` is the Satoshi-denominated value of the sum of all party's collateral.

### The `contract_descriptor` Type

This type contains information about a contract's outcomes and their corresponding payouts.

To save space, only the offerer's payouts are included in this message as the accepter's can be derived using
`accept_payout = total_collateral - offer_payout`.

#### Version 0 `contract_descriptor`

1. type: 42768 (`contract_descriptor_v0`)
2. data:
* [`bigsize`:`num_outcomes`]
* [`string`:`outcome_1`]
* [`u64`:`payout_1`]
* ...
* [`sha256`:`outcome_n`]
* [`u64`:`outcome_n_local_payout`]
* [`string`:`outcome_num_outcomes`]
* [`u64`:`payout_num_outcomes`]

This type represents an enumerated outcome contract.

This type of contract info is a simple enumeration of pairs of the hash of an outcome value with the corresponding payout for the local party.
#### Version 1 `contract_descriptor`

1. type: 42784 (`contract_descriptor_v1`)
2. data:
* [`u16`:`num_digits`]
* [`payout_function`:`payout_function`]
* [`rounding_intervals`:`rounding_intervals`]

This type represents a numeric outcome contract.

The type `payout_function` is defined [here](PayoutCurve.md#curve-serialization).
The type `rounding_intervals` is defined [here](NumericOutcome.md#rounding-interval-serialization).

### The `oracle_info` Type

This type contains information about the oracle(s) to be used in executing a DLC, and possibly the outcomes possible if these are not specified in the corresponding `contract_info`.
This type contains information about the oracles to be used in executing a DLC.

#### Version 0 `oracle_info`

1. type: 42770 (`oracle_info_v0`)
2. data:
* [`x_point`:`oracle_public_key`]
* [`x_point`:`oracle_nonce`]
* [`oracle_announcement`:`oracle_announcement`]

This type of oracle info is for single-oracle events.

#### Version 1 `oracle_info`

1. type: 42786 (`oracle_info_v1`)
2. data:
* [`u16`:`threshold`]
* [`u16`:`num_oracles`]
* [`oracle_announcement`:`oracle_announcement_1`]
* ...
* [`oracle_announcment`:`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,
and any `threshold` oracles must sign (exactly) corresponding messages for execution to happen.

#### Version 2 `oracle_info`

1. type: 55340 (`oracle_info_v2`)
2. data:
* [`u16`:`threshold`]
* [`u16`:`num_oracles`]
* [`oracle_announcement`:`oracle_announcement_1`]
* ...
* [`oracle_announcment`:`oracle_announcement_num_oracles`]
* [`oracle_params`:`oracle_params`]

The order of the oracle announcements represents a total ordering of preference on the oracles.

This type of oracle info is for multi-oracle numeric events where allowed differences in the values
signed by oracles is specified in `oracle_params`.

### The `oracle_params` Type

Contains information about how oracle information is used in a given contract.

#### Version 0 `oracle_params`

1. type: 55338 (`oracle_params_v0`)
2. data
* [`u16`:`maxErrorExp`]
* [`u16`:`minFailExp`]
* [`bool`:`maximize_coverage`]

This type is used when the error bound requirements for any set of oracles `threshold` oracles in a
multi-oracle numeric outcome DLC with allowed error is the same.

### The `negotiation_fields` Type

This type contains preferences of the accepter of a DLC which are taken into account during DLC construction.

#### Version 0 `negotiation_fields`

1. type: 55334 (`negotiation_fields_v0`)
2. data:
* (empty)

This type signifies that the accepter has no negotiation fields.

#### Version 1 `negotiation_fields`

1. type: 55336 (`negotiation_fields_v1`)
2. data
* [`rounding_intervals`: `rounding_intervals`]

`rounding_intervals` represents the maximum amount of allowed rounding at any possible oracle outcome
in a numeric outcome DLC.

This type of oracle info is for single-oracle, single signature (and hence single nonce) events.
The type `rounding_intervals` is defined [here](NumericOutcome.md#rounding-interval-serialization).

### The `funding_input` Type

Expand Down
9 changes: 4 additions & 5 deletions Protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,6 @@ the funding transaction and CETs.
* [`byte`:`contract_flags`]
* [`chain_hash`:`chain_hash`]
* [`contract_info`:`contract_info`]
* [`oracle_info`:`oracle_info`]
* [`point`:`funding_pubkey`]
* [`spk`:`payout_spk`]
* [`u64`:`total_collateral_satoshis`]
Expand All @@ -87,8 +86,7 @@ The existence of the `chain_hash` allows nodes to open contracts
across many distinct blockchains as well as have contracts within multiple
blockchains opened to the same peer (if it supports the target chains).

`contract_info` specifies the sender's payouts for all events. `oracle_info`
specifies the oracle(s) to be used as well as their commitments to events.
`contract_info` specifies the contract to be constructed and the oracles to be used.

`funding_pubkey` is the public key in the 2-of-2 multisig script of
the funding transaction output. `payout_spk` specifies the script
Expand Down Expand Up @@ -133,7 +131,7 @@ The receiving node MAY reject the contract if:

- it does not agree to the terms in `contract_info`.
- the `contract_info` is missing relevant events.
- it does not want to use the oracle(s) specified in `oracle_info`.
- it does not want to use the oracle(s) specified in `contract_info`.
- `total_collateral_satoshis` is too small.
- `feerate_per_vb` is too small.
- `feerate_per_vb` is too large.
Expand All @@ -142,7 +140,7 @@ The receiving node MUST reject the contract if:

- the `chain_hash` value is set to a hash of a chain that is unknown to the receiver.
- the `contract_info` refers to events unknown to the receiver.
- the `oracle_info` refers to an oracle unknown or inaccessible to the receiver.
- the `contract_info` refers to an oracle unknown or inaccessible to the receiver.
- it considers `feerate_per_vb` too small for timely processing or unreasonably large.
- `funding_pubkey` is not a valid secp256k1 pubkey in compressed format.
- `funding_inputs` do not contribute at least `total_collateral_satoshis` plus full [fee payment](Transactions.md#fee-payment).
Expand All @@ -165,6 +163,7 @@ and closing transactions.
* [`spk`:`change_spk`]
* [`cet_adaptor_signatures`:`cet_adaptor_signatures`]
* [`signature`:`refund_signature`]
* [`negotiation_fields`:`negotiation_fields`]

#### Requirements

Expand Down