Migration support: "v12" to "v13" (April 2024) #392

andreibancioiu · 2024-02-28T14:20:26Z

Here, we describe the main steps for migrating from sdk-core v12 to sdk-core v13.

💡 For any questions about the migration, feel free to leave a comment 🙏 💡

When transitioning from v12 to v13, you should encounter little to no breaking changes.

However, we've introduced new approaches of creating transactions (transfers, smart contract transactions, token management operations, delegation operations), performing contract queries, and parsing transaction outcome. These new approaches are (mostly) in line with our newest SDK specs, and we recommend you to use them whenever possible.

Legacy methods are still available - though, at some point into the future, they will be marked as deprecated.

References:

Release notes of v13
SDK-JS cookbook
Auto-generated API documentation
SDK-JS examples
PR that updated the SDK-JS cookbook: Update cookbook wrt. js-core v13 mx-sdk-js-examples#31
Main "feat" PR on SDK-JS: v13: Merge feat/next into main #347
sdk-specs

andreibancioiu · 2024-02-28T15:01:05Z

1 / Non-breaking change: new `TransactionFactories` vs. legacy factories and builders

In v13, we have new ways of constructing transactions. The existing (legacy) approaches (v12) are still available.

Transfer (EGLD, ESDT) transactions

Instead of new TransferTransactionsFactory(gasEstimator), use new TransferTransactionsFactory({ config: new TransactionsFactoryConfig(...), tokenComputer: new TokenComputer() }).
Instead of TransferTransactionsFactory.createEGLDTransfer(), use TransferTransactionsFactory.createTransactionForNativeTokenTransfer().
Instead of TransferTransactionsFactory.createESDTTransfer(), use TransferTransactionsFactory.createTransactionForESDTTokenTransfer.
Instead of TransferTransactionsFactory.createESDTNFTTransfer, use TransferTransactionsFactory.createTransactionForESDTTokenTransfer.
Instead of TransferTransactionsFactory.createMultiESDTNFTTransfer, use TransferTransactionsFactory.createTransactionForESDTTokenTransfer.

Smart Contract transactions

Instead of SmartContract.deploy(), use SmartContractTransactionsFactory.createTransactionForDeploy().
Instead of SmartContract.upgrade(), use SmartContractTransactionsFactory.createTransactionForUpgrade().
Instead of SmartContract.call(), use SmartContractTransactionsFactory.createTransactionForExecute().

Relayed transactions

Instead of RelayedTransactionV1Builder, use RelayedTransactionsFactory.createRelayedV1Transaction()
Instead of RelayedTransactionV2Builder, use RelayedTransactionsFactory.createRelayedV2Transaction()

Token management transactions

Instead of TokenOperationsFactory (legacy, somehow unknown), use the new TokenManagementTransactionsFactory.

References

andreibancioiu · 2024-02-28T15:05:12Z

2 / Non-breaking change: new way of performing contract queries

The existing (legacy) approaches are still working.

Before:

query = contract.createQuery({
    func: "getUltimateAnswer"
});

rawResponse = await networkProvider.queryContract(query);

Or using the interaction API:

query = contract.methods.getUltimateAnswer().buildQuery();
rawResponse = await networkProvider.queryContract(query);

Now:

adapter = new QueryRunnerAdapter({ networkProvider });
controller = new SmartContractQueriesController({ abi, queryRunner: adapter });
nicelyParsedResponse = await controller.runQuery({ function: "getUltimateAnswer" });

References

https://docs.multiversx.com/sdk-and-tools/sdk-js/sdk-js-cookbook-v13/#contract-queries

andreibancioiu · 2024-02-28T15:11:01Z

3 / Non-breaking change: new way of parsing outcome of transactions

The existing (legacy) approaches are still available.

Smart Contract transactions

Instead of ResultsParser.parseOutcome(), use SmartContractTransactionsOutcomeParser.parseExecute().
Instead of ResultsParser.parseUntypedOutcome(), use SmartContractTransactionsOutcomeParser.parseExecute().
Instead of ResultsParser.parseEvent(), use TransactionEventsParser.parseEvent().

Token management transactions

Instead of TokenOperationsOutcomeParser.*, use TokenManagementTransactionsOutcomeParser.*.

References

For the rest of outcome parsers & more details, check out:

andreibancioiu · 2024-02-28T15:14:18Z

4 / Non-breaking change: constructor and properties of `Transaction`

Since v13, the Transaction class exhibits its state as public read-write properties. For example, you can access and set the nonce property, instead of using getNonce and setNonce.

Additionally, the constructor has been adjusted in a non-breaking manner to accept initialization parameters as improved, simplified types.

E.g. transaction data can now be passed both as a simple, standard Uint8Array (new approach) and as a legacy TransactionPayload object. Value can now be passed both as a simple, standard bigint (new approach) and as a BigNumber (legacy). For the rest, see the cookbook and the auto-generated API docs.

Cookbook

andreibancioiu · 2024-02-28T15:16:31Z

5 / Small breaking change on `Transaction`: adjusted type for `version` and `options`

In v12, these fields were marked as deprecated:

class Transaction {
    // @deprecated
    version: TransactionVersion;
    // @deprecated
    options: TransactionOptions;

Now, in v13, we've un-deprecated them, but we've also altered their types:

class Transaction {
    ...
    version: number;
    options: number;
    ...
}

References

andreibancioiu · 2024-03-24T21:59:18Z

6 / Non-breaking (in practice) change: default transaction version is now 2, instead of 1

That is, when you create a Transaction object and do not specify an explicit version for the transaction, the new default is 2. Previously, it was 1.

Generally speaking, this should not be a breaking change within client code.

Overriding the transaction version is possible.

References

andreibancioiu · 2024-03-25T08:30:07Z

7 / Non-breaking change: pass a transaction hash to `TransactionWatcher.await*`

This is a non-breaking change. The old way of using TransactionWatcher is still available. However, we recommend the new approach.

Before:

async awaitCompleted(transaction: ITransaction): Promise<ITransactionOnNetwork> {...}
async awaitAnyEvent(transaction: ITransaction): Promise<ITransactionOnNetwork> {...}
...

Now:

async awaitCompleted(txHash: string): Promise<ITransactionOnNetwork> {...}
async awaitAnyEvent(txHash: string): Promise<ITransactionOnNetwork> {...}
...

References

andreibancioiu · 2024-03-25T19:17:49Z

8 / Non-breaking change: `BigInt` vs. `BigNumber`

We now favor the use of bigint primitive, instead of number or BigNumber of bignumber.js (library) - where applicable: for nonces, gas limit, gas price, amounts etc.

Classes / functions continue to accept BigNumber of bignumber.js library, just as before v13.

References

andreibancioiu · 2024-03-25T20:32:47Z

9 / Non-breaking change: serializing objects for signing

The legacy method serializeForSigning() is still available on Transaction and Message. However, we recommend using the new TransactionComputer and MessageComputer to convert these objects to raw bytes - in order to sign them:

const transactionComputer = new TransactionComputer();
const transactionBytes = transactionComputer.computeBytesForSigning(transaction);

const messageComputer = new MessageComputer();
const messageBytes = messageComputer.computeBytesForSigning(message);

Furthermore, the class SignableMessage is not deprecated - use Message, instead. Additionally, if your application is concerned with passing signed message over the Internet (e.g. towards a service, an API) and verifying them, you might be interested into: packing and unpacking a message.

References

andreibancioiu · 2024-04-01T19:20:50Z

10 / Formatting and parsing amounts

For formatting or parsing token amounts as numbers (with fixed number of decimals), do not rely on sdk-core. Instead, use sdk-dapp (higher level) or bignumber.js (lower level).

References

andreibancioiu · 2024-04-01T19:33:36Z

11 / Breaking change (trivial): `Interaction.withSingleESDTNFTTransfer()` and `Interaction.withMultiESDTNFTTransfer()` - dropped `sender` parameter

We've removed the (long deprecated) sender parameter from the methods: Interaction.withSingleESDTNFTTransfer() and Interaction.withMultiESDTNFTTransfer().

When using the (now legacy) interaction facility to build smart contract calls, make sure to use withSender() instead.

However, now, since v13, the recommended way to build smart contract calls is by means of the new transactions factories. See SmartContractTransactionsFactory.

Cookbook

andreibancioiu · 2024-04-01T19:49:44Z

12 / Small (trivial) breaking change: `Address` constructor cannot be called without parameters anymore

The Address constructor cannot be called without parameters anymore. Replacement: Address.empty().

However, generally speaking, new Address(/no params/) should have never been used within client code. Just the same, Address.empty() should not be used by client code, generally speaking (internal use only).

References

andreibancioiu · 2024-04-01T19:52:27Z

13 / Breaking (fixing) change: `TokenOperationsFactory` - removed `canMint`, `canBurn`

On TokenOperationsFactory (legacy, somehow unknown component), some unused and already deprecated input parameters (flags) have been removed: canMint, canBurn.

However, now, since v13, the recommended way to build smart contract calls is by means of the new transactions factories. Note: TokenOperationsFactory is not part of the new set of factories - it's an old one. The corresponding new one is called TokenManagementTransactionsFactory.

Cookbook

pending

Additional references

https://docs.multiversx.com/tokens/esdt-tokens (globalBurn and globalMint do not exist anymore, for a long time)

andreibancioiu · 2024-04-17T14:12:32Z

14 / Breaking change when passing `variadic` values to `SmartContract.call()`

Please follow this:

andreibancioiu added the migration Migration support label Feb 28, 2024

andreibancioiu mentioned this issue Mar 24, 2024

v13: Merge feat/next into main #347

Merged

andreibancioiu assigned popenta and andreibancioiu Mar 25, 2024

andreibancioiu mentioned this issue Mar 27, 2024

Cookbooks sdk-js: versioned multiversx/mx-docs#851

Merged

7 tasks

multiversx deleted a comment from andreibancioiu Mar 27, 2024

andreibancioiu changed the title ~~Migration support: "v12" to "v13" (March 2024)~~ Migration support: "v12" to "v13" (April 2024) Apr 1, 2024

multiversx deleted a comment from BrodysgotMs Apr 17, 2024

andreibancioiu mentioned this issue Apr 18, 2024

Merge feat/next into main (v13.1.0) #445

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migration support: "v12" to "v13" (April 2024) #392

Migration support: "v12" to "v13" (April 2024) #392

andreibancioiu commented Feb 28, 2024 •

edited

andreibancioiu commented Feb 28, 2024 •

edited

andreibancioiu commented Feb 28, 2024 •

edited

andreibancioiu commented Feb 28, 2024 •

edited

andreibancioiu commented Feb 28, 2024 •

edited

andreibancioiu commented Feb 28, 2024 •

edited

andreibancioiu commented Mar 24, 2024 •

edited

andreibancioiu commented Mar 25, 2024 •

edited

andreibancioiu commented Mar 25, 2024 •

edited

andreibancioiu commented Mar 25, 2024 •

edited

andreibancioiu commented Apr 1, 2024 •

edited

andreibancioiu commented Apr 1, 2024 •

edited

andreibancioiu commented Apr 1, 2024 •

edited

andreibancioiu commented Apr 1, 2024 •

edited

andreibancioiu commented Apr 17, 2024 •

edited

Migration support: "v12" to "v13" (April 2024) #392

Migration support: "v12" to "v13" (April 2024) #392

Comments

andreibancioiu commented Feb 28, 2024 • edited

💡 For any questions about the migration, feel free to leave a comment 🙏 💡

References:

andreibancioiu commented Feb 28, 2024 • edited

1 / Non-breaking change: new TransactionFactories vs. legacy factories and builders

Transfer (EGLD, ESDT) transactions

Smart Contract transactions

Relayed transactions

Token management transactions

References

andreibancioiu commented Feb 28, 2024 • edited

2 / Non-breaking change: new way of performing contract queries

References

andreibancioiu commented Feb 28, 2024 • edited

3 / Non-breaking change: new way of parsing outcome of transactions

Smart Contract transactions

Token management transactions

References

andreibancioiu commented Feb 28, 2024 • edited

4 / Non-breaking change: constructor and properties of Transaction

Cookbook

andreibancioiu commented Feb 28, 2024 • edited

5 / Small breaking change on Transaction: adjusted type for version and options

References

andreibancioiu commented Mar 24, 2024 • edited

6 / Non-breaking (in practice) change: default transaction version is now 2, instead of 1

References

andreibancioiu commented Mar 25, 2024 • edited

7 / Non-breaking change: pass a transaction hash to TransactionWatcher.await*

References

andreibancioiu commented Mar 25, 2024 • edited

8 / Non-breaking change: BigInt vs. BigNumber

References

andreibancioiu commented Mar 25, 2024 • edited

9 / Non-breaking change: serializing objects for signing

References

andreibancioiu commented Apr 1, 2024 • edited

10 / Formatting and parsing amounts

References

andreibancioiu commented Apr 1, 2024 • edited

11 / Breaking change (trivial): Interaction.withSingleESDTNFTTransfer() and Interaction.withMultiESDTNFTTransfer() - dropped sender parameter

Cookbook

andreibancioiu commented Apr 1, 2024 • edited

12 / Small (trivial) breaking change: Address constructor cannot be called without parameters anymore

References

andreibancioiu commented Apr 1, 2024 • edited

13 / Breaking (fixing) change: TokenOperationsFactory - removed canMint, canBurn

Cookbook

Additional references

andreibancioiu commented Apr 17, 2024 • edited

14 / Breaking change when passing variadic values to SmartContract.call()

andreibancioiu commented Feb 28, 2024 •

edited

andreibancioiu commented Feb 28, 2024 •

edited

1 / Non-breaking change: new `TransactionFactories` vs. legacy factories and builders

andreibancioiu commented Feb 28, 2024 •

edited

andreibancioiu commented Feb 28, 2024 •

edited

andreibancioiu commented Feb 28, 2024 •

edited

4 / Non-breaking change: constructor and properties of `Transaction`

andreibancioiu commented Feb 28, 2024 •

edited

5 / Small breaking change on `Transaction`: adjusted type for `version` and `options`

andreibancioiu commented Mar 24, 2024 •

edited

andreibancioiu commented Mar 25, 2024 •

edited

7 / Non-breaking change: pass a transaction hash to `TransactionWatcher.await*`

andreibancioiu commented Mar 25, 2024 •

edited

8 / Non-breaking change: `BigInt` vs. `BigNumber`

andreibancioiu commented Mar 25, 2024 •

edited

andreibancioiu commented Apr 1, 2024 •

edited

andreibancioiu commented Apr 1, 2024 •

edited

11 / Breaking change (trivial): `Interaction.withSingleESDTNFTTransfer()` and `Interaction.withMultiESDTNFTTransfer()` - dropped `sender` parameter

andreibancioiu commented Apr 1, 2024 •

edited

12 / Small (trivial) breaking change: `Address` constructor cannot be called without parameters anymore

andreibancioiu commented Apr 1, 2024 •

edited

13 / Breaking (fixing) change: `TokenOperationsFactory` - removed `canMint`, `canBurn`

andreibancioiu commented Apr 17, 2024 •

edited

14 / Breaking change when passing `variadic` values to `SmartContract.call()`