TronWeb Documentation

For heavy testing and automation, you can run a local private TRON network using the TRON Runtime Environment (TRE) via Docker. Once running, the node is available at http://localhost:9090.

docker run -it -p 9090:9090 --rm --name tron tronbox/tre:dev

Shasta is the official TRON testnet. To interact with it, use the following endpoint:

https://api.shasta.trongrid.io

You can obtain Shasta TRX at trongrid.io/shasta and explore transactions on shasta.tronscan.org.

To use TronWeb in a browser, you can copy the dist file to your project directory and include it via a <script> tag. Alternatively, you can use NPM-based CDN mirrors (ensure you use sub-resource integrity).

# Copy the dist file to your working folder
cp node_modules/tronweb/dist/TronWeb.js ./js/tronweb.js

<script src="./js/tronweb.js"></script>

To use TronWeb in a Node.js environment, install it using your preferred package manager.

npm install tronweb
# or
yarn add tronweb

To enable full TypeScript type safety and method discovery when using a contract instance, you must define your ABI using as const.

If the ABI is not defined with as const, the TypeScript compiler widens the type to a generic AbiFragment[]. This causes the length property to become number and strips the literal types from fragment names and stateMutability. Consequently, the ContractInstance will not be able to derive specific method names from the ABI, and you will lose autocomplete and type checking for contract calls.

Correct usage:

const MY_ABI = [
  { name: 'transfer', type: 'function', ... },
] as const;

// This allows ContractInstance to map 'transfer' to a specific Method type
const contract: ContractInstance<typeof MY_ABI> = ...;

TRON accounts use resources to execute operations. The AccountResource interface tracks these metrics:

• energy_usage: Current energy consumption.
• frozen_balance_for_energy: The amount of TRX frozen specifically to provide energy.
• storage_limit / storage_usage: Limits and current usage for account state storage.
• energy_window_size: The window for energy consumption calculation.
• delegated_frozen_balance_for_energy: Energy acquired via delegation.

Resource types are defined by the ResourceCode enum:

• BANDWIDTH (0x00)
• ENERGY (0x01)
• TRON_POWER (0x02)

TronWeb's public API surface is composed of several key modules that handle different aspects of interacting with the TRON blockchain. The main entry points include:

• TronWeb: The primary class used to interact with the TRON network.
• Contract: Used for interacting with smart contracts.
• Transaction: Handles transaction-related data and structures.
• TransactionBuilder: Provides methods to construct various types of transactions.
• Providers: Manages connections to the blockchain.
• ABI: Handles Application Binary Interface definitions for smart contracts.
• Trx: Utilities and types specific to TRX operations.
• APIResponse: Defines the structure of responses received from the TRON nodes.
• Event: Handles blockchain event types.

When signing structured data, you must define a TypedDataDomain to prevent replay attacks across different chains or contracts. The domain includes metadata about the signing context.

interface TypedDataDomain {
    name?: null | string;          // Human-readable name
    version?: null | string;       // Major version
    chainId?: null | BigNumberish; // Chain ID
    verifyingContract?: null | string; // Contract address
    salt?: null | BytesLike;       // Optional salt
}

The Application Binary Interface (ABI) is composed of several types of fragments that define the interface of a smart contract. When working with contract ABIs, you will encounter these specific fragment types:

• constructor: Defines the contract's initialization function.
• function: Defines a contract method that can be called.
• event: Defines an event that the contract can emit.
• error: Defines a custom error type.
• fallback: A special function called when no other function matches the call.
• receive: A special function used specifically for receiving Ether/TRX.

Each fragment contains metadata such as name, type, and stateMutability (e.g., pure, view, nonpayable, payable).

TronWeb uses several interfaces to represent transactions at different stages of their lifecycle:

1. Transaction: The base structure representing an unsigned transaction. It includes txID, raw_data (containing the contract, block references, expiration, and timestamp), and raw_data_hex.
2. SignedTransaction: An extension of Transaction that includes a signature (an array of strings) and an optional contract_address. This represents a transaction that has been cryptographically signed and is ready for broadcasting.
3. CreateSmartContractTransaction: A specialized Transaction used specifically for deploying new smart contracts, which includes the contract_address of the contract being created.

TRON API responses for transactions follow specific shapes that extend base transaction types:

• GetTransactionResponse: An extension of SignedTransaction that includes a visible boolean flag and a ret array. The ret array contains objects with a contractRet string, which indicates the execution result of the transaction contract.
• GetSignWeightResponse: Returned when checking signature weights. It includes the permission (as APIReturnedPermission), a result object containing a code string, and the transaction as a TransactionWrapper.