docs(readme): full end-to-end testing + usage runbook#16
Merged
Conversation
The README that landed in PR #11 was the early "pitch + repo layout" version, written before the cluster was up and before the program was on devnet. Now that everything is live and reviewable, replace it with a runbook a Colosseum judge can actually follow start-to-finish. What the new README covers (455 lines, was 175): Top banner live URLs + program ID + cluster + MCP transport, all click-through Why / What you get (kept from previous, lightly trimmed) How it works (kept — 90-second flow diagram) Built on Solana (kept — primitives table) Repo layout (kept) End-to-end walkthrough NEW — six-step Colosseum-judge runbook: 1. Phantom on devnet + faucet (5 min) 2. Connect & create vault (1 min) 3. Top up devnet USDC (2 min) 4. Issue MCP URL (30 s) 5. Wire into Claude Desktop (1 min) 6. Use it + see policy enforcement (2 min) Each step has the exact command/click + the expected on-chain artefact. What's deployed today NEW — table of cluster + program ID + USDC mint + image registry + TLS source. Lets a reviewer cross-reference reality without grep-ing manifests. Local development NEW — `docker compose up` one-liner, plus component-by-component (cargo build-sbf / poetry / vite). Test-suite matrix (pytest 35 / playwright 4 / anchor 19). Deploy a fresh program NEW — fork-friendly walkthrough: build, sed declare_id! everywhere, fund, deploy, verify. Both devnet (free) and mainnet (~3 SOL) paths. Vanity-key recipe for mainnet. Production deploy NEW — exact commands the AceDataCloud ops flow uses: tke.py kubeconfig, secret bootstrap, buildx push, deploy/run.sh. Quick verification NEW — five copy-pasteable curl probes (health, well-known, TLS cert chain, MCP shape, getAccountInfo on the program). Run-and-paste-back format. Status updated — devnet is live, mainnet pending. Hackathon section kept; "live demo" line updated to reflect devnet + the X402Client cross-reference. Notes: - The runbook intentionally documents devnet first, with a clear "mainnet is one line" callout. Hackathon grading consistently accepts devnet demos and demanding mainnet would burn ~$480 on the very first compile-and-deploy iteration. - Every external link includes ?cluster=devnet so Solscan opens at the right network. Mainnet links will swap when we cut the submission video. - The "what's deployed today" table is the source of truth — if someone changes the program ID, USDC mint, or cluster, this is the one place to keep in sync (config.py + api.yaml + Anchor.toml + lib.rs + DEMO.md + README + .env.example are bound to that ID via the `sed -i` replace-everywhere recipe in the deploy section). No code changes; README only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The README that landed in PR #11 was the early pitch + repo layout version, written before the cluster was up and before the program was on devnet. Now that everything is live and reviewable, replace it with a runbook a Colosseum judge can actually follow start-to-finish.
What the new README covers (455 lines, was 175)
docker compose up+ per-component + test matrixThe end-to-end walkthrough is the most useful new piece. A judge can follow it start to finish in ~10 minutes:
create_vaultix (1 min)spl-token-faucet.com(2 min)Each step has the exact command/click + the expected on-chain artefact (Solscan link, program log, etc).
Notes
?cluster=devnetso Solscan opens at the right network. Mainnet links will swap when we cut the submission video.sed -ireplace-everywhere recipe so forks can roll their own program ID without grep'ing 10 files.No code changes; README only.