unrip/archive/implementation/20260518T162356Z-db-backed-asset-registry-and-multi-pair-strategy-configuration-implementation.md

Implementation Turn: DB-backed asset registry and multi-pair strategy configuration

Status: open Opened: 2026-05-12

Goal

Move supported assets, enabled pairs, pair filters, and per-pair edge/trading limits out of environment variables and into durable Postgres state, with a re-importable NEAR Intents asset catalog and fail-closed live trading behavior.

Selected backlog items

• none selected; this turn was opened directly from the approved operator request on 2026-05-12.

Design rules

• DB state is the source of truth for assets, enabled pairs, edge, limits, and pair modes.
• Env remains only for infra/secrets/service wiring.
• Importing an asset never enables trading by itself.
• Pair config updates are versioned. Historical decisions must remain explainable.
• Services fail closed if DB config is missing, stale, invalid, or internally inconsistent.
• Current nBTC/EURe behavior must survive the migration before any additional pair trades.

External source

The supported asset catalog comes from the NEAR Intents 1Click tokens endpoint:

GET https://1click.chaindefuser.com/v0/tokens

The docs describe this endpoint as the source for supported token assetId values. A live check on 2026-05-12 returned an array of 163 token records and included:

• nep141:nbtc.bridge.near
• nep141:btc.omft.near
• nep141:gnosis-0x420ca0f9b9b604ce0fd9c18ef134c705e5fa3430.omft.near

Backend changes

1. Add config schema

Add tables through the tracked schema path:

supported_asset_import_runs
trading_assets
trading_pairs
pair_strategy_configs
pair_price_routes
pair_config_audit_log

Minimum fields:

• supported_asset_import_runs: run id, source URL, fetched_at, status, token_count, added_count, updated_count, retired_count, raw response hash, error.
• trading_assets: asset id, venue, symbol, label, decimals, blockchain, contract address, latest price, price updated at, supported, retired_at, enabled_for_inventory, raw payload, updated_at.
• trading_pairs: pair id, venue, asset_in, asset_out, mode, enabled, status, created_at, updated_at.
• pair_strategy_configs: config id, pair id, version, active, edge_bps, max_notional, min_notional, slippage_bps, min_deadline_ms, price_max_age_ms, inventory_max_age_ms, created_at, created_by, reason.
• pair_price_routes: route id, pair id, source, base asset id, quote asset id, route config JSON, max age, enabled.
• pair_config_audit_log: audit id, entity type, entity id, action, old value, new value, changed_at, changed_by, reason.

2. Build supported-token importer

• Add a pure normalizer for 1Click token records.
• Add an idempotent importer that fetches /v0/tokens, validates shape, upserts trading_assets, and writes supported_asset_import_runs.
• Mark previously supported assets as supported=false and retired_at=<run time> when missing from the latest import.
• Keep raw payloads and source metadata.
• Add an operator-safe command/API to rerun the importer.
• Add tests for success, duplicate import, token update, asset retirement, malformed response, and network failure.

3. Seed current production truth

• Seed current nBTC, legacy OMFT BTC, and EURe assets if absent.
• Seed both directed nBTC/EURe pair rows needed by maker quote response.
• Seed the active strategy config at 49 bps.
• Seed current max notional/deadline/freshness settings from existing production defaults.
• Keep legacy OMFT BTC inventory-visible but not active for maker trading unless explicitly enabled.

4. Runtime DB config loader

• Add a loader module that returns:
  • asset registry map
  • enabled pair set
  • pair strategy config by pair
  • tracked asset ids
  • supported/retired flags
• Cache briefly but refresh without restart.
• Expose config load state in service /state.
• Fail closed when DB is unreachable or config is invalid.
• Store config version metadata in emitted decisions and commands.

5. Replace env-backed pair filtering

• Remove runtime dependency on NEAR_INTENTS_PAIR_FILTER.
• near-intents-ingest loads enabled observed pairs from DB.
• Ingest should preserve raw quote data but only normalize/publish pairs approved for observation/trading.
• Pair updates must apply without redeploy.
• Keep a safe disabled state when no pairs are configured.

6. Replace env-backed strategy edge

• Remove runtime dependency on STRATEGY_GROSS_THRESHOLD_PCT.
• Strategy selects the active pair_strategy_configs row for the incoming quote pair.
• Decisions include pair_id, pair_config_id, pair_config_version, edge_bps, and active limits.
• Unsupported/disabled/unpriced pairs emit explicit rejected decisions, not silent drops where practical.
• Existing nBTC/EURe math remains the first compatibility target.

7. Generalize asset and pair math

• Replace tradingBtc/tradingEure assumptions in strategy with pair assets from DB.
• Use DB decimals for amount conversion.
• Preserve current BTC/EURe reference-price support first.
• Block pairs whose price route is missing or stale.
• Keep pair direction explicit instead of inferring BTC/EURe-only names.

8. Price route model

• Current market reference is BTC/EUR-specific.
• Add DB price routes before enabling non-BTC/EURe trading.
• For this turn, support the current nBTC/EURe route and make other pairs blocked with price_route_missing.
• Persist enough price-route metadata so later sources can be added without another env-based pair model.

9. Inventory and funding visibility

• Inventory sync uses DB trading_assets for tracked assets.
• Dashboard shows balances for known/tracked assets including retired assets.
• Funding/deposit observations label assets from DB metadata.
• Assets may be supported=false but still inventory-visible.

10. Dashboard controls

• Add an asset catalog section:
  • import status
  • import button/control
  • counts for supported/retired/known assets
  • searchable asset table
• Add a pair config section:
  • pair rows with mode/status
  • active strategy config and edge bps
  • price route status
  • controls to enable observe-only and update edge
• Live trading enablement must remain explicit and separated from import.
• Show pair config version in quote lifecycle rows.

11. Alerts and health

• Runtime health uses DB active pair set instead of a single activePair.
• Alerts must include pair id where applicable.
• Missing DB config or invalid active pair config becomes a critical blocked state for trading services.
• NEAR upstream incident relevance should be scoped to DB tracked assets/chains.

12. Deployment config cleanup

• Remove pair/asset/edge env vars from deploy/k8s/base/unrip.yaml after DB seed and runtime loading are in place.
• Keep infra/secrets env vars.
• Ensure a repo push deploys the whole change without manual database editing.

Concrete implementation order

Phase 1. Schema and seed

• Add DB schema and helper functions.
• Add seed routine for current nBTC/EURe production config.
• Add tests proving seed is idempotent.

Phase 2. Asset importer

• Implement 1Click token fetch/normalize/import.
• Add CLI/control path for re-import.
• Add tests for import and retirement semantics.

Phase 3. Runtime config loader

• Implement DB loader and fail-closed validation.
• Convert asset registry consumers that only need labels/decimals.
• Add tests for missing/invalid config.

Phase 4. Ingest migration

• Replace env/file pair filter with DB pair set.
• Preserve current pair behavior.
• Add tests for pair update and no-config disabled behavior.

Phase 5. Strategy migration

• Load pair strategy config from DB.
• Remove global env edge use from runtime.
• Persist pair config version in decisions/commands.
• Add current-pair compatibility and edge-version tests.

Phase 6. Dashboard and controls

• Add asset import and pair config surfaces.
• Add controls for re-import and observe-only/pair edge update.
• Add tests proving dashboard data comes from DB.

Phase 7. Deployment cleanup and validation

• Remove asset/pair/edge env vars from deployment config.
• Run targeted tests and full test suite.
• Build dashboard bundle.
• Deploy through repo workflow.
• Validate live importer, current pair config, quote ingest, decisions, and dashboard bootstrap.

Test plan

• Asset import normalizer tests.
• Import idempotency tests.
• Retired asset tests.
• Schema/seed idempotency tests.
• Runtime config loader tests.
• Fail-closed missing DB config tests.
• Ingest DB pair filter tests.
• Strategy per-pair edge tests.
• Strategy config versioning tests.
• Dashboard asset/pair config tests.
• Deployment config static test proving pair/edge env vars are absent.

Validation checklist against the proof

• DB contains current assets and current nBTC/EURe pair.
• Supported-token importer can rerun and record a new import run.
• Current active pair and 49 bps edge load from DB.
• NEAR Intents ingest no longer depends on NEAR_INTENTS_PAIR_FILTER.
• Strategy no longer depends on STRATEGY_GROSS_THRESHOLD_PCT.
• Dashboard shows asset import status and pair strategy config.
• New imported assets are not trade-enabled by default.
• Current pair still emits decisions and quote responses when armed.
• All services deploy from repo push.

Known fakes allowed at start of this turn

• Only current BTC/EURe pricing route is real.
• Additional imported pairs may be observe-only or blocked until price routes exist.
• Venue-native terminal fills remain unavailable unless existing paths already provide them.
• Fee-complete realized PnL remains unavailable.