Migration support: "v11" to "v12" (April 2023)

andreibancioiu commented 1 year ago

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

:bulb: For any questions about the migration, feel free to leave a comment :pray: :bulb:

References:

Release notes of v12
SDK-JS cookbook
SDK-JS examples
PR(s) that updated the SDK-JS cookbook: https://github.com/multiversx/mx-docs/pull/619
Main "feat" PR on SDK-JS: https://github.com/multiversx/mx-sdk-js-core/pull/263

andreibancioiu commented 1 year ago

Breaking change

Passing the sender is now required on most transaction builders (not only on the Transaction constructor). For example, you are required to pass the caller when using smartContract.call() or the deployer when using smartContract.deploy(). When using the interactions API, make sure to call interaction.withSender(). transaction.setSender() is also supported (if needed).

andreibancioiu commented 1 year ago

Important change (wallet - signing & verifying)

See: https://docs.multiversx.com/sdk-and-tools/sdk-js/sdk-js-cookbook/#signing-objects

For developers of wallet / wallet-like applications, or for back-end applications or scripts that sign transactions and messages:

sdk-core v12 supports both sdk-wallet v3 and sdk-wallet v4. Though, we recommend migrating to sdk-wallet v4. Then, signing transactions would look as follows:

const serialized: Buffer = transaction.serializeForSigning();
const signature: Buffer = await signer.sign(serialized);
transaction.applySignature(signature);

Breaking change (related)

transaction.getSignature() now returns a Buffer, instead of a ISignature object.
signableMessage.getSignature() now returns a Buffer, instead of a ISignature object.

andreibancioiu commented 1 year ago

Breaking changes (ABI)

We've slightly simplified the loading of an ABI and feeding it to a SmartContract object. See https://github.com/multiversx/mx-sdk-js-core/pull/281. In v12, this is done as follows:

const abiRegistry = AbiRegistry.create({ ... });
const contract = new SmartContract({ address: existingAddress, abi: abiRegistry });

Related breaking changes

We've removed SmartContractAbi and ContractInterface - they were over-engineered, designed to handle multiple sets of contract endpoints (namespaces / separate interfaces etc.). We've kept AbiRegistry, which is sufficient.
abiRegistry.getAllEndpoints has been renamed to getEndpoints().
SmartContract.setAbi() has been removed. The ABI is passed in constructor only.
SmartContract.getAbi() is not exposed anymore. When an ABI definition is needed (e.g. endpoint, type), it should be found in the AbiRegistry.
Removed ContractFunction.equals() - was already deprecated for some time.

andreibancioiu commented 1 year ago

Breaking change (formatting, less important)

tokenPayment.toRationalNumber() has been renamed to toAmount() - and, actually, it became private, you cannot use (should not use) it anymore. toPrettyString() is still available, but it may be deprecated in a future release, in favor of a separate, more customizable formatter.

andreibancioiu commented 1 year ago

Deprecation(s) / changes on constructing transfers

TokenPayment has been deprecated (renamed). Use the new name: TokenTransfer, instead. ITokenPayment became ITokenTransfer, as well. The old names will be removed in the next major version.

Deprecated the parameter sender of interaction.withSingleESDTNFTTransfer() and interaction.withMultiESDTNFTTransfer(). Use interaction.withSender() instead, when setting up the interaction object.

andreibancioiu commented 1 year ago

Breaking change: transaction options and version

The following changes are a result of integrating the support for guarded transactions :lock:

We've removed the static function TransactionOptions.withTxHashSignOptions. Use the constructor instead, and pass it the necessary flags (options).
The constant TRANSACTION_VERSION_TX_HASH_SIGN has been renamed to TRANSACTION_VERSION_WITH_OPTIONS.

Directly reading or setting the fields transaction.options, transaction.version is now deprecated. Use the get* and set* functions, instead.

andreibancioiu commented 1 year ago

Breaking change (minor) - transaction completion

We've slightly altered the constructor of TransactionWatcher.

raress96 commented 1 year ago

Hello, why was the function toAmount made private in TokenTransfer? I find it quite useful since I do a lot of custom formatting, and toPrettyString also has the tokenIdentifier in it which I don't want. It is also useful when representing amounts without so many decimals, and want to compare agains the token transfer value.

Now I have to call the amountAsBigInteger and do shiftBy myself which is more tedious... If it exists as a getter it should be public IMO, there is no side effect it can cause.

andreibancioiu commented 1 year ago

Hello, why was the function toAmount made private in TokenTransfer? I find it quite useful since I do a lot of custom formatting, and toPrettyString also has the tokenIdentifier in it which I don't want. It is also useful when representing amounts without so many decimals, and want to compare agains the token transfer value.

Now I have to call the amountAsBigInteger and do shiftBy myself which is more tedious... If it exists as a getter it should be public IMO, there is no side effect it can cause.

Hello @raress96,

We'd like to have as little as possible UI logic in sdk-core, thus this change. Indeed, you are now required to apply formatting logic on your side. That is, the logic in your front-end has to know to format numbers (this is intended).

We might include a customizable formatter in the future - but this is not yet decided.

Thank you for your understanding :pray:

andreibancioiu commented 1 year ago

ESDTTransferPayloadBuilder, ESDTNFTTransferPayloadBuilder etc. have been previously deprecated (in v11). Now, they aren't exported anymore - they will be removed in the next major release.

Make sure to use the TransferTransactionsFactory instead: https://docs.multiversx.com/sdk-and-tools/sdk-js/sdk-js-cookbook/#token-transfers

multiversx / mx-sdk-js-core