amp

Documentation

Index

• type Child
  • func DeriveChild(root Share, desc ChildDesc) *Child
  • func ReconstructChildren(descs ...ChildDesc) []*Child
  • func (c *Child) String() string
• type ChildDesc
• type SeedSharer
  • func NewSeedSharer() (*SeedSharer, error)
  • func SeedSharerFromRoot(root *Share) *SeedSharer
  • func (s *SeedSharer) Child(index uint32) *Child
  • func (s *SeedSharer) Root() Share
  • func (s *SeedSharer) Split() (Sharer, Sharer, error)
• type Share
  • func (z *Share) Xor(x, y *Share)
• type Sharer

Types

type Child

type Child struct {
	// ChildDesc contains the data required to derive the child hash and
	// preimage below.
	ChildDesc

	// Preimage is the child payment preimage that can be used to settle the
	// HTLC carrying Hash.
	Preimage lntypes.Preimage

	// Hash is the child payment hash that to be carried by the HTLC.
	Hash lntypes.Hash
}

Child is a payment hash and preimage pair derived from the root seed. In addition to the derived values, a Child carries all information required in the derivation apart from the root seed (unless n=1).

func DeriveChild

func DeriveChild(root Share, desc ChildDesc) *Child

DeriveChild computes the child preimage and child hash for a given (root, share, index) tuple. The derivation is defined as:

child_preimage = SHA256(root || share || be32(index)),
child_hash     = SHA256(child_preimage).

func ReconstructChildren

func ReconstructChildren(descs ...ChildDesc) []*Child

ReconstructChildren derives the set of children hashes and preimages from the provided descriptors. The shares from each child descriptor are first used to compute the root, afterwards the child hashes and preimages are deterministically computed. For child descriptor at index i in the input, it's derived child will occupy index i of the returned children.

func (*Child) String

func (c *Child) String() string

String returns a human-readable description of a Child.

type ChildDesc

type ChildDesc struct {
	// Share is one of n shares of the root seed. Once all n shares are
	// known to the receiver, the Share will also provide entropy to the
	// derivation of child hash and preimage.
	Share Share

	// Index is 32-bit value that can be used to derive up to 2^32 child
	// hashes and preimages from a single Share. This allows the payment
	// hashes sent over the network to be refreshed without needing to
	// modify the Share.
	Index uint32
}

ChildDesc contains the information necessary to derive a child hash/preimage pair that is attached to a particular HTLC. This information will be known by both the sender and receiver in the process of fulfilling an AMP payment.

type SeedSharer

type SeedSharer struct {
	// contains filtered or unexported fields
}

SeedSharer orchestrates the sharing of the root AMP seed along multiple paths. It also supports derivation of the child payment hashes that get attached to HTLCs, and the child preimages used by the receiver to settle individual HTLCs in the set.

func NewSeedSharer

func NewSeedSharer() (*SeedSharer, error)

NewSeedSharer generates a new SeedSharer instance with a seed drawn at random.

func SeedSharerFromRoot

func SeedSharerFromRoot(root *Share) *SeedSharer

SeedSharerFromRoot instantiates a SeedSharer with an externally provided seed.

func (*SeedSharer) Child

func (s *SeedSharer) Child(index uint32) *Child

Child derives a preimage/hash pair to be used for an AMP HTLC. All children of s will use the same underlying share, but have unique preimage and hash. This can be used to rerandomize the preimage/hash pair for a given HTLC if a new route is needed.

func (*SeedSharer) Root

func (s *SeedSharer) Root() Share

Seed returns the sharer's seed, the primary source of entropy for deriving shares of the root.

func (*SeedSharer) Split

func (s *SeedSharer) Split() (Sharer, Sharer, error)

Split constructs two child Sharers whose shares sum to the parent Sharer. This allows an HTLC whose payment amount could not be routed to be recursively split into smaller subpayments. After splitting a sharer the parent share should no longer be used, and the caller should use the Child method on each to derive preimage/hash pairs for the HTLCs.

type Share

type Share [32]byte

Share represents an n-of-n sharing of a secret 32-byte value. The secret can be recovered by XORing all n shares together.

func (*Share) Xor

func (z *Share) Xor(x, y *Share)

Xor stores the byte-wise xor of shares x and y in z.

type Sharer

type Sharer interface {
	// Root returns the root share of the derivation tree. This is the value
	// that will be reconstructed when combining the set of all child
	// shares.
	Root() Share

	// Child derives a child preimage and child hash given a 32-bit index.
	// Passing a different index will generate a unique preimage-hash pair
	// with high probability, allowing the payment hash carried on HTLCs to
	// be refreshed without needing to modify the share value. This would
	// typically be used when an partial payment needs to be retried if it
	// encounters routine network failures.
	Child(index uint32) *Child

	// Split returns a Sharer for the left and right child of the parent
	// Sharer. XORing the share values of both sharers always yields the
	// share value of the parent. The sender should use this to recursively
	// divide payments that are too large into smaller subpayments, knowing
	// that the shares of all nodes descending from the parent will XOR to
	// the parent's share.
	Split() (Sharer, Sharer, error)
}

Sharer facilitates dynamic splitting of a root share value and derivation of child preimage and hashes for individual HTLCs in an AMP payment. A sharer represents a specific node in an abstract binary tree that can generate up to 2^32-1 unique child preimage-hash pairs for the same share value. A node can also be split into it's left and right child in the tree. The Sharer guarantees that the share value of the left and right child XOR to the share value of the parent. This allows larger HTLCs to split into smaller subpayments, while ensuring that the reconstructed secret will exactly match the root seed.