xrpl-lab 1.5.0

XRPL training workbook — learn by doing, prove by artifact

日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

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+.

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

12 modules across five tracks: Foundations, DEX, Reserves, Audit, and AMM. Prerequisites are explicit — the CLI and linter enforce them.

#	Module	Track	Mode	What you learn	What you prove
1	Receipt Literacy	foundations	testnet	Send a payment, read every receipt field	txid + verification report
2	Failure Literacy	foundations	testnet	Break a tx on purpose, diagnose, fix, resubmit	failed + fixed txid trail
3	Trust Lines 101	foundations	testnet	Create issuer, set trust line, issue tokens	trust line + token balance
4	Debugging Trust Lines	foundations	testnet	Intentional trust line failure, error decode, fix	error → fix txid trail
5	DEX Literacy	dex	testnet	Create offers, read order books, cancel	offer create + cancel txids
6	Reserves 101	reserves	testnet	Account snapshots, owner count, reserve math	before/after snapshot delta
7	Account Hygiene	reserves	testnet	Cancel offers, remove trust lines, free reserves	cleanup verification report
8	Receipt Audit	audit	testnet	Batch verify transactions with expectations	audit pack (MD + CSV + JSON)
9	AMM Liquidity 101	amm	dry-run	Create pool, deposit, earn LP, withdraw	AMM lifecycle txids
10	DEX Market Making 101	dex	testnet	Bid/ask offers, position snapshots, cleanup	strategy txids + hygiene report
11	Inventory Guardrails	dex	testnet	Threshold-based quoting, safe-side-only placement	inventory check + guarded txids
12	DEX vs AMM Risk Literacy	amm	dry-run	Side-by-side DEX and AMM lifecycle comparison	comparison report + audit trail

Tracks

• foundations — wallet, payments, trust lines, error handling
• 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

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 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 certificate        Export completion certificate
xrpl-lab doctor             Run diagnostic checks
xrpl-lab self-check         Alias for doctor
xrpl-lab feedback           Generate support bundle (markdown)
xrpl-lab support-bundle [--json] [--verify FILE]  Generate or verify support bundles
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              Wipe local state (requires RESET confirmation)

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 with restrictive file permissions)
• Module progress and transaction IDs (stored in ~/.xrpl-lab/state.json)
• 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, or reports — ever

Permissions:

• Filesystem: reads/writes only ~/.xrpl-lab/ and ./.xrpl-lab/ (local workspace)
• Network: XRPL Testnet RPC + faucet only (both overridable via env vars, both optional with --dry-run)
• No elevated permissions required

See SECURITY.md for the full security policy.

Requirements

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

License

MIT

Built by MCP Tool Shop