Release v0.3.0

vendor/github.com/lightningnetwork/lnd/lnwire/features.go

@@ -2,10 +2,16 @@ package lnwire
 
 import (
 	"encoding/binary"
-	"fmt"
+	"errors"
 	"io"
 )
 
+var (
+	// ErrFeaturePairExists signals an error in feature vector construction
+	// where the opposing bit in a feature pair has already been set.
+	ErrFeaturePairExists = errors.New("feature pair exists")
+)
+
 // FeatureBit represents a feature that can be enabled in either a local or
 // global feature vector at a specific bit position. Feature bits follow the
 // "it's OK to be odd" rule, where features at even bit positions must be known
@@ -35,6 +41,16 @@ const (
 	// connection is established.
 	InitialRoutingSync FeatureBit = 3
 
+	// UpfrontShutdownScriptRequired is a feature bit which indicates that a
+	// peer *requires* that the remote peer accept an upfront shutdown script to
+	// which payout is enforced on cooperative closes.
+	UpfrontShutdownScriptRequired FeatureBit = 4
+
+	// UpfrontShutdownScriptOptional is an optional feature bit which indicates
+	// that the peer will accept an upfront shutdown script to which payout is
+	// enforced on cooperative closes.
+	UpfrontShutdownScriptOptional FeatureBit = 5
+
 	// GossipQueriesRequired is a feature bit that indicates that the
 	// receiving peer MUST know of the set of features that allows nodes to
 	// more efficiently query the network view of peers on the network for
@@ -65,6 +81,36 @@ const (
 	// party's non-delay output should not be tweaked.
 	StaticRemoteKeyOptional FeatureBit = 13
 
+	// PaymentAddrRequired is a required feature bit that signals that a
+	// node requires payment addresses, which are used to mitigate probing
+	// attacks on the receiver of a payment.
+	PaymentAddrRequired FeatureBit = 14
+
+	// PaymentAddrOptional is an optional feature bit that signals that a
+	// node supports payment addresses, which are used to mitigate probing
+	// attacks on the receiver of a payment.
+	PaymentAddrOptional FeatureBit = 15
+
+	// MPPOptional is a required feature bit that signals that the receiver
+	// of a payment requires settlement of an invoice with more than one
+	// HTLC.
+	MPPRequired FeatureBit = 16
+
+	// MPPOptional is an optional feature bit that signals that the receiver
+	// of a payment supports settlement of an invoice with more than one
+	// HTLC.
+	MPPOptional FeatureBit = 17
+
+	// AnchorsRequired is a required feature bit that signals that the node
+	// requires channels to be made using commitments having anchor
+	// outputs.
+	AnchorsRequired FeatureBit = 1336
+
+	// AnchorsRequired is an optional feature bit that signals that the
+	// node supports channels to be made using commitments having anchor
+	// outputs.
+	AnchorsOptional FeatureBit = 1337
+
 	// maxAllowedSize is a maximum allowed size of feature vector.
 	//
 	// NOTE: Within the protocol, the maximum allowed message size is 65535
@@ -78,28 +124,32 @@ const (
 	maxAllowedSize = 32764
 )
 
-// LocalFeatures is a mapping of known connection-local feature bits to a
-// descriptive name. All known local feature bits must be assigned a name in
-// this mapping. Local features are those which are only sent to the peer and
-// not advertised to the entire network. A full description of these feature
-// bits is provided in the BOLT-09 specification.
-var LocalFeatures = map[FeatureBit]string{
-	DataLossProtectRequired: "data-loss-protect",
-	DataLossProtectOptional: "data-loss-protect",
-	InitialRoutingSync:      "initial-routing-sync",
-	GossipQueriesRequired:   "gossip-queries",
-	GossipQueriesOptional:   "gossip-queries",
+// IsRequired returns true if the feature bit is even, and false otherwise.
+func (b FeatureBit) IsRequired() bool {
+	return b&0x01 == 0x00
 }
 
-// GlobalFeatures is a mapping of known global feature bits to a descriptive
-// name. All known global feature bits must be assigned a name in this mapping.
-// Global features are those which are advertised to the entire network. A full
-// description of these feature bits is provided in the BOLT-09 specification.
-var GlobalFeatures = map[FeatureBit]string{
-	TLVOnionPayloadRequired: "tlv-onion",
-	TLVOnionPayloadOptional: "tlv-onion",
-	StaticRemoteKeyOptional: "static-remote-key",
-	StaticRemoteKeyRequired: "static-remote-key",
+// Features is a mapping of known feature bits to a descriptive name. All known
+// feature bits must be assigned a name in this mapping, and feature bit pairs
+// must be assigned together for correct behavior.
+var Features = map[FeatureBit]string{
+	DataLossProtectRequired:       "data-loss-protect",
+	DataLossProtectOptional:       "data-loss-protect",
+	InitialRoutingSync:            "initial-routing-sync",
+	UpfrontShutdownScriptRequired: "upfront-shutdown-script",
+	UpfrontShutdownScriptOptional: "upfront-shutdown-script",
+	GossipQueriesRequired:         "gossip-queries",
+	GossipQueriesOptional:         "gossip-queries",
+	TLVOnionPayloadRequired:       "tlv-onion",
+	TLVOnionPayloadOptional:       "tlv-onion",
+	StaticRemoteKeyOptional:       "static-remote-key",
+	StaticRemoteKeyRequired:       "static-remote-key",
+	PaymentAddrOptional:           "payment-addr",
+	PaymentAddrRequired:           "payment-addr",
+	MPPOptional:                   "multi-path-payments",
+	MPPRequired:                   "multi-path-payments",
+	AnchorsRequired:               "anchor-commitments",
+	AnchorsOptional:               "anchor-commitments",
 }
 
 // RawFeatureVector represents a set of feature bits as defined in BOLT-09.  A
@@ -121,6 +171,26 @@ func NewRawFeatureVector(bits ...FeatureBit) *RawFeatureVector {
 	return fv
 }
 
+// Merges sets all feature bits in other on the receiver's feature vector.
+func (fv *RawFeatureVector) Merge(other *RawFeatureVector) error {
+	for bit := range other.features {
+		err := fv.SafeSet(bit)
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// Clone makes a copy of a feature vector.
+func (fv *RawFeatureVector) Clone() *RawFeatureVector {
+	newFeatures := NewRawFeatureVector()
+	for bit := range fv.features {
+		newFeatures.Set(bit)
+	}
+	return newFeatures
+}
+
 // IsSet returns whether a particular feature bit is enabled in the vector.
 func (fv *RawFeatureVector) IsSet(feature FeatureBit) bool {
 	return fv.features[feature]
@@ -131,6 +201,20 @@ func (fv *RawFeatureVector) Set(feature FeatureBit) {
 	fv.features[feature] = true
 }
 
+// SafeSet sets the chosen feature bit in the feature vector, but returns an
+// error if the opposing feature bit is already set. This ensures both that we
+// are creating properly structured feature vectors, and in some cases, that
+// peers are sending properly encoded ones, i.e. it can't be both optional and
+// required.
+func (fv *RawFeatureVector) SafeSet(feature FeatureBit) error {
+	if _, ok := fv.features[feature^1]; ok {
+		return ErrFeaturePairExists
+	}
+
+	fv.Set(feature)
+	return nil
+}
+
 // Unset marks a feature as disabled in the vector.
 func (fv *RawFeatureVector) Unset(feature FeatureBit) {
 	delete(fv.features, feature)
@@ -184,8 +268,16 @@ func (fv *RawFeatureVector) Encode(w io.Writer) error {
 	return fv.encode(w, length, 8)
 }
 
+// EncodeBase256 writes the feature vector in base256 representation. Every
+// feature is encoded as a bit, and the bit vector is serialized using the least
+// number of bytes.
+func (fv *RawFeatureVector) EncodeBase256(w io.Writer) error {
+	length := fv.SerializeSize()
+	return fv.encode(w, length, 8)
+}
+
 // EncodeBase32 writes the feature vector in base32 representation. Every feature
-// encoded as a bit, and the bit vector is serialized using the least number of
+// is encoded as a bit, and the bit vector is serialized using the least number of
 // bytes.
 func (fv *RawFeatureVector) EncodeBase32(w io.Writer) error {
 	length := fv.SerializeSize32()
@@ -207,8 +299,8 @@ func (fv *RawFeatureVector) encode(w io.Writer, length, width int) error {
 }
 
 // Decode reads the feature vector from its byte representation. Every feature
-// encoded as a bit, and the bit vector is serialized using the least number of
-// bytes. Since the bit vector length is variable, the first two bytes of the
+// is encoded as a bit, and the bit vector is serialized using the least number
+// of bytes. Since the bit vector length is variable, the first two bytes of the
 // serialization represent the length.
 func (fv *RawFeatureVector) Decode(r io.Reader) error {
 	// Read the length of the feature vector.
@@ -221,6 +313,13 @@ func (fv *RawFeatureVector) Decode(r io.Reader) error {
 	return fv.decode(r, int(length), 8)
 }
 
+// DecodeBase256 reads the feature vector from its base256 representation. Every
+// feature encoded as a bit, and the bit vector is serialized using the least
+// number of bytes.
+func (fv *RawFeatureVector) DecodeBase256(r io.Reader, length int) error {
+	return fv.decode(r, length, 8)
+}
+
 // DecodeBase32 reads the feature vector from its base32 representation. Every
 // feature encoded as a bit, and the bit vector is serialized using the least
 // number of bytes.
@@ -274,6 +373,11 @@ func NewFeatureVector(featureVector *RawFeatureVector,
 	}
 }
 
+// EmptyFeatureVector returns a feature vector with no bits set.
+func EmptyFeatureVector() *FeatureVector {
+	return NewFeatureVector(nil, Features)
+}
+
 // HasFeature returns whether a particular feature is included in the set. The
 // feature can be seen as set either if the bit is set directly OR the queried
 // bit has the same meaning as its corresponding even/odd bit, which is set
@@ -303,9 +407,9 @@ func (fv *FeatureVector) UnknownRequiredFeatures() []FeatureBit {
 func (fv *FeatureVector) Name(bit FeatureBit) string {
 	name, known := fv.featureNames[bit]
 	if !known {
-		name = "unknown"
+		return "unknown"
 	}
-	return fmt.Sprintf("%s(%d)", name, bit)
+	return name
 }
 
 // IsKnown returns whether this feature bit represents a known feature.
@@ -324,3 +428,19 @@ func (fv *FeatureVector) isFeatureBitPair(bit FeatureBit) bool {
 	name2, known2 := fv.featureNames[bit^1]
 	return known1 && known2 && name1 == name2
 }
+
+// Features returns the set of raw features contained in the feature vector.
+func (fv *FeatureVector) Features() map[FeatureBit]struct{} {
+	fs := make(map[FeatureBit]struct{}, len(fv.RawFeatureVector.features))
+	for b := range fv.RawFeatureVector.features {
+		fs[b] = struct{}{}
+	}
+	return fs
+}
+
+// Clone copies a feature vector, carrying over its feature bits. The feature
+// names are not copied.
+func (fv *FeatureVector) Clone() *FeatureVector {
+	features := fv.RawFeatureVector.Clone()
+	return NewFeatureVector(features, fv.featureNames)
+}