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_quantity (const char hex, uint64_t out)
	Parse a JSON-RPC QUANTITY ("0x0", "0x1a", 64 hex chars) into a uint64, saturating 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

Parse a JSON-RPC QUANTITY ("0x0", "0x1a", 64 hex chars) into a uint64, saturating instead of wrapping.

A balance is a uint256 and this is not, so a value wider than 16 significant hex digits reports UINT64_MAX. That direction is the safe one for the callers here: these numbers are compared against what a sale costs, and an over-reported balance only lets a doomed sale through to the node that would have refused it anyway — which is the behaviour without this check at all — whereas a wrapped one would refuse a sale that is funded. An account holding 20 ETH is past 2^64 wei, so this is the ordinary case and not a corner.

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 135 of file eth_json.h.

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

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

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ eth_json_receipt_t

Function Documentation

◆ eth_json_error_message()

◆ eth_json_hex_quantity()

◆ eth_json_receipt_check()

◆ eth_json_receipt_status()

◆ eth_json_result_string()