Protocol 19 SDK Support
Shaptic opened this issue · comments
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.