Protocol 19 SDK Support

[George]

Protocol 19 SDK Support

Once voted in, the release of Protocol 19 will introduce two new CAPs:

• CAP-21, which introduces new transaction validity preconditions, and
• CAP-40, which introduces a new type of signer: signed payloads

API Changes

Horizon will return new fields for both accounts and transactions:

Accounts

Account records can now contain two new, optional fields:

"sequence_ledger": 0, // uint32 ledger number
"sequence_time": "0"  // uint64 unix time in seconds, as a string

The absence of these fields indicates that the account hasn't taken any actions since prior to the Protocol 19 release. Note that they'll either be both present or both absent.

Transactions

Each transaction record can now contain the following optional object:

"preconditions": {
  "timebounds": {
    "min_time": "0",  // uint64 unix time in seconds, as a string
    "max_time": "0"   // as above
  },
  "ledgerbounds": {
    "min_ledger": 0,  // uint32 ledger number
    "max_ledger": 0   // as above
  },
  "min_account_sequence": "0",          // int64 sequence number, as a string
  "min_account_sequence_age": "0",      // uint64 unix time in seconds, as a string
  "min_account_sequence_ledger_gap": 0, // uint32 ledger count

  "extra_signers": [] // list of signers as StrKeys
}

All of the top-level fields within this object are also optional. However, the "ledgerbounds" object will always have its inner values set.

Note that the existing "valid_before_time" and "valid_after_time" fields on the top-level object will be identical to the "preconditions.timebounds.min_time" and "preconditions.timebounds.min_time" fields, respectively, if those exist. The "valid_before_time" and "valid_after_time" fields are now considered deprecated and will be removed in Horizon v3.0.0.

StrKey Changes

The specification for CAP-40's new signed payload signers is outlined in this SEP-23 change: stellar/stellar-protocol#0943c19e. In summary, it should be prefixed with a P, then encode the signer address followed by the payload in typical XDR fashion.

Keypair Changes

It should be possible to create decorated signature hints from signed payloads as described in CAP-40.

Transaction Builder Changes

SDKs should allow transactions to be built with the new preconditions:

• ledger bounds
• minimum account sequence number
• minimum account sequence age
• minimum ledger-gap from the account sequence
• extra signers

Refer to CAP-21 for the details on their intended functionality.

For handling timebounds, we recommend the following pattern:

• If a transaction only has a timebound set, set the PRECOND_TIME XDR structure
• If the transaction has other preconditions set, set the PRECOND_V2 XDR structure

This provides both backwards compatibility and future efficiency. Note that SDKs typically require that timebounds be set on a transaction. Omitting timebounds must be done explicitly, e.g. by doing .setTimeout(TIMEOUT_INFINITE) in the JavaScript SDK.

Signers should be represented as their human-readable StrKey strings, but should decode to (and encode from) SignerKey XDR instances.

Reference Implementations

There are three reference implementations authored by SDF:

• Go: stellar/go#4261
• Java: lightsail-network/java-stellar-sdk#409
• JavaScript: stellar/js-stellar-sdk#763

You can follow each respective issue to its implementation PRs.