services/horizon: Support new CAP-21 transaction conditions

[Shaptic]

Breakdown and Rollout: Horizon & Protocol 19. See #4261 for the master issue.

---

Background

CAP-21 adds a new set of transaction preconditions:

• Time bounds (timeBounds): as before, you can define a min/max time range
• Ledger bounds (ledgerBounds): a min/max ledger range
• Sequence num (minSeqNum): a min sequence number, meaning the transaction is only valid if the source account’s sequence number is >= than this
• Duration (minSeqAge): a ledger time delta, meaning the transaction is only valid if a certain amount of time has passed since account’s last sequence number change (expanded upon later)
• Sequence-ledger gap (minSeqLedgerGap): a ledger number delta past the account’s last sequence number change (similar to minSeqAge but a ledger count)

Relevant XDR:

typedef int64 Duration;

struct LedgerBounds {
    uint32 minLedger;
    uint32 maxLedger;
};

struct PreconditionsV2 {
    TimeBounds *timeBounds;

    // Transaciton only valid for ledger numbers n such that
    // minLedger <= n < maxLedger
    LedgerBounds *ledgerBounds;

    // If NULL, only valid when sourceAccount's sequence number
    // is seqNum - 1.  Otherwise, valid when sourceAccount's
    // sequence number n satisfies minSeqNum <= n < tx.seqNum.
    // Note that after execution the account's sequence number
    // is always raised to tx.seqNum, and a transaction is not
    // valid if tx.seqNum is too high to ensure replay protection.
    SequenceNumber *minSeqNum;

    // For the transaction to be valid, the current ledger time must
    // be at least minSeqAge greater than sourceAccount's seqTime.
    Duration minSeqAge;

    // For the transaction to be valid, the current ledger number
    // must be at least minSeqLedgerGap greater than sourceAccount's
    // seqLedger.
    uint32 minSeqLedgerGap;

    // For the transaction to be valid, there must be a signature
    // corresponding to every Signer in this array, even if the
    // signature is not otherwise required by the sourceAccount or
    // operations.
    SignerKey extraSigners<2>;
};

Affected Endpoints

• GET /transactions
• GET /transactions/:id
• GET [any endpoint]/transactions

API Changes

--- a/protocols/horizon/main.go
+++ b/protocols/horizon/main.go
@@ -525,10 +527,23 @@ type Transaction struct {
        Signatures         []string                `json:"signatures"`
+    // Action needed in release: horizon-v3.0.0: remove valid_(after|before)
        ValidAfter         string                      `json:"valid_after,omitempty"`
        ValidBefore        string                      `json:"valid_before,omitempty"`
+       Preconditions      TransactionPreconditions    `json:"preconditions,omitempty"`
        FeeBumpTransaction *FeeBumpTransaction         `json:"fee_bump_transaction,omitempty"`
        InnerTransaction   *InnerTransaction           `json:"inner_transaction,omitempty"`
 }
 
+type TransactionPreconditions struct {
+       Timebounds struct {
+               MinTime string `json:"min_time,omitempty"`
+               MaxTime string `json:"max_time,omitempty"`
+       } `json:"timebounds,omitempty"`
+       Ledgerbounds struct {
+               MinLedger uint32 `json:"min_ledger"`
+               MaxLedger uint32 `json:"max_ledger"`
+       } `json:"ledgerbounds,omitempty"`
+
+       MinAccountSequence    string `json:"min_account_sequence,omitempty"`
+       MinSequenceAge        string `json:"min_account_sequence_age,omitempty"`
+       MinSequenceLedgerGap  uint32 `json:"min_account_sequence_ledger_gap,omitempty"`
+
+       Signers []string `json:"extra_signers,omitempty"`
 }

Behavior

The new Preconditions object always exists if the transaction has preconditions, regardless of whether or not they are CAP-21 preconditions. This means the ValidAfter/Before and Preconditions.Timebounds.MinTime/MaxTime fields match, for backwards compatibility.

[Shaptic]

Closed by #4297