Implementation of the Tron transaction hex helpers. More...

#include "tron_tx.h"
#include <stdio.h>
#include <string.h>

Include dependency graph for tron_tx.cpp:

Classes
struct	pb_t
	Cursor over a hex byte string; positions count BYTES, not nibbles. More...
struct	pb_field_t
	One field: its number and either its varint or its payload range. More...

Macros
#define	TRON_TYPE_TRANSFER 1U /* ContractType.TransferContract */
#define	TRON_TYPE_TRIGGER 31U /* ContractType.TriggerSmartContract */
#define	TRON_URL_TRANSFER "type.googleapis.com/protocol.TransferContract"
#define	TRON_URL_TRIGGER "type.googleapis.com/protocol.TriggerSmartContract"

Functions
static char	nibble_hex (unsigned n)
static bool	is_hex_digit (char c)
static char	lower_ascii (char c)
static size_t	hex_strlen (const char *s)
	Length of `s` if every character is hex, 0 otherwise.
static bool	raw_hex_ok (const char *raw)
	true if `raw` is usable raw_data hex: all hex, non-empty, whole bytes.
static bool	addr_hex_ok (const char *addr)
	true if `addr` is a "41"-prefixed 21-byte Tron address in 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.
static int	hex_val (char c)
static bool	pb_byte (pb_t p, uint8_t b)
static bool	pb_varint (pb_t p, uint64_t v)
static bool	pb_next (pb_t p, pb_field_t f)
static bool	pb_once (const pb_field_t f, uint32_t wire, uint32_t seen)
	true if field `f` is wire `wire` and was not seen before.
static bool	pb_is_hex (const pb_t sub, const char want)
	true if a payload is exactly the hex string `want` (any case).
static bool	pb_is_str (const pb_t sub, const char want)
	true if a payload is exactly the ASCII string `want`.
static bool	any_ok (pb_t any, const char url, const char v1, const char *v2)
	Any { 1 type_url, 2 value }: exactly `url` and one of the values.
static bool	contract_ok (pb_t c, uint32_t type, const char url, const char v1, const char *v2)
	Contract { 1 type, 2 parameter } and nothing else.
static bool	raw_ok (const char raw_hex, uint32_t type, const char url, const char v1, const char v2, uint64_t fee_limit, uint64_t now_ms, uint64_t *expiration_ms)
	Walk raw_data. `fee_limit` 0 means the field must be absent.
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

Implementation of the Tron transaction hex helpers.

Definition in file tron_tx.cpp.

Macro Definition Documentation

◆ TRON_TYPE_TRANSFER

#define TRON_TYPE_TRANSFER 1U /* ContractType.TransferContract */

Definition at line 216 of file tron_tx.cpp.

Referenced by tron_tx_contract_ok().

◆ TRON_TYPE_TRIGGER

#define TRON_TYPE_TRIGGER 31U /* ContractType.TriggerSmartContract */

Definition at line 217 of file tron_tx.cpp.

Referenced by tron_tx_trc20_ok().

◆ TRON_URL_TRANSFER

#define TRON_URL_TRANSFER "type.googleapis.com/protocol.TransferContract"

Definition at line 218 of file tron_tx.cpp.

Referenced by tron_tx_contract_ok().

◆ TRON_URL_TRIGGER

#define TRON_URL_TRIGGER "type.googleapis.com/protocol.TriggerSmartContract"

Definition at line 219 of file tron_tx.cpp.

Referenced by tron_tx_trc20_ok().

Function Documentation

◆ addr_hex_ok()

bool addr_hex_ok ( const char * addr )

static

true if addr is a "41"-prefixed 21-byte Tron address in hex.

Definition at line 69 of file tron_tx.cpp.

References hex_strlen(), and TRON_ADDR_HEX_LEN.

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

◆ any_ok()

bool any_ok	(	pb_t	any,
		const char *	url,
		const char *	v1,
		const char *	v2 )

static

Any { 1 type_url, 2 value }: exactly url and one of the values.

Definition at line 222 of file tron_tx.cpp.

References pb_t::end, pb_field_t::num, pb_is_hex(), pb_is_str(), pb_next(), pb_once(), pb_t::pos, and pb_field_t::sub.

Referenced by contract_ok().

◆ contract_ok()

bool contract_ok	(	pb_t	c,
		uint32_t	type,
		const char *	url,
		const char *	v1,
		const char *	v2 )

static

Contract { 1 type, 2 parameter } and nothing else.

Definition at line 243 of file tron_tx.cpp.

References any_ok(), pb_t::end, pb_field_t::num, pb_next(), pb_once(), pb_t::pos, pb_field_t::sub, and pb_field_t::value.

Referenced by raw_ok().

◆ hex_strlen()

size_t hex_strlen ( const char * s )

static

Length of s if every character is hex, 0 otherwise.

Definition at line 47 of file tron_tx.cpp.

References is_hex_digit().

Referenced by addr_hex_ok(), raw_hex_ok(), and tron_tx_envelope_hex().

◆ hex_val()

int hex_val ( char c )

static

Definition at line 123 of file tron_tx.cpp.

References lower_ascii().

Referenced by pb_byte().

◆ is_hex_digit()

bool is_hex_digit ( char c )

static

Definition at line 34 of file tron_tx.cpp.

Referenced by hex_strlen().

◆ lower_ascii()

char lower_ascii ( char c )

static

Definition at line 41 of file tron_tx.cpp.

Referenced by hex_val(), pb_is_hex(), and tron_trc20_param_hex().

◆ nibble_hex()

char nibble_hex ( unsigned n )

static

Definition at line 28 of file tron_tx.cpp.

Referenced by tron_trc20_param_hex(), and tron_varint_hex().

◆ pb_byte()

bool pb_byte	(	pb_t *	p,
		uint8_t *	b )

static

Definition at line 131 of file tron_tx.cpp.

References pb_t::end, pb_t::hex, hex_val(), and pb_t::pos.

Referenced by pb_is_str(), and pb_varint().

◆ pb_is_hex()

bool pb_is_hex	(	const pb_t *	sub,
		const char *	want )

static

true if a payload is exactly the hex string want (any case).

Definition at line 190 of file tron_tx.cpp.

References pb_t::end, pb_t::hex, lower_ascii(), and pb_t::pos.

Referenced by any_ok().

◆ pb_is_str()

bool pb_is_str	(	const pb_t *	sub,
		const char *	want )

static

true if a payload is exactly the ASCII string want.

Definition at line 202 of file tron_tx.cpp.

References pb_t::end, pb_byte(), and pb_t::pos.

Referenced by any_ok().

◆ pb_next()

bool pb_next	(	pb_t *	p,
		pb_field_t *	f )

static

Definition at line 162 of file tron_tx.cpp.

References pb_t::end, pb_t::hex, pb_field_t::num, pb_varint(), pb_t::pos, pb_field_t::sub, pb_field_t::value, and pb_field_t::wire.

Referenced by any_ok(), contract_ok(), and raw_ok().

◆ pb_once()

bool pb_once	(	const pb_field_t *	f,
		uint32_t	wire,
		uint32_t *	seen )

static

true if field f is wire wire and was not seen before.

Definition at line 181 of file tron_tx.cpp.

References pb_field_t::num, and pb_field_t::wire.

Referenced by any_ok(), contract_ok(), and raw_ok().

◆ pb_varint()

bool pb_varint	(	pb_t *	p,
		uint64_t *	v )

static

Definition at line 142 of file tron_tx.cpp.

References pb_byte().

Referenced by pb_next().

◆ raw_hex_ok()

bool raw_hex_ok ( const char * raw )

static

true if raw is usable raw_data hex: all hex, non-empty, whole bytes.

Odd-length hex is not a byte string, so it is refused here rather than read.

Definition at line 61 of file tron_tx.cpp.

References hex_strlen().

Referenced by tron_tx_contract_ok(), and tron_tx_trc20_ok().

◆ raw_ok()

bool raw_ok	(	const char *	raw_hex,
		uint32_t	type,
		const char *	url,
		const char *	v1,
		const char *	v2,
		uint64_t	fee_limit,
		uint64_t	now_ms,
		uint64_t *	expiration_ms )

static

Walk raw_data. fee_limit 0 means the field must be absent.

The expiration is bounded as well as returned. A node that set it hours out could hold the signed transaction back and broadcast it after the terminal has told the operator it never went out and a second payment was taken. The chain allows up to 24 h; a real answer is about 60 s.

Definition at line 273 of file tron_tx.cpp.

References contract_ok(), pb_t::end, now_ms(), pb_field_t::num, pb_next(), pb_once(), pb_t::pos, pb_field_t::sub, TRON_TX_MAX_EXPIRY_MS, and pb_field_t::value.

Referenced by tron_tx_contract_ok(), and tron_tx_trc20_ok().

◆ 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().

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ TRON_TYPE_TRANSFER

◆ TRON_TYPE_TRIGGER

◆ TRON_URL_TRANSFER

◆ TRON_URL_TRIGGER

Function Documentation

◆ addr_hex_ok()

◆ any_ok()

◆ contract_ok()

◆ hex_strlen()

◆ hex_val()

◆ is_hex_digit()

◆ lower_ascii()

◆ nibble_hex()

◆ pb_byte()

◆ pb_is_hex()

◆ pb_is_str()

◆ pb_next()

◆ pb_once()

◆ pb_varint()

◆ raw_hex_ok()

◆ raw_ok()

◆ tron_trc20_param_hex()

◆ tron_tx_contract_ok()

◆ tron_tx_envelope_hex()

◆ tron_tx_trc20_ok()

◆ tron_varint_hex()