-
Notifications
You must be signed in to change notification settings - Fork 313
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 13 support #529
Comments
This has been implemented in |
Action needed: Revert support of M-strkeys from all SDKsTL;DR: we need to remove support for M-strkeys (SEP23) from all the SDKs. If the SDK you are maintaining still doesn't have support for SEP23, you can ignore this message. We have already reverted support for SEP23 in the Go SDK and the Javascript SDK. You can use those PRs as reference to do the same in your SDK. ContextSEP23 is still a draft and may not be promoted to final. Adding support for it means that users may end up storing M-strkeys, We implemented support for SEP23 prematurely due as part of the Protocol 13 effort. Again, we are truly sorry we asked the community to implement support for it and later remove it. We apologize for the inconvenience. What need to be doneThe SDKs shouldn't generate or accept M-strkeys (e.g. We encourage removing any code generating or parsing M-keys to avoid confusions (the code can later be recovered for VCS if need be).
cc @2opremio |
Stellar Protocol 13 is coming soon, and we need your help bringing support for it to your SDK.
The most relevant changes for SDKs are:
This issue includes all the necessary changes to support Protocol 13, and gives you a path to release a new version of the SDK which is backwards compatible with the current version of the protocol (12). We suggest you aim to release such a backwards compatible version to allow seamless operation through the protocol vote.
For reference, SDF expects to update the testnet to Protocol 13 on 7 May 2020, and pubnet approximately a month after that.
1 - Update XDR
The first step to support Protocol 13 is to recreate your XDR definitions. You can use xdrgen to do that.
You can find the latest XDR definitions in the stellar-core repo.
2 - Update code which depends on TransactionEnvelope
The low-level representation for
TransactionEnvelope
changed from anxdr.Struct
to anxdr.Union
. That means you'll need to get the discriminant before reading its value.As listed above, a transaction envelope can contain a
TransactionV0Envelope
, aTransactionV1Envelope
, or aFeeBumpTransactionEnvelope
.TransactionV0Envelope
andTransactionV1Envelope
are very similar, but differ in one attribute: the source account.Next, let's explore how to handle each discriminant. We'll use js-stellar-base as a reference; however, implementation might change depending on your programming language.
TransactionV0Envelope and TransactionV1Envelope
Both
v0
andv1
can be handled in the same wrapper class; we extended theTransaction
class in js-stellar-base to do so. https://github.com/stellar/js-stellar-base/blob/a15fc74c1f5d37e1a2a94bd610990ccea62292bb/src/transaction.jsIn the constructor, we check for the discriminant and throw an error if the envelope doesn't contain a
v0
orv1
transaction.Something important to keep in mind here is that the source account is called sourceAccount of type MuxedAccount in V1, but it is called sourceAccountEd25519 of type Uint256 in V0.
The following code handles both scenarios to pull out their string key representation:
Source
Another important thing to keep in mind is that you need to do some special handling when getting the signature base for a
V0
transaction.Source
And finally, you also need to add special handling when converting the transaction back to an
xdr.TransactionEnvelope
(see the implementation of toEnvelope).For your SDK to be compatible with Protocol 12 and Protocol 13, you need to create a
TransactionEnvelope
withTransactionV0
. If you try to submit av1
transaction or a fee bump transaction to an instance of Stellar running Protocol 12, then it will fail.In
js-stellar-base
we have a builder class which generatesv0
transactions by default. You can see the implementation here. You'll also notice that we added a feature flag which allows generation ofv1
transactions.Ideally, once Protocol 13 is released, you should update your SDK to generate
V1
transactions by default.FeeBumpTransactionEnvelope
To handle the scenario when the envelope contains a
FeeBumpTransactionEnvelope
, let's usejs-stellar-base
as a reference.You can see that we added a new class called
FeeBumpTransaction
, which wraps axdr.TransactionEnvelope
with aFeebump
transaction https://github.com/stellar/js-stellar-base/blob/a15fc74c1f5d37e1a2a94bd610990ccea62292bb/src/fee_bump_transaction.jsIn the constructor for the class above, you can see the following code:
It restricts the kind of transaction envelope which can be received by this class.
You can also see that it has a getter for the innerTransaction, which returns a
Transaction
class that allows consumers to query data about the transaction being wrapped by the fee bump transaction. This allows you to answer questions like:ftx.innerTransaction.fee
ftx.innerTransaction.hash
ftx.innerTransaction.signatures
Besides that, it exposes other fee bump-specific attributes like
feeSource
,hash
,signatureBase
, etc.We also extended the builder to make it easy for users to create fee bump transactions. The helper is called buildFeeBumpTransaction.
In addition, we added a
fromXDR
helper function to the builder to make it easier to read aTransaction
orFeeBumpTransaction
. See the implementation here.3 - Handle muxed accounts
There are two major changes around muxed accounts. The first is updating fields which expect a
MuxedAccount
;the second is extending.Strkey
to generatedM...
accountsFirst, you need to update the following fields — which were previously an
xdr.AccountID
and are now anxdr.MuxedAccount
:PaymentOp.destination
PathPaymentStrictReceiveOp.destination
PathPaymentStrictSendOp.destination
Operation.sourceAccount
Operation.destination (for ACCOUNT_MERGE)
Transaction.sourceAccount
FeeBumpTransaction.feeSource
The following pull requests show you the changes in the JS library:
Second, you need to implement SEP0023, which allows you to turn aSee the update below about M address support.MuxedAccount
into a string. A reference implementation can be found in pull request #330.4 - Add support for Fine-Grained Control of Authorization
CAP 18 changed the data type for the attribute
authorize
inAllowTrustOp
. It is now auint32
instead of aboolean
. It also includes a newTrustLineFlag
which isauthorizedToMaintainLiabilitiesFlag
with value2
.You can see the implementation in
js-stellar-base
here, which still accepts booleans but converts the value to anuint32
.5 - Update Horizon response for Transaction, Balance, Operation, and Effect.
In the Horizon 1.1.0 release we added new attributes to different resources:
fee_account
(the account which paid the transaction fee)fee_bump_transaction
(only present in Protocol 13 fee bump transactions)inner_transaction
(only present in Protocol 13 fee bump transactions) (#2406).is_authorized_to_maintain_liabilities
toBalance
.authorize_to_maintain_liabilities
toAllowTrust
operation.trustline_authorized_to_maintain_liabilities
.In the upcoming Horizon 1.2.0 release a base 64 encoding of the bytes in a transaction memo will be included in the Horizon transaction response as
memo_bytes
Horizon 1.2.0 also schedule a couple of breaking changes which are required to support CAP-15.
int64
tostring
in 1.3.0:fee_charged
in Transaction resource.max_fee
in Transaction resource.You SDK should be able to parse either a
string
or anumber
.6 - Testing
Once you have your implementation ready, you can test it out by submitting a transaction to Horizon 1.1 or later. Remember that for now, your library should produce V0 transactions.
The Stellar Laboratory now has support for protocol 13, so you can also create
V1
and fee bump transactions and test them out in the XDR viewer there.References stellar/stellar-protocol#600.
The text was updated successfully, but these errors were encountered: