Appearance

Quickstart ​

This doc will take you through the basics of creating a TronBox project and deploying a smart contract to a blockchain.

TIP

NOTE: Before you begin, it is advised that you read the TRON documentation.

Install TronBox ​

Before using TronBox, please install it using npm command. You can install TronBox by referring to the installation instructions.

Create a project ​

Most TronBox commands run inside a TronBox project. We'll use tronbox init to create a project from the built-in MetaCoin template, which creates a token that can be transferred between accounts.

  1. Create an empty directory for MetaCoin:
Terminal
shell
mkdir MetaCoin
cd MetaCoin
  1. Initialize the project:
Terminal
shell
tronbox init

Select Create a MetaCoin project from the interactive menu:

Terminal
text
? What do you want to do? …
  Create a sample project
❯ Create a MetaCoin project
  Quit

TronBox creates the project files and installs the npm dependencies automatically.

Once this operation is completed, you will have a project structure with the following items:

Explore the project ​

TIP

NOTE: This page is just a quickstart, and we're going to get into the details in the following sections.

  • contracts/MetaCoin.sol: This Solidity contract creates a MetaCoin token using OpenZeppelin ERC20 and contracts/ConvertLib.sol. It also includes a TRX locking and withdrawal example.
  • contracts/Migrations.sol: This is a separate Solidity file that records deployment progress on-chain, so tronbox migrate runs only the migrations that have not run yet. It is optional, is scaffolded by default, and usually does not need to be edited.
  • migrations/1_initial_migration.js: This is the script used to deploy the Migrations contract defined in contracts/Migrations.sol.
  • migrations/2_deploy_contracts.js: This is a deployment script that is used to deploy the MetaCoin contract. (Deployment scripts run in sequence. Scripts titled with 2 normally run after those titled 1.)
  • test/metacoin.js: This is a testing script written in JavaScript that ensures your contract is working as expected.
  • tronbox-config.js: This is the TronBox configuration file, for setting network information and other project-related settings. The template already provides the local development configuration used in this tutorial.

Compile contracts ​

Execute the compilation:

Terminal
shell
tronbox compile

We will see the following output:

Terminal
shell
Compiling your contracts...
===========================
Compiling ./contracts/ConvertLib.sol...
Compiling ./contracts/MetaCoin.sol...
Compiling ./contracts/Migrations.sol...
Compiling @openzeppelin/contracts/interfaces/draft-IERC6093.sol...
Compiling @openzeppelin/contracts/token/ERC20/ERC20.sol...
Compiling @openzeppelin/contracts/token/ERC20/IERC20.sol...
Compiling @openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol...
Compiling @openzeppelin/contracts/utils/Context.sol...
Writing artifacts to ./build/contracts

> Compiled successfully using:
  - solc: 0.8.31

Deploy to TRE ​

To deploy our smart contracts, we're going to need to connect to a blockchain. TronBox provides a TronBox Runtime Environment (TRE) private chain that can be used for testing. Please note that this blockchain is local to your system and does not interact with the main TRON network. You can start this blockchain and interact with it using TRE. This step is to create a complete personal chain for development on TRON.

  1. Pull images from the Docker:
Terminal
shell
docker pull tronbox/tre

For how to install Docker, please refer to Docker installation documentation

  1. Start the TronBox Runtime Environment (TRE) and run the following commands:
Terminal
shell
docker run -it -p 9090:9090 --rm --name tron tronbox/tre

For TRE configuration details, see the TRE documentation.

Startup output includes the following (private keys and the mnemonic are omitted):

Terminal
text
----------------------------------

TronBox Runtime Environment v2.0.0

----------------------------------
06:48:14 INFO  Available Accounts
==================

(0) TWtvhFs3cpvzmgWmX9Qwi1g6jmL4uH65RA (10000 TRX)
(1) TQTatyThj2jHMroMcaanSUb4o8t23WiCCU (10000 TRX)
(2) TDFqvxvk3MrwGZuyeofhbmRUiMJrBkjybo (10000 TRX)
(3) TJe4jF5XunL8TZwp1fXZ5zEGnWzSFrT7us (10000 TRX)
(4) TFoguFPAeFCBVrnyQN2FqQruSsYYxCpBGh (10000 TRX)
(5) TZ1PmukAMr4ekPSnRDS9qc23gKkiLQsKR8 (10000 TRX)
(6) TTsFfxDKNRuY16y78WTuDj8wV7r84cebsS (10000 TRX)
(7) TMZZekv1R8c6tQuGdQxJYKcTrC3zrTga3w (10000 TRX)
(8) TPdt3WfK3Lt3my79XWqKbYQdc5gyPrjXP9 (10000 TRX)
(9) TQxA1qEcmopaU7kuJk6DtF5pJjyKZZGNPc (10000 TRX)

Private Keys
==================

(0) ...PRIVATE_KEY_HERE...
(1) ...PRIVATE_KEY_HERE...
(2) ...PRIVATE_KEY_HERE...
(3) ...PRIVATE_KEY_HERE...
(4) ...PRIVATE_KEY_HERE...
(5) ...PRIVATE_KEY_HERE...
(6) ...PRIVATE_KEY_HERE...
(7) ...PRIVATE_KEY_HERE...
(8) ...PRIVATE_KEY_HERE...
(9) ...PRIVATE_KEY_HERE...

HD Wallet
==================
Mnemonic:      ... MNEMONIC_HERE ...
Base HD Path:  m/44'/60'/0'/0/{account_index}

Keep this terminal running. Wait until TRE prints Available Accounts and finishes funding the test accounts.

  1. Open another terminal, change to your MetaCoin directory, and deploy:
Terminal
shell
tronbox migrate

We will see the following output:

Terminal
shell
Using network 'development'.

Compiling your contracts...
===========================
> Everything is up to date, there is nothing to compile.

Running migration: 1_initial_migration.js
  Deploying Migrations...
  Migrations:
    (base58) TK6VFN5K2pDdfgYcavAeBhAKL6Fi6kL6sk
    (hex) 4164199b15a9c614728830e18bc742280664ce76d0
Saving successful migration to network...
Saving artifacts...
Running migration: 2_deploy_contracts.js
  Deploying ConvertLib...
  ConvertLib:
    (base58) TY21iar68zk4nvhfQyGtvBgA5YECaCDnz8
    (hex) 41f1da987e9b263461dfe29d0a8759e1e5f6fa2336
  Linking ConvertLib to MetaCoin
  Deploying MetaCoin...
  MetaCoin:
    (base58) TXbYXf7uu2X8njYgTdzVZBdCapyXWVAVnu
    (hex) 41ed39eab885224ca73c89f010c60fbf9334532d99
Saving successful migration to network...
Saving artifacts...

This shows the network, addresses of your deployed contracts, and transaction statuses.

TIP

NOTE: Your transaction hashes and contract addresses will be different from the above.

Test contracts ​

  1. Run the JavaScript tests in a terminal:
Terminal
shell
tronbox test ./test/metacoin.js
  1. After hitting the return key, you will see the following output:
Terminal
shell
Using network 'development'.

Compiling your contracts...
===========================
> Everything is up to date, there is nothing to compile.

Deploying contracts to development network...
Preparing JavaScript tests (if any)...


  Contract: MetaCoin
    ✔ should verify that there are at least two available accounts
    ✔ should verify that the contract has been deployed by accounts[0]
    ✔ should put 10000 MetaCoin in the first account
    ✔ should call a function that depends on a linked library
    ✔ should send coins from account 0 to 1 (48ms)
Sleeping for 10 seconds... Slept.
    ✔ should allow owner to withdraw TRX after unlock time (10125ms)


  6 passing (10s)

TIP

NOTE: If you’re on Windows and encountering problems running this command, please see the documentation on Solving naming conflicts on Windows.

Interact with the contract ​

To interact with the contract, you can use the tronbox console.

Terminal
shell
tronbox console

You will see the following prompt:

Terminal
shell
tronbox(development)>

TIP

NOTE: The name in the parentheses of the prompt tronbox(development)> is the network that is currently connected to.

For example:

  • Check the account balance:
Terminal
shell
tronbox(development)> tronWeb.trx.getAccount();

// outputs:
// {
//   address: '41e58b5d828330f2696d89d657ba7a0e7cc61af6d6',
//   balance: 7905694282,
//   latest_opration_time: 1790159739153,
//   free_net_usage: 4752,
//   latest_consume_free_time: 1790158875654,
//   net_window_size: 86400000000,
//   net_window_optimized: true,
//   account_resource: {
//     latest_consume_time_for_energy: 1790159739153,
//     energy_window_size: 86400000000,
//     energy_window_optimized: true
//   },
//   owner_permission: { permission_name: 'owner', threshold: 1, keys: [ [Object] ] },
//   active_permission: [
//     {
//       type: 'Active',
//       id: 2,
//       permission_name: 'active',
//       threshold: 1,
//       operations: '7fff1fc0033ec30f000000000000000000000000000000000000000000000000',
//       keys: [Array]
//     }
//   ],
//   frozenV2: [ {}, { type: 'ENERGY' }, { type: 'TRON_POWER' } ],
//   asset_optimized: true
// }
  • Obtain the list of accounts:
Terminal
shell
tronbox(development)> tronWeb._accounts;

// outputs:
// [
//   'TWtvhFs3cpvzmgWmX9Qwi1g6jmL4uH65RA',
//   'TQTatyThj2jHMroMcaanSUb4o8t23WiCCU',
//   'TDFqvxvk3MrwGZuyeofhbmRUiMJrBkjybo',
//   'TJe4jF5XunL8TZwp1fXZ5zEGnWzSFrT7us',
//   'TFoguFPAeFCBVrnyQN2FqQruSsYYxCpBGh',
//   'TZ1PmukAMr4ekPSnRDS9qc23gKkiLQsKR8',
//   'TTsFfxDKNRuY16y78WTuDj8wV7r84cebsS',
//   'TMZZekv1R8c6tQuGdQxJYKcTrC3zrTga3w',
//   'TPdt3WfK3Lt3my79XWqKbYQdc5gyPrjXP9',
//   'TQxA1qEcmopaU7kuJk6DtF5pJjyKZZGNPc'
// ]
  • Call the contract to check the account balance:
Terminal
shell
tronbox(development)> MetaCoin.deployed().then(res => res.balanceOf(tronWeb._accounts[0]));

// outputs:
// 10000n
  • Transfer some metacoin to other accounts:
Terminal
shell
tronbox(development)> MetaCoin.deployed().then(res => res.sendCoin(tronWeb._accounts[1], 500));

// outputs:
// 'f1c96960d78029ac54211f54c526f46bfa5aa19d88d9f0352fdf1713aaa6047e'
  • Check that the transfer succeeded, using the transaction ID returned above:
Terminal
shell
tronbox(development)> tronWeb.trx.getTransactionInfo('f1c96960d78029ac54211f54c526f46bfa5aa19d88d9f0352fdf1713aaa6047e').then(info => info.receipt?.result);

// outputs:
// 'SUCCESS'

If the result is undefined, wait a few seconds and retry. Continue to the balance checks only after the result is SUCCESS.

  • Check the balance of the account that received the metacoin:
Terminal
shell
tronbox(development)> MetaCoin.deployed().then(res => res.balanceOf(tronWeb._accounts[1]));

// outputs:
// 500n
  • Check the balance of the account that sent the metacoin:
Terminal
shell
tronbox(development)> MetaCoin.deployed().then(res => res.balanceOf(tronWeb._accounts[0]));

// outputs:
// 9500n

Continue learning ​

This quickstart showed you the basics of the TronBox project lifecycle, but there is much more to learn. Please continue with the rest of our documentation.