Synesso / scala-stellar-sdk

Scala SDK for the Stellar network
https://synesso.github.io/scala-stellar-sdk
Apache License 2.0
22 stars 15 forks source link

Protocol 19 SDK Support #522

Open Shaptic opened 2 years ago

Shaptic commented 2 years ago

Protocol 19 SDK Support

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

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:

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

For handling timebounds, we recommend the following pattern:

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:

You can follow each respective issue to its implementation PRs.