@usherlabs/cex-broker 0.2.45 → 0.2.46

package/README.md

@@ -735,7 +735,7 @@ Every successful `CreateOrder` response, successful `GetOrderDetails` response,
 - Execution values: requested quantity/notional, executed base quantity, executed quote quantity/cost, average execution price, filled amount, remaining amount, fee amount, fee currency, fee rate
 - Timing: exchange timestamp when present and broker observed timestamp
 
-Use metrics for aggregations and alerts. For the durable execution audit trail, the broker archives every order lifecycle event to `broker_execution.order_events` (and pre-order top-of-book to `broker_execution.market_metadata_snapshots`) through the **archive forwarder** — the same HTTP `/archive` → ClickHouse path used for `market_data.*`. Set `CEX_BROKER_ARCHIVE_ENABLED=true`, an explicit HTTP(S) `CEX_BROKER_ARCHIVE_FORWARDER_URL`, and a writable durable JSONL path in `CEX_BROKER_ARCHIVE_DEAD_LETTER_PATH`; startup fails if either required sink configuration is missing or invalid. In production, that path must be on persistent writable storage or a mounted volume rather than the container's ephemeral filesystem. Queue shedding, rows that remain undeliverable during shutdown, and batches the forwarder rejected on every attempt are written to that loss journal with their original `{table,row}` payload before being discarded. Replay them with `bun run archive:loss:replay --journal <path>`, which re-posts through the forwarder and reports a per-entry verdict; it is idempotent across reruns, never modifies the journal, and only archives it once every entry is terminal and the operator asserts `--broker-stopped`. When the journal lives on an encrypted enclave mount (SGX deployments), its host-side bytes are sealed ciphertext the replay tool cannot read; set `CEX_BROKER_ARCHIVE_DEAD_LETTER_EXPORT_PATH` to a path on a plain (untrusted) mount and the broker exports a boot-time plaintext snapshot of the journal there, with an adjacent `.sha256` receipt whose digest is also logged from inside the enclave for integrity comparison. The export is one-shot — an existing target file is left untouched, so remove it to request a fresh snapshot — and a failed export fails startup. Setting `CEX_BROKER_ARCHIVE_OTEL_LOGS_ENABLED=true` additionally mirrors execution rows to OTel logs for observability, but OTel is never the archive sink of record. Analysts join Maker action rows to `broker_execution.order_events` using `maker_action_id`, `idempotency_id`, `client_order_id`, or the exchange `order_id`, then compare Maker propAMM execution price against `average_execution_price` and fees. Failed CreateOrder rows keep bounded exchange error detail in `error_message`; their telemetry-shaped `payload_json`, metrics, and ordinary telemetry logs remain redacted. The broker does not emit raw exchange payloads, API keys, secrets, or credentials in telemetry fields.
+Use metrics for aggregations and alerts. For the durable execution audit trail, the broker archives every order lifecycle event to `broker_execution.order_events` (and pre-order top-of-book to `broker_execution.market_metadata_snapshots`) through the **archive forwarder** — the same HTTP `/archive` → ClickHouse path used for `market_data.*`. Set `CEX_BROKER_ARCHIVE_ENABLED=true`, an explicit HTTP(S) `CEX_BROKER_ARCHIVE_FORWARDER_URL`, and a writable durable JSONL path in `CEX_BROKER_ARCHIVE_DEAD_LETTER_PATH`; startup fails if either required sink configuration is missing or invalid. In production, that path must be on persistent writable storage or a mounted volume rather than the container's ephemeral filesystem. Queue shedding, rows that remain undeliverable during shutdown, and batches the forwarder rejected on every attempt are written to that loss journal with their original `{table,row}` payload before being discarded. Replay them with `bun run archive:loss:replay --journal <path>`, which re-posts through the forwarder and reports a per-entry verdict; it is idempotent across reruns, never modifies the journal, and only archives it once every entry is terminal and the operator asserts `--broker-stopped`. When the journal lives on an encrypted enclave mount (SGX deployments), its host-side bytes are sealed ciphertext the replay tool cannot read; set `CEX_BROKER_ARCHIVE_DEAD_LETTER_EXPORT_PATH` to a path on a plain (untrusted) mount and the broker exports a boot-time plaintext snapshot of the journal there, with an adjacent `.sha256` receipt whose digest is also logged from inside the enclave for integrity comparison. The export and receipt are published as a durable pair. A completed pair is left untouched; an export with a missing or malformed receipt fails startup instead of being silently reused. Remove both files to request a fresh snapshot. Setting `CEX_BROKER_ARCHIVE_OTEL_LOGS_ENABLED=true` additionally mirrors execution rows to OTel logs for observability, but OTel is never the archive sink of record. Analysts join Maker action rows to `broker_execution.order_events` using `maker_action_id`, `idempotency_id`, `client_order_id`, or the exchange `order_id`, then compare Maker propAMM execution price against `average_execution_price` and fees. Failed CreateOrder rows keep bounded exchange error detail in `error_message`; their telemetry-shaped `payload_json`, metrics, and ordinary telemetry logs remain redacted. The broker does not emit raw exchange payloads, API keys, secrets, or credentials in telemetry fields.
 
 ### User-stream health archive contract