Migration guide from v14 to v15

[danielailie]

Migration from v14 to v15

v15 is a major release that introduces several important changes:

• New GasLimitEstimator component
  In response to the Barnard release, where gas limit overestimation dropped from 10x to 2x, we’ve added the GasLimitEstimator.
  This component simulates a transaction to compute the required gas limit and allows an optional multiplier (e.g., 1.2) for safety margins.
  It can be passed to any TransactionFactory or Controller.

• Removal of deprecated methods
  Several previously deprecated methods have been removed to streamline the codebase.

⚠️ This release includes breaking changes. Please review the list below to ensure a smooth upgrade from v14.

[danielailie]

Breaking Changes

1. All factory methods are now async
   All methods from transaction factories are now asynchronous.
   Make sure to await these methods wherever you previously used them to build a transaction.

   // v14
   const tx = factory.createTransactionFor...(...);
   
   // v15
   const tx = await factory.createTransactionFor...(...);

[danielailie]

2. Entrypoint initialization has changed
   Entrypoints now follow a unified options pattern consistent with other components.
   Review your entrypoint initialization code and update it to match the new options style.

// v14
const entrypoint = new DevnetEntrypoint("https://devnet-gateway.multiversx.com", "proxy");

// v15
const entrypoint = new DevnetEntrypoint({ url: "https://devnet-gateway.multiversx.com", kind: "proxy" });

[danielailie]

3. Removed deprecated methods in CodeMetadata
   The following methods have been removed. Use the updated alternatives:

   • CodeMetadata.newFromBuffer(buffer: Buffer)
     → Use CodeMetadata.newFromBytes(bytes: Uint8Array) instead.

   • codeMetadata.toBuffer()
     → Use codeMetadata.toBytes() instead.

[danielailie]

4. Removed deprecated methods in TokenTransfer
   Many methods in TokenTransfer have been removed. Use the new constructor-based API or recommended utilities:

   • TokenTransfer.egldFromAmount(amount: BigNumber.Value)
     → Use TokenTransfer.newFromNativeAmount(amount: bigint) instead.

   • TokenTransfer.egldFromBigInteger(amountAsBigInteger: BigNumber.Value)
     → Use TokenTransfer.newFromNativeAmount(amount: bigint) instead.

   • TokenTransfer.fungibleFromAmount(tokenIdentifier: string, amount: BigNumber.Value, numDecimals: number)
     → Use: new TokenTransfer({ token, amount })

   • TokenTransfer.fungibleFromBigInteger(tokenIdentifier: string, amountAsBigInteger: BigNumber.Value, numDecimals: number)
     → Use: new TokenTransfer({ token, amount })

   • TokenTransfer.nonFungible(tokenIdentifier: string, nonce: number)
     → Use: new TokenTransfer({ token, amount })

   • TokenTransfer.semiFungible(tokenIdentifier: string, nonce: number, quantity: number)
     → Use: new TokenTransfer({ token, amount })

   • TokenTransfer.metaEsdtFromAmount(tokenIdentifier: string, nonce: number, amount: BigNumber.Value, numDecimals: number)
     → Use: new TokenTransfer({ token, amount })

   • TokenTransfer.metaEsdtFromBigInteger(tokenIdentifier: string, nonce: number, amountAsBigInteger: BigNumber.Value, numDecimals?: number)
     → Use: new TokenTransfer({ token, amount })

   • TokenTransfer.valueOf()
     → Use the amount field directly.

   • TokenTransfer.toPrettyString()
     → For formatting and parsing amounts, use sdk-dapp utilities or libraries like bignumber.js.

   • TokenTransfer.isEgld()
     → Avoid mixing native EGLD and custom tokens.
     Use:

     • TransferTransactionsFactory.createTransactionForNativeTokenTransfer()
     • TransferTransactionsFactory.createTransactionForESDTTokenTransfer()

   • TokenTransfer.isFungible()
     → Use TokenComputer.isFungible(token) instead.

[danielailie]

5. Removed deprecated methods in Transaction
   All getter and setter methods have been removed in favor of direct property access.
   Additionally, some utility methods have been moved to the TransactionComputer class.

   ✅ Replace these with direct property access:

   • transaction.getNonce() / transaction.setNonce(nonce)
     → Use transaction.nonce

   • transaction.getValue() / transaction.setValue(value)
     → Use transaction.value

   • transaction.getSender() / transaction.setSender(sender)
     → Use transaction.sender

   • transaction.getReceiver()
     → Use transaction.receiver

   • transaction.getSenderUsername() / transaction.setSenderUsername(username)
     → Use transaction.senderUsername

   • transaction.getReceiverUsername() / transaction.setReceiverUsername(username)
     → Use transaction.receiverUsername

   • transaction.getGuardian() / transaction.setGuardian(guardian)
     → Use transaction.guardian

   • transaction.getGasPrice() / transaction.setGasPrice(price)
     → Use transaction.gasPrice

   • transaction.getGasLimit() / transaction.setGasLimit(limit)
     → Use transaction.gasLimit

   • transaction.getData()
     → Use transaction.data

   • transaction.getChainID() / transaction.setChainID(id)
     → Use transaction.chainID

   • transaction.getVersion() / transaction.setVersion(version)
     → Use transaction.version

   • transaction.getOptions() / transaction.setOptions(options)
     → Use transaction.options

   • transaction.getSignature()
     → Use transaction.signature

   • transaction.getGuardianSignature() / transaction.applyGuardianSignature(signature)
     → Use transaction.guardianSignature

   ❗ Additional method replacements:

   • transaction.serializeForSigning()
     → Use TransactionComputer.computeBytesForSigning(transaction)

   • transaction.computeFee(networkConfig)
     → Use TransactionComputer.computeTransactionFee(transaction, networkConfig)

   • Transaction.fromPlainObject(plainObjectTransaction)
     → Use Transaction.newFromPlainObject(plainObjectTransaction)

   • transaction.applySignature(signature)
     → Use transaction.signature = signature

[danielailie]

6. Removed deprecated method in TransactionStatus

• transactionStatus.isExecuted()
  → Use transactionStatus.isCompleted() instead.

[danielailie]

7. Removed deprecated methods in Address class Several deprecated methods have been removed. Please use the recommended replacements below:

• Address.fromBech32(bech32Address: string)
  → Use Address.fromBech32Address(bech32Address: string) instead.

• address.toString()
  → Use address.bech32() instead.

• address.toBuffer()
  → Use address.toBytes() instead.

• address.isContractAddress()
  → Use address.isSmartContract() instead.