nsatoshi
f4e235edc6
.github/workflows/ci.yml:
- Go version: 1.22 -> 1.23.4 (matches go.mod's 'go 1.23.0' declaration).
- Split into four jobs with explicit names:
* test-backend: go vet + go build + go test
* scan-backend: staticcheck + govulncheck (installed from pinned tags)
* test-frontend: npm ci + eslint + tsc --noEmit + next build
* gitleaks: full-history secret scan on every PR
- Branches triggered: master + main + develop (master is the repo
default; the previous workflow only triggered on main/develop and
would never have run on the repo's actual PRs).
- actions/checkout@v4, actions/setup-go@v5, actions/setup-node@v4.
- Concurrency group cancels stale runs on the same ref.
- Node and Go caches enabled for faster CI.
.gitleaks.toml (new):
- Extends gitleaks defaults.
- Custom rule 'explorer-legacy-db-password-L@ker' keeps the historical
password pattern L@kers?\$?2010 wedged in the detection set even
after rotation, so any re-introduction (via copy-paste from old
branches, stale docs, etc.) fails CI.
- Allowlists docs/SECURITY.md and CHANGELOG.md where the string is
cited in rotation context.
backend/staticcheck.conf (new):
- Enables the full SA* correctness set.
- Temporarily disables ST1000/1003/1005/1020/1021/1022, U1000, S1016,
S1031. These are stylistic/cosmetic checks; the project has a long
tail of pre-existing hits there that would bloat every PR. Each is
commented so the disable can be reverted in a dedicated cleanup.
Legit correctness issues surfaced by staticcheck and fixed in this PR:
- backend/analytics/token_distribution.go: 'best-effort MV refresh'
block no longer dereferences a shadowed 'err'; scope-tight 'if err :='
used for the subsequent QueryRow.
- backend/api/rest/middleware.go: compressionMiddleware() was parsing
Accept-Encoding and doing nothing with it. Now it's a literal
pass-through with a TODO comment pointing at gorilla/handlers.
- backend/api/rest/mission_control.go: shadowed 'err' from
json.Unmarshal was assigned to an ignored outer binding via
fmt.Errorf; replaced with a scoped 'if uerr :=' that lets the RPC
fallback run as intended.
- backend/indexer/traces/tracer.go: best-effort CREATE TABLE no longer
discards the error implicitly.
- backend/indexer/track2/block_indexer.go: 'latestBlock - uint64(i) >= 0'
was a tautology on uint64. Replaced with an explicit
'if uint64(i) > latestBlock { break }' guard so operators running
count=1000 against a shallow chain don't underflow.
- backend/tracing/tracer.go: introduces a local ctxKey type and two
constants so WithValue calls stop tripping SA1029.
Verification:
- go build ./... clean.
- go vet ./... clean.
- go test ./... all existing tests PASS.
- staticcheck ./... clean except for the SA1029 hits in
api/middleware/auth.go and api/track4/operator_scripts_test.go,
which are resolved by PR #4 once it merges to master.
Advances completion criterion 4 (CI in good health).
SolaceScan Explorer - Tiered Architecture
🚀 Quick Start - Complete Deployment
Execute this single command to complete all deployment steps:
cd ~/projects/proxmox/explorer-monorepo
bash EXECUTE_DEPLOYMENT.sh
What This Does
- ✅ Tests database connection
- ✅ Runs migration (if needed)
- ✅ Stops existing server
- ✅ Starts server with database
- ✅ Tests all endpoints
- ✅ Provides status summary
Manual Execution
If the script doesn't work, see START_HERE.md for step-by-step manual commands.
Frontend
- Production (canonical target): the current Next.js standalone frontend in
frontend/src/, built fromfrontend/withnpm run buildand deployed to VMID 5000 as a Node service behind nginx. - Canonical deploy script:
./scripts/deploy-next-frontend-to-vmid5000.sh - Canonical nginx wiring: keep
/api,/api/config/*,/explorer-api/*,/token-aggregation/api/v1/*,/snap/, and/health; proxy/and/_next/to the frontend service usingdeployment/common/nginx-next-frontend-proxy.conf. - Legacy fallback only: the static SPA (
frontend/public/index.html+explorer-spa.js) remains in-repo for compatibility/reference, but it is not a supported primary deployment target. - Architecture command center:
frontend/public/chain138-command-center.html— tabbed Mermaid topology (Chain 138 hub, network, stack, flows, cross-chain, cW Mainnet, off-chain, integrations). Linked from the SPA More → Explore → Visual Command Center. - Legacy static deploy scripts:
./scripts/deploy-frontend-to-vmid5000.shand./scripts/deploy.shnow fail fast with a deprecation message and point to the canonical Next.js deploy path. - Frontend review & tasks: frontend/FRONTEND_REVIEW.md, frontend/FRONTEND_TASKS_AND_REVIEW.md
Documentation
docs/README.md— Documentation overview and indexdocs/EXPLORER_API_ACCESS.md— API access, 502 fix, CSP, frontend deploySTART_HERE.md— Quick start with all commandsCOMPLETE_DEPLOYMENT.md— Detailed deployment stepsDEPLOYMENT_COMPLETE_FINAL.md— Final status reportREADME_DEPLOYMENT.md— Deployment quick referencedeployment/DEPLOYMENT_GUIDE.md— Full LXC/Nginx/Cloudflare deployment guidedocs/INDEX.md— Bridge and operations doc index
Architecture
- Track 1 (Public): RPC Gateway - No authentication required
- Track 2 (Approved): Indexed Explorer - Requires authentication
- Track 3 (Analytics): Analytics Dashboard - Requires Track 3+
- Track 4 (Operator): Operator Tools - Requires Track 4 + IP whitelist
Configuration
- Database User:
explorer - Database Password:
***REDACTED-LEGACY-PW*** - RPC URL:
http://192.168.11.250:8545 - Chain ID:
138 - Port:
8080
Reusable libs (extraction)
Reusable components live under backend/libs/ and frontend/libs/ and may be split into separate repos and linked via git submodules. Clone with submodules:
git clone --recurse-submodules <repo-url>
# or after clone:
git submodule update --init --recursive
See docs/REUSABLE_COMPONENTS_EXTRACTION_PLAN.md for the full plan.
Testing
- All unit/lint:
make test— backendgo test ./...and frontendnpm test(lint + type-check). - Backend:
cd backend && go test ./...— API tests run without a real DB; health returns 200 or 503, DB-dependent endpoints return 503 when DB is nil. - Frontend:
cd frontend && npm run buildornpm test— Next.js build (includes lint) or lint + type-check only. - E2E:
make test-e2eornpm run e2efrom repo root — Playwright tests against https://blockscout.defi-oracle.io by default; useEXPLORER_URL=http://localhost:3000for local.
Status
✅ All implementation complete
✅ All scripts ready
✅ All documentation complete
✅ Frontend: C1–C4, M1–M4, H4, H5, L2, L4 done; H1/H2/H3 (escapeHtml/safe href) in place; optional L1, L3 remain
✅ CI: backend + frontend tests; lint job runs go vet, npm run lint, npm run type-check
✅ Tests: make test, make test-e2e, make build all pass
Ready for deployment!