Skip to content
Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
291 lines (235 sloc) 12.6 KB

BMW #0: Introduction and Index

Welcome, friend! These BOLT MimbleWimble (BMW) documents describe a layer-2 protocol for off-chain MimbleWimble asset transfer by mutual cooperation, relying on on-chain transactions for enforcement if necessary.

Some requirements are subtle; we have tried to highlight motivations and reasoning behind the results you see here. I'm sure we've fallen short; if you find any part confusing or wrong, please contact us and help us improve.

As these documents are designed to be implementation agnostic so for a better reading experience we describe everything using the fictional mw-coin (MWC) instead of any implementation specific currency.

This is version 0.

  1. BMW #1: Base Protocol
  2. BMW #2: Peer Protocol for Channel Management
  3. BMW #3: Mw-coin Transaction and Script Formats
  4. BMW #4: Onion Routing Protocol
  5. BMW #5: Recommendations for On-chain Transaction Handling
  6. BMW #7: P2P Node and Channel Discovery
  7. BMW #8: Encrypted and Authenticated Transport
  8. BMW #9: Assigned Feature Flags
  9. BMW #10: DNS Bootstrap and Assisted Node Location
  10. BMW #11: Invoice Protocol for Lightning Payments

The Spark: A Short Introduction to Lightning

Lightning is a protocol for making fast payments with any compatible cryptocurrency using a network of channels.

Channels

Lightning works by establishing channels: two participants create a Lightning payment channel that contains some amount of mw-coin (e.g., 0.1 MWC) that they've locked up on the network. It is spendable only with both their signatures.

Initially they each hold a mw-coin transaction that sends all the mw-coin (e.g. 0.1 mw-coin) back to one party. They can later sign a new mw-coin transaction that splits these funds differently, e.g. 0.09 mw-coin to one party, 0.01 mw-coin to the other, and invalidate the previous mw-coin transaction so it won't be spent.

See BMW #2: Channel Establishment for more on channel establishment and BMW #3: Funding Transaction Output for the format of the mw-coin transaction that creates the channel. See BMW #5: Recommendations for On-chain Transaction Handling for the requirements when participants disagree or fail, and the cross-signed mw-coin transaction must be spent.

Conditional Payments

A Lightning channel only allows payment between two participants, but channels can be connected together to form a network that allows payments between all members of the network. This requires the technology of a conditional payment, which can be added to a channel, e.g. "you get 0.01 mw-coin if you reveal the secret within 6 hours". Once the recipient presents the secret, that mw-coin transaction is replaced with one lacking the conditional payment and adding the funds to that recipient's output.

See BMW #2: Adding an HTLC for the commands a participant uses to add a conditional payment, and BMW #3: Commitment Transaction for the complete format of the mw-coin transaction.

Forwarding

Such a conditional payment can be safely forwarded to another participant with a lower time limit, e.g. "you get 0.01 mw-coin if you reveal the secret within 5 hours". This allows channels to be chained into a network without trusting the intermediaries.

See BMW #2: Forwarding HTLCs for details on forwarding payments, BMW #4: Packet Structure for how payment instructions are transported.

Network Topology

To make a payment, a participant needs to know what channels it can send through. Participants tell each other about channel and node creation, and updates.

See BMW #7: P2P Node and Channel Discovery for details on the communication protocol, and BMW #10: DNS Bootstrap and Assisted Node Location for initial network bootstrap.

Payment Invoicing

A participant receives invoices that tell her what payments to make.

See BMW #11: Invoice Protocol for Lightning Payments for the protocol describing the destination and purpose of a payment such that the payer can later prove successful payment.

Glossary and Terminology Guide

FIXME: Update these definitions according to changes in other BMWs.

  • Announcement:

    • A gossip message sent between peers intended to aid the discovery of a channel or a node.
  • chain_hash:

    • The uniquely identifying hash of the target blockchain (usually the genesis hash). This allows nodes to create and reference channels on several blockchains. Nodes are to ignore any messages that reference a chain_hash that are unknown to them. Unlike bitcoin-cli, the hash is not reversed but is used directly.
  • Channel:

    • A fast, off-chain method of mutual exchange between two peers. To transact funds, peers exchange signatures to create an updated commitment transaction.
    • See closure methods: mutual close, revoked transaction close, unilateral close
    • See related: route
  • Closing transaction:

    • A transaction generated as part of a mutual close. A closing transaction is similar to a commitment transaction, but with no pending payments.
    • See related: commitment transaction, funding transaction, penalty transaction
  • Commitment number:

    • A 48-bit incrementing counter for each commitment transaction; counters are independent for each peer in the channel and start at 0.
    • See container: commitment transaction
    • See related: closing transaction, funding transaction, penalty transaction
  • Commitment revocation private key:

    • Every commitment transaction has a unique commitment revocation pre-image value that allows the other peer to spend all outputs immediately: revealing this value is how old commitment transactions are revoked. To support revocation, each output of the commitment transaction refers to the commitment revocation image.
    • See container: commitment transaction
  • Commitment transaction:

    • A transaction that spends the funding transaction. Each peer holds the other peer's signature for this transaction, so that each always has a commitment transaction that it can spend. After a new commitment transaction is negotiated, the old one is revoked.
    • See parts: commitment number, HTLC, outpoint
    • See related: closing transaction, funding transaction, penalty transaction
    • See types: revoked commitment transaction
  • Final node:

    • The final recipient of a packet that is routing a payment from an origin node through some number of hops. It is also the final receiving peer in a chain.
    • See category: node
    • See related: origin node, processing node
  • Funding transaction:

    • An irreversible on-chain transaction that pays to both peers on a channel. It can only be spent by mutual consent.
    • See related: closing transaction, commitment transaction, penalty transaction
  • Hop:

    • A node. Generally, an intermediate node lying between an origin node and a final node.
    • See category: node
  • HTLC: Hashed Time Locked Contract.

    • A conditional payment between two peers: the recipient can spend the payment by presenting its signature and a payment preimage, otherwise the payer can cancel the contract by spending it after a given time. These are implemented as outputs from the commitment transaction.
    • See container: commitment transaction
    • See parts: Payment hash, Payment preimage
  • Invoice: A request for funds on the Lightning Network, possibly including payment type, payment amount, expiry, and other information. This is how payments are made on the Lightning Network, rather than using Bitcoin-style addresses.

  • It's ok to be odd:

    • A rule applied to some numeric fields that indicates either optional or compulsory support for features. Even numbers indicate that both endpoints MUST support the feature in question, while odd numbers indicate that the feature MAY be disregarded by the other endpoint.
  • Mutual close:

    • A cooperative close of a channel, accomplished by broadcasting an unconditional spend of the funding transaction with an output to each peer (unless one output is too small, and thus is not included).
    • See related: revoked transaction close, unilateral close
  • Node:

    • A computer or other device that is part of the Lightning network.
    • See related: peers
    • See types: final node, hop, origin node, processing node, receiving node, sending node
  • Origin node:

    • The node that originates a packet that will route a payment through some number of hops to a final node. It is also the first sending peer in a chain.
    • See category: node
    • See related: final node, processing node
  • Outpoint:

    • A transaction hash and output index that uniquely identify an unspent transaction output. Needed to compose a new transaction, as an input.
    • See related: funding transaction, commitment transaction
  • Payment hash:

    • The HTLC contains the payment hash, which is the hash of the payment preimage.
    • See container: HTLC
    • See originator: payment preimage
  • Payment preimage:

    • Proof that payment has been received, held by the final recipient, who is the only person who knows this secret. The final recipient releases the preimage in order to release funds. The payment preimage is hashed as the payment hash in the HTLC.
    • See container: HTLC
    • See derivation: payment hash
  • Peers:

    • Two nodes that are in communication with each other.
      • Two peers may gossip with each other prior to setting up a channel.
      • Two peers may establish a channel through which they transact.
    • See related: node
  • Penalty transaction:

    • A transaction that spends all outputs of a revoked commitment transaction, using the commitment revocation private key. A peer uses this if the other peer tries to "cheat" by broadcasting a revoked commitment transaction.
    • See related: closing transaction, commitment transaction, funding transaction
  • Processing node:

    • A node that is processing a packet that originated with an origin node and that is being sent toward a final node in order to route a payment. It acts as a receiving peer to receive the message, then a sending peer to send on the packet.
    • See category: node
    • See related: final node, origin node
  • Receiving node:

    • A node that is receiving a message.
    • See category: node
    • See related: sending node
  • Receiving peer:

    • A node that is receiving a message from a directly connected peer.
    • See category: peer
    • See related: sending peer
  • Revoked commitment transaction:

    • An old commitment transaction that has been revoked because a new commitment transaction has been negotiated.
    • See category: commitment transaction
  • Revoked transaction close:

    • An invalid close of a channel, accomplished by broadcasting a revoked commitment transaction. Since the other peer knows the commitment revocation secret key, it can create a penalty transaction.
    • See related: mutual close, unilateral close
  • Route: A path across the Lightning Network that enables a payment from an origin node to a final node across one or more hops.

    • See related: channel
  • Sending node:

    • A node that is sending a message.
    • See category: node
    • See related: receiving node
  • Sending peer:

    • A node that is sending a message to a directly connected peer.
    • See category: peer
    • See related: receiving peer.
  • Unilateral close:

    • An uncooperative close of a channel, accomplished by broadcasting a commitment transaction. This transaction is larger (i.e. less efficient) than a mutual close transaction, and the peer whose commitment is broadcast cannot access its own outputs for some previously-negotiated duration.
    • See related: mutual close, revoked transaction close

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

You can’t perform that action at this time.