Extend SDKs to easily build transactions with CAP-21 preconditions

[Shaptic]

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

---

Implementations:

• Go: txnbuild: Extend transaction building to allow CAP-21 preconditions #4282
• JavaScript: Adding builder methods for new preconditions. js-stellar-base#513
• Java: Extend transaction building to allow CAP-21 preconditions lightsail-network/java-stellar-sdk#411

---

Existing transactions only have one possible precondition: timebounds. Transactions after CAP-21 can have many more preconditions. Transaction builders within SDKs need to be extended to support the new preconditions:

• timebounds: unchanged
• ledger bounds: explicitly set via a ledgerBounds: { minLedger, maxLedger } parameter on initialization
• minimum sequence number: set via minAccountSequenceNum: int
• minimum sequence age: set via minAccountSequenceAge: float
• minimum sequence ledger gap: set via minAccountSeqLedgerGap: int

The specific names should obviously be specific to their respective language conventions. For example, if your SDK consistently uses SequenceNumber (rather than SeqNumber, SequenceNum, etc.) to refer to sequence numbers, your precondition fields should be minAccountSequenceNumber, etc.

Behavior

SDKs should create V1 transactions if only timebound precondition are set. This has a couple of benefits:

• Binary compatibility: code written before Protocol 19 and run after a Protocol 19 SDK upgrade results in the same transactions being created on a binary level
• Size optimization: V2 conditions are larger even when they aren’t being used, so translating V1 to V2 conditions results in bigger transaction than before

Expressing this in (pseudo)code might look something like this:

this._conditions = {};
const timeBounds = tx.timeBounds();
if (timeBounds) {
    condition = {
        minTime: timeBounds.minTime().toString(),
        maxTime: timeBounds.maxTime().toString()
    };
    if (!otherPreconditions /* e.g. ledger bounds */) {
        this._timeBounds = condition;
    } else {
        this._conditions._timeBounds = condition;
    }
}
// more code related to extracting V2 conditions from the envelope

To reiterate: if users specify only timebounds preconditions, SDKs should create V1 preconditions. Only setting additional conditions should set up V2 preconditions.

When parsing transactions, the timebounds will be present in both the valid_after/before fields as well as in the preconditions.timebounds.max_time/min_time fields. To future-proof SDKs for Horizon v3, SDKs should only use the latter set of fields.

Validation

SDKs should only do sanity-check validation on conditions, e.g. "is maxLedger >= minLedger?". They should not do compositional validation, that is ensuring that the conditions work together. Validation on timebounds stays the same.

Account Sequence

Most of the SDKs have a way to automatically increment the account sequence number after the transaction is built. CAP-21 specifies a new behavior:

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.

To adhere to this behavior, transaction builders should set the account sequence number to the transaction's sequence number if auto-increment behavior is enabled.

Furthermore, SDKs need to provide a way to set the sequence number on a transaction rather than pulling it directly as account.seqNum + 1.