eth_json.h File Reference

JSON-RPC response parsing helpers — kept in their own unit (cJSON + CW_Utils only, no ESP-IDF networking) so they can be fuzzed on the host (see fuzz/fuzz_eth_rpc_json.cpp). More...

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

Include dependency graph for eth_json.h:

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

Go to the source code of this file.

Classes
struct	eth_receipt_expect_t
	What a receipt must show for the payment to count — see eth_json_receipt_check. More...

Enumerations
enum	eth_json_receipt_t {   ETH_JSON_RECEIPT_ERROR = 0 , ETH_JSON_RECEIPT_PENDING , ETH_JSON_RECEIPT_SUCCESS , ETH_JSON_RECEIPT_REVERTED ,   ETH_JSON_RECEIPT_MISMATCH }
	Verdict for an eth_getTransactionReceipt response body. More...

Functions
bool	eth_json_result_string (const char *resp, char *out, size_t out_size)
	Extract the top-level "result" string from a JSON-RPC response.
bool	eth_json_error_message (const char *resp, char *out, size_t out_size)
	Extract the JSON-RPC error.message from a response body.
eth_json_receipt_t	eth_json_receipt_status (const char *resp)
	Classify an eth_getTransactionReceipt response body.
eth_json_receipt_t	eth_json_receipt_check (const char *resp, const eth_receipt_expect_t *want)
	Classify a receipt AND check it is the payment that was asked for.
static bool	eth_json_hex_u256 (const char *hex, uint8_t out[32])
	Parse a JSON-RPC QUANTITY ("0x0", "0x1a", 64 hex chars) into a 32-byte big-endian uint256 — the width Ethereum itself uses for a balance.
static bool	eth_json_hex_quantity (const char *hex, uint64_t *out)
	eth_json_hex_u256, narrowed to a uint64 that saturates at UINT64_MAX instead of wrapping.

Detailed Description

JSON-RPC response parsing helpers — kept in their own unit (cJSON + CW_Utils only, no ESP-IDF networking) so they can be fuzzed on the host (see fuzz/fuzz_eth_rpc_json.cpp).

Definition in file eth_json.h.

Enumeration Type Documentation

eth_json_receipt_t

enum eth_json_receipt_t

Verdict for an eth_getTransactionReceipt response body.

Enumerator
ETH_JSON_RECEIPT_ERROR	Not valid JSON, or an unexpected shape (caller should treat as a transient RPC error and retry).
ETH_JSON_RECEIPT_PENDING	result is null — not mined yet.
ETH_JSON_RECEIPT_SUCCESS	result.status == "0x1".
ETH_JSON_RECEIPT_REVERTED	result is an object but status != 0x1.
ETH_JSON_RECEIPT_MISMATCH	A mined receipt that is not the payment asked for (eth_json_receipt_check): another hash, recipient, token or amount.

Definition at line 26 of file eth_json.h.

Function Documentation

eth_json_error_message()

bool eth_json_error_message	(	const char *	resp,
		char *	out,
		size_t	out_size )

Extract the JSON-RPC error.message from a response body.

The counterpart to eth_json_result_string, and the only place a node ever says why it refused a transaction: "insufficient funds for gas * price + value", "nonce too low", "transaction underpriced". Dropping it on the floor is what turns every one of those into an identical "Broadcast failed" on the panel, which tells an operator nothing they can act on.

A message longer than out_size is truncated rather than rejected — half a reason beats none, and the caller's buffer is a panel line, not a log.

Parameters

[in]	resp	NUL-terminated response body.
[out]	out	NUL-terminated message on success; untouched otherwise.
[in]	out_size	Capacity of out.

Returns

true if the body parsed and carried a non-empty error message.

Definition at line 39 of file eth_json.cpp.

References ok().

Referenced by eth_rpc_send_raw_tx().

eth_json_hex_quantity()

bool eth_json_hex_quantity ( const char * hex, uint64_t * out )

inlinestatic

eth_json_hex_u256, narrowed to a uint64 that saturates at UINT64_MAX instead of wrapping.

For the quantities that are small by nature (a nonce, decimals, a 6-decimal token balance). Saturating is the safe direction for the same reason as above. A native balance is not one of them: use the uint256 form.

Definition at line 183 of file eth_json.h.

References eth_json_hex_u256().

Referenced by eth_rpc_get_token_balance(), eth_rpc_get_token_decimals(), tron_rpc_get_trc20_balance(), and tron_rpc_get_trc20_decimals().

eth_json_hex_u256()

bool eth_json_hex_u256 ( const char * hex, uint8_t out[32] )

inlinestatic

Parse a JSON-RPC QUANTITY ("0x0", "0x1a", 64 hex chars) into a 32-byte big-endian uint256 — the width Ethereum itself uses for a balance.

Wider than 64 significant hex digits cannot be a uint256 at all; it reports all-0xFF rather than failing, the safe direction for a balance compared against what a sale costs (it can only fail to refuse, never refuse a funded sale).

Header-only, and deliberately: it is the one piece of this unit a host test can reach without cJSON (tests/units/test_eth_hex.cpp).

Parameters

[in]	hex	"0x"-prefixed, NUL-terminated hex string.
[out]	out	Parsed value on success; untouched on failure.

Returns

true on a well-formed quantity; false on a missing prefix, an empty body, or any non-hex character anywhere in it.

Definition at line 132 of file eth_json.h.

Referenced by eth_json_hex_quantity(), and eth_rpc_get_balance().

eth_json_receipt_check()

eth_json_receipt_t eth_json_receipt_check	(	const char *	resp,
		const eth_receipt_expect_t *	want )

Classify a receipt AND check it is the payment that was asked for.

A status of 0x1 alone proves nothing: a node that never broadcast our transaction can answer with the receipt of any other successful one. So on top of eth_json_receipt_status this requires transactionHash to be the hash computed on the device, to to be the expected contract (or payee), and — for a token — a Transfer log from that contract to payee for exactly amount. A mined receipt failing any of those is ETH_JSON_RECEIPT_MISMATCH, never SUCCESS or REVERTED.

Parameters

[in]	resp	NUL-terminated response body.
[in]	want	What the receipt must show; NULL yields ERROR.

Returns

One of eth_json_receipt_t.

Definition at line 162 of file eth_json.cpp.

References addr_hex(), eth_receipt_expect_t::amount, ETH_JSON_RECEIPT_ERROR, ETH_JSON_RECEIPT_MISMATCH, ETH_JSON_RECEIPT_REVERTED, eth_json_receipt_status(), ETH_JSON_RECEIPT_SUCCESS, has_transfer(), eth_receipt_expect_t::payee, str_is(), eth_receipt_expect_t::to, eth_receipt_expect_t::tx_hash, and word_hex().

Referenced by eth_rpc_get_tx_receipt().

eth_json_receipt_status()

eth_json_receipt_t eth_json_receipt_status

(

const char *

resp

)

Classify an eth_getTransactionReceipt response body.

Parses the JSON and inspects the top-level result: null means the tx is still pending; an object's status field ("0x1" = success, anything else = reverted) gives the final verdict. Any other shape (invalid JSON, result neither null nor object, missing/non-string status) yields ETH_JSON_RECEIPT_ERROR.

Parameters

[in]

resp

NUL-terminated response body.

Returns

One of eth_json_receipt_t.

Definition at line 69 of file eth_json.cpp.

References ETH_JSON_RECEIPT_ERROR, ETH_JSON_RECEIPT_PENDING, ETH_JSON_RECEIPT_REVERTED, and ETH_JSON_RECEIPT_SUCCESS.

Referenced by eth_json_receipt_check().

eth_json_result_string()

bool eth_json_result_string	(	const char *	resp,
		char *	out,
		size_t	out_size )

Extract the top-level "result" string from a JSON-RPC response.

Uses a real JSON parser (cJSON) instead of strstr so that JSON-RPC error objects, HTTP error bodies, or look-alike substrings are rejected.

Parameters

[in]	resp	NUL-terminated response body.
[out]	out	NUL-terminated "result" value on success; untouched on failure.
[in]	out_size	Capacity of out.

Returns

true on success; false if the body is not valid JSON, "result" is absent or not a string, or the value does not fit in out.

Definition at line 18 of file eth_json.cpp.

References ok().

Referenced by eth_rpc_get_balance(), eth_rpc_get_nonce(), eth_rpc_get_token_balance(), eth_rpc_get_token_decimals(), and eth_rpc_send_raw_tx().