Migration guide from v13 to v14

[danielailie]

This major update brings significant enhancements, including new features, a streamlined and simplified API, and a focus on improved usability. Please note that v14 introduces breaking changes from v13, reflecting our commitment to delivering a cleaner and more robust development experience. We recommend reviewing the updated documentation and migration guide to make the transition as smooth as possible.

Check out the Cookbook for examples.

[danielailie]

1. Address Type Standardization

• Change:
  • IAddress interface has been removed, and string is no longer used for addresses (less ambiguity).
  • All functions related to Address were updated (old ones are deprecated and will be removed in future versions):
    • pubKey -> getPubKey
    • fromBech32 -> newFromBech32
    • fromHex -> newFromHex
    • hex -> toHex
    • bech32 -> toBech32
    • isContracAddress -> isSmartContract
    • fromString -> newFromBech32
• Action:
  • Everywhere an address is used (e.g., sender, receiver), update it to use the Address type.
  • Use the new functions names instead of the deprecated ones

Before:

const sender: IAddress = someSender;
const receiver: string = "erd1...";
const contractAddress: string = someAddress.bech32();

After:

const sender: Address = Address.newFromHex(hexValue);
const receiver: Address = Address.newFromBech32("erd1...");
const contractAddress: string = someAddress.toBech32();

[danielailie]

2. Changes in TransactionOnNetwork

• Removed:
  • TransactionOutcome
  • ITransactionOnNetwork
  • Receipt
  • TransactionEventData - data is now Uint8Array
  • TransactionEventTopic - topics are now Uint8Array
• Renamed:
  • contractResults -> smartContractResults
• Updated Types:
  • sender and receiver now use Address instead of IAddress.
• Action: Update all references to TransactionOnNetwork.

[danielailie]

3. Removed Components

• ResultParser and SmartContractQueries are removed.
• Action: If you were using these, you can now use SmartContractController, SmartContractTransactionsFactory and SmartContractTransactionsOutcomeParser.

[danielailie]

4. Transaction Event Parser Changes

• Change: TransactionEventParser no longer receives IAbi but instead uses Abi.
• Action: Update instances where IAbi was used.

Before:

const parser = new TransactionEventParser(abiInterface);

After:

const parser = new TransactionEventParser(new Abi());

[danielailie]

5. Transaction Event Data Handling

• Change: data is no longer used; use additionalData instead.
• Action: Update event handling logic.

Before:

const eventData = event.data;

After:

const eventData = event.additionalData;

[danielailie]

6. Changes in Transaction Object

The Transaction class has been fully updated with concrete types:

• ITransaction interface removed.

• Updated types:

  • sender, receiver, guardian, relayer: Address
  • nonce, value, gasPrice, gasLimit: bigint
  • version, options: number
  • data: Uint8Array
  • chainId: string

• Rename functions to follow convention

  • fromPlainObject -> newFromPlainObject

• Action: Update all transaction-related code.

Before:

const txn: ITransaction = {
  sender: "erd1...",
  receiver: "erd1...",
  nonce: 1,
  value: "1000000000000000000",
  gasLimit: 50000
};

After:

const txn = new Transaction({
  sender: new Address("erd1..."),
  receiver: new Address("erd1..."),
  nonce: 1n,
  value: 1000000000000000000n,
  gasLimit: 50000n,
});

[danielailie]

7. Dropped Interfaces

• Change: The following interfaces were removed and this are the types we will use from now on

  • ITokenTransfer -> TokenTransfer
  • ITransactionPayload -> Uint8Array
  • IGasLimit -> bigint
  • IGasPrice -> bigint
  • Nonce -> bigint
  • ITransactionOptions -> number
  • ITransactionVersion -> number
  • ITransactionValue -> bigint
  • ISignature -> Uint8Array
  • IAccountBalance -> bigint

• Action: Remove references to these interfaces and use concrete types.

[danielailie]

8. Removal of GasEstimator

• Change: GasEstimator is no longer needed and has been removed.
• Action: If you were using GasEstimator, you must now manually specify gas values.

[danielailie]

9. CodeMetadata Method Renaming

• Change:

  • fromBytes → newFromBytes
  • fromBuffer → newFromBuffer

• Action: Update method calls.

Before:

const metadata = CodeMetadata.fromBytes(bytes);

After:

const metadata = CodeMetadata.newFromBytes(bytes);

[danielailie]

10. Network Providers Synchronization

Change:

• The network providers (Api and Proxy) have been completely redesigned and refactored.
• Both now share a common interface, allowing them to be used interchangeably to an extent.
• This improves flexibility and maintainability.

Action:

• If your code directly interacts with network providers, ensure that it aligns with the new structure.
• Since both providers now share a common interface, you can switch between them with minimal changes.
• Check the Cookbook and SDK Specs for in-depth guidance.

For more information check the specs.

[danielailie]

11. Removal of Relayed Transactions (V1 & V2)

Change: RelayedV1 and RelayedV2 were removed.
Action: If you were using these, consider using Relayed V3.

[danielailie]

12. Restructuring

Change:

• The folder structure has been updated to follow a feature-based pattern, making it more intuitive and easier to navigate.

Action Required:

• If you are referencing internal paths, ensure that import statements are updated accordingly.
• Review the new structure to adapt your project layout if necessary.

[danielailie]

13. Introduction of Controllers

Change: New controllers have been added to manage various functionalities:

• AccountManagementController
• DelegationController
• SmartContractsController
• TokenManagementController
• TransfersController

Action: Familiarize yourself with these controllers and refactor your code to utilize them where appropriate. This may involve replacing direct service calls with the corresponding controller methods.