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
  • Wire Messages
  • Type-Length-Value
  • Sub-types
    • Plain sub-type
    • Sibling sub-type
    • Optional sub-type
• Fundamental Types
• DLC Specific Types
  • The contract_info Type
    • single_contract_info
    • disjoint_contract_info
  • The contract_descriptor Type
    • enumerated_contract_descriptor
    • numeric_outcome_contract_descriptor
  • The oracle_info Type
    • single_oracle_info
    • multi_oracle_info
  • The oracle_params Type
    • oracle_params
  • The negotiation_fields Type
    • single_negotiation_fields
    • disjoint_negotiation_fields
  • The funding_input Type
    • funding_input
  • The cet_adaptor_signatures Type
    • cet_adaptor_signatures
  • The funding_signatures Type
    • funding_signatures
  • The event_descriptor Type
    • enum_event_descriptor
    • digit_decomposition_event_descriptor
  • The oracle_event Type
    • oracle_event
  • The oracle_announcement Type
    • oracle_announcement
  • The oracle_attestation Type
    • 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 for messages sent over the wire, the Type-Length-Value Format (TLV) for message extensibility and extra features support, and a custom format for sub-types.

Note that contrary to the LN messages, collections of items are prefixed with a BigSize and not a u16.

Test vectors for serialization are available here.

Wire Messages

Any encoded binary blob that can be sent over the wire will follow the Lightning Message Format. This means that wire messages are prefixed with a u16 field (defined below) and their length is omitted from their encoding because the transport layer has the length in a separate un-encrypted field.

Type-Length-Value

A TLV stream is defined for each wire message, and can be used to extend the protocol and for application specific features. See the Type-Length-Value Format section in the LN BOLTs for specifications.

Sub-types

Wire messages (and sub-types themselves) contain embedded data structures. These sub-types can have three functions:

• Plain sub-types to factor out a number of fields to make specifications clearer,
• Sibling sub-types to support multiple variants of a field,
• Optional sub-types to support optional fields.

Plain sub-type

Plain sub-types do not have any particular format, and their field can simply be replaced in place where they are used.

For example, the funding input type is a plain sub-type which does not require any particular prefix.

Sibling sub-type

Sibling sub-types are prefixed with a bigsize type identifier. The type identifiers are specific to a set of type variants, and can thus be reused across different sub-types. Type identifiers are defined within the type definitions, starting from 0 and increasing by 1.

Optional sub-type

Optional sub-types are prefixed with a single byte where:

• 0x00 means that the field is absent
• 0x01 means that the field is present

Optional fields are denoted in this specification using the notation Optional(field_type) where field_type is the type of the optional field.

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.

single_contract_info

1. implements: contract_info
2. type: 0
3. 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.

disjoint_contract_info

1. implements: contract_info
2. type: 1
3. 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.

Validity requirement For a contract descriptor to be valid, it is necessary that a single payout is defined for any possible outcome that can be attested by the oracle(s).

enumerated_contract_descriptor

1. implements: contract_descriptor
2. type: 0
3. 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.

numeric_outcome_contract_descriptor

1. implements: contract_descriptor
2. type: 1
3. 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.

single_oracle_info

1. implements: oracle_info
2. type: 0
3. data:
   • [oracle_announcement:oracle_announcement]

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

multi_oracle_info

1. implements: oracle_info
2. type: 1
3. data:
   • [u16:threshold]
   • [bigsize:num_oracles]
   • [oracle_announcement:oracle_announcement_1]
   • ...
   • [oracle_announcement:oracle_announcement_num_oracles]
   • [Optional(oracle_params): oracle_params]

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

If oracle_params is not provided, then all oracles are expected to be 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.

If oracle_params is provided, allowed differences in the values signed by oracles is specified in oracle_params.

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

The oracle_params Type

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

oracle_params

1. 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.

single_negotiation_fields

1. implements: negotiation_fields
2. type: 0
3. 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.

disjoint_negotiation_fields

1. implements: negotiation_fields
2. type: 1
3. 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.

funding_input

1. data:
   • [u64:input_serial_id]
   • [bigsize: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.

cet_adaptor_signatures

1. data:
   • [bigsize:nb_signatures]
   • [ecdsa_adaptor_signature:signature_1]
   • [dleq_proof:dleq_prf_1]
   • ...
   • [ecdsa_adaptor_signature:signature_n]
   • [dleq_proof:dleq_prf_n]

The funding_signatures Type

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

funding_signatures

1. data:
   • [bigsize:num_witnesses]
   • [bigsize:num_witness_elems_1]
   • [num_witness_elems_1*witness_element:witness_elements_1]
   • ...
   • [bigsize:num_witness_elems_num_witnesses]
   • [num_witness_elems_num_witnesses*witness_element:witness_elements_num_witnesses]
2. subtype: witness_element
3. data:
   • [bigsize: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.

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
2. type: 55302
3. 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.

digit_decomposition_event_descriptor

1. implements: event_descriptor
2. type: 55306
3. 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.

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
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. As oracle announcements can be broadcast directly, they are encoded as wire messages. See the Oracle specifications 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
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). As oracle attestations can be broadcast directly, they are encoded as wire messages. See the Oracle specifications 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_attestation

1. type: 55400
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.