hardening.h File Reference

Decision-integrity primitives (see docs/HARDENING.md §3, §4). More...

#include <stdint.h>
#include <string.h>
#include "eth_addr.h"

Include dependency graph for hardening.h:

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

Go to the source code of this file.

Classes
struct	pos_amount_t
struct	pos_addr_t

Macros
#define	TRUE32   ((bool32)0x5AA55AA5u)
#define	FALSE32   ((bool32)0xA55AA55Au)
#define	IS_TRUE32(x)
#define	POS_VERDICT_APPROVED   ((pos_verdict_t)0x33CC33CCu)
#define	POS_VERDICT_DECLINED   ((pos_verdict_t)0xCC33CC33u)

Typedefs
typedef uint32_t	bool32
typedef uint32_t	pos_verdict_t

Functions
static void	pos_amount_set (pos_amount_t *a, uint64_t v)
	Write both amount stores from one value (two independent writes).
void	pos_handle_anomaly (const char *where)
	Report an anomaly: bump a self-checked persisted counter, log it, and keep a local ring buffer for on-site inspection.
uint32_t	pos_anomaly_count (void)
	Persisted total anomaly count (for the optional maintenance view).
static bool32	amount_consistent (const pos_amount_t *a)
static bool32	address_consistent (const pos_addr_t *a)
static bool32	run_payment_decision (const pos_amount_t *amount, const pos_addr_t *to, pos_verdict_t verdict)
	§4 decision gate: return TRUE32 only if amount and recipient are self-consistent AND the verdict is the explicit APPROVED token.

Detailed Description

Decision-integrity primitives (see docs/HARDENING.md §3, §4).

Anti-symmetric booleans, dual-stored business data (amount, recipient) and a fail-closed payment-decision gate. On ESP32 these give bit-flip robustness, NOT a fault-injection boundary — scope any FI claim to the STM32U585 secure host, per the threat model.

The types and the pure comparators are header-only (no ESP-IDF deps) so they build and self-test on the host (see tests/units/test_hardening.cpp). Anomaly persistence (NVS + log) lives in hardening.cpp, firmware-only.

Definition in file hardening.h.

Macro Definition Documentation

FALSE32

#define FALSE32   ((bool32)0xA55AA55Au)

Definition at line 42 of file hardening.h.

Referenced by address_consistent(), amount_consistent(), and run_payment_decision().

IS_TRUE32

#define IS_TRUE32

(

x

)

Value:

((x) == TRUE32)

Definition at line 43 of file hardening.h.

Referenced by app_main(), run_payment_decision(), settle_inflight(), sign_and_broadcast(), and sign_and_broadcast_tron().

POS_VERDICT_APPROVED

#define POS_VERDICT_APPROVED   ((pos_verdict_t)0x33CC33CCu)

Definition at line 47 of file hardening.h.

Referenced by run_payment_decision(), and settle_inflight().

POS_VERDICT_DECLINED

#define POS_VERDICT_DECLINED   ((pos_verdict_t)0xCC33CC33u)

Definition at line 48 of file hardening.h.

Referenced by settle_inflight().

TRUE32

#define TRUE32   ((bool32)0x5AA55AA5u)

Definition at line 41 of file hardening.h.

Referenced by address_consistent(), amount_consistent(), and run_payment_decision().

Typedef Documentation

bool32

typedef uint32_t bool32

Definition at line 38 of file hardening.h.

pos_verdict_t

typedef uint32_t pos_verdict_t

Definition at line 46 of file hardening.h.

Function Documentation

address_consistent()

bool32 address_consistent ( const pos_addr_t * a )

inlinestatic

Definition at line 98 of file hardening.h.

References pos_addr_t::addr, pos_addr_t::addr_echo, ETH_ADDR_LEN, FALSE32, and TRUE32.

Referenced by app_main(), run_payment_decision(), sign_and_broadcast(), and sign_and_broadcast_tron().

amount_consistent()

bool32 amount_consistent ( const pos_amount_t * a )

inlinestatic

Definition at line 93 of file hardening.h.

References pos_amount_t::amount_minor, pos_amount_t::amount_minor_inv, FALSE32, and TRUE32.

Referenced by app_main(), run_payment_decision(), sign_and_broadcast(), and sign_and_broadcast_tron().

pos_amount_set()

void pos_amount_set ( pos_amount_t * a, uint64_t v )

inlinestatic

Write both amount stores from one value (two independent writes).

Definition at line 70 of file hardening.h.

References pos_amount_t::amount_minor, and pos_amount_t::amount_minor_inv.

Referenced by app_main().

pos_anomaly_count()

uint32_t pos_anomaly_count

(

void

)

Persisted total anomaly count (for the optional maintenance view).

Definition at line 125 of file hardening.cpp.

References ensure_loaded(), and s_ctr.

pos_handle_anomaly()

void pos_handle_anomaly

(

const char *

where

)

Report an anomaly: bump a self-checked persisted counter, log it, and keep a local ring buffer for on-site inspection.

Fails the current transaction closed (the caller's gate returns FALSE32); never bricks — a keyless POS holds no secret to protect (§3.3). Firmware only (NVS + esp_log); defined in hardening.cpp.

Definition at line 99 of file hardening.cpp.

References ANOM_RING, anom_entry_t::at_count, ensure_loaded(), nvs_store_ctr(), s_ctr, s_ctr_echo, s_ring, s_ring_head, TAG, and anom_entry_t::where.

Referenced by app_main(), settle_inflight(), sign_and_broadcast(), and sign_and_broadcast_tron().

run_payment_decision()

bool32 run_payment_decision ( const pos_amount_t * amount, const pos_addr_t * to, pos_verdict_t verdict )

inlinestatic

§4 decision gate: return TRUE32 only if amount and recipient are self-consistent AND the verdict is the explicit APPROVED token.

Single exit, default FALSE32 — every unexpected path (including a flip on ok itself) leaves the gate closed. Pure: leaves logging to the caller.

Parameters

[in]	amount	Dual-stored amount to reconcile.
[in]	to	Dual-stored recipient to reconcile.
[in]	verdict	Verdict token from the operator's confirmation.

Returns

TRUE32 to proceed with the payment, FALSE32 otherwise.

Definition at line 118 of file hardening.h.

References address_consistent(), amount_consistent(), FALSE32, IS_TRUE32, ok(), POS_VERDICT_APPROVED, and TRUE32.

Referenced by settle_inflight().