Data Layer & Evidence#

Partial implementation. MemoryStore deployed. PostgresStore + PersistentEventBus = Phase 2 - current build uses in-process event bus with ephemeral retention. PostgreSQL required before mainnet rollout.

Audit Trails#

Tamper-evident WORM ledger with SHA-256 hash chain. Every settlement event is immutable evidence.

Credit Management#

Pre-approved trading capacity per workspace. Auto-replenishes on settlement.

Workspace Isolation#

Multi-entity structure with scoped API keys, members, and corridors.

Evidence Chain#

Evidence Hash Chain

Actor

Engine

Contract

Network

Settlement event occurs → serialized with previous entry's SHA-256 hash
New hash computed → entry appended to chain (never modified, never deleted)
Hot storage serves queries; EventBus persists asynchronously to cold storage

Storage Tiers#

Tier	Technology	Latency	Data
Hot	In-memory (DashMap)	under 0μs	Active solvers, circuit breaker, rate limits
Warm	In-memory + async	under 0ms	Active orders, session state
Cold	PostgreSQL	under 0ms p95	Evidence, compliance decisions, quotes
Event	Broadcast	Non-blocking	Order, compliance, evidence events

Critical rule - database writes NEVER occur on the POST /api/v1/quotes critical path. All persistence via EventBus subscribers or background jobs.

Credit System#

Concept	Description
Credit Line	Max trading capacity per workspace (USD equivalent)
Utilization	Outstanding exposure - sum of open unsettled orders
Available	Credit Line − Utilization
Auto-Replenish	Utilization decreases on settlement, freeing capacity

Taker submits RFQ → engine checks amount ≤ available
If approved: utilization increases, RFQ proceeds to auction
On settlement: utilization decreases. On refund: capacity restored

Workspace Model#

Workspace Structure

Actor

Engine

Contract

Network

Structure#

Organization - legal entity, owns workspaces
Workspace - isolated API keys, credit, members
Corridors - active trading routes per workspace

Member Roles#

Admin Manage members, corridors, full access
Trader Submit RFQs, accept quotes, monitor
Viewer Read-only dashboards and history

API Key Isolation#

Keys scoped per workspace (tfk_live_...)
Cannot access other workspaces in same org
Rotate independently without cross-impact

Repository Pattern#

text

1StorageTrait
2  ├─ ComplianceStorageTrait   (counterparties, attestations, decisions)
3  └─ EvidenceStorageTrait     (append-only entries, hash chain)

3 linestext

Implementation	Status	Use Case
MemoryStore	Deployed	DashMap, sub-μs reads. Primary active data store
PostgresStore	Planned	Cold storage for evidence and compliance
PersistentEventBus	Planned	Redis Streams, at-least-once delivery

Database Schema#

Core#

orders solvers circuit_breaker_states metrics_timeseries

Compliance#

counterparties companies compliance_decisions policies

Audit#

evidence_entries quotes - hash-chained, append-only, exportable

EventBus Streams#

Stream	Events
`tetrafi:events:orders`	Lifecycle created, filled, settled, expired
`tetrafi:events:compliance`	Decisions check_passed, check_failed, blocked
`tetrafi:events:evidence`	Audit entries appended to WORM ledger
`tetrafi:events:system`	Health circuit breaker, deployments

Pagination#

Strategy	Pattern	Best For
Offset/Limit	`?offset=0&limit=50`	Bounded collections (orders, policies)
Cursor-based	`?cursor=<id>&limit=50`	Append-only (evidence, events)