proxmox/scripts/verify/build-cmc-top10-ecosystem-coverage.py

#!/usr/bin/env python3
"""Build a repo-side CMC top-10 ecosystem coverage matrix."""

from __future__ import annotations

import json
from datetime import datetime, timezone
from pathlib import Path
from typing import Any


ROOT = Path(__file__).resolve().parents[2]
OUT_JSON = ROOT / "reports/status/cmc-top10-ecosystem-coverage-latest.json"
OUT_MD = ROOT / "docs/04-configuration/CMC_TOP10_ECOSYSTEM_ACCESSIBILITY_MATRIX.md"

SOURCE = {
    "name": "CoinMarketCap coins page",
    "url": "https://coinmarketcap.com/coins/",
    "observedAt": "2026-05-11",
    "note": "Ranks are volatile; rerun or update this snapshot before external outreach.",
}

TOKENS: list[dict[str, Any]] = [
    {
        "rank": 1,
        "symbol": "BTC",
        "name": "Bitcoin",
        "accessibility": "non_evm_wrapped_lane_required",
        "dbisTouchpoint": "cWBTC / BTC reserve-or-wrapper evidence lane",
        "timeframe": "1-2 weeks repo evidence after wallet/venue binding",
        "repoDoableNext": [
            "Bind canonical BTC custody/address evidence fields.",
            "Add BTC venue and wrapped-asset evidence placeholders.",
            "Keep claims as provenance-only until custody and liquidity are independently evidenced.",
        ],
        "requiresExternalHuman": False,
    },
    {
        "rank": 2,
        "symbol": "ETH",
        "name": "Ethereum",
        "accessibility": "native_evm_core_surface",
        "dbisTouchpoint": "WETH/cWETH, Ethereum Mainnet cWUSDC, gas/quote evidence",
        "timeframe": "1-3 days repo hardening",
        "repoDoableNext": [
            "Refresh Ethereum pool and quote-side evidence.",
            "Add CMC/Dex/Gecko sanity checks for ETH-paired surfaces.",
        ],
        "requiresExternalHuman": False,
    },
    {
        "rank": 3,
        "symbol": "USDT",
        "name": "Tether USDt",
        "accessibility": "evm_quote_asset_and_wrapped_transport",
        "dbisTouchpoint": "cUSDT / cWUSDT",
        "timeframe": "1-3 days repo-side; provider acceptance external",
        "repoDoableNext": [
            "Refresh cUSDT/cWUSDT provider packet fields.",
            "Validate official USDT quote addresses per chain.",
        ],
        "requiresExternalHuman": False,
    },
    {
        "rank": 4,
        "symbol": "XRP",
        "name": "XRP",
        "accessibility": "xrpl_lane_required",
        "dbisTouchpoint": "XRPLAdapter / wXRP / MintBurnController",
        "timeframe": "1-2 weeks after wallet/trustline binding",
        "repoDoableNext": [
            "Bind XRPL account and destination tag policy placeholders.",
            "Document XRP reserve, trustline, and issuer requirements.",
        ],
        "requiresExternalHuman": False,
    },
    {
        "rank": 5,
        "symbol": "BNB",
        "name": "BNB",
        "accessibility": "evm_compatible_bsc_lane",
        "dbisTouchpoint": "BSC cW* routing and gas surface",
        "timeframe": "2-5 days repo-side",
        "repoDoableNext": [
            "Refresh BSC cW* pool and official quote evidence.",
            "Check BNB gas budget and CMC report values.",
        ],
        "requiresExternalHuman": False,
    },
    {
        "rank": 6,
        "symbol": "USDC",
        "name": "USD Coin",
        "accessibility": "primary_focus_ready_for_submission",
        "dbisTouchpoint": "cUSDC / cWUSDC",
        "timeframe": "submission-ready now; price/listing acceptance external",
        "repoDoableNext": [
            "Keep Etherscan/CoinGecko/CMC/DexScreener packets current.",
            "Maintain exact CAIP-19 discipline for Mainnet cWUSDC.",
        ],
        "requiresExternalHuman": False,
    },
    {
        "rank": 7,
        "symbol": "SOL",
        "name": "Solana",
        "accessibility": "solana_spl_lane_required",
        "dbisTouchpoint": "SolanaAdapter and config/solana-gru-bridge-lineup.json",
        "timeframe": "3-7 days repo-side if mints are bound",
        "repoDoableNext": [
            "Bind SPL mint placeholders and minimum rent/gas targets.",
            "Separate confirmed Chain 138 adapter evidence from native Solana liquidity claims.",
        ],
        "requiresExternalHuman": False,
    },
    {
        "rank": 8,
        "symbol": "TRX",
        "name": "TRON",
        "accessibility": "tron_wallet_and_energy_lane_required",
        "dbisTouchpoint": "TronAdapter and derived/canonical Tron wallet evidence",
        "timeframe": "3-7 days after address confirmation",
        "repoDoableNext": [
            "Bind canonical Tron address policy placeholder.",
            "Document TRX energy/bandwidth and TRC-20 inventory requirements.",
        ],
        "requiresExternalHuman": False,
    },
    {
        "rank": 9,
        "symbol": "DOGE",
        "name": "Dogecoin",
        "accessibility": "new_non_evm_adapter_or_custody_lane",
        "dbisTouchpoint": "future DOGE wrapper/custody evidence lane",
        "timeframe": "1-3 weeks for serious repo evidence",
        "repoDoableNext": [
            "Create DOGE custody and bridge evidence stub.",
            "Keep DOGE out of provider claims until wallet, reserve, and venue evidence exist.",
        ],
        "requiresExternalHuman": False,
    },
    {
        "rank": 10,
        "symbol": "HYPE",
        "name": "Hyperliquid",
        "accessibility": "new_chain_or_venue_research_required",
        "dbisTouchpoint": "future Hyperliquid venue/asset touchpoint",
        "timeframe": "1-3 weeks for discovery/evidence",
        "repoDoableNext": [
            "Open a research stub for chain/asset identifiers and supported custody paths.",
            "Do not include HYPE in liquidity or settlement claims until identifiers are bound.",
        ],
        "requiresExternalHuman": False,
    },
]


def table(headers: list[str], rows: list[list[Any]]) -> str:
    def cell(value: Any) -> str:
        if isinstance(value, list):
            value = "<br>".join(str(item) for item in value)
        return str(value).replace("|", "\\|").replace("\n", "<br>")

    return "\n".join(
        [
            f"| {' | '.join(cell(header) for header in headers)} |",
            f"| {' | '.join('---' for _ in headers)} |",
            *[f"| {' | '.join(cell(value) for value in row)} |" for row in rows],
        ]
    )


def main() -> int:
    payload = {
        "schema": "cmc-top10-ecosystem-coverage/v1",
        "generatedAt": datetime.now(timezone.utc).isoformat(),
        "source": SOURCE,
        "summary": {
            "tokenCount": len(TOKENS),
            "repoDoableWithoutOutsideHumanCount": sum(1 for token in TOKENS if not token["requiresExternalHuman"]),
            "externalAcceptanceStillRequired": [
                "CMC/CoinGecko/DexScreener/Etherscan listing and price acceptance",
                "Any custody, bank, exchange, or provider-side manual review",
            ],
        },
        "tokens": TOKENS,
    }
    OUT_JSON.parent.mkdir(parents=True, exist_ok=True)
    OUT_JSON.write_text(json.dumps(payload, indent=2) + "\n")

    lines = [
        "# CMC Top 10 Ecosystem Accessibility Matrix",
        "",
        f"- Generated: `{payload['generatedAt']}`",
        f"- Source: [{SOURCE['name']}]({SOURCE['url']})",
        f"- Observed: `{SOURCE['observedAt']}`",
        f"- Boundary: {SOURCE['note']}",
        "",
        table(
            ["Rank", "Token", "Accessibility", "DBIS touchpoint", "Repo-side timeframe", "Repo-doable next work"],
            [
                [
                    token["rank"],
                    f"{token['symbol']} ({token['name']})",
                    token["accessibility"],
                    token["dbisTouchpoint"],
                    token["timeframe"],
                    token["repoDoableNext"],
                ]
                for token in TOKENS
            ],
        ),
        "",
        "## Operating Rule",
        "",
        "This matrix is a repo-side planning artifact. It improves DBIS coverage discipline, but it does not imply that any external tracker, wallet, exchange, custodian, or market-data provider has accepted a token.",
    ]
    OUT_MD.parent.mkdir(parents=True, exist_ok=True)
    OUT_MD.write_text("\n".join(lines) + "\n")
    print(f"Wrote {OUT_JSON.relative_to(ROOT)}")
    print(f"Wrote {OUT_MD.relative_to(ROOT)}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())