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 ¶
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 ¶
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.
type ChildDesc ¶
type ChildDesc struct {
// 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 ¶
AMP returns any extra AMP records that should be set for the final hop on the route used by this shard.
type ShardTracker ¶
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.MilliBronees) *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.
type Sharer ¶
type Sharer interface {
// that will be reconstructed when combining the set of all child
// shares.
Root() Share
// 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
// 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)
// XOR-ing its share with the Sharer's current share.
Merge(*Child) Sharer
// 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.
Source Files