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
    • The oracle_info Type
      • Version 0 oracle_info
    • 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 external_event_descriptor
      • Version 0 enum_event_descriptor
      • Version 0 range_event_descriptor
    • The oracle_event Type
      • Version 0 oracle_event
    • The oracle_announcement Type
      • Version 0 oracle_announcement
• 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 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.

Version 0 contract_info

1. type: 42768 (contract_info_v0)
2. data:
   • [sha256:outcome_1]
   • [u64:outcome_1_local_payout]
   • ...
   • [sha256:outcome_n]
   • [u64:outcome_n_local_payout]

This type of contract info is a simple enumeration where the value n is omitted from being explicitly included as it can be derived from the length field of the TLV.

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.

Version 0 oracle_info

1. type: 42770 (oracle_info_v0)
2. data:
   • [x_point:oracle_public_key]
   • [x_point:oracle_nonce]

This type of oracle info is for single-oracle, single signature (and hence single nonce) events.

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:
   • [u16:prevtx_len]
   • [prevtx_len*byte:prevtx]
   • [u32:prevtx_vout]
   • [u32:sequence]
   • [u16:max_witness_len]
   • [spk:redeemscript]

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:
   • [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. As in contract_info_v0, the number of signatures is omitted as it can be derived from the length field of the TLV.

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.

Authors

Nadav Kohen nadavk25@gmail.com

Ben Carman benthecarman@live.com

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