Tron transaction hex helpers — protobuf varints, the TransferContract integrity check and the signed-Transaction envelope. More...

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for tron_tx.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	TRON_ADDR_HEX_LEN 42U
	Hex length of a Tron address (21 bytes: 0x41 \|\| 20-byte key hash).
#define	TRON_SIG_HEX_LEN 130U
	Hex length of a Tron signature (r \|\| s \|\| v).
#define	TRON_TRC20_SELECTOR "a9059cbb"
	TRC-20 `transfer(address,uint256)` selector, hex (same as ERC-20).
#define	TRON_TRC20_PARAM_HEX_LEN 128U
	Hex length of the two ABI argument words that follow the selector.
#define	TRON_TX_MAX_EXPIRY_MS (15ULL * 60ULL * 1000ULL)
	Latest raw_data.expiration accepted, relative to now (15 min). A real node answer expires ~60 s out; see raw_ok() in tron_tx.cpp.

Functions
size_t	tron_varint_hex (uint64_t v, char *out, size_t out_size)
	Hex-encode a value as a protobuf base-128 varint.
bool	tron_tx_contract_ok (const char raw_data_hex, const char owner_hex, const char to_hex, uint64_t amount_sun, uint64_t now_ms, uint64_t expiration_ms)
	Verify that a node-serialised raw_data really transfers what we asked.
size_t	tron_trc20_param_hex (const char to_hex, uint64_t amount, char out, size_t out_size)
	ABI-encode the arguments of `transfer(address,uint256)`, hex.
bool	tron_tx_trc20_ok (const char raw_data_hex, const char owner_hex, const char contract_hex, const char to_hex, uint64_t amount, uint64_t fee_limit_sun, uint64_t now_ms, uint64_t *expiration_ms)
	Verify that a node-serialised raw_data really is the TRC-20 transfer we asked for.
size_t	tron_tx_envelope_hex (const char raw_data_hex, const char sig_hex, char *out, size_t out_size)
	Build the hex of a signed `Transaction` protobuf for broadcasthex.

Detailed Description

Tron transaction hex helpers — protobuf varints, the TransferContract integrity check and the signed-Transaction envelope.

Pure unit: string/hex work only, no IDF, no networking, no globals — so it builds and self-checks on the host (see tests/units/test_tron_tx.cpp), the same pattern as eth_json.cpp and civil_time.cpp.

Why a check at all: a Tron terminal does not serialise its own transaction, it asks a full node to (/wallet/createtransaction) and signs the txID the node hands back. That makes the node a trust boundary — it could return a transaction paying somebody else. tron_tx_contract_ok and tron_tx_trc20_ok walk raw_data field by field, require exactly one contract whose value is byte-for-byte the one we asked for, and refuse any other field (a memo, extra authorities, a second contract), so a hostile or buggy node cannot redirect funds.

Definition in file tron_tx.h.

Macro Definition Documentation

◆ TRON_ADDR_HEX_LEN

#define TRON_ADDR_HEX_LEN 42U

Hex length of a Tron address (21 bytes: 0x41 || 20-byte key hash).

Definition at line 38 of file tron_tx.h.

Referenced by addr_hex_ok(), sign_and_broadcast_tron(), token_decimals_ok(), tron_addr_to_hex(), tron_rpc_get_trc20_balance(), tron_rpc_get_trc20_decimals(), tron_trc20_param_hex(), tron_tx_contract_ok(), and tron_tx_trc20_ok().

◆ TRON_SIG_HEX_LEN

#define TRON_SIG_HEX_LEN 130U

Hex length of a Tron signature (r || s || v).

Definition at line 41 of file tron_tx.h.

Referenced by tron_rpc_broadcast(), and tron_tx_envelope_hex().

◆ TRON_TRC20_PARAM_HEX_LEN

#define TRON_TRC20_PARAM_HEX_LEN 128U

Hex length of the two ABI argument words that follow the selector.

Definition at line 47 of file tron_tx.h.

Referenced by tron_rpc_create_trc20_transfer(), tron_trc20_param_hex(), and tron_tx_trc20_ok().

◆ TRON_TRC20_SELECTOR

#define TRON_TRC20_SELECTOR "a9059cbb"

TRC-20 transfer(address,uint256) selector, hex (same as ERC-20).

Definition at line 44 of file tron_tx.h.

Referenced by tron_tx_trc20_ok().

◆ TRON_TX_MAX_EXPIRY_MS

#define TRON_TX_MAX_EXPIRY_MS (15ULL * 60ULL * 1000ULL)

Latest raw_data.expiration accepted, relative to now (15 min). A real node answer expires ~60 s out; see raw_ok() in tron_tx.cpp.

Definition at line 51 of file tron_tx.h.

Referenced by raw_ok().

Function Documentation

◆ tron_trc20_param_hex()

size_t tron_trc20_param_hex	(	const char *	to_hex,
		uint64_t	amount,
		char *	out,
		size_t	out_size )

ABI-encode the arguments of transfer(address,uint256), hex.

Two 32-byte words, no selector: the recipient left-padded (its 0x41 Tron prefix dropped — the ABI address word holds the bare 20-byte key hash) and the amount big-endian. This is exactly what the HTTP API's parameter field wants, and exactly what must reappear inside the node's raw_data.

Parameters

[in]	to_hex	Recipient, TRON_ADDR_HEX_LEN hex chars, "41"-prefixed.
[in]	amount	Token amount in base units.
[out]	out	Destination, NUL-terminated on success.
[in]	out_size	Capacity of `out` (>= TRON_TRC20_PARAM_HEX_LEN + 1).

Returns: TRON_TRC20_PARAM_HEX_LEN on success, 0 on bad input or overflow.

Definition at line 341 of file tron_tx.cpp.

References addr_hex_ok(), lower_ascii(), nibble_hex(), TRON_ADDR_HEX_LEN, and TRON_TRC20_PARAM_HEX_LEN.

Referenced by tron_rpc_create_trc20_transfer(), and tron_tx_trc20_ok().

◆ tron_tx_contract_ok()

bool tron_tx_contract_ok	(	const char *	raw_data_hex,
		const char *	owner_hex,
		const char *	to_hex,
		uint64_t	amount_sun,
		uint64_t	now_ms,
		uint64_t *	expiration_ms )

Verify that a node-serialised raw_data really transfers what we asked.

Parses raw_data_hex as a Transaction.raw protobuf: exactly one TransferContract whose value is exactly owner (field 1), to (field 2) and amount (field 3); only the reference-block, expiration and timestamp fields besides it; no fee_limit, memo, authorities or scripts; no repeated field. Fails closed — the caller must decline the payment rather than sign it.

Parameters

[in]	raw_data_hex	Hex of the node's raw_data protobuf.
[in]	owner_hex	Sender, TRON_ADDR_HEX_LEN hex chars, "41"-prefixed.
[in]	to_hex	Recipient, same form.
[in]	amount_sun	Amount in sun (1 TRX = 1e6 sun).
[in]	now_ms	Current Unix time in ms; must be non-zero.
[out]	expiration_ms	raw_data.expiration on success; may be NULL.

Returns: true only if raw_data is exactly the requested transfer and expires within TRON_TX_MAX_EXPIRY_MS of now_ms.

Definition at line 316 of file tron_tx.cpp.

References addr_hex_ok(), now_ms(), raw_hex_ok(), raw_ok(), TRON_ADDR_HEX_LEN, TRON_TYPE_TRANSFER, TRON_URL_TRANSFER, and tron_varint_hex().

Referenced by tron_rpc_create_transfer().

◆ tron_tx_envelope_hex()

size_t tron_tx_envelope_hex	(	const char *	raw_data_hex,
		const char *	sig_hex,
		char *	out,
		size_t	out_size )

Build the hex of a signed Transaction protobuf for broadcasthex.

Transaction { 1: raw_data (bytes) , 2: signature (repeated bytes) }

Parameters

[in]	raw_data_hex	Hex of the raw_data protobuf (even length).
[in]	sig_hex	Signature hex, exactly TRON_SIG_HEX_LEN chars.
[out]	out	Destination, NUL-terminated on success.
[in]	out_size	Capacity of `out`.

Returns: number of hex characters written, 0 on bad input or overflow.

Definition at line 406 of file tron_tx.cpp.

References hex_strlen(), TRON_SIG_HEX_LEN, and tron_varint_hex().

Referenced by tron_rpc_broadcast().

◆ tron_tx_trc20_ok()

bool tron_tx_trc20_ok	(	const char *	raw_data_hex,
		const char *	owner_hex,
		const char *	contract_hex,
		const char *	to_hex,
		uint64_t	amount,
		uint64_t	fee_limit_sun,
		uint64_t	now_ms,
		uint64_t *	expiration_ms )

Verify that a node-serialised raw_data really is the TRC-20 transfer we asked for.

The TRX sibling of this check is tron_tx_contract_ok, with the same strict parse; a token transfer is a TriggerSmartContract instead, whose value must be exactly (call_value 0 may be explicit):

0a15 owner | 1215 contract | 2244 a9059cbb | to-word | amount-word

The contract address decides which asset moves. The fee_limit (raw_data field 18) must be present and equal to fee_limit_sun: it caps the TRX a failed call may burn.

Parameters

[in]	raw_data_hex	Hex of the node's raw_data protobuf.
[in]	owner_hex	Sender, TRON_ADDR_HEX_LEN hex chars, "41"-prefixed.
[in]	contract_hex	Token contract, same form.
[in]	to_hex	Recipient, same form.
[in]	amount	Token amount in base units; must be non-zero.
[in]	fee_limit_sun	Fee cap in sun, as requested; must be non-zero.
[in]	now_ms	Current Unix time in ms; must be non-zero.
[out]	expiration_ms	raw_data.expiration on success; may be NULL.

Returns: true only if raw_data is exactly the requested call.

Definition at line 365 of file tron_tx.cpp.

References addr_hex_ok(), now_ms(), raw_hex_ok(), raw_ok(), TRON_ADDR_HEX_LEN, tron_trc20_param_hex(), TRON_TRC20_PARAM_HEX_LEN, TRON_TRC20_SELECTOR, TRON_TYPE_TRIGGER, and TRON_URL_TRIGGER.

Referenced by tron_rpc_create_trc20_transfer().

◆ tron_varint_hex()

size_t tron_varint_hex	(	uint64_t	v,
		char *	out,
		size_t	out_size )

Hex-encode a value as a protobuf base-128 varint.

Parameters

[out]	out	Destination, NUL-terminated on success (>= 21 bytes is always enough).
[in]	out_size	Capacity of `out`.
[in]	v	Value to encode.

Returns: number of hex characters written (excluding the NUL), 0 if out is NULL or too small.

Definition at line 76 of file tron_tx.cpp.

References nibble_hex().

Referenced by tron_tx_contract_ok(), and tron_tx_envelope_hex().

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ TRON_ADDR_HEX_LEN

◆ TRON_SIG_HEX_LEN

◆ TRON_TRC20_PARAM_HEX_LEN

◆ TRON_TRC20_SELECTOR

◆ TRON_TX_MAX_EXPIRY_MS

Function Documentation

◆ tron_trc20_param_hex()

◆ tron_tx_contract_ok()

◆ tron_tx_envelope_hex()

◆ tron_tx_trc20_ok()

◆ tron_varint_hex()