Home /Modules/http-3.0/http3_basket.h

http3_basket.h

http-3.0/http3_basket.h · 84 line(s) · c

/* ==========================================================================
 * http3_basket.h -- SLeeLa HTTP 3.0 basket of goods & services.
 *
 * A fixed, carefully-selected basket of 14 goods and services, atomic-bound to
 * the United States capitalism system. Each item carries an indivisible atomic
 * number and an ISO value expressed "for a Gram", denominated in United States
 * dollars (ISO 4217 USD / 840) as integer MICRO-USD per gram (1,000,000
 * micro-USD = 1 USD).
 *
 * The full basket travels in every HTTP 3.0 packet (see http3_envelope.h): it
 * is serialized into a canonical, endianness-independent block that is carried
 * on the wire and covered by the packet's keyed MAC, so it cannot be altered in
 * transit without detection. The basket is authoritative here (the same data is
 * mirrored in the human-readable BASKET.docx at the repo root and in the Python
 * reference http3_flow.py).
 *
 * Pure data: no I/O, no crypto, no allocation.
 * ========================================================================== */
#ifndef HTTP3_BASKET_H
#define HTTP3_BASKET_H

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

#ifdef __cplusplus
extern "C" {
#endif

/* Number of items in the fixed basket. */
#define HTTP3_BASKET_ITEMS 14u

/* ISO 4217 currency the per-gram values are denominated in. */
#define HTTP3_BASKET_ISO_CURRENCY "USD"
#define HTTP3_BASKET_ISO_NUMERIC  840u

/* Max name length stored per item (display/diagnostics only; the name does NOT
 * travel on the wire -- only the atomic number and per-gram value do). */
#define HTTP3_BASKET_NAME_MAX 32u

/* One basket item: an indivisible atomic number and its ISO value per gram in
 * integer micro-USD (uUSD/g). */
typedef struct {
    uint32_t atomic_number;                 /* indivisible 1-based id          */
    uint64_t value_ugram;                   /* micro-USD per gram (ISO USD)     */
    char     name[HTTP3_BASKET_NAME_MAX];   /* display name (not on the wire)   */
} http3_basket_item_t;

/*
 * Canonical serialized size of the per-packet basket block (big-endian):
 *   [iso_numeric:2][item_count:2] then, per item, [atomic_number:4][value_ugram:8]
 * = 4 + 14*12 = 172 bytes.
 */
#define HTTP3_BASKET_BLOCK_SIZE (4u + HTTP3_BASKET_ITEMS * 12u)

/* Access the fixed basket table (HTTP3_BASKET_ITEMS entries). */
const http3_basket_item_t *http3_basket_table(void);

/*
 * Serialize the fixed basket into the canonical block. `out` must have room for
 * HTTP3_BASKET_BLOCK_SIZE bytes. Returns the number of bytes written, or 0 on
 * error. Deterministic and endianness-independent (matches the Python
 * reference byte-for-byte).
 */
size_t http3_basket_serialize(uint8_t *out, size_t out_cap);

/*
 * Parse a canonical basket block into `items` (capacity `cap` entries; names
 * are left empty since they are not carried on the wire). On success writes the
 * ISO numeric code to *iso_numeric and returns the item count; returns 0 on a
 * malformed/short block.
 */
size_t http3_basket_parse(const uint8_t *in, size_t in_len,
                          http3_basket_item_t *items, size_t cap,
                          uint16_t *iso_numeric);

/* Sum of all per-gram values in the fixed basket (uUSD/g), for diagnostics. */
uint64_t http3_basket_total_ugram(void);

#ifdef __cplusplus
}
#endif

#endif /* HTTP3_BASKET_H */