Tron blockchain PHP docking development package [support USDT-TRC20]

Posted by Calcartman on Thu, 09 Apr 2020 17:42:20 +0200

The TronTool development package is suitable for rapidly increasing the support ability of Tron/USDT-TRC20 digital assets for PHP applications, that is, it supports the application scenarios using its own Tron blockchain nodes, and also supports the lightweight deployment scenarios based on the official public API services of Tron. Official download address of TronTool: http://sc.hubwiz.com/codebag/tron-php-lib/.

1. Development package overview

The TronTool development package mainly includes the following features:

  • Support Tron blockchain native Trx transaction
  • Support Tron smart contract and TRC20 token, such as USDT-TRC20, etc
  • Support offline signature of transaction to avoid private key disclosure
  • Complete Tron node API encapsulation, supporting the API provided by all nodes, solid nodes and event nodes
  • Support the use of own nodes or third-party nodes, such as the public nodes officially provided by Tron

TronTool software package runs in * * Php 7.1 + *, current version is 1.0.0, main classes / interfaces and relationships are shown in the following figure:

For the list of main code files of TronTool, please refer to the instructions on the official website: TronTool PHP .

2. Use sample code

2.1 create new address

Enter the demo code directory at the terminal and execute the following command:

~$ cd ~/trontool/demo
~/trontool/demo$ php NewAddressDemo.php

The results are as follows:

2.2 Trx transfer and balance query

Enter the demo code directory at the terminal and execute the following command:

~$ cd ~/trontool/demo
~/trontool/demo$ php TrxDemo.php

The results are as follows:

2.3 Trc20 token transfer, balance query and event monitoring

Enter the demo code directory at the terminal and execute the following command:

~$ cd ~/trontool/demo
~/trontool/demo$ php Trc20Demo.php

The results are as follows:

2.4 Tron smart contract deployment

Enter the demo code directory at the terminal and execute the following command:

~$ cd ~/trontool/demo
~/trontool/demo$ php DeployContractDemo.php

The results are as follows:

2. Using TronKit

TronKit is the entry to the development package. Using this class, you can quickly implement the following functions:

  • Trx transfer and balance inquiry
  • Trc20 token transfer, authorization, balance query, etc

2.1 instantiate TronKit

TronKit instantiation needs to pass in the TronApi object and the Credential object. These two parameters encapsulate the API provided by the Tron node and the user identity information for transaction signature.

For example, the following code creates a TronKit instance connected to the main chain of Tron and signs the transaction with the specified private key:

use TronTool\TronKit;
use TronTool\TronApi;
use TronTool\Credential;

$kit = new TronKit(
  TronApi::mainNet(),                                       //Access backbone
  Credential::fromPrivateKey('87c12d....d435')              //Use the specified private key
);

2.2 Trx transfer and balance query

Use the sendTrx() method of TronKit to transfer Trx, such as sending 1000 TRX:

$to = 'TDN3QY85Jft3RwgyatjRNmrwRmwkn8qwqx';                 //Transfer target address
$amount = 1000000000;                                       //Transfer amount in SUN
$ret = $kit->sendTrx($to,$amount);                          //Submit Trx transfer transaction
echo 'txid => ' . $ret->tx->txID .  PHP_EOL;                //Show transaction ID
echo 'result => ' . $ret->result . PHP_EOL;                 //Show transaction results

Note: the amount unit needs to be converted to SUN, 1 TRX = 1000000 SUN.

Use the getTrxBalance() method to query the Trx balance of the specified address, for example:

$addr = 'TDN3QY85Jft3RwgyatjRNmrwRmwkn8qwqx';               //Tron address to query
$balance = $kit->getTrxBlanace($addr);                      //Query Trx balance in SUN
echo 'trx balance => ' . $balance . PHP_EOL;                //Display balance

2.3 TRC20 token transfer

Use the Trc20() method to get an example of the specified TRC20 token contract, then invoke the transfer() method of the contract to make TRC20 token transfer. For example, the following code specifies the USDT-TRC20 token of 1315300 minimum units transferred between addresses, i.e. 1.3153 USDT:

$to = 'TDN3QY85Jft3RwgyatjRNmrwRmwkn8qwqx';                 //Transfer target address
$amount = 1315300;                                          //Transfer Trc20 token quantity
$contractAddress = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'     //Deployment address of USDT-TRC20 token contract
$usdt = $kit->Trc20($contractAddress);                      //Create Trc20 token contract instance
$ret = $usdt->transfer($to,$amount);                        //Transfer Trc20 token
echo 'txid => ' . $ret->tx->txID .  PHP_EOL;                //Display transfer transaction ID
echo 'result => ' . $ret->result . PHP_EOL;                 //Display transfer transaction results

2.4 TRC20 token balance query

Use the Trc20() method to get an example of the specified TRC20 token contract, then call the balanceOf() method of the contract to query the TRC20 token balance of the specified address. For example, the following code queries the USDT token balance for the specified address:

$usdt = $kit->Trc20('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t');          //Create a USDT-TRC20 token contract instance
$balance = $usdt->balanceOf('TDN3QY85Jft3RwgyatjRNmrwRmwkn8qwqx');  //Query Trc20 token balance
echo 'usdt balance => ' . $balance . PHP_EOL;                       //Display token balance

2.5 TRC20 token event query

Use the Trc20() method to get an example of the specified TRC20 token contract, then call the events() method to query the specified contract trigger event.

For example, query the last 10 seconds of a USDT token contract:

$usdt = $kit->Trc20('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t');    //Create Trc20 token contract instance
$since = time() - 10000;                                      //Calculate check point
$events = $usdt->events($since);                              //Extract contract event
foreach($events as $event){                                   
  echo 'block height => ' . $event->block_number . PHP_EOL;   //Show block height triggered by event
  echo 'event name => ' . $event->event_name . PHP_EOL;       //Show event name
}  

The result returned by events() is an array of event objects. The main fields of each member object are described as follows:

  • Caller ﹣ contract ﹣ address: call contract address, base58 format
  • Transaction? ID: transaction ID triggering contract event, hexadecimal string
  • result: contract event parameter list, array
  • Result "type: contract event parameter type list, array
  • block_timestamp: time stamp of the block where the event is located, integer
  • Block u number: the block number of the event, integer
  • Event name: event name, string
  • Contract "address: contract address, base58 format
  • event_index: sequence number of event index, integer

For example, the following is the JSON representation of the Transfer event object of a TRC20 token contract. The event name is given in the event name field, and the event parameters in two index forms are given in the result field:

{
  "caller_contract_address": "TS2Hzo6KpAc8Ym2nGb3idpMtUpM2GiK2gL",
  "transaction_id": "265cf378f4943b7c77b7a294f533d4b8c718c297dd28a664848d77cd3f3a0af0",
  "result": {
    "0": "0x2539ef4f3eb733c105a957eebb20fd60ad8c9a43",      //Event parameter 0
    "1": "0x6f6794f3904ff51f9fa81e928afdec91f6744a50",      //Event parameter 1
    "2": "8",                                               //Event parameter 2        
    "_from": "0x2539ef4f3eb733c105a957eebb20fd60ad8c9a43",  //Event parameter from
    "_value": "8",                                          //Event parameter
    "_to": "0x6f6794f3904ff51f9fa81e928afdec91f6744a50"     //Event parameters
  },
  "result_type": {
    "_from": "address",                                     
    "_value": "uint256",
    "_to": "address"
  },
  "block_timestamp": 1586263455000,
  "block_number": 3539438,
  "event_name": "Transfer",                                 //Event name   
  "contract_address": "TS2Hzo6KpAc8Ym2nGb3idpMtUpM2GiK2gL",
  "event_index": 0
}

3. Identity and address representation of Tron blockchain

In TronTool, use Credential to represent a user identity in the Tron blockchain and Address to represent an Address in the Tron blockchain. The difference between the two is that Credential contains the user's private key information, which can be used to sign transactions, so it needs to be protected, and Address is the information that can be disclosed.

Create a new account using the static method create() of the Credential class. For example, the following code creates a new account and displays its private key, public key, and address:

use TronTool\Credential;

$credential = Credential::create();                           //Create a new account
echo 'private key => ' . $credential->privateKey() . PHP_EOL; //Display private key
echo 'public key => ' . $credential->publicKey() . PHP_EOL;   //Display public key
echo 'address => ' . $credential->address() . PHP_EOL;        //display address

You can use the static method fromPrivateKey() to import the existing private key to instantiate the Credential. For example, the following code imports the existing private key and displays the address:

use TronTool\Credential;

$credential = Credential::fromPrivateKey('7889...023a');      //Import existing private key
echo 'address => ' . $credential->address() . PHP_EOL;        //Display corresponding address

In Tron blockchain, there are two representations of address: hexadecimal and base58. For example, the following are two representations of the same address:

  • base58: TDN3QY85Jft3RwgyatjRNmrwRmwkn8qwqx
  • Hex: 412539EF4F3EB733C105A957EEBB20FD60AD8C9A43

The address class contains the corresponding encoding and decoding logic. Address can be instantiated with different forms of address. For example:

$a1 = Address::fromBase58('TDN3QY85Jft3RwgyatjRNmrwRmwkn8qwqx');
echo $a1->hex() . PHP_EOL;        //Output: 412539EF4F3EB733C105A957EEBB20FD60AD8C9A43

$a2 = Address::fromHex('412539EF4F3EB733C105A957EEBB20FD60AD8C9A43');
echo $a2->base58() . PHP_EOL;     //Output: TDN3QY85Jft3RwgyatjRNmrwRmwkn8qwqx

Sometimes we just need to convert the Address between base58 and hexadecimal. At this time, we don't need the middle Address object. We can directly use the static methods encode() and decode(). For example:

$a1 = Address::decode('TDN3QY85Jft3RwgyatjRNmrwRmwkn8qwqx');
echo $a1 . PHP_EOL;             //Output: 412539EF4F3EB733C105A957EEBB20FD60AD8C9A43

$a2 = Address::encode('412539EF4F3EB733C105A957EEBB20FD60AD8C9A43');
echo $a2 . PHP_EOL;             //Output: TDN3QY85Jft3RwgyatjRNmrwRmwkn8qwqx

4. Using TronApi to access the Tron node API

Use TronApi to access the various node APIs of Tron. TronApi aggregates the APIs provided by many Tron nodes, such as the Tron full node, the solidity node and the event service node.

When instantiating TronApi, you can specify different connection URL s for different types of Tron nodes, for example:

use TronTool\TronApi;

$tc = new TronApi(
  'https://api.trongrid.io ', / / full node URL
  'https://api.trongrid.io ', / / contract node URL
  'https://api.trongrid.io '/ / event node URL
);

When the URL s of the above three nodes are the same, they can be abbreviated as:

$tc = new TronApi('https://api.trongrid.io');

If you use the official TronGrid node provided by Tron, you can directly use the two static functions mainNet() and testNet() provided by TronApi to access the main chain and shasta test chain respectively.

For example, the following code is equivalent:

$tc = new TronApi('https://api.trongrid.io');
$tc = TronApi::mainNet();                       //Equivalent to above

$tc = new TronApi('https://api.shasta.trongrid.io');
$tc = TronApi::testNet();                       //Equivalent to above

TronApi encapsulates the API s provided by many official nodes of Tron, and basically maintains the corresponding relationship for easy search and utilization. For example, to query the TRX balance of an account:

$info = $tc->getAccount('TEgM5CPeqowkKUXoKrFrpvB7vcBgVkD4tP');  //Query account information
echo 'balance -> ' . $info->balance . PHP_EOL;                  //Display account balance  

Tron blockchain docking PHP development package: http://sc.hubwiz.com/codebag/tron-php-lib/

Topics: PHP Blockchain JSON encoding