Backend Contract

This page is the compact engineering review contract for data sources, backend formats, and runtime execution.

Detailed references:

• Clash Of Clones Product Spec
• Backend Overview
• Economy Module
• Clone Service Module
• Prop Trading Module
• Lifecycle Module
• Client API Contract
• Data Sources
• SQLite + R2 Market Memory Plan
• Backend Ownership And Runtime Contract
• Data Source API And UX Spec

Implementation Status

Implemented in backend:

• SQLite migrations and repository layer.
• Hyperliquid, Polymarket, and DefiLlama ingestion/storage.
• Hyperliquid asset taxonomy and category-based selection.
• Clone pipeline graph persistence.
• Workflow graph layout persistence for the visual Trading Clone Block.
• Pipeline API and save-time validation.
• Latest-data endpoint for workflow data stream review.
• Clone capacity entitlement storage and read endpoint.
• Pipeline save enforcement for max active asset capacity.
• Backend model-strength enforcement for clone model updates and strategy publication.
• Decision-worker entitlement checks for model strength and active asset capacity.
• Effective context resolver that reads structured SQLite memories.
• Ingestion health and dashboard API for source/channel status, volume, coverage, and lag review.
• Unlinked frontend ingestion dashboard at /admin/ingestion.
• Decision run/action tables and repository.
• Decision worker loop with cadence checks and a pluggable engine interface.
• Safe local no-op hold engine.
• Model-backed workflow dry-run and prop-account decision engine path.
• Dry-run execution safety gates.
• Legacy clone-scoped dry-run order/ledger audit path for workflow debugging.
• Decision artifact index with in-memory, file, R2, and S3-compatible storage adapters.
• Prop accounts, prop-account decision runner, decision-action intake, safety gates, simulated fills, positions, snapshots, mark-to-market, and admin controls.
• Prop-account decision worker cadence.
• Audition fee deposit verification, entitlement grant, and audition submit/evaluate/retry.
• Promotion Queue and Arena slot admission storage/read/sync, approved-profile gates, and admin removal/retirement controls.
• Public clone profile and moderation queue.
• Worker heartbeat storage and /api/v1/internal/health/workers.
• Client-facing lifecycle API boundaries in doc/openapi/client-api.openapi.yaml.

Not implemented yet:

• Race, ticket, settlement, retirement history, and Hall of Fame tables.
• Race, ticket, and settlement HTTP route handlers behind future OpenAPI client routes.
• Economy reconciliation worker for stale pending purchases.
• Host-level alert wiring, backup checks, and deployment tuning.
• Live order adapter and personal-wallet execution boundary.
• Full frontend controls polish against the new graph builder.

Migration Stance

This backend has not been deployed to production yet. SQLite migrations can stay simple and direct during this phase: prefer clear schema/data cleanup over production-grade backfill ceremony. Once production data exists, migrations should become compatibility-safe and operationally reversible where needed.

Data Sources And Storage

Market data is global, not per user. Clone strategies filter shared market memory instead of duplicating source data per clone.

Source Coverage

Source	Stored context	Role
Hyperliquid	OHLCV, RSI, Bollinger Bands, MA/EMA, MACD, funding rates	Trade universe and asset-level market context
Polymarket	Live/upcoming market discovery, immediate market, later market	Related event/context layer
DefiLlama	TVL/base capital, flow changes, DEX volume/fees/revenue/OI	Macro/market-regime layer

Hyperliquid channel origin:

source-backed:
- OHLCV: 1-minute candle WebSocket subscriptions
- funding rates: metaAndAssetCtxs + predictedFundings REST polls, perps only

derived:
- RSI, Bollinger Bands, Moving Averages, and MACD: local derivation from 1-minute candles
- 1-hour OHLCV: local rollup from 1-minute source candles

Hyperliquid derived indicators should follow common technical-analysis defaults: Wilder RSI 14, Bollinger Bands with 20-period SMA and 2 standard deviations, SMA/EMA 20, and MACD 12/26/9. The hyperliquid_assets registry is the source of truth for channel capability. Compiled read plans must skip unsupported Hyperliquid channel/asset pairs, such as spot funding rates, before context retrieval.

Retention And Granularity

Suggested Hyperliquid price hot retention:

last 24 hours: 1-minute source candles
last 7 days: 1-hour granularity
older than 7 days: delete or archive to R2

Feature families should stay compact:

• Store derived profile rows in SQLite.
• Avoid retaining full raw orderbook/update payloads in SQLite.
• Archive raw payloads to R2 only when useful for audit or replay.

Working assumption:

7-day hot SQLite data is comfortably manageable on the initial backend box.

SQLite Vs R2

SQLite stores compact queryable rows:

• Structured observations.
• Feature/profile rows.
• Clone and strategy graph configuration.
• Decision/action indexes.
• Orders, fills, positions, and ledger rows.
• R2 object keys.

R2 stores large immutable payloads:

• Full prompt/context/response payloads.
• Large reason/debug traces.
• Raw source payloads when useful for audit/replay.
• Backups or cold archives.

Backend Data Formats

The canonical backend configuration shape is:

data_stream -> asset_selection -> trading_prompt

Product language maps to:

Data Stream Block -> Asset Block -> Trading Prompt Block

The workflow canvas can also show a visual Trading Clone Block:

Data Stream Block -> Asset Block -> Trading Prompt Block -> Trading Clone Block

The Trading Clone Block is a UI/runtime terminal for clone-level model, trading on/off, and history. It is not a persisted strategy node in the v1 graph. Its visual position and prompt-to-clone line are persisted as layout metadata, separate from executable graph nodes and edges.

Each Trading Prompt Block defines one strategy. At execution time, a strategy branch expands into per-asset prompt executions. Each decision run row is for one asset.

A. Asset Selection Format

Answers:

Which assets can this clone consider trading?

Stored user intent:

• highLevelCategories
• subcategories
• explicitlyEnabledSymbols
• explicitlyDisabledSymbols

Effective output:

• Enabled trade universe for the clone or strategy branch.
• Selection source for each symbol.
• Display metadata for UI review.
• Trading/context support flags.

B. Data Stream Format

Answers:

What structured market memory is available to the strategy branch?

Stored concepts:

• profile: fast, balanced, or deep.
• sourcePolicy: per-source behavior for Hyperliquid, Polymarket, and DefiLlama.
• profileDefinitions: editable retrieval definitions for power users.
• assetOverrides: implementation field for per-asset configurations.
• Polymarket target fields for specific market/event blocks. Asset-linked Polymarket rows remain a legacy ingestion-matching path, not the primary workflow UI.
• DefiLlama target fields for global, chain, protocol, or stablecoin macro scopes.

Current user-facing controls expose retrieval depth, prompt inclusion, lookback, and granularity on each context block. Hyperliquid blocks are dropped by source/channel and configured with one associated asset inside the block. DefiLlama blocks are dropped empty and configured with channel plus macro scope. Max datapoints and prompt budget are derived or internally managed from those settings.

The compiled read plan separates:

• symbol: the asset receiving the trading decision.
• contextSymbol: the asset or subject read from market memory.

For same-asset context these are identical. For cross-asset context they differ, such as a BTC decision branch that reads ETH Hyperliquid or DefiLlama rows because ETH conditions may influence BTC.

Override precedence:

per-asset configuration
> asset/group profile assignment
> data stream default profile
> built-in profile definition

Retrieval is deterministic. There is no AI prompt for data retrieval.

C. Pipeline Graph Format

Answers:

How are data streams, assets, and trading prompts connected?

Allowed v1 paths:

data_stream -> asset_selection
asset_selection -> trading_prompt

The visual Trading Clone Block is stored outside the executable graph:

type ClonePipelineLayout = {
  strategyClone?: {
    position?: { x: number; y: number };
    connectedPromptNodeIds?: string[];
  };
};

connectedPromptNodeIds controls the visible Trading Prompt -> Trading Clone line in the workflow canvas. It is layout metadata only; the compiler still validates only data_stream -> asset_selection -> trading_prompt.

The graph is the source of truth. Simple UI controls should update graph nodes instead of creating independent configuration sources.

D. Trading Execution Format

Answers:

How should this strategy decide and act?

Stored concepts:

• enabled
• customBehaviorPrompt
• decisionCadenceSec
• candidatePolicy
• coverageMode
• assetOverrides: implementation field for per-asset prompt configurations

maxAssetsPerRun may still appear in legacy compatibility payloads, but it is no longer a user-facing or enforced branch cap. A trading prompt expands across every enabled connected asset.

Legacy migration fields such as traderType, analysisTimeframe, and marketMomentumSensitivity can still exist in compatibility payloads, but they are not current primary workflow controls.

Prompt coverage modes:

global
global_with_asset_overrides
asset_specific_only

E. Effective Context Packet

The effective context packet is downstream of A-D.

It combines:

• Clone ownership and config.
• Compiled graph.
• Effective asset universe.
• Per-asset read plans.
• Cross-asset context reads, where symbol is the traded asset and contextSymbol is the memory subject.
• Structured SQLite market memory.
• Prop-account positions, orders, fills, ledger summary, equity, drawdown, and account checks.
• Prompt sections and estimated prompt tokens.
• R2 keys for large context/prompt/response payloads.

Workflow layout metadata is stored and returned by the pipeline API, but it is ignored by the effective context resolver because it has no impact on trading behavior.

Product Economy Boundary

The paper-trading runtime should produce auditable synthetic trading results. The Clash Arena economy consumes those results for lifecycle and settlement decisions.

The prop trading engine should use Prop Account as its runtime account boundary:

one clone -> many prop accounts over time
one prop account -> one bounded synthetic trading run

Examples:

clone 42 -> sandbox prop account
clone 42 -> audition prop account
clone 42 -> race #123 prop account
clone 42 -> race #124 prop account

cloneId remains the product actor and strategy owner. propAccountId should be the primary key for synthetic balances, positions, fills, PnL, drawdown, account checks, and ledger events. This avoids coupling repeated auditions, fresh race accounts, and historical audits to a single clone-scoped account row.

Runtime-owned outputs:

• Prop account PnL for a bounded sandbox, audition, or race.
• Orders, fills, positions, balances, fees, and ledger events.
• Account checks, liquidation state, mark-to-market snapshots, and finalized result snapshots.

Arena-owned inputs and outputs:

• Audition Fee payment status.
• Public clone identity and moderation status.
• Promotion Queue and Arena slot state.
• Race accumulation, launch, live, settling, settled, and archive state.
• Ticket purchases for the currently accumulating race.
• Pool split rows for protocol rake, creator pool, and distribution pool.
• Weighted parimutuel payout rows for ticket holders.
• Creator royalty rows.
• Retirement strike state and Hall of Fame preservation.

This boundary keeps trading correctness separate from economy correctness. Trading determines performance; Arena settlement determines who gets paid and what lifecycle transition happens next.

See Prop Trading Module for the current module contract between lifecycle services, the AI trader engine, and the prop engine.

Runtime Pipeline

The current product runtime path is:

1. Global data ingestion
2. Clone strategy graph compilation
3. Per-strategy asset expansion
4. Deterministic context retrieval from SQLite
5. Trading prompt assembly
6. Prop-account decision worker creates one due run per asset
7. Decision engine proposes an action for that asset
8. Prop Trading safety gates validate or reject the action
9. Valid executable actions paper-fill against the latest execution price
10. Prop Trading updates orders, fills, positions, balances, and ledger rows atomically
11. Decision artifact store archives large prompt/context/response blobs when configured

There is no separate v1 insight creator or generated insight storage layer.

Current local worker commands:

cd backend
npm run decisions:run-once -- --clone-id=42 --force
npm run decisions:worker
npm run prop:decisions:worker
npm run prop:mark-to-market:worker
npm run lifecycle:auditions:worker
npm run lifecycle:arena-entry:worker

The current executable product path supports no-op/model decision engines feeding prop accounts through deterministic safety gates and paper fills. The older clone-scoped dry-run order path still exists for workflow debugging and compatibility; new lifecycle work should target prop accounts. Live exchange execution and personal-wallet trading remain separate future boundaries.

Candidate Policy

The platform can support every Hyperliquid asset, but a strategy should not blindly send every asset into a model call by default.

Separate:

• Supported assets: everything the backend knows about.
• Trade universe: assets the clone or strategy allows.
• Decision run: one model call for one selected asset.
• Decision action: the proposed or validated action from that run.

Default strategy candidates should include:

• Assets with open positions.
• Assets in the enabled trade universe.
• Assets passing deterministic prefilters.

Recommended branch candidate cap before per-asset execution:

10 assets by default
25 assets advanced maximum

For users watching hundreds of assets, the system should scan structured data deterministically first, then run the strategy on the strongest candidates.