Where the tape lives — Scylla tables, retention and backups

This addon writes to two stores. Its configuration, its money and its audit trail are in MySQL. Its entire trade history, its order records and its real-user P&L ledger are in ScyllaDB, and the platform's own MySQL backup does not cover ScyllaDB at all.

That sentence is the whole reason this page exists. An operator who backs up MySQL nightly and never touches Scylla has a complete record of what every market was configured to do and no record whatsoever of what it did.

The Scylla tables

The addon reuses the Ecosystem keyspace — whatever SCYLLA_KEYSPACE names in .env (the default is trading; most installs set it to ecosystem). It does not create a keyspace of its own.

Its tables are created on the engine's first successful start, by initializeAiMarketMakerTables(), with CREATE TABLE IF NOT EXISTS. You create nothing by hand.

Three materialized views come with them:

Two more Scylla tables are not the addon's, but the addon is a heavy writer to both — they belong to Ecosystem and are shared with everything else trading that market:

• candles — thirteen intervals from 1m to 1w. Every AI print writes all thirteen, and so does the throttled heartbeat that keeps a gated market's chart continuous. This is where your charts come from.
• orderbook and trades — the depth and the tape your customers see. Both carry the addon's rows alongside genuine ones. See What your users actually see.

What lives in MySQL instead

ai_market_maker_history.action is one of TRADE, PAUSE, RESUME, REBALANCE, TARGET_CHANGE, DEPOSIT, WITHDRAW, START, STOP, CONFIG_CHANGE, EMERGENCY_STOP, AUTO_PAUSE, PHASE_CHANGE, BIAS_CHANGE or MOMENTUM_EVENT. The daily summaries are written into that same table as CONFIG_CHANGE rows carrying details.field = "DAILY_SUMMARY", one per market per UTC day, by the daily reset job.

The model has a beforeDestroy guard that refuses an individual delete — "History records cannot be directly deleted - they are immutable for audit trail integrity" — unless it is running inside a transaction or is an explicit cascade. The retention job sidesteps it with a bulk destroy, and the market-maker delete sidesteps it with its transaction. Nothing else can remove a row.

Retention

Admin → AI Market Maker → Settings → Trading, labelled Trade History Retention, under the Storage group. Accepted 0–3650.

processAiHistoryRetention runs daily and is the only thing in the product that deletes history. It prunes exactly two kinds of row, both from MySQL:

• action = "TRADE" — the individual prints.
• action = "CONFIG_CHANGE" where details.field = "PRICE_DEVIATION_ALERT" — the price-sync job's alerts, at most one per market per hour but forever.

Everything else survives: daily summaries and every lifecycle audit row are never pruned. START, STOP, PAUSE, RESUME, AUTO_PAUSE, EMERGENCY_STOP, DEPOSIT, WITHDRAW, REBALANCE, TARGET_CHANGE, PHASE_CHANGE, BIAS_CHANGE and operator CONFIG_CHANGE rows are low-volume and audit-bearing, so the aggregate stays readable after the prints behind it are gone.

The floor of two days is not arbitrary: the daily summariser reads yesterday's TRADE rows, so a shorter window would delete its own input before it ran.

Each run deletes in batches of 5,000 with a short yield between them — it shares a thread with the one-second engine tick — and is capped at 200 passes, so a million rows per run. A large backlog drains over several days rather than in one lock-heavy sweep. The job is deliberately not gated on aiMarketMakerEnabled: a disabled market maker is exactly when nobody is watching the table.

The volume, and why every read is bounded

The seeded daily trade budgets are 1,200 / 3,500 / 9,000 prints per market per day for CONSERVATIVE / MODERATE / AGGRESSIVE. Each print writes a MySQL TRADE row, a Scylla ai_bot_trades row and thirteen candle writes.

An aggressive market therefore records roughly 9,000 trades a day. Multiply by markets, then by your retention window.

That is why the analytics reads are capped and say so:

• Performance (/admin/ai/market-maker/analytics, Performance) reads at most 5,000 history rows per request and returns a truncated flag. On a 30-day window over an aggressive market an unbounded query would pull a quarter of a million rows to draw a few hundred chart points. When the flag is set, the window you are looking at is the most recent 5,000 rows, not the whole period — the cap drops the oldest.
• Trades pages against MySQL ai_market_maker_history, filtering before paging.
• P&L period figures read Scylla ai_bot_real_trades as a bounded fan of partition lookups (bots × days), not a table scan.

What deleting a market maker destroys

In order:

1. Stops the market through the engine if it is ACTIVE or PAUSED, and waits up to ten seconds for the engine to confirm. The database status is set to STOPPED regardless.
2. Cancels the bots' open ecosystem orders for that symbol, in parallel, through the matching engine. The response reports how many were found, how many were cancelled and which failed.
3. Withdraws both pool balances to the deleting admin's own ecosystem wallet, creating the wallet if it does not exist, and writing an ordinary wallet transaction for each side. If a wallet cannot be resolved the log says "funds will be lost" and the deletion continues.
4. Runs cleanupMarketMakerData against ScyllaDB.
5. Deletes the MySQL rows — bots, pool, history, then the market maker — in a single transaction.

cleanupMarketMakerData deletes, for that market:

Three things are worth knowing precisely about that list:

ai_bot_real_trades is not deleted. The per-fill ledger of every trade against a real user survives the deletion in Scylla — but the ai_bot rows that own those partitions are gone from MySQL, so nothing in the product can read it back. Treat the P&L record as destroyed for practical purposes while the rows themselves persist.

Candles are not deleted. The chart for that market survives, frozen at the last price the engine published. That is deliberate — the engine also refuses to clear candles on restart, to preserve chart history.

Verifying Scylla is reachable

The addon has no health screen of its own. Three checks:

cqlsh -u <user> -p '<password>' -e "DESCRIBE KEYSPACE ecosystem;" | grep ai_

You should see ai_bot_orders, ai_bot_trades, ai_price_history, ai_real_liquidity_orders, ai_bot_real_trades and the three materialized views. If they are absent, the engine has never successfully started.

pm2 logs backend --lines 200 | grep -iE "SCYLLA|AI_MM"

On success the addon logs AI_MM Database tables initialized. On failure, Failed to initialize database tables: ….

3. The dashboard masthead at /admin/ai/market-maker names the engine process and its status.

What the addon does when Scylla is down

The engine calls initializeAiMarketMakerTables() during startup, after it has claimed leadership. That call initialises Ecosystem's Scylla client first, which:

• probes the first contact point over TCP with a short timeout and, if it does not answer, logs "ScyllaDB unreachable at <host:port> — skipping connection retries; ecosystem trading features are unavailable" and fails immediately rather than spending a minute on retries;
• refuses outright when SCYLLA_ENABLED="false".

Either way the engine's initialize() throws and its status becomes ERROR. No market loads, no price advances, no order is placed. The market rows stay at whatever status an operator last set — ACTIVE markets keep their ACTIVE badge throughout — so the list screen looks healthy while nothing at all is running.

The six non-engine cron jobs keep running. They touch only MySQL, so they will report completed every cycle. A green cron page is not evidence that Scylla is up.

Fix Scylla, then recover the engine one of two ways: restart the backend, or press START on any market — the status endpoint routes through ensureRunning(), which is the one path that clears ERROR back to STOPPED and re-initialises.