proxmox/docs/04-configuration/EXPLORER_GAPS_AND_RECOMMENDATIONS.md

Explorer: Gaps, Recommendations, and Additional Items

Purpose: Single reference for explorer (https://explorer.d-bis.org): loading, bridge/lanes, contract verification (Verify & Publish + Forge batch), user/API keys, and all other recommendations and gaps.

Related: EXPLORER_FUNCTIONALITY_REVIEW.md | EXPLORER_METAMASK_TECHNICAL_RESPONSE.md | EXPLORER_TROUBLESHOOTING.md | BLOCKSCOUT_VERIFICATION_GUIDE.md | explorer-monorepo/docs/EXPLORER_LOADING_TROUBLESHOOTING.md

---

1. Loading on all pages

1.1 Intended behavior

Page / view	Data loaded	Source
Home	Stats, Gas & Network, Latest Blocks, Latest Transactions	loadStats(), loadGasAndNetworkStats(), loadLatestBlocks(), loadLatestTransactions() — all use /api/v2/* (Blockscout).
Blocks	Paginated block list	loadAllBlocks() → /api/v2/blocks?page=&page_size=25.
Transactions	Paginated transaction list	loadAllTransactions() → /api/v2/transactions?page=&page_size=25.
Bridge	Static bridge/lanes content	refreshBridgeData() — no API; builds HTML from hardcoded routes. If "Loading bridge data…" persists, a JS error likely prevents this from running.
Tokens	Token list	loadTokensList() → /api/v2/tokens?page=1&page_size=100.
WETH	Static UI + wallet balance (if connected)	No Blockscout list API; wrap/unwrap uses RPC.
Watchlist	LocalStorage-backed list	_renderWatchlist() — no API.
Analytics	Placeholder (Track 3)	"Coming soon" message; gated by hasAccess(3).
Operator	Placeholder (Track 4)	"Coming soon" message; gated by hasAccess(4).

1.2 If widgets stay "Loading…" or "—"

• Ensure all of these return 200 when opened from the explorer origin: /api/v2/stats, /api/v2/blocks?page=1&page_size=10, /api/v2/transactions?page=1&page_size=10, /api/v2/tokens?page=1&page_size=100. See EXPLORER_LOADING_TROUBLESHOOTING for exact URLs and do-now checks.
• Redeploy frontend after SPA changes; use cache-bust explorer-spa.js?v=3 (or higher) and hard-refresh.

---

2. Bridges and lanes / routes to all networks

2.1 Current state

• Bridge Monitoring view shows:
  • Chain 138 WETH9/WETH10 bridge addresses (correct: 0x971cD9…, 0xe0E932…).
  • WETH9 routes: BSC (56), Polygon (137), Avalanche (43114), Base (8453), Arbitrum (42161), Optimism (10), Ethereum Mainnet (1).
  • WETH10 routes: Same 7 destinations.
  • Ethereum Mainnet bridges: WETH9 0x2A0840…, WETH10 0xb7721d… (correct).
• Source of truth for lanes: 07-ccip/CHAIN138_COMPLETE_ROUTING_TABLE.md, 07-ccip/MAPPER_GAPS_DEPLOYMENTS_AND_IMPROVEMENTS.md.

2.2 Gaps and recommendations

Item	Status	Recommendation
Destination-chain "Bridge Address" in SPA	Addresses for BSC/Polygon/etc. in the SPA are hardcoded; some may be placeholders (e.g. CCIP Router 138 reused).	Source remote bridge (or router) addresses from config/API (e.g. token-aggregation or config/smart-contracts-master.json) when available; or add a "Reference" link to CHAIN138_COMPLETE_ROUTING_TABLE.
Cronos (25), Gnosis (100), Celo (42220), Wemix (1111)	Routing table lists Cronos as live; 100/42220/1111 as "Config ready". SPA shows only 7 destinations.	Add Cronos (25) to the Bridge Monitoring table when destination bridge address is confirmed; add a short "More chains (Gnosis, Celo, Wemix) when configured" note and link to routing table.
All lanes load	Bridge view is static HTML; no runtime fetch of lanes.	Optional: call GET /api/v1/bridge/routes (or equivalent) if the explorer backend exposes it, and render lanes from response so new chains appear without SPA redeploy.

---

3. Contract verification

3.1 What exists

• Blockscout on VMID 5000 supports contract verification (Etherscan-compatible + v2 API).
• Forge verification: Use the forge-verification-proxy so Forge’s payload is translated to Blockscout v2. See forge-verification-proxy/README.md and 08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md.
• Scripts: scripts/verify/run-contract-verification-with-proxy.sh, scripts/verify-contracts-blockscout.sh (and smom-dbis-138 equivalents).

3.2 Verify & Publish (Blockscout UI)

To verify a contract from the explorer when automated verification is unavailable or returns 502:

1. Open https://explorer.d-bis.org/addresses/<CONTRACT_ADDRESS>
2. Go to the Contract tab → Verify & Publish
3. Choose method: Via Standard JSON Input (recommended), Via Sourcify, or Via Multi-file
4. Upload source (or paste) and provide constructor arguments if needed; submit.

If you see no “Verify & Publish” (or no contract-verification controls) on the address page: the hostname may be serving the custom explorer SPA only, which does not embed every Blockscout screen. Use one of these instead:

• Forge (recommended): source scripts/lib/load-project-env.sh then ./scripts/verify/run-contract-verification-with-proxy.sh (submits to Blockscout via the local proxy; no explorer form required).
• Native Blockscout (LAN): open http://192.168.11.140:4000 (VM Blockscout) and use the instance’s contract verification entry (in many Blockscout versions: Other → Verify contract, or the Code / contract area on the address page — labels vary by release).
• Cronos: manual UI is always at https://explorer.cronos.org/verifyContract (separate stack).

See 08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md for Forge/proxy batch verification and troubleshooting (502, HTML response).

3.3 Recommendations

Item	Recommendation
Batch verification (Forge + proxy)	From a host that can reach Blockscout (LAN): source smom-dbis-138/.env 2>/dev/null; ./scripts/verify/run-contract-verification-with-proxy.sh. Uses canonical addresses from .env; see BLOCKSCOUT_VERIFICATION_GUIDE.
API key for Blockscout	Self-hosted Blockscout at explorer.d-bis.org does not require an API key for read API. If rate limits or private endpoints are added later, document API key issuance (see §4).

---

4. User profile and dev API key issuance

4.1 Gap

• No user accounts or developer API keys are implemented in the explorer or Blockscout today. Blockscout (self-hosted) typically does not ship a "developer portal" for API key signup; read API is public or protected at the reverse-proxy/nginx level.

4.2 Recommendations

Option	Effort	Notes
A. Blockscout API keys (if enabled)	Low	If your Blockscout version supports API keys for the read API, enable them and document how operators issue keys (e.g. via Blockscout admin or env).
B. Nginx/API gateway rate limit by key	Medium	Put an API gateway or nginx in front of /api that requires a query param or header (e.g. ?apikey=) and issue keys out-of-band (e.g. from a simple script or internal form).
C. Separate developer portal	High	Build a small "developer portal" (e.g. in dbis_core or the-order) that allows signup/login and issues API keys for explorer (and other) APIs; store keys and enforce in gateway.

Suggested short-term: Document that the explorer API is currently public (no key). If you need keys later, start with (A) or (B) and add a one-page "API access" doc with whom to contact for a key and which base URL to use.

---

5. Other recommendations and suggestions

5.1 From existing docs

• Snap /send HTTPS: Ensure "Send on Chain 138" link is absolute HTTPS (GATSBY_SNAP_SITE_URL in Snap build). Done in repo; rebuild and redeploy Snap site to apply.
• CoinGecko / API keys: Token-aggregation and oracle may use CoinGecko (and optional CMC); see COINGECKO_API_KEY_SETUP.md and API_KEYS_REQUIRED.md. Not explorer-specific but affects Snap/market data.
• RPC TRACE: Already enabled on public RPC (VMID 2201) for Blockscout indexing; see explorer-monorepo/docs/RPC_FUNCTIONALITY_AND_BLOCKSCOUT_TRACE.md.

5.2 Explorer-specific

#	Recommendation	Priority
1	Ensure all SPA views that call /api handle 4xx/5xx and show a clear "Retry" or error message.	High
2	Add a "Verify contract" link or short instructions on the address/contract page (link to Blockscout verification or BLOCKSCOUT_VERIFICATION_GUIDE).	Medium
3	Consider serving bridge routes from a small config or API so new chains don’t require an SPA redeploy.	Low
4	Analytics (Track 3) / Operator (Track 4): when implemented, document access control and any API keys.	Future
5	Optional: add Blockscout "API" or "Docs" link in footer (e.g. to Blockscout API docs or internal API overview).	Low

---

6. Quick checklist (operator)

• All explorer pages load; no persistent "Loading…" for stats, blocks, transactions, tokens, bridge (see §1).
• Bridge Monitoring shows Chain 138 + Mainnet bridges and 7 (or more) destination lanes; add Cronos/config-ready chains if desired (§2).
• Contract verification: proxy + Forge runbook documented; run batch verification for main contracts (§3).
• User/API key: decision documented; if keys are introduced, add "API access" doc and issuance process (§4).
• Snap site: rebuilt with GATSBY_SNAP_SITE_URL; /snap/send link is HTTPS (§5).