Migrating from TronWeb v5

Why v6.x

New Features & Capabilities

• TronWeb v6.x includes support for newer TRON protocol updates and TRON-based standards.
• Future feature development will only support version v6.x, while version v5.x will receive security fixes only.

Developer Experience Upgrades

• TronWeb v6.x provides improved TypeScript type definitions and compatibility, making it more developer-friendly and reducing bugs in large projects.
• Full TypeScript definitions for better IDE autocompletion and type safety.
• TronWeb v6.x uses Promises instead of callbacks, aligning with modern JavaScript practices like async/await.

Security Improvements

• Active versions like v6.x receive critical security patches.
• Regularly fixes vulnerable dependency packages to enhance security.

Better ESM support

• Native ESM module exports (import/export syntax) enable tree-shaking and seamless integration with modern bundlers like Webpack/Vite.

Better Documentation and Community Support

• As v6.x becomes the standard, more tutorials, community solutions, and official resources focus on it.

To better support its use in TypeScript project, we have rewritten the entire library in TypeScript. And to make TronWeb API more secure and more consistent, there are some breaking changes.

The breaking changes are listed below.

Change Default exports to Named exports

The default export of the project is no longer the TronWeb class. You can use import { TronWeb } from 'tronweb'; instead. And other constructors are also no longer mounted on the TronWeb class. You have to use the same way to import them. For example if you want to use TronWeb.utils, you should import { utils as TronWebUtils } from 'tronweb'; and then use TronWebUtils; Example:

import { TronWeb, utils as TronWebUtils, Trx, TransactionBuilder, Contract, Event, Plugin } from 'tronweb';

Transaction and SignedTransaction

In typescript, those are two types. After you sign a transaction, the transaction object add signature prop automatically, and you can pass it to trx.sendRawTransaction as below:

await tronWeb.trx.sign(transaction, pk);
const result = {
  transaction,
  receipt: await tronWeb.trx.sendRawTransaction(transaction),
};

But if you do it in typescript, it will throw an error. Because transaction is Transaction type and trx.sendRawTransaction only accepts SignedTransaction type. To solve it, use the returned object from trx.sign like below:

const signedTransaction = await tronWeb.trx.sign(transaction, pk);
const result = {
  transaction,
  receipt: await tronWeb.trx.sendRawTransaction(signedTransaction),
};

Some methods are changed

TronWeb.createRandom

Change TronWeb.createRandom(options) to TronWeb.createRandom(password, path, wordlist).

TronWeb.fromMnemonic

Change TronWeb.fromMnemonic(mnemonic, path, wordlist) to TronWeb.fromMnemonic(mnemonic, path, password, wordlist).

utils.abi.decodeParams

The parameters are as follows: utils.abi.decodeParams(names: string[], types: string[], output: string, ignoreMethodHash = false) You must pass names argument. If there is no name, pass an empty array.

utils.code.hexStr2byteArray

utils.code.hexStr2byteArray will not verify whether the argument is a string.

Strict check for position and type of parameters

In the previous version, most methods support variable parameter length. For example, the following codes are both valid:

// Normally the third parameter is 'fromAddress', and the forth is options.
await tronWeb.transactionBuilder.sendTrx('toAddress', 10, 'fromAddress', { permissionId: 2 });

// If the third parameter is object, it will be treated as options and fromAddress will be tronWeb.defaultAddress.
await tronWeb.transactionBuilder.sendTrx('toAddress', 10, { permissionId: 2 });

In v6.x, we do not support ignoring some of the arguments between required arguments and object arguments such as options with permissioinId.

Throw Error instance instead of string when error occurs

In the previous version, most methods support a callback parameter to get an asynchronous result. And if no callback is passed, the method returns a promise with injectpromise. If you catch an error, you will receive a string message:

try {
  await tronWebV5.transactionBuilder.clearABI('contractAddress');
} catch (e) {
  console.log(typeof e); // will print 'string'
}

In v6.x, we removed this feature and all mothods only return a promise. When an method throws error, you will receive an Error instance:

try {
  await tronWeb.transactionBuilder.clearABI('contractAddress');
} catch (e) {
  console.log(typeof e); // will print 'object'
  console.log(e.message);
}

Method will throw error with Invalid privateKey

In the previous version, TronWeb.trx#multiSign() reports that the key has no permission to sign if you pass an invalid privateKey.

In v6.x, the method will throw an error if the privateKey is invalid. And wherever you use an invalid privateKey, an error is also output.

triggerSmartContract api doesn't support 6 arguments

In the previous version, tronWeb.transactionBuilder.triggerSmartContract can support 6 arguments except callback argument. It's a rare usage and we removed the usage to make the api more consistent. Thus, the third argument must be the options. Here is a code example:

// previous version
const transaction = await tronWeb.transactionBuilder.triggerSmartContract(
  contractAddress,
  functionSelector,
  1000000000, // feeLimit
  0, // callValue
  parameters,
  ownerAddress,
);

// In v6
const transaction = await tronWeb.transactionBuilder.triggerSmartContract(
  contractAddress,
  functionSelector,
  {
    feeLimit: 1000000000,
    callValue: 0,
  },
  parameters,
  ownerAddress,
);

TronWeb#sidechain is removed.

Sidechain has been removed from TronWeb. If you still want to use it, use SunWeb instead.

Events service has changed.

Event#watch() is removed.

contract.someEvent().watch() is no longer supported.

Events backend services have changed.

Since a new backend service is provided for querying contract events, there are some changes in the returned data structure compared to the previous version.

The standard format of the return value of the event query API is shown as follows:

{
    "success":true,
    "data": [
      {
          "block_number": 42054864,
          "block_timestamp": 1700704884000,
          "caller_contract_address": "TPYwAC9Y4uUcT2QH3WPPjqxzJSJWymMoMS",
          "contract_address": "TPYwAC9Y4uUcT2QH3WPPjqxzJSJWymMoMS","event_index": 1,
          "event_name": "Transfer",
          "result": {
             "0": "0x65fa68800fff5a10346d1a3aa1fb2ce92f2e2971",
             "1": "0xbbd6d9c36cf31f73b01ad2415b12d9d2bda7fb08",
             "2": "27000000","from":"0x65fa68800fff5a10346d1a3aa1fb2ce92f2e2971",
             "to": "0xbbd6d9c36cf31f73b01ad2415b12d9d2bda7fb08","value": "27000000"
          },
          "result_type": {
            "from":"address",
            "to":"address",
            "value":"uint256"
          },
          "event": "Transfer(address indexed from, address indexed to, uint256 value)",
          "transaction_id": "9c9e4776de1ee889aad48be360262e3dd6d1a1e3d4e0d7c72dc50075260846df"
        }
    ],
    "meta": {
        "at":1700720666204,
        "page_size": 1
    }
}

Typing for plugins

When using plugins in typescript, TronWeb doesn't know what are added to it. So, custom typing should be added too. For example, you have a plugin called MyPlugin, before you want to use it, you should add plugins type to TronWeb to avoid the editor prompting errors. You can do it as below:

declare namespace globalThis {
    interface MyTronWeb extends TronWeb {
        trx: {
            getCurrentBlock(): Promise<Block & { fromPlugin: true }>;
            getLatestBlock(): Promise<Block & { fromPlugin: true }>;
            getSomeParameter(): string;
        } & Trx;
    }
}
const tronWeb = new TronWeb() as globalThis.MyTronWeb;
const someParameter = 'someParameter';
const result = tronWeb.plugin.register(MyPlugin, {
    someParameter,
});

const result2 = await tronWeb.trx.getCurrentBlock();
assert.isTrue(result2.fromPlugin);
assert.equal(result2.blockID.length, 64);

const result3 = await tronWeb.trx.getSomeParameter();
assert.equal(result3, someParameter);

New API

1. getEventsByBlockNumber Query events by block number.

2. getEventsOfLatestBlock Query events of the latest block.

FAQ

1. Cannot destructure property 'Transaction' of 'globalThis.TronWebProto' as it is undefined.

This is a problem caused by webpack as it doesn't load cjs file correctly. To solve this problem, you need to add a new rule like below:

{
      test: /\.cjs$/,
      type: 'javascript/auto'
}

2. TronWeb.isAddress() and some other functions not working in browser.

For reducing package size of TronWeb, we didn't polyfill Buffer and crypto. You have to polyfill them in your config. For vite, try methods listed here. For nuxt, add configs like below:

alias: {
  'crypto': 'crypto-browserify',
  'buffer': 'buffer/',
  'stream': 'readable-stream',
},
app: {
  head: {
    script: [{ children: "window.global ||= window;" }],
  },
},

3. Type 'Uint8Array' is not generic.

In TronWeb v6.0.3, we use TypeScript v5.8.2. It generates Uint8Array as a generic type. And it will fail if you compile your code with a TypeScript version below v5.7. To fix this, make sure you're using TypeScript v5.7 or later.

4. 'Uncaught Error: unknown function' or 'EE Error' occured when using tronWeb.contract().

TronWeb now strictly checks abi types. Therefore, if you use the tuple type in inputs or outputs, you have to provide components field in the abi.