Data model

Data model overview

The three storage layers, the data-ownership matrix, key relationships, and the critical data rules.

The data model spans three storage layers plus an ephemeral transport, each with one clear responsibility. The same raw data is never duplicated across all of them.

Ownership matrix

Data	Source of truth
Opportunities, strategies, approvals, positions, orders, agent reports	Convex
Long-term lessons, historical decisions, human patterns	SQLite memory
Raw trades, order books, social & on-chain history, backtest datasets	Parquet
Analytical queries	DuckDB
Temporary events	Redis Streams
Secrets	Docker secrets / encrypted files

Identity model

Ticker symbols are not identifiers — unrelated assets share symbols, and an attacker can mint a token imitating a real project. Canonical identity is keyed by chain and contract:

Entity	Canonical key
On-chain asset	chain_id + contract_address
CEX market	exchange_id + exchange_market_id
On-chain pool	chain_id + dex_id + pool_address
Aggregated route	aggregator_id + chain_id + route_hash

Clawlas keeps these entities distinct rather than collapsing them onto a ticker:

asset (the economic token) · chain_asset (a contract on a specific chain) · venue (CEX, DEX, launchpad, aggregator);
market (base/quote on a venue) · pool (an AMM pool) · route (pools chosen for an execution);
listing (availability on a venue) · bridge representation (a wrapped/bridged version).

Avoiding false equivalence

Two assets sharing a ticker are never assumed equivalent. Equivalence requires verified evidence: identical chain and contract, official documentation, a verified bridge mapping, a trusted provider identifier, an exchange deposit-network mapping, or a manually approved mapping.

Conventions

Native IDs internally; external IDs (exchange_order_id, tx_hash) stored separately.
All dates in UTC; financial values use decimals, never floats.
Strategies, scoring formulas, prompts, features and configs are immutable once used.

Key relationships

chains → token_contracts → tokens
exchanges → markets → listing_events → opportunities
opportunities → { opportunity_snapshots, signal_snapshots,
                  score_snapshots, agent_reports, trades }
strategies → strategy_versions → { experiments → experiment_runs, trades }
trades → { positions, orders → order_events, risk_events }
workflow_runs → { agent_reports, model_runs }
memory_items → { relations, evidence, embeddings, feedback, revisions }

How the operational and memory entities connect.

The 12 critical rules

Convex is not the market-data warehouse; SQLite holds no high-frequency history; Redis is never permanent. Agents never modify production strategies; trade-used config stays immutable; every live order is idempotent; every score references its feature & strategy versions; every trade is reproducible; every memory keeps its evidence; raw chain-of-thought is never stored; exchange secrets never touch Convex/SQLite/prompts; analytical datasets are append-only.

The next pages give the full field-by-field schema for each layer — Convex operational tables, the SQLite memory tables, the Parquet/DuckDB analytical datasets, and the dedicated early-token tables (token_launches, launch_events, liquidity_pools, security_assessments, sellability_tests, plus the early snapshot datasets), and the operational tables for venues, routing and cost governance.