XRPL Lab

XRPL training workbook — learn by doing, prove by artifact.

Each module teaches one XRPL skill and produces a verifiable artifact: a transaction ID, a signed receipt, or a diagnostic report. No accounts, no fluff, no cloud — just competence and receipts.

Install

pipx install xrpl-lab

Or with pip:

pip install xrpl-lab

Requires Python 3.11+.

No Python? The npm wrapper downloads the standalone binary (requires Node 18+):

npx @mcptoolshop/xrpl-lab

Quickstart

xrpl-lab start

The guided launcher walks you through wallet setup, funding, and your first module.

Offline mode

xrpl-lab start --dry-run

No network required. Simulated transactions for learning the workflow.

Modules

32 modules across ten tracks: Foundations, NFTs, Tokens, Payments, Identity, DEX, Reserves, Audit, AMM, and Capstone. Prerequisites are explicit — the CLI and linter enforce them.

The # column matches the order shown by xrpl-lab list (canonical track order).

#	Module	Track	Mode	Prerequisites	Produces
1	Receipt Literacy	foundations	testnet	—	txid, report
2	Failure Literacy	foundations	testnet	Receipt Literacy	txid, report
3	Trust Lines 101: Issued Currencies as Relationships	foundations	testnet	—	txid, report
4	Debugging Trust Lines	foundations	testnet	Trust Lines 101: Issued Currencies as Relationships	txid, report
5	Multisig Treasury (SignerListSet): N-of-M Control of the Studio Wallet	foundations	testnet	Receipt Literacy	txid, report
6	NFT Minting 101: Your First Game Asset	nfts	testnet	—	txid, report
7	NFT Marketplace 101: Trading Assets with Enforced Royalties	nfts	testnet	—	txid, report
8	Dynamic NFTs 101: A Game Item That Levels Up	nfts	testnet	—	txid, report
9	MPT Issuance 101: A Game Currency in One Transaction	tokens	testnet	—	txid, report
10	MPT Distribution 101: Getting the Currency to Players	tokens	testnet	MPT Issuance 101: A Game Currency in One Transaction	txid, report
11	Token Freeze 101: The Issuer's Pause Button	tokens	testnet	—	txid, report
12	Clawback 101: The Issuer Recall Lever	tokens	testnet	—	txid, report
13	Escrow 101: Time-Locked XRP	payments	testnet	—	txid, report
14	Escrow Finish 101: Releasing Locked XRP	payments	testnet	Escrow 101: Time-Locked XRP	txid, report
15	Token Escrow (XLS-85): Locking IOUs, Not Just XRP	payments	testnet	Trust Lines 101: Issued Currencies as Relationships, Escrow 101: Time-Locked XRP	txid, report
16	Checks 101: Deferred Pull-Payments (CheckCreate / CheckCash / CheckCancel)	payments	testnet	Receipt Literacy	txid, report
17	Payment Channels 101: Sign Many, Settle Once	payments	testnet	—	txid, report
18	Delivered Amount: The Partial-Payment Exploit	payments	testnet	Trust Lines 101: Issued Currencies as Relationships	txid, report
19	Custodial Player Crediting: One Pooled Wallet, Many Players (Destination Tags)	payments	testnet	Delivered Amount: The Partial-Payment Exploit	txid, report
20	DID 101: On-Ledger Identity	identity	testnet	—	txid, report
21	Credentials 101 (XLS-70): On-Ledger KYC & Age Attestations	identity	testnet	DID 101: On-Ledger Identity	txid, report
22	Permissioned Domains & Gated DEX (XLS-80/81): Compliant, Credential-Gated Trading	identity	testnet	Credentials 101 (XLS-70): On-Ledger KYC & Age Attestations	txid, report
23	Deposit Gate (DepositAuth + DepositPreauth): Credential-Gated Treasury Deposits	identity	testnet	Credentials 101 (XLS-70): On-Ledger KYC & Age Attestations	txid, report
24	DEX Literacy: Offers, Order Books, and Cancellations	dex	testnet	Trust Lines 101: Issued Currencies as Relationships	txid, report
25	DEX Market Making 101: Earning Spread on the Order Book	dex	testnet	DEX Literacy: Offers, Order Books, and Cancellations	txid, report
26	DEX Inventory Guardrails: Don't Get Lopsided	dex	testnet	DEX Market Making 101: Earning Spread on the Order Book	txid, report
27	Reserves 101: Where Your XRP 'Went'	reserves	testnet	Trust Lines 101: Issued Currencies as Relationships	txid, report
28	Account Hygiene: Freeing Reserves and Cleaning Up Objects	reserves	testnet	Reserves 101: Where Your XRP 'Went'	txid, report
29	Audit Mode: Verify Receipts at Scale	audit	testnet	Receipt Literacy	report, audit_pack
30	AMM Liquidity 101: Providing Liquidity and Earning Fees	amm	testnet	Trust Lines 101: Issued Currencies as Relationships	txid, report
31	DEX vs AMM Risk Literacy: Comparing Trading Strategies	amm	dry-run	DEX Market Making 101: Earning Spread on the Order Book, AMM Liquidity 101: Providing Liquidity and Earning Fees	txid, report
32	Capstone: Stand Up a Minimal Game Economy on XRPL	capstone	testnet	MPT Issuance 101: A Game Currency in One Transaction, NFT Minting 101: Your First Game Asset, Escrow 101: Time-Locked XRP, Audit Mode: Verify Receipts at Scale	txid, report, audit_pack

The Produces column lists the artifact kinds each module emits (txid, report, audit_pack); see each module's page in the handbook for the full skill walkthrough and what you prove on-ledger.

Tracks

• foundations — wallet, payments, trust lines, error handling
• nfts — NFT game assets: minting, marketplace settlement (XLS-20), dynamic NFTs (XLS-46)
• tokens — MPT issuance & distribution (XLS-33), token freeze, clawback (XLS-39)
• payments — time-locked escrow, checks, payment channels, partial payments, destination tags
• identity — DID (XLS-40), credentials (XLS-70), permissioned DEX (XLS-80/81), deposit auth
• dex — offers, order books, market making, inventory management
• reserves — account reserves, owner count, cleanup
• audit — batch verification, audit reports
• amm — automated market maker liquidity, DEX vs AMM comparison
• capstone — compose skills across tracks into one game-economy build

Modes

• testnet — real transactions on the XRPL Testnet
• dry-run — offline sandbox with simulated transactions (no network required)

Commands

xrpl-lab start              Guided launcher
xrpl-lab list               Show all modules with status and progression
xrpl-lab run <module_id>    Run a specific module
xrpl-lab status [--json]    Progress, curriculum position, blockers, track progress
xrpl-lab cohort-status [--dir DIR] [--format FORMAT]  Aggregate per-learner status across a cohort directory (facilitator)
xrpl-lab session-export [--dir DIR] [--format FORMAT] [--outfile FILE]  Archive all learner artifacts with a SHA-256 manifest
xrpl-lab tracks             Track-level completion summaries
xrpl-lab recovery           Diagnose stuck states, show recovery commands
xrpl-lab lint [glob] [--json] [--no-curriculum]  Validate module files and curriculum
xrpl-lab proof-pack         Export shareable proof pack
xrpl-lab verify-artifact <file> [--json] [--live]  Verify any artifact (proof packs, certificates, audit packs, support bundles); --live also checks a proof pack's or certificate's transactions on the ledger
xrpl-lab certificate        Export completion certificate
xrpl-lab doctor             Run diagnostic checks
xrpl-lab support-bundle [--json]  Generate a support bundle
xrpl-lab audit              Batch verify transactions
xrpl-lab last-run           Show last module run + audit command
xrpl-lab serve [--port N] [--host H] [--dry-run]  Start web dashboard and API server
xrpl-lab reset [--module MODULE_ID]  Wipe local state OR reset a single module (requires confirmation)
xrpl-lab module init --id ID --track TRACK --title TITLE --time TIME  Scaffold a lint-passing module skeleton
xrpl-lab curriculum manifest  Print the curriculum manifest the docs are generated from

xrpl-lab wallet create      Create a new wallet
xrpl-lab wallet show        Show wallet info (no secrets)
xrpl-lab fund               Fund wallet from testnet faucet
xrpl-lab send --to <address> --amount <xrp> [--memo <text>]  Send a payment
xrpl-lab verify --tx <id>   Verify a transaction on-ledger

All commands support --dry-run for offline mode where applicable.

Workshop Use

XRPL Lab is designed for real teaching settings. No accounts, no telemetry, no cloud. Everything runs locally.

Facilitator status

xrpl-lab status             # Where is this learner? What's blocked? What's next?
xrpl-lab status --json      # Machine-readable for scripting
xrpl-lab tracks             # Track-level completion: what was actually practiced
xrpl-lab recovery           # Stuck? See exactly what to run next

Support handoff

xrpl-lab support-bundle              # Human-readable markdown bundle
xrpl-lab support-bundle --json       # Machine-parseable JSON
xrpl-lab support-bundle --verify bundle.json  # Verify a received bundle

A facilitator can diagnose any learner's issue from a support bundle without reproducing the whole session. No secrets are included.

Workshop flows

All-offline sandbox — no network required:

xrpl-lab wallet create
xrpl-lab start --dry-run

Mixed offline + testnet — real transactions for basics, sandbox for advanced:

xrpl-lab wallet create
xrpl-lab fund
xrpl-lab start

Camp → Lab progression — continue from xrpl-camp:

xrpl-lab start    # auto-detects camp wallet and certificate

Artifacts

Proof pack (xrpl_lab_proof_pack.json): Shareable record of completed modules, transaction IDs, and explorer links. Includes a SHA-256 integrity hash. No secrets.

Certificate (xrpl_lab_certificate.json): Slim completion record.

Reports (reports/*.md): Human-readable summaries of what you did and proved.

Audit packs (audit_pack_*.json): Batch verification results with SHA-256 integrity hash.

Security and Trust Model

Data XRPL Lab touches:

• Wallet seed (stored locally in ~/.xrpl-lab/wallet.json as plaintext JSON — POSIX mode 0o600 / 0o700 parent, or an owner-only ACL on Windows; not encrypted)
• Module progress and transaction IDs (stored in ~/.xrpl-lab/state.json, atomic writes via tmp + rename)
• XRPL Testnet RPC (public endpoint, transactions signed locally before submission)
• Testnet faucet (public HTTP, only your address is sent)

Data XRPL Lab does NOT touch:

• No mainnet. Testnet only
• No telemetry, analytics, or phone-home of any kind
• No cloud accounts, no registration, no third-party APIs
• No secrets in proof packs, certificates, reports, or support bundles — ever

Permissions and storage tiers:

• Home ~/.xrpl-lab/ — private secrets tier (POSIX 0o700 / 0o600, or an owner-only ACL on Windows). Stores wallet seed, doctor log, audit packs.
• Workspace ./.xrpl-lab/ — designed-shareable tier, 0o755 directory. Stores module reports, proof packs, certificates. Facilitators can review without permission elevation.
• Filesystem: reads/writes only the two locations above
• Network: XRPL Testnet RPC + faucet only (both overridable via env vars, both optional with --dry-run)
• No elevated permissions required

Dashboard surface (when xrpl-lab serve is running):

• WebSocket runner endpoint enforces an Origin allow-list (closes non-allow-listed connections with code 4003)
• HTTP requests that change state (POST, PUT, PATCH, DELETE) from a non-allow-listed Origin are refused with 403 ORIGIN_REJECTED, so a page in another tab can't start a run; requests with no Origin (CLI, curl) still work
• Requests whose Host isn't loopback or the address serve bound to are refused with 400 HOST_REJECTED, which closes DNS rebinding (off for a 0.0.0.0 bind)
• All error frames emit a structured envelope (code, message, hint, severity, icon_hint) — no path leakage, no internal-state leakage
• Bounded per-connection message queue with documented back-pressure behavior

See SECURITY.md for the full security policy and workshop-setup guidance.

Requirements

• Python 3.11+
• Internet connection for testnet (or use --dry-run for fully offline mode)

License

MIT

Built by MCP Tool Shop