Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Protocol 19 SDK Support #42

Closed
Shaptic opened this issue Apr 12, 2022 · 4 comments
Closed

Protocol 19 SDK Support #42

Shaptic opened this issue Apr 12, 2022 · 4 comments

Comments

@Shaptic
Copy link

Shaptic commented Apr 12, 2022

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:

You can follow each respective issue to its implementation PRs.

@christian-rogobete
Copy link
Contributor

Hello @Shaptic, thank you for providing this issue. We will update the sdk for protocol 19 support

@rice2000
Copy link

rice2000 commented May 4, 2022

@christian-rogobete Do you have an ETA on this? FYI: the Testnet upgrade is May 9 (next week!), and the public network upgrade vote is June 8.

@christian-rogobete
Copy link
Contributor

Hey @rice2000, I will finish the implementation until Friday, test it as soon as the testnet is upgraded and then release a new version.

@christian-rogobete
Copy link
Contributor

done in release 1.3.3

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants
@Shaptic @rice2000 @christian-rogobete and others