dlcspecs/Messaging.md

Messaging Protocol

Overview

This protocol assumes an underlying authenticated and ordered transport mechanism that takes care of framing individual messages. BOLT #8 specifies the canonical transport layer used in Lightning, though it can be replaced by any transport that fulfills the above guarantees.

All data fields are unsigned big-endian unless otherwise specified.

Table of Contents

• Connection Handling and Multiplexing
• Message Format
• Fundamental Types
• DLC Specific Types
  • The contract_info Type
    • Version 0 contract_info
    • Version 1 contract_info
  • The contract_descriptor Type
    • Version 0 contract_descriptor
    • Version 1 contract_descriptor
  • The oracle_info Type
    • Version 0 oracle_info
    • Version 1 oracle_info
    • Version 2 oracle_info
  • The oracle_params Type
    • Version 0 oracle_params
  • The negotiation_fields Type
    • Version 0 negotiation_fields
    • Version 1 negotiation_fields
    • Version 2 negotiation_fields
  • The funding_input Type
    • Version 0 funding_input
  • The cet_adaptor_signatures Type
    • Version 0 cet_adaptor_signatures
  • The funding_signatures Type
    • Version 0 funding_signatures
  • The event_descriptor Type
    • Version 0 enum_event_descriptor
    • Version 0 digit_decomposition_event_descriptor
  • The oracle_event Type
    • Version 0 oracle_event
  • The oracle_announcement Type
    • Version 0 oracle_announcement
  • The oracle_attestation Type
    • Version 0 oracle_attestation
• Authors

Connection Handling and Multiplexing

Implementations MUST use a single connection per peer; contract messages (which include a contract ID) are multiplexed over this single connection.

Message Format

We reuse the Lightning Message Format and the Type-Length-Value Format (TLV). To be clear, any encoded binary blob that can be sent over the wire will follow the Lightning Message Format while all sub-types internal to these messages will follow the Type-Length-Value Format. This means that types on outer-messages will be represented with u16 integers (defined below) and their length is omitted from their encoding because the transport layer has the length in a separate unencrypted field. Meanwhile all typed sub-messages (which follow TLV format) will have their types represented using bigsize integers (defined below) and their lengths (also bigsize) are included in their encodings.

Fundamental Types

Various fundamental types are referred to in the message specifications:

• byte: an 8-bit byte
• u16: a 2 byte unsigned integer
• u32: a 4 byte unsigned integer
• u64: an 8 byte unsigned integer
• int32: a 4 byte signed integer
• bool: a boolean value represented as a byte which can have only two value, 0x01 to represent true and 0x00 to represent false (any other value should be considered invalid).

Inside TLV records which contain a single value, leading zeros in integers can be omitted:

• tu16: a 0 to 2 byte unsigned integer
• tu32: a 0 to 4 byte unsigned integer
• tu64: a 0 to 8 byte unsigned integer

The following convenience types are also defined:

• chain_hash: a 32-byte chain identifier (see BOLT #0)
• contract_id: a 32-byte contract_id (see Protocol Specification)
• sha256: a 32-byte SHA2-256 hash
• signature: a 64-byte bitcoin Elliptic Curve signature
• ecdsa_adaptor_signature: a 65-byte ECDSA adaptor signature (TODO: link to doc once #50 is done)
• dleq_proof: a 97-byte zero-knowledge proof of discrete log equality (TODO: link to doc once #50 is done)
• x_point: a 32-byte x-only public key with implicit y-coordinate being even as in BIP 340
• point: a 33-byte Elliptic Curve point (compressed encoding as per SEC 1 standard)
• spk: A bitcoin script public key encoded as ASM prefixed with a u16 value indicating its length.
• short_contract_id: an 8 byte value identifying a contract funding transaction on-chain (see BOLT #7)
• bigsize: a variable-length, unsigned integer similar to Bitcoin's CompactSize encoding, but big-endian. Described in BigSize.
• string: a UTF-8 encoded string using NFC for normalization, prefixed by a bigsize value indicating its length in bytes.

DLC Specific Types

The following DLC-specific types are used throughout the specification. All type numbers are placeholders subject to change both here and in Protocol.md.

The contract_info Type

This type contains information about a contract's outcomes, their corresponding payouts, and the oracles to be used.

Version 0 contract_info

1. type: 55342 (contract_info_v0)
2. data:
   • [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.

Version 1 contract_info

1. type: 55344 (contract_info_v1)
2. data:
   • [u64:total_collateral]
   • [bigsize:num_disjoint_events]
   • [contract_descriptor:contract_descriptor_1]
   • [oracle_info:oracle_info_1]
   • ...
   • [contract_descriptor:contract_descriptor_num_disjoint_events]
   • [oracle_info:oracle_info_num_disjoint_events]

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

Each contract_descriptor and oracle_info pair determines a set of CETs so that this contract_info determines the union of these CET sets. The order of CET adaptor signatures for a disjoint union DLC is simply the ordered (by index above) concatenation of the CET set order as it would be computed for contract_info_v0.

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]
   • ...
   • [string:outcome_num_outcomes]
   • [u64:payout_num_outcomes]

This type represents an enumerated outcome contract.

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. The type rounding_intervals is defined here.

The oracle_info Type

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:
   • [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_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, 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.

The type rounding_intervals is defined here.

Version 2 negotiation_fields

1. type: 55346 (negotiation_fields_v2)
2. data:
   • [bigsize:num_disjoint_events]
   • [negotiation_fields:negotiation_fields_1]
   • ...
   • [negotiation_fields:negotiation_fields_num_disjoint_events]

This type is used within dlc_accept messages that respond to dlc_offers containing a contract_info_v1. The num_disjoint_events here must be equal to the num_disjoint_events in that contract_info_v1 and all of the negotiation_fields nested here must be version 0 or 1.

The funding_input Type

This type contains information about a specific input to be used in a funding transaction, as well as its corresponding on-chain UTXO.

Version 0 funding_input

1. type: 42772 (funding_input_v0)
2. data:
   • [u64:input_serial_id]
   • [u16:prevtx_len]
   • [prevtx_len*byte:prevtx]
   • [u32:prevtx_vout]
   • [u32:sequence]
   • [u16:max_witness_len]
   • [spk:redeemscript]

input_serial_id is a randomly chosen number which uniquely identifies this input. Inputs in the funding transaction will be sorted by input_serial_id.

prevtx_tx is the serialized transaction whose prevtx_vout output is being spent. The transaction is used to validate this spent output's value and to validate that it is a SegWit output.

max_witness_len is the total serialized length of the witness data that will be supplied (e.g. sizeof(varint) + sizeof(witness) for each) in funding_signatures.

redeemscript the witness script public key to be revealed for P2SH spending. Only applicable for P2SH-wrapped inputs. In all native Segwit inputs, redeemscript will be a u16 zero (from the spk size prefix). Note that when doing fee computation, script_sig_len is either zero in the case that redeemscript is empty or else it is equal to 1 + len(redeemscript) where the added byte is for pushing redeemscript onto the stack in the script signature.

The cet_adaptor_signatures Type

This type contains CET signatures and any necessary information linking the signatures to their corresponding outcome.

Version 0 cet_adaptor_signatures

1. type: 42774 (cet_adaptor_signatures_v0)
2. data:
   • [bigsize:nb_signatures]
   • [ecdsa_adaptor_signature:signature_1]
   • [dleq_proof:dleq_prf_1]
   • ...
   • [ecdsa_adaptor_signature:signature_n]
   • [dleq_proof:dleq_prf_n]

This type should be used with contract_info_v0 where each indexed signature in the data corresponds to the outcome of the same index.

The funding_signatures Type

This type contains signatures of the funding transaction and any necessary information linking the signatures to their inputs.

Version 0 funding_signatures

1. type: 42776 (funding_signatures_v0)
2. data:
   • [u16:num_witnesses]
   • [u16:num_witness_elems_1]
   • [num_witness_elems_1*witness_element:witness_elements_1]
   • ...
   • [u16:num_witness_elems_num_witnesses]
   • [num_witness_elems_num_witnesses*witness_element:witness_elements_num_witnesses]
3. subtype: witness_element
4. data:
   • [u16:len]
   • [len*byte:witness]

witness is the data for a witness element in a witness stack. An empty witness_stack is an error, as every input must be Segwit. Witness elements should not include their length as part of the witness data.

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 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 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 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 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 nadavk25@gmail.com

Ben Carman benthecarman@live.com

This work is licensed under a Creative Commons Attribution 4.0 International License.