Add MEV execution readiness verifier

2026-04-13 12:22:32 -07:00
parent e7cfd26c90
commit cbbb05eabe
5 changed files with 438 additions and 1 deletions
--- a/docs/04-configuration/MEV_CONTROL_COMPLETION_PUNCHLIST.md
+++ b/docs/04-configuration/MEV_CONTROL_COMPLETION_PUNCHLIST.md
@@ -0,0 +1,85 @@
+# MEV Control Completion Punch List
+
+Current live state:
+- Public GUI and same-origin `/api` are live on `https://mev.defi-oracle.io`
+- Backend control plane is contained in CT `2421` on `r630-04`
+- Health, infra, supervisor controls, and signer telemetry are live
+
+Status labels:
+- `live`: deployed and working in production
+- `partial`: implemented but still simplified or incomplete
+- `missing`: not implemented yet
+- `stale-doc`: documentation no longer matches production
+- `needs-validation`: implemented but requires a dedicated operator test
+
+## Control Plane
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Public GUI routing | `live` | CT `2410` serves GUI and proxies `/api` to backend CT `2421` |
+| Backend containment | `live` | No MEV services run directly on a Proxmox host |
+| Supervisor single-service control | `live` | Start/stop per service works |
+| Supervisor bulk control | `live` | Start-all / stop-all exposed through admin API and GUI |
+| Worker auto-start after boot | `live` | `mev-start-all.service` starts workers after admin API is ready |
+| Infra health (Postgres / Redis / NATS) | `live` | Admin API reports all three with real checks |
+| Signer telemetry API | `live` | Reports configured/shadow mode, derived signer address, and execution config |
+| Safety page signer UX | `live` | UI now shows signer wiring instead of placeholder text |
+
+## Pipeline Runtime
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Pool indexer | `partial` | Running, but MVP-level scope and indexing behavior |
+| State ingestion | `partial` | Running; currently simplified reserve fetch strategy |
+| Liquidity graph | `partial` | Running; graph API exists but UX is still raw |
+| Opportunity search | `partial` | Route search is DB-adjacency based, not fully liquidity-aware |
+| Simulation | `partial` | Uses simplified assumptions for gas/amount/slippage |
+| Bundle builder | `partial` | Emits placeholder tx payloads; real signing not complete |
+| Execution gateway | `partial` | Relay submission exists; inclusion tracking is placeholder |
+| Settlement analytics | `partial` | Service runs, but final economics remain limited by gateway data |
+
+## Critical Remaining Execution Work
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Real bundle signing | `partial` | Code path exists and can sign `executeArbitrage(...)` transactions, but live deployment remains blocked by missing signer key, executor contract, flash-loan provider, and V2 router config |
+| Inclusion detection | `partial` | Receipt polling path exists, but real inclusion truth still depends on real signed submission and relay acceptance |
+| Profit realization accuracy | `partial` | Analytics work, but realized PnL still depends on live submission and real inclusion outcomes |
+
+## Market / Search Coverage
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Uniswap V2-style PMM flow | `partial` | Present today |
+| Uniswap V3 ingestion and math | `missing` | Not yet implemented |
+| Curve ingestion and math | `missing` | Not yet implemented |
+| Multicall batching | `missing` | Needed for scale |
+| Block subscription / `newHeads` | `missing` | Current flow is not fully event-driven |
+| Incremental live indexer | `missing` | Still needs proper new-block log scanning |
+
+## Operator / UX Gaps
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Config editor + restart semantics | `partial` | Raw TOML edit exists; safer validation / restart flow still needed |
+| Graph visualization | `partial` | Raw JSON inspector, not a full operator graph surface |
+| Real-time event UX | `partial` | SSE exists for health; broader event streaming remains limited |
+| Per-service throughput / lag metrics | `missing` | Needed for serious operations |
+| Correlation IDs | `missing` | Tracked in repo docs, not yet deployed |
+
+## Documentation
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Deployment split-topology docs | `partial` | Updated for backend CT IP `192.168.11.223`; continue reviewing cross-links |
+| Runtime completion inventory | `live` | This punch list is the current source of truth |
+| MEV implementation gap doc | `live` | `MEV_Bot/mev-platform/docs/REMAINING_GAPS_IMPLEMENTATION.md` remains authoritative for execution-path debt |
+
+## Recommended Next Execution Order
+
+1. Commit and push the current admin API, supervisor, UI, and doc changes.
+2. Implement real bundle signing in `bundle-builder`.
+3. Implement inclusion detection and real profit capture in `execution-gateway` / `settlement-analytics`.
+4. Upgrade ingestion/search for Uniswap V3, Curve, multicall, and block subscriptions.
+5. Add operator-grade observability: queue depth, per-service lag, event counters, and correlation IDs.
+6. Run a full end-to-end validation from discovery through relay submission and confirmed inclusion.
--- a/docs/04-configuration/MEV_EXECUTION_VALUE_SOURCES_AND_READINESS.md
+++ b/docs/04-configuration/MEV_EXECUTION_VALUE_SOURCES_AND_READINESS.md
@@ -0,0 +1,106 @@
+# MEV Execution Value Sources And Readiness
+
+**Last Updated:** 2026-04-13  
+**Purpose:** Identify every execution-critical MEV value, where it is supposed to come from, what this repo currently knows, and what is still missing before live bundle submission can be enabled.
+
+This document is intentionally strict. It separates:
+
+- values that are already authoritative in repo docs or config
+- values that must come from a secret store or runtime env
+- values that must come from an actual on-chain deployment and therefore cannot be guessed
+
+Use the verifier before promoting or committing execution-related config:
+
+```bash
+bash scripts/verify/check-mev-execution-readiness.sh \
+  --config MEV_Bot/mev-platform/config.toml \
+  --env-file config/mev-platform/mev-platform-backend-ct.env.example
+```
+
+To compare local expectations with the live public admin API:
+
+```bash
+MEV_API_KEY='...'
+bash scripts/verify/check-mev-execution-readiness.sh \
+  --config MEV_Bot/mev-platform/config.toml \
+  --env-file config/mev-platform/mev-platform-backend-ct.env.example \
+  --base https://mev.defi-oracle.io \
+  --api-key "$MEV_API_KEY"
+```
+
+## What is already known
+
+| Value | Source | Current state |
+|------|--------|---------------|
+| Public GUI URL | [MEV_CONTROL_DEFI_ORACLE_IO_DEPLOYMENT.md](MEV_CONTROL_DEFI_ORACLE_IO_DEPLOYMENT.md) | `https://mev.defi-oracle.io` |
+| Backend CT IP | [MEV_CONTROL_LAN_BRINGUP_CHECKLIST.md](MEV_CONTROL_LAN_BRINGUP_CHECKLIST.md) | `192.168.11.223` |
+| Admin API port | [config/mev-platform/mev-platform-backend-ct.env.example](../../config/mev-platform/mev-platform-backend-ct.env.example) | `9090` |
+| Supervisor port | [config/mev-platform/mev-platform-backend-ct.env.example](../../config/mev-platform/mev-platform-backend-ct.env.example) | `9091` |
+| Relay URL | [MEV_Bot/mev-platform/config.toml](../../MEV_Bot/mev-platform/config.toml) | `https://relay.flashbots.net` |
+| Mainnet factory addresses | [MEV_Bot/mev-platform/config.toml](../../MEV_Bot/mev-platform/config.toml) | Uniswap V2 and Sushi factory addresses are present |
+| Current safety truth | Public `/api/safety/signer` | Live endpoint reports the active blocker set |
+
+## Execution-critical values
+
+| Value | Where it should come from | Needed for | Current repo state |
+|------|----------------------------|------------|--------------------|
+| `MEV_EXECUTOR_PRIVATE_KEY` | Runtime secret env only; never commit | Signing real bundle txs | Missing from repo examples except commented placeholder |
+| `MEV_SUBMIT_DISABLED` | Runtime env | Guardrail for shadow vs live submission | Present and intentionally set to `1` in examples |
+| `chains.<id>.execution.executor_contract` | Real deployed contract address | `executeArbitrage(...)` destination | Still zero address in checked-in config |
+| `chains.<id>.execution.flash_loan_provider` | Real deployed venue/provider address | Arbitrage executor input | Still zero address in checked-in config |
+| `chains.<id>.execution.relay_url` | Config / operator choice | Relay submission target | Present in config |
+| `chains.<id>.factories[].router` for `uniswap_v2` / `sushiswap` | Authoritative DEX router addresses for the chain | Router-based swap-step encoding | Missing in checked-in config |
+
+## What the current live API confirms
+
+As of the current public deployment, the live signer readiness endpoint reports:
+
+- `MEV_EXECUTOR_PRIVATE_KEY is not configured`
+- `submit_disabled is enabled`
+- `chain 1: router missing for dex uniswap_v2`
+- `chain 1: router missing for dex sushiswap`
+- `chain 1: executor_contract is zero address`
+- `chain 1: flash_loan_provider is zero address`
+
+That means the code path is present, but the deployment inputs for real execution are not.
+
+## Values that must not be guessed
+
+These must come from a controlled operator source, secret manager, or an actual deployment result:
+
+- `MEV_EXECUTOR_PRIVATE_KEY`
+- `chains.<id>.execution.executor_contract`
+- `chains.<id>.execution.flash_loan_provider`
+
+The repo currently does **not** contain authoritative values for them. If they are to be committed into non-secret config, they must first exist as real deployment outputs.
+
+## Values that still need operator selection
+
+These may be public addresses, but they still need to be selected intentionally for the exact chain and venue plan:
+
+- `chains.<id>.factories[].router` for each V2-style DEX used by execution
+- any non-default relay endpoint if Flashbots is not the intended submission path
+
+They should not be filled by assumption if the deployment target is expected to be canonical and auditable.
+
+## Recommended source order
+
+1. Runtime secret store or backend CT env for `MEV_EXECUTOR_PRIVATE_KEY`.
+2. Actual deployment output from the MEV contracts deployment process for `executor_contract`.
+3. Actual deployment output or operator-selected venue address for `flash_loan_provider`.
+4. Canonical chain venue inventory for router addresses, then validate through the readiness script and live `/api/safety/signer`.
+
+## Commit policy
+
+Safe to commit:
+
+- non-secret config schema changes
+- docs that list required values and readiness checks
+- verification scripts
+- non-secret deployed contract addresses **only after** they are real and validated
+
+Not safe to commit:
+
+- `MEV_EXECUTOR_PRIVATE_KEY`
+- ad hoc guessed addresses
+- config values copied from memory without an auditable source
--- a/docs/04-configuration/README.md
+++ b/docs/04-configuration/README.md
@@ -36,6 +36,8 @@ This directory contains setup and configuration guides.
 - **[INFO_DEFI_ORACLE_IO_DEPLOYMENT.md](INFO_DEFI_ORACLE_IO_DEPLOYMENT.md)** - **`info.defi-oracle.io`** Chain 138 hub SPA (incl. `/governance`, `/ecosystem`, `/documentation`, `/solacenet`, `/disclosures`, agents): VMID **2410**, nginx **`/token-aggregation/`** proxy, `sync-info-defi-oracle-to-vmid2400.sh`, NPMplus, Cloudflare DNS (`set-info-defi-oracle-dns-to-vmid2400-tunnel.sh`), `purge-info-defi-oracle-cache.sh`, `pnpm run verify:info-defi-oracle-public`, CI `info-defi-oracle-138.yml` + `verify-info-defi-oracle-public.yml`, optional `pnpm run audit:info-defi-oracle-site`
 - **[MEV_CONTROL_DEFI_ORACLE_IO_DEPLOYMENT.md](MEV_CONTROL_DEFI_ORACLE_IO_DEPLOYMENT.md)** — **`mev.defi-oracle.io`** MEV Control GUI (`MEV_Bot/mev-platform/gui`): `sync-mev-control-gui-defi-oracle.sh`, nginx `/api` → mev-admin-api, NPMplus + `set-mev-defi-oracle-dns.sh`
 - **[MEV_CONTROL_LAN_BRINGUP_CHECKLIST.md](MEV_CONTROL_LAN_BRINGUP_CHECKLIST.md)** — concrete LAN operator checklist for the full MEV Control stack with **public GUI on CT `2410`** and a **dedicated backend CT on `r630-04`**: CT provisioning, env file, Docker infra, systemd units, migrations, supervisor, admin API, pipeline bring-up order, and public cutover verification
+- **[MEV_CONTROL_COMPLETION_PUNCHLIST.md](MEV_CONTROL_COMPLETION_PUNCHLIST.md)** — live inventory of what is complete, partial, missing, stale-doc, or still needs validation for the MEV Control stack
+- **[MEV_EXECUTION_VALUE_SOURCES_AND_READINESS.md](MEV_EXECUTION_VALUE_SOURCES_AND_READINESS.md)** — source-of-truth for which execution-critical values are already known, which are still missing, where they should come from, and how to verify readiness before promotion
 - **[SOLACENET_PUBLIC_HUB.md](SOLACENET_PUBLIC_HUB.md)** — Public **SolaceNet** page (`/solacenet`) on the info hub plus `dbis_core/docs/solacenet/` markdown map
 - **[PROXMOX_LOAD_BALANCING_RUNBOOK.md](PROXMOX_LOAD_BALANCING_RUNBOOK.md)** - Balance Proxmox load: migrate containers from r630-01 to r630-02/ml110; candidates, script, cluster vs backup/restore
 - **[PROXMOX_ADD_THIRD_FOURTH_R630_DECISION.md](PROXMOX_ADD_THIRD_FOURTH_R630_DECISION.md)** - Add 3rd/4th R630 before migration? r630-03/04 status, HA/Ceph (3–4 nodes), order of operations
--- a/docs/MASTER_INDEX.md
+++ b/docs/MASTER_INDEX.md
@@ -16,7 +16,7 @@
 | **Agent / IDE instructions** | [AGENTS.md](../AGENTS.md) (repo root) |
 | **Local green-path tests** | Root `pnpm test` → [`scripts/verify/run-repo-green-test-path.sh`](../scripts/verify/run-repo-green-test-path.sh) |
 | **Git submodule hygiene + explorer remotes** | [00-meta/SUBMODULE_HYGIENE.md](00-meta/SUBMODULE_HYGIENE.md) — detached HEAD, push order, Gitea/GitHub, `submodules-clean.sh` |
-| **MEV intel + public GUI (`mev.defi-oracle.io`)** | Framing: [../MEV_Bot/docs/framing/README.md](../MEV_Bot/docs/framing/README.md); deploy: [04-configuration/MEV_CONTROL_DEFI_ORACLE_IO_DEPLOYMENT.md](04-configuration/MEV_CONTROL_DEFI_ORACLE_IO_DEPLOYMENT.md); LAN bring-up: [04-configuration/MEV_CONTROL_LAN_BRINGUP_CHECKLIST.md](04-configuration/MEV_CONTROL_LAN_BRINGUP_CHECKLIST.md) (dedicated backend CT on `r630-04`); specs: [../MEV_Bot/specs/README.md](../MEV_Bot/specs/README.md) |
+| **MEV intel + public GUI (`mev.defi-oracle.io`)** | Framing: [../MEV_Bot/docs/framing/README.md](../MEV_Bot/docs/framing/README.md); deploy: [04-configuration/MEV_CONTROL_DEFI_ORACLE_IO_DEPLOYMENT.md](04-configuration/MEV_CONTROL_DEFI_ORACLE_IO_DEPLOYMENT.md); LAN bring-up: [04-configuration/MEV_CONTROL_LAN_BRINGUP_CHECKLIST.md](04-configuration/MEV_CONTROL_LAN_BRINGUP_CHECKLIST.md) (dedicated backend CT on `r630-04`); completion list: [04-configuration/MEV_CONTROL_COMPLETION_PUNCHLIST.md](04-configuration/MEV_CONTROL_COMPLETION_PUNCHLIST.md); execution values/readiness: [04-configuration/MEV_EXECUTION_VALUE_SOURCES_AND_READINESS.md](04-configuration/MEV_EXECUTION_VALUE_SOURCES_AND_READINESS.md); specs: [../MEV_Bot/specs/README.md](../MEV_Bot/specs/README.md) |
 | **What to do next** | [00-meta/NEXT_STEPS_INDEX.md](00-meta/NEXT_STEPS_INDEX.md) — ordered actions, by audience, execution plan |
 | **Live verification evidence (dated)** | [00-meta/LIVE_VERIFICATION_LOG_2026-03-30.md](00-meta/LIVE_VERIFICATION_LOG_2026-03-30.md) |
 | **Your personal checklist** | [00-meta/NEXT_STEPS_FOR_YOU.md](00-meta/NEXT_STEPS_FOR_YOU.md) |
@@ -87,6 +87,8 @@
 | **FQDN → expected content (web / API / RPC)** | [04-configuration/FQDN_EXPECTED_CONTENT.md](04-configuration/FQDN_EXPECTED_CONTENT.md) | — |
 | **Sankofa / Phoenix public vs portal vs admin endpoints (fix list)** | [03-deployment/SANKOFA_PHOENIX_PUBLIC_PORTAL_ADMIN_ENDPOINT_CORRECTION_TASKS.md](03-deployment/SANKOFA_PHOENIX_PUBLIC_PORTAL_ADMIN_ENDPOINT_CORRECTION_TASKS.md) | — |
 | **Sankofa marketplace surfaces** (native vs partner offerings; IRU catalog vs portal SSO vs Studio landing) | [03-deployment/SANKOFA_MARKETPLACE_SURFACES.md](03-deployment/SANKOFA_MARKETPLACE_SURFACES.md) | — |
+| **Entity institutions** (Aseret, TAJ, Solace Bank Group — web/portal completion tracker) | [03-deployment/ENTITY_INSTITUTIONS_WEB_PORTAL_COMPLETION.md](03-deployment/ENTITY_INSTITUTIONS_WEB_PORTAL_COMPLETION.md) | Code: `~/projects/Aseret_Bank`, `~/projects/TAJ_PSFO/web`, `~/projects/Solace_Bank_Group/web`; static: [`solace-bank-group-portal/`](../solace-bank-group-portal/) |
+| **Sankofa / Phoenix consolidated runtime** (single non-chain web hub + single API hub — resource model) | [02-architecture/SANKOFA_PHOENIX_CONSOLIDATED_FRONTEND_AND_API.md](02-architecture/SANKOFA_PHOENIX_CONSOLIDATED_FRONTEND_AND_API.md) | Examples + systemd: `config/nginx/sankofa-*.example.conf`, `config/systemd/sankofa-*-hub-nginx.service.example`, [`config/compose/sankofa-consolidated-runtime.example.yml`](../config/compose/sankofa-consolidated-runtime.example.yml); verify [`scripts/verify/check-sankofa-consolidated-nginx-examples.sh`](../scripts/verify/check-sankofa-consolidated-nginx-examples.sh); plan [`scripts/deployment/plan-sankofa-consolidated-hub-cutover.sh`](../scripts/deployment/plan-sankofa-consolidated-hub-cutover.sh) |
 | **IP conflict resolutions** | [reports/status/IP_CONFLICTS_RESOLUTION_COMPLETE.md](../reports/status/IP_CONFLICTS_RESOLUTION_COMPLETE.md), `scripts/resolve-ip-conflicts.sh` | — |
 | **Wormhole AI docs (LLM / MCP / RAG)** | [04-configuration/WORMHOLE_AI_RESOURCES_LLM_PLAYBOOK.md](04-configuration/WORMHOLE_AI_RESOURCES_LLM_PLAYBOOK.md), [04-configuration/WORMHOLE_AI_RESOURCES_RAG.md](04-configuration/WORMHOLE_AI_RESOURCES_RAG.md), `scripts/doc/sync-wormhole-ai-resources.sh`, `scripts/verify/verify-wormhole-ai-docs-setup.sh`, [`mcp-wormhole-docs/`](../mcp-wormhole-docs/) | Wormhole protocol reference only — not Chain 138 canonical addresses (use [11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md](11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md), CCIP runbooks for 138) |