Categorygithub.com/lightningnetwork/lightning-onion
modulepackage
1.2.0
Repository: https://github.com/lightningnetwork/lightning-onion.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
18
Dependents
99
Files
1.9k SLOC

# README

lightning-onion

This repository houses an implementation of the Lightning Network's onion routing protocol. The Lightning Network uses onion routing to securely, and privately route HTLC's (Hash-Time-Locked-Contracts, basically a conditional payment) within the network. (A full specification of the protocol can be found amongst the lighting-rfc repository, specifically within BOLT#04.

The Lightning Network is composed of a series of "payment channels" which are essentially tubes of money whose balances can instantaneous be reallocated between two participants. By linking these payment channels in a pair-wise manner, a network of connect payment channels are created.

Within the Lightning Network, source-routing is utilized in order to give nodes full control over the route their payment follows within the network. This level of control is highly desirable as with it, senders are able to fully specify: the total number of hops in their routes, the total cumulative fee they'll pay to send the payment, and finally the total worst-case time-lock period enforced by the conditional payment contract.

In line with Bitcoin's spirit of decentralization and censorship resistance, we employ an onion routing scheme within the Lightning protocol to prevent the ability of participants on the network to easily censor payments, as the participants are not aware of the final destination of any given payment. Additionally, by encoding payment routes within a mix-net like packet, we are able to achieve the following security and privacy features:

  • Participants in a route don't know their exact position within the route
  • Participants within a route don't know the source of the payment, nor the ultimate destination of the payment
  • Participants within a route aren't aware exactly how many other participants were involved in the payment route
  • Each new payment route is computationally indistinguishable from any other payment route

Our current onion routing protocol utilizes a message format derived from Sphinx. In order to cater Sphinx's mix-format to our specification application, we've made the following modifications:

  • We've added a MAC over the entire mix-header as we have no use for SURB's (single-use-reply-blocks) in our protocol.
  • Additionally, the end-to-end payload to the destination has been removed in order to cut down on the packet-size, and also as we don't currently have a use for a large message from payment sender to recipient.
  • We've dropped usage of LIONESS (as we don't need SURB's), and instead utilize chacha20 uniformly throughout as a stream cipher.
  • Finally, the mix-header has been extended with a per-hop-payload which provides each hops with exact instructions as to how and where to forward the payment. This includes the amount to forward, the destination chain, and the time-lock value to attach to the outgoing HTLC.

For further information see these resources:

In the near future, this repository will be extended to also includes a application specific version of HORNET.

# Packages

No description provided by the author

# Functions

BlankPacketFiller is a packet filler that doesn't attempt to fill out the packet at all.
DeterministicPacketFiller is a packet filler that generates a deterministic set of filler bytes by using chacha20 with a key derived from the session key.
DisableLog disables all library log output.
NewBatch initializes an object for constructing a set of entries to atomically add to a replay log.
NewHopPayload creates a new hop payload given an optional set of forwarding instructions for a hop, and a set of optional opaque extra onion bytes to drop off at the target hop.
NewMemoryReplayLog constructs a new MemoryReplayLog.
NewOnionErrorDecrypter creates new instance of onion decrypter.
NewOnionErrorEncrypter creates new instance of the onion encrypter backed by the passed router, with encryption to be doing using the passed ephemeralKey.
NewOnionPacket creates a new onion packet which is capable of obliviously routing a message through the mix-net path outline by 'paymentPath'.
NewReplaySet initializes an empty replay set.
NewRouter creates a new instance of a Sphinx onion Router given the node's currently advertised onion private key, and the target Bitcoin network.
RandPacketFiller is a packet filler that reads a set of random bytes from a CSPRNG.
ReadVarInt reads a variable length integer from r and returns it as a uint64.
UseLogger uses a specified Logger to output package logging info.
WriteVarInt serializes val to w using a variable number of bytes depending on its value.

# Constants

addressSize is the length of the serialized address used to uniquely identify the next hop to forward the onion to.
AmtForwardSize is the number of bytes that the amount to forward occupies.
ExitNode indicates that the node which processed the Sphinx packet is the destination hop in the route.
Failure indicates that a failure occurred during packet processing.
HashPrefixSize is the size in bytes of the keys we will be storing in the ReplayLog.
HMACSize is the length of the HMACs used to verify the integrity of the onion.
LegacyHopDataSize is the fixed size of hop_data.
MaxPayloadSize is the maximum size a payload for a single hop can be.
MoreHops indicates that there are additional hops left within the route.
NumMaxHops is the maximum path length.
NumPaddingBytes is the number of padding bytes in the hopData.
OutgoingCLTVSize is the number of bytes that the outgoing CLTV value occupies.
PayloadLegacy is the legacy payload type.
PayloadTLV is the new modern TLV based format.
RealmByteSize is the number of bytes that the realm byte occupies.

# Variables

ErrAlreadyCommitted signals that an entry could not be added to the batch because it has already been persisted.
ErrInvalidOnionHMAC is returned during onion parsing process, when received mac does not corresponds to the generated one.
ErrInvalidOnionKey is returned during onion parsing process, when onion key is invalid.
ErrInvalidOnionVersion is returned during decoding of the onion packet, when the received packet has an unknown version byte.
ErrLogEntryNotFound is an error returned when a packet lookup in a replay log fails because it is missing.
No description provided by the author
ErrReplayedPacket is an error returned when a packet is rejected during processing due to being an attempted replay or probing attempt.
ErrVarIntNotCanonical signals that the decoded varint was not minimally encoded.

# Structs

Batch is an object used to incrementally construct a set of entries to add to the replay log.
Circuit is used encapsulate the data which is needed for data deobfuscation.
DecryptedError contains the decrypted error message and its sender.
HopData is the information destined for individual hops.
HopPayload is a slice of bytes and associated payload-type that are destined for a specific hop in the PaymentPath.
MemoryReplayLog is a simple ReplayLog implementation that stores all added sphinx packets and processed batches in memory with no persistence.
OnionErrorDecrypter is a struct that's used to decrypt onion errors in response to failed HTLC routing attempts according to BOLT#4.
OnionErrorEncrypter is a struct that's used to implement onion error encryption as defined within BOLT0004.
OnionHop represents an abstract hop (a link between two nodes) within the Lightning Network.
OnionPacket is the onion wrapped hop-to-hop routing information necessary to propagate a message through the mix-net without intermediate nodes having knowledge of their position within the route, the source, the destination, and finally the identities of the past/future nodes in the route.
PrivKeyECDH is an implementation of the SingleKeyECDH in which we do have the full private key.
ProcessedPacket encapsulates the resulting state generated after processing an OnionPacket.
ReplaySet is a data structure used to efficiently record the occurrence of replays, identified by sequence number, when processing a Batch.
Router is an onion router within the Sphinx network.
Tx is a transaction consisting of a number of sphinx packets to be atomically written to the replay log.

# Interfaces

ReplayLog is an interface that defines a log of incoming sphinx packets, enabling strong replay protection.
SingleKeyECDH is an abstraction interface that hides the implementation of an ECDH operation against a specific private key.

# Type aliases

Hash256 is a statically sized, 32-byte array, typically containing the output of a SHA256 hash.
HashPrefix is a statically size, 20-byte array containing the prefix of a Hash256, and is used to detect duplicate sphinx packets.
PacketFiller is a function type to be specified by the caller to provide a stream of random bytes derived from a CSPRNG to fill out the starting packet in order to ensure we don't leak information on the true route length to the receiver.
PayloadType denotes the type of the payload included in the onion packet.
PaymentPath represents a series of hops within the Lightning Network starting at a sender and terminating at a receiver.
ProcessCode is an enum-like type which describes to the high-level package user which action should be taken after processing a Sphinx packet.