descriptors: add Lift and PlanAt methods

This commit adds the Lift() and PlanAt() methods to the
Descriptor struct.

Author: guggero

descriptors/differential_test.go

@@ -18,6 +18,8 @@ type descRecords struct {
 	mplen   string
 	typ     string
 	mweight string
+	lift    string
+	plan    []string
 	keys    []string
 	addr    [][]string
 	scode   [][]string
@@ -73,6 +75,12 @@ func TestDescriptorDifferential(t *testing.T) {
 		case "MWEIGHT":
 			rec.mweight = fields[2]
 
+		case "LIFT":
+			rec.lift = fields[2]
+
+		case "PLAN":
+			rec.plan = fields[2:]
+
 		case "KEY":
 			rec.keys = append(rec.keys, fields[2])
 
@@ -96,6 +104,48 @@ func TestDescriptorDifferential(t *testing.T) {
 	}
 }
 
+// planScriptSigAdjustment returns how much larger the scriptSig this package
+// reports for a plan is than the one rust-miniscript v13 reports, which is only
+// non-zero for P2SH descriptors and has two independent reasons:
+//
+//   - for a P2SH-wrapped segwit output, rust reports the raw length of the
+//     scriptSig, while Plan.ScriptSigSize is documented as the size of the
+//     serialized field, i.e. one byte more for the var-int that prefixes it. (A
+//     plan with an empty scriptSig reports 1 in both implementations, so rust is
+//     only self-consistent for that case.)
+//   - for a legacy P2SH, rust does not count the redeem script at all, because
+//     its plan hands it to the PSBT input as a separate field instead of
+//     producing scriptSig bytes. Plan.Satisfy does produce them, so its size has
+//     to cover the redeem script push. Note rust's own max_weight_to_satisfy
+//     counts the redeem script too, i.e. its two APIs disagree with each other.
+//     No byte is added for the var-int here: rust sizes a legacy scriptSig like
+//     a witness, whose element count takes the byte our convention spends on the
+//     var-int prefix.
+func planScriptSigAdjustment(t *testing.T, d *Descriptor) uint64 {
+	switch d.DescType() {
+	case DescTypeShWpkh, DescTypeShWsh:
+		return 1
+
+	case DescTypeSh:
+		// The redeem script of a legacy P2SH is its script code.
+		redeem, err := d.ScriptCodeAt(0, 0)
+		require.NoError(t, err)
+
+		return uint64(pushOpcodeSize(len(redeem)) + len(redeem))
+
+	default:
+		return 0
+	}
+}
+
+// mustUint64 parses a decimal reference value.
+func mustUint64(t *testing.T, s string) uint64 {
+	value, err := strconv.ParseUint(s, 10, 64)
+	require.NoErrorf(t, err, "parsing %q", s)
+
+	return value
+}
+
 // checkDescriptor parses one descriptor in Go and asserts all of its computed
 // properties match the rust reference records.
 func checkDescriptor(t *testing.T, expr string, rec *descRecords) {
@@ -120,6 +170,51 @@ func checkDescriptor(t *testing.T, expr string, rec *descRecords) {
 			"max weight to satisfy for %s", expr)
 	}
 
+	// Lifted semantic policy, compared in its canonical display form.
+	policy, liftErr := d.Lift()
+	if strings.HasPrefix(rec.lift, "ERR:") {
+		require.Errorf(t, liftErr, "expected lift error for %s", expr)
+	} else {
+		require.NoErrorf(t, liftErr, "lift for %s", expr)
+		require.Equalf(t, rec.lift, policy.String(),
+			"lifted policy for %s", expr)
+	}
+
+	// Plan weights, computed with every signature and timelock available so
+	// the planner picks the cheapest spending path.
+	relLock, absLock := uint32(65535), uint32(499999999)
+	plan, planErr := d.PlanAt(0, 0, Assets{
+		LookupEcdsaSig: func(string) bool { return true },
+		LookupTapKeySpendSig: func(string) (uint32, bool) {
+			return 64, true
+		},
+		LookupTapLeafScriptSig: func(string, string) (uint32, bool) {
+			return 64, true
+		},
+		RelativeLocktime: &relLock,
+		AbsoluteLocktime: &absLock,
+	})
+	if len(rec.plan) == 1 && rec.plan[0] == "ERR" {
+		require.Errorf(t, planErr, "expected plan error for %s", expr)
+	} else {
+		require.NoErrorf(t, planErr, "plan for %s", expr)
+		require.Lenf(t, rec.plan, 3, "plan record for %s", expr)
+
+		// The scriptSig accounting of a P2SH plan intentionally differs
+		// from rust-miniscript v13, see planScriptSigAdjustment.
+		adjust := planScriptSigAdjustment(t, d)
+		wantScriptSig := mustUint64(t, rec.plan[1]) + adjust
+		wantWeight := mustUint64(t, rec.plan[0]) + 4*adjust
+
+		require.Equalf(t, wantWeight, plan.SatisfactionWeight(),
+			"plan satisfaction weight for %s", expr)
+		require.Equalf(t, wantScriptSig, plan.ScriptSigSize(),
+			"plan scriptsig size for %s", expr)
+		require.Equalf(t, rec.plan[2], strconv.FormatUint(
+			plan.WitnessSize(), 10),
+			"plan witness size for %s", expr)
+	}
+
 	for _, a := range rec.addr {
 		// a = [mp, idx, net, value] (value may be "ERR:..."), or
 		//     [mp, idx, "ERR", msg] for a derivation error.

descriptors/key.go

@@ -424,6 +424,56 @@ func (k *descKey) multipathLen() int {
 	return 1
 }
 
+// definiteString returns the canonical string of the key with its path fully
+// resolved at the given multipath and derivation index: the multipath element
+// is replaced by its multipath-index value and the wildcard by the derivation
+// index. This matches rust-miniscript's DefiniteDescriptorKey display and is
+// the identifier passed to the plan asset and satisfier lookups.
+func (k *descKey) definiteString(multipathIndex,
+	derivationIndex uint32) string {
+
+	// Keep any optional "[origin]" prefix verbatim, since it contains its
+	// own path separators.
+	origin, rest := "", k.raw
+	if strings.HasPrefix(rest, "[") {
+		if end := strings.IndexByte(rest, ']'); end >= 0 {
+			origin, rest = rest[:end+1], rest[end+1:]
+		}
+	}
+
+	// The remainder is the key followed by its path steps; the key is the
+	// part before the first separator.
+	base := rest
+	if slash := strings.IndexByte(rest, '/'); slash >= 0 {
+		base = rest[:slash]
+	}
+
+	var b strings.Builder
+	b.WriteString(origin)
+	b.WriteString(base)
+	for _, step := range k.steps {
+		b.WriteByte('/')
+		switch step.kind {
+		case stepMultipath:
+			b.WriteString(step.multipath[multipathIndex].String())
+
+		case stepWildcard:
+			// The wildcard resolves to the derivation index, which
+			// keeps the hardened indicator of the wildcard itself.
+			resolved := pathIndex{
+				num:      derivationIndex,
+				hardened: step.index.hardened,
+			}
+			b.WriteString(resolved.String())
+
+		default:
+			b.WriteString(step.index.String())
+		}
+	}
+
+	return b.String()
+}
+
 // isWildcard returns whether the key has a wildcard element and is therefore
 // ranged.
 func (k *descKey) isWildcard() bool {

descriptors/key_test.go

@@ -4,6 +4,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/btcsuite/btcd/btcutil/v2/hdkeychain"
 	"github.com/stretchr/testify/require"
 )
 
@@ -246,3 +247,85 @@ func TestKeyOriginValidation(t *testing.T) {
 		})
 	}
 }
+
+// TestHardenedDerivation checks the handling of hardened derivation steps,
+// which BIP380 and BIP389 allow anywhere in a path, including as the wildcard
+// and inside a multipath element. Deriving one needs the private extended key:
+// the descriptor is valid either way, so the distinction belongs at derivation
+// time rather than at parse time, where a hardened wildcard used to be rejected
+// outright.
+func TestHardenedDerivation(t *testing.T) {
+	t.Parallel()
+
+	const (
+		xpub = "xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqh" +
+			"MkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJu" +
+			"ZZvRcEL"
+		xprv = "xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWY" +
+			"pDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCq" +
+			"E2VbFWc"
+	)
+
+	// A hardened path is derivable from a private extended key.
+	priv, err := parseDescKey(xprv+"/3h/4'/5h/*h", keyFormCompressed)
+	require.NoError(t, err)
+
+	derived, err := priv.derive(0, 7)
+	require.NoError(t, err)
+	require.Len(t, derived, 33)
+
+	// The definite key string keeps the hardened indicators, with the
+	// wildcard resolved to the derivation index.
+	require.Equal(
+		t, xprv+"/3'/4'/5'/7'", priv.definiteString(0, 7),
+	)
+
+	// The same expression is valid with a public extended key, but cannot
+	// be derived from it.
+	pub, err := parseDescKey(xpub+"/3h/4h/5h/*h", keyFormCompressed)
+	require.NoError(t, err)
+
+	_, err = pub.derive(0, 7)
+	require.ErrorContains(t, err, "cannot derive the hardened child")
+
+	// An unhardened wildcard on the same key works.
+	unhardened, err := parseDescKey(xpub+"/*", keyFormCompressed)
+	require.NoError(t, err)
+
+	_, err = unhardened.derive(0, 7)
+	require.NoError(t, err)
+
+	// A derivation index in the hardened range must not silently turn an
+	// unhardened wildcard into a hardened derivation.
+	_, err = unhardened.derive(0, hdkeychain.HardenedKeyStart)
+	require.ErrorContains(t, err, "in the hardened range")
+
+	// A multipath element may hold hardened indices (BIP389), which select
+	// hardened children of the private key.
+	multi, err := parseDescKey(
+		xprv+"/<2147483647h;0>/0", keyFormCompressed,
+	)
+	require.NoError(t, err)
+	require.Equal(t, 2, multi.multipathLen())
+
+	hardenedPath, err := multi.derive(0, 0)
+	require.NoError(t, err)
+	unhardenedPath, err := multi.derive(1, 0)
+	require.NoError(t, err)
+	require.NotEqual(t, hardenedPath, unhardenedPath)
+
+	require.Equal(t, xprv+"/2147483647'/0", multi.definiteString(0, 0))
+	require.Equal(t, xprv+"/0/0", multi.definiteString(1, 0))
+
+	// A multipath element must not repeat an index (BIP389).
+	_, err = parseDescKey(xpub+"/<0;0>/*", keyFormCompressed)
+	require.ErrorContains(t, err, "more than once")
+
+	_, err = parseDescKey(xpub+"/<0;1;0>/*", keyFormCompressed)
+	require.ErrorContains(t, err, "more than once")
+
+	// The hardened and unhardened spelling of the same index are the same
+	// child, so they collide as well.
+	_, err = parseDescKey(xprv+"/<1h;1'>/*", keyFormCompressed)
+	require.ErrorContains(t, err, "more than once")
+}