txnbuild: Add support for new CAP-21 preconditions.

txnbuild/ledgerbounds.go

@@ -0,0 +1,19 @@
+package txnbuild
+
+import "github.com/stellar/go/support/errors"
+
+// Ledgerbounds represent a transaction precondition that controls the ledger
+// range for which a transaction is valid. Setting MaxLedger = 0 indicates there
+// is no maximum ledger.
+type Ledgerbounds struct {
+	MinLedger uint32
+	MaxLedger uint32
+}
+
+func (lb *Ledgerbounds) Validate() error {
+	if lb.MaxLedger > 0 && lb.MaxLedger < lb.MinLedger {
+		return errors.New("invalid ledgerbound: max ledger < min ledger")
+	}
+
+	return nil
+}

txnbuild/preconditions.go

@@ -0,0 +1,153 @@
+package txnbuild
+
+import (
+	"github.com/stellar/go/support/errors"
+	"github.com/stellar/go/xdr"
+)
+
+// Preconditions is a container for all transaction preconditions.
+type Preconditions struct {
+	// Transaction is only valid during a certain time range. This is private
+	// because it should mirror the one set via TransactionParams, and this
+	// association should be done via `NewPreconditions()`.
+	timebounds *Timebounds
+	// Transaction is valid for ledger numbers n such that minLedger <= n <
+	// maxLedger (if maxLedger == 0, then only minLedger is checked)
+	Ledgerbounds *Ledgerbounds
+	// If nil, the transaction is only valid when sourceAccount's sequence
+	// number "N" is seqNum - 1. Otherwise, valid when N satisfies minSeqNum <=
+	// N < tx.seqNum.
+	MinSequenceNumber *int64
+	// Transaction is valid if the current ledger time is at least
+	// minSequenceNumberAge greater than the source account's seqTime.
+	MinSequenceNumberAge xdr.Duration
+	// Transaction is valid if the current ledger number is at least
+	// minSequenceNumberLedgerGap greater than the source account's seqLedger.
+	MinSequenceNumberLedgerGap uint32
+	// Transaction is valid if there is a signature corresponding to every
+	// Signer in this array, even if the signature is not otherwise required by
+	// the source account or operations.
+	ExtraSigners []xdr.SignerKey
+}
+
+// NewPreconditions creates a set of preconditions with timebounds enabled
+func NewPreconditions(timebounds *Timebounds) Preconditions {
+	cond := Preconditions{}
+	if err := cond.SetTimebounds(timebounds); err != nil {
+		panic(err)
+	}
+	return cond
+}
+
+func NewPreconditionsFromTimebounds(minTime, maxTime int64) Preconditions {
+	tb := NewTimebounds(minTime, maxTime)
+	return NewPreconditions(&tb)
+}
+
+// SetTimebounds enables the timebound precondition.
+//
+// Note that timebounds are a *required* precondition, but they're passed here
+// by pointer in order to align with `TransactionParams.Timebound`.
+func (cond *Preconditions) SetTimebounds(timebounds *Timebounds) error {
+	if timebounds == nil {
+		return errors.New("timebounds are required")
+	}
+
+	if err := timebounds.Validate(); err != nil {
+		return err
+	}
+
+	if cond.timebounds != nil {
+		// only fail if they differ
+		if cond.timebounds.MinTime != timebounds.MinTime ||
+			cond.timebounds.MaxTime != timebounds.MaxTime {
+			return errors.New("timebounds set twice")
+		}
+	}
+
+	cond.timebounds = timebounds
+	return nil
+}
+
+func (cond *Preconditions) Timebounds() Timebounds {
+	return *cond.timebounds
+}
+
+// Validate ensures that all enabled preconditions are valid.
+func (cond *Preconditions) Validate() error {
+	var err error
+
+	if err = cond.timebounds.Validate(); err != nil {
+		return err
+	}
+
+	if ok := cond.ValidateSigners(); !ok {
+		return errors.New("invalid signers")
+	}
+
+	if cond.Ledgerbounds != nil {
+		err = cond.Ledgerbounds.Validate()
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (cond *Preconditions) ValidateSigners() bool {
+	return len(cond.ExtraSigners) <= 2
+}
+
+// HasV2Conditions determines whether or not this has conditions on top of
+// the (required) timebound precondition.
+func (cond *Preconditions) HasV2Conditions() bool {
+	return (cond.Ledgerbounds != nil ||
+		cond.MinSequenceNumber != nil ||
+		cond.MinSequenceNumberAge > xdr.Duration(0) ||
+		cond.MinSequenceNumberLedgerGap > 0 ||
+		len(cond.ExtraSigners) > 0)
+}
+
+// BuildXDR will create a precondition structure that varies depending on
+// whether or not there are additional preconditions besides timebounds (which
+// are required).
+func (cond *Preconditions) BuildXDR() xdr.Preconditions {
+	xdrCond := xdr.Preconditions{}
+	xdrTimeBounds := xdr.TimeBounds{
+		MinTime: xdr.TimePoint(cond.timebounds.MinTime),
+		MaxTime: xdr.TimePoint(cond.timebounds.MaxTime),
+	}
+
+	// Only build PRECOND_V2 structure if we need to
+	if cond.HasV2Conditions() {
+		xdrPrecond := xdr.PreconditionsV2{
+			TimeBounds:      &xdrTimeBounds,
+			MinSeqAge:       cond.MinSequenceNumberAge,
+			MinSeqLedgerGap: xdr.Uint32(cond.MinSequenceNumberLedgerGap),
+			ExtraSigners:    cond.ExtraSigners,
+		}
+
+		// micro-optimization: if the ledgerbounds will always succeed, omit them
+		if cond.Ledgerbounds != nil && !(cond.Ledgerbounds.MinLedger == 0 &&
+			cond.Ledgerbounds.MaxLedger == 0) {
+			xdrPrecond.LedgerBounds = &xdr.LedgerBounds{
+				MinLedger: xdr.Uint32(cond.Ledgerbounds.MinLedger),
+				MaxLedger: xdr.Uint32(cond.Ledgerbounds.MaxLedger),
+			}
+		}
+
+		if cond.MinSequenceNumber != nil {
+			seqNum := xdr.SequenceNumber(*cond.MinSequenceNumber)
+			xdrPrecond.MinSeqNum = &seqNum
+		}
+
+		xdrCond.Type = xdr.PreconditionTypePrecondV2
+		xdrCond.V2 = &xdrPrecond
+	} else {
+		xdrCond.Type = xdr.PreconditionTypePrecondTime
+		xdrCond.TimeBounds = &xdrTimeBounds
+	}
+
+	return xdrCond
+}

txnbuild/preconditions_test.go

@@ -0,0 +1,173 @@
+package txnbuild
+
+import (
+	"testing"
+
+	"github.com/stellar/go/xdr"
+	"github.com/stretchr/testify/assert"
+)
+
+var Signers = []xdr.SignerKey{
+	xdr.MustSigner("GAOQJGUAB7NI7K7I62ORBXMN3J4SSWQUQ7FOEPSDJ322W2HMCNWPHXFB"),
+	xdr.MustSigner("GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"),
+	xdr.MustSigner("PA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUAAAAAQACAQDAQCQMBYIBEFAWDANBYHRAEISCMKBKFQXDAMRUGY4DUPB6IBZGM"),
+}
+
+var (
+	seqNum    = int64(14)
+	xdrSeqNum = xdr.SequenceNumber(seqNum)
+	xdrCond   = xdr.Preconditions{
+		Type: xdr.PreconditionTypePrecondV2,
+		V2: &xdr.PreconditionsV2{
+			TimeBounds: &xdr.TimeBounds{
+				MinTime: xdr.TimePoint(27),
+				MaxTime: xdr.TimePoint(42),
+			},
+			LedgerBounds: &xdr.LedgerBounds{
+				MinLedger: xdr.Uint32(27),
+				MaxLedger: xdr.Uint32(42),
+			},
+			MinSeqNum:       &xdrSeqNum,
+			MinSeqAge:       xdr.Duration(27),
+			MinSeqLedgerGap: xdr.Uint32(42),
+			ExtraSigners:    Signers[:1],
+		},
+	}
+	tb = NewTimebounds(27, 42)
+	pc = Preconditions{
+		timebounds:                 &tb,
+		Ledgerbounds:               &Ledgerbounds{27, 42},
+		MinSequenceNumber:          &seqNum,
+		MinSequenceNumberAge:       xdr.Duration(27),
+		MinSequenceNumberLedgerGap: 42,
+		ExtraSigners:               Signers[:1],
+	}
+)
+
+// TestClassifyingPreconditions ensures that Preconditions will correctly
+// differentiate V1 (timebounds-only) or V2 (all other) preconditions correctly.
+func TestClassifyingPreconditions(t *testing.T) {
+	tbpc := NewPreconditions(&tb)
+	assert.False(t, (&Preconditions{}).HasV2Conditions())
+	assert.False(t, tbpc.HasV2Conditions())
+	assert.True(t, pc.HasV2Conditions())
+}
+
+// TestPreconditions ensures correct XDR is generated for a (non-exhaustive)
+// handful of precondition combinations.
+func TestPreconditions(t *testing.T) {
+	preconditionModifiers := []struct {
+		Name     string
+		Modifier func() (xdr.Preconditions, Preconditions)
+	}{
+		{
+			"unchanged",
+			func() (xdr.Preconditions, Preconditions) {
+				return xdrCond, pc
+			},
+		},
+		{
+			"only timebounds",
+			func() (xdr.Preconditions, Preconditions) {
+				tb := NewTimebounds(1, 2)
+				return xdr.Preconditions{
+					Type: xdr.PreconditionTypePrecondTime,
+					TimeBounds: &xdr.TimeBounds{
+						MinTime: xdr.TimePoint(1),
+						MaxTime: xdr.TimePoint(2),
+					},
+				}, NewPreconditions(&tb)
+			},
+		},
+		{
+			"unbounded ledgerbounds",
+			func() (xdr.Preconditions, Preconditions) {
+				newCond, newPc := clone(xdrCond, pc)
+				newCond.V2.LedgerBounds.MaxLedger = 0
+				newPc.Ledgerbounds.MaxLedger = 0
+				return newCond, newPc
+			},
+		},
+		{
+			"nil ledgerbounds",
+			func() (xdr.Preconditions, Preconditions) {
+				newCond, newPc := clone(xdrCond, pc)
+				newCond.V2.LedgerBounds = nil
+				newPc.Ledgerbounds = nil
+				return newCond, newPc
+			},
+		},
+		{
+			"nil minSeq",
+			func() (xdr.Preconditions, Preconditions) {
+				newCond, newPc := clone(xdrCond, pc)
+				newCond.V2.MinSeqNum = nil
+				newPc.MinSequenceNumber = nil
+				return newCond, newPc
+			},
+		},
+	}
+	for _, testCase := range preconditionModifiers {
+		t.Run(testCase.Name, func(t *testing.T) {
+			xdrCond, precond := testCase.Modifier()
+			assert.NoError(t, precond.Validate())
+
+			expectedBytes, err := xdrCond.MarshalBinary()
+			assert.NoError(t, err)
+
+			actualBytes, err := precond.BuildXDR().MarshalBinary()
+			assert.NoError(t, err)
+			assert.Equal(t, expectedBytes, actualBytes)
+		})
+	}
+}
+
+// TestPreconditionsValidation ensures that validation fails when necessary.
+func TestPreconditionsValidation(t *testing.T) {
+	t.Run("too many signers", func(t *testing.T) {
+		pc.ExtraSigners = Signers
+		assert.Error(t, pc.Validate())
+	})
+}
+
+func clone(pcXdr xdr.Preconditions, pc Preconditions) (xdr.Preconditions, Preconditions) {
+	return cloneXdrPreconditions(pcXdr), clonePreconditions(pc)
+}
+
+func cloneXdrPreconditions(pc xdr.Preconditions) xdr.Preconditions {
+	binary, err := pc.MarshalBinary()
+	if err != nil {
+		panic(err)
+	}
+
+	clone := xdr.Preconditions{}
+	if err = clone.UnmarshalBinary(binary); err != nil {
+		panic(err)
+	}
+
+	return clone
+}
+
+func clonePreconditions(precond Preconditions) Preconditions {
+	tb := NewTimebounds(precond.timebounds.MinTime, precond.timebounds.MaxTime)
+	cond := NewPreconditions(&tb)
+	if precond.Ledgerbounds != nil {
+		cond.Ledgerbounds = &Ledgerbounds{
+			MinLedger: precond.Ledgerbounds.MinLedger,
+			MaxLedger: precond.Ledgerbounds.MaxLedger,
+		}
+	}
+
+	if precond.MinSequenceNumber != nil {
+		cond.MinSequenceNumber = precond.MinSequenceNumber
+	}
+
+	cond.MinSequenceNumberAge = precond.MinSequenceNumberAge
+	cond.MinSequenceNumberLedgerGap = precond.MinSequenceNumberLedgerGap
+
+	if len(precond.ExtraSigners) > 0 {
+		cond.ExtraSigners = append(cond.ExtraSigners, precond.ExtraSigners...)
+	}
+
+	return cond
+}

txnbuild/timebounds.go

@@ -28,7 +28,7 @@ type Timebounds struct {
 // using a factory method. This is done to ensure that default Timebound structs (which have no limits) are not
 // valid - you must explicitly specifiy the Timebound you require.
 func (tb *Timebounds) Validate() error {
-	if !tb.wasBuilt {
+	if tb == nil || !tb.wasBuilt {
 		return errors.New("timebounds must be constructed using NewTimebounds(), NewTimeout(), or NewInfiniteTimeout()")
 	}
 	if tb.MinTime < 0 {