wownerogue/docs/FINANCIAL_EVENT_EXPORT.md

Financial event export

Migrations 041_financial_event_outbox.sql and 042_immutable_financial_event_snapshots.sql create financial_event_outbox, a durable outbox for confirmed customer payments and final refund states. Database triggers append an immutable source snapshot inside the payment or refund transaction, so a slow or unreachable accounting receiver can never hold a money transaction open. src/services/financialEventExporter.js performs delivery asynchronously and never reconstructs an event from later-mutated payment rows.

Event sources

Event kind	Trigger source	Fires when
payment.confirmed	payments	status becomes confirmed and received_amount > 0
payment.refund	payment_refunds	status reaches recorded (bookkeeping reversal) or completed (wallet refund)

Refunds in requested, processing, or needs_review are never accounting events. Confirmed payments with received_amount = 0 lack economic evidence and are never turned into revenue. Uniqueness on (event_kind, source_type, source_id) and on event_id means one source produces at most one event; the foreign key to payments is ON DELETE RESTRICT.

Source snapshot

payload_snapshot uses schema financial-event-source/v1. A CHECK constraint restricts it to exactly this key set: schema, event_id, event_kind, source_type, source_id, aggregate_id, occurred_at, atomic_amount, payment_type, product_id, provider_id, receipt_count, refund_status. The constraint also pins event_id, event_kind, source_type, source_id, and aggregate_id to the matching columns.

The snapshot carries no player ID, wallet address, invoice destination, transaction hash, provider invoice ID, session token, IP address, email address, or authentication material.

Delivery document

On the first delivery attempt the worker builds delivery_payload from the snapshot plus the deployment's chain profile (src/chain/chainProfile.js) and writes it once. Schema is financial-event/v1:

• id: the immutable event ID, also used as the idempotency key.
• occurred_at: ISO-8601 timestamp derived from the snapshot.
• producer / product: wowngeon.
• activity: customer-payment, customer-refund (completed wallet refund), or customer-payment-reversal (recorded bookkeeping reversal).
• account_refs and each leg's account_ref: FINANCIAL_EVENT_ACCOUNT_REF.
• provenance: one entry of kind wowngeon-payment or wowngeon-refund referencing payment-<id> or payment-refund-<id>.
• legs: one leg with the chain profile's asset symbol, decimal quantity, direction in for payments and out for refunds, and a network identifier.
• attributes: valuation_required, atomic_amount, atomic_decimals, source_type, source_id, aggregate_id, plus refund_status for refunds or payment_type / product_id / provider_id / receipt_count for payments.

The leg's usd_value is "0" with empty price_source and price_confidence, and memo plus attributes.valuation_required state that the receiving system must apply USD valuation before confirming the entry. The exporter deliberately performs no pricing.

The network identifier is wownero:mainnet when CRYPTO_TYPE resolves to the WOW profile, and monero:<MONERO_NETWORK> otherwise. An unrecognised CRYPTO_TYPE resolves to the XMR-shaped default profile (12 decimals, 120000 ms mean block time).

Once written, the delivery document is immutable and every retry reuses it byte for byte.

Delivery contract

Delivery is at least once. Each attempt is a POST with a bearer authorization header, content-type: application/json, idempotency-key set to the immutable event ID, manual redirect handling, and a 10-second timeout. The receiving system must durably deduplicate that key and durably record the event before answering 2xx. A timeout or lost acknowledgement otherwise produces a repeat request. The application marks a row delivered only after a 2xx response.

Row lifecycle

pending → in_flight → delivered, with dead_letter and ignored as the other terminal states.

• A run first moves rows whose attempts already reached FINANCIAL_EVENT_MAX_ATTEMPTS to dead_letter.
• Claiming selects the oldest due row with FOR UPDATE SKIP LOCKED, increments attempts, and takes a five-minute lease. An expired lease makes the row claimable again, so a crashed worker never strands an event.
• A failed attempt returns the row to pending with backoff of 30 seconds doubled per attempt and capped at one hour, recording the sanitised error in last_error.
• An attempt that exhausts FINANCIAL_EVENT_MAX_ATTEMPTS moves the row to dead_letter for operator review.
• Each run processes at most FINANCIAL_EVENT_BATCH_SIZE rows.

Immutability

A BEFORE UPDATE trigger rejects any change to event_kind, aggregate_id, source_type, source_id, event_id, or payload_snapshot. delivery_payload has exactly one legal transition, NULL to its final value, and only while the row is in_flight. A row cannot reach delivered without a delivery document.

Configuration

Variable	Default	Notes
FINANCIAL_EVENT_SINK_URL	unset	Enables export together with the token
FINANCIAL_EVENT_SINK_TOKEN	unset	Bearer secret, at least 32 characters
FINANCIAL_EVENT_ACCOUNT_REF	wowngeon:receipts	Non-PII account identifier
FINANCIAL_EVENT_POLL_MS	60000	Clamped to 5000-3600000
FINANCIAL_EVENT_BATCH_SIZE	20	Clamped to 1-100
FINANCIAL_EVENT_MAX_ATTEMPTS	8	Clamped to 1-100

FINANCIAL_EVENT_SINK_URL=https://ledger.operator.example/v1/events
FINANCIAL_EVENT_SINK_TOKEN=<strong protected bearer token>
FINANCIAL_EVENT_ACCOUNT_REF=wowngeon:wow-receipts
FINANCIAL_EVENT_POLL_MS=60000
FINANCIAL_EVENT_BATCH_SIZE=20
FINANCIAL_EVENT_MAX_ATTEMPTS=8

The full environment template is src/.env.example; the mainnet and stagenet profiles are src/.env.mainnet.example and src/.env.stagenet.example.

Startup validation (src/config/environmentValidator.js) and the exporter constructor both enforce:

• URL and token are set together or not at all.
• The URL parses, uses http: or https:, and embeds no credentials. https: is required when NODE_ENV=production.
• The token is at least 32 characters, contains at least 8 distinct characters, and matches no placeholder pattern such as change_me, example, password, or secret.
• The account reference matches ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$.
• Sink configuration is rejected on any non-mainnet MONERO_NETWORK.

Set the URL and token only in the protected mainnet runtime environment. Never place the token in Git, Ansible inventory, an invocation, a receipt, a log, or a public health check.

Non-mainnet networks

When MONERO_NETWORK is not mainnet, export is disallowed and each run moves every pending, in_flight, or dead_letter row to ignored with reason non_mainnet_network. This keeps no-value test activity out of real books. Migration 042 separately marks legacy rows whose historical amount is unusable as ignored with reason malformed_legacy_snapshot, so they terminate instead of retrying forever.

Health reporting

The public /health response includes a financialEvents object: the delivery contract string, enabled, exportAllowed, running, the backlog, deadLetters, and ignoredRows gauges, and the cumulative delivered, deferred, deadLettered, and ignored counters. It exposes no sink URL, token, account reference, event ID, error text, payload, source identity, or timestamp.

Accounting export is informational and does not make gameplay readiness fail, so production monitoring must alert on backlog age, dead letters, and the exporter's process logs and metrics in order to detect stale delivery.

The poll loop runs even with no sink configured, so the backlog gauge stays truthful and non-mainnet deployments keep suppressing newly appended rows.

Operations

Before enabling mainnet export, prove in a disposable environment that the sink:

1. authenticates the protected bearer token over TLS;
2. deduplicates repeated requests by Idempotency-Key;
3. durably records the event before returning 2xx;
4. rejects malformed events without echoing secrets; and
5. supports alerting and reconciliation for a deliberately generated dead letter.

Keep the outbox in database backups. Do not delete or rewrite a dead-letter row to make monitoring green: reconcile it against the receiving ledger, preserve the evidence, and use a separately reviewed repair procedure. Running without a sink is permitted, but confirmed mainnet events then accumulate as pending rows and must be reconciled by another route.