amp

package
v0.0.20 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2023 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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) Merge

func (s *SeedSharer) Merge(child *Child) Sharer

Merge takes the given Child and "merges" it into the Sharer by XOR-ing its share with the Sharer's current share.

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.

func (*SeedSharer) Zero

func (s *SeedSharer) Zero() Sharer

Zero returns a a new "zero Sharer" that has its current share set to zero, while keeping the root share. Merging a Child from the original Sharer into this zero-Sharer gives back the original Sharer.

type Shard

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

Shard is an implementation of the shards.PaymentShards interface specific to AMP payments.

func (*Shard) AMP

func (s *Shard) AMP() *record.AMP

AMP returns any extra AMP records that should be set for the final hop on the route used by this shard.

func (*Shard) Hash

func (s *Shard) Hash() lntypes.Hash

Hash returns the hash used for the HTLC representing this AMP shard.

func (*Shard) MPP

func (s *Shard) MPP() *record.MPP

MPP returns any extra MPP records that should be set for the final hop on the route used by this shard.

type ShardTracker

type ShardTracker struct {
	sync.Mutex
	// contains filtered or unexported fields
}

ShardTracker is an implementation of the shards.ShardTracker interface that is able to generate payment shards according to the AMP splitting algorithm. It can be used to generate new hashes to use for HTLCs, and also cancel shares used for failed payment shards.

func NewShardTracker

func NewShardTracker(root, setID, payAddr [32]byte,
	totalAmt lnwire.MilliSatoshi) *ShardTracker

NewShardTracker creates a new shard tracker to use for AMP payments. The root shard, setID, payment address and total amount must be correctly set in order for the TLV options to include with each shard to be created correctly.

func (*ShardTracker) CancelShard

func (s *ShardTracker) CancelShard(pid uint64) error

CancelShard cancel's the shard corresponding to the given attempt ID.

func (*ShardTracker) GetHash

func (s *ShardTracker) GetHash(pid uint64) (lntypes.Hash, error)

GetHash retrieves the hash used by the shard of the given attempt ID. This will return an error if the attempt ID is unknown.

func (*ShardTracker) NewShard

func (s *ShardTracker) NewShard(pid uint64, last bool) (shards.PaymentShard,
	error)

NewShard registers a new attempt with the ShardTracker and returns a new shard representing this attempt. This attempt's shard should be canceled if it ends up not being used by the overall payment, i.e. if the attempt fails.

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)

	// Merge takes the given Child and "merges" it into the Sharer by
	// XOR-ing its share with the Sharer's current share.
	Merge(*Child) Sharer

	// Zero returns a a new "zero Sharer" that has its current share set to
	// zero, while keeping the root share. Merging a Child from the
	// original Sharer into this zero-Sharer gives back the original
	// Sharer.
	Zero() Sharer
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL