Metadata-Version: 2.4
Name: xrpl-lab
Version: 2.3.0
Summary: XRPL training workbook — learn by doing, prove by artifact
Project-URL: Homepage, https://mcp-tool-shop-org.github.io/xrpl-lab/
Project-URL: Repository, https://github.com/mcp-tool-shop-org/xrpl-lab
Project-URL: Issues, https://github.com/mcp-tool-shop-org/xrpl-lab/issues
Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: blockchain,cli,education,training,xrpl
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: idna>=3.15
Requires-Dist: msgpack>=1.2.1
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: starlette>=1.0.1
Requires-Dist: uvicorn>=0.30
Requires-Dist: xrpl-py<5.0.0,>=4.0.0
Provides-Extra: dev
Requires-Dist: pip-audit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: urllib3>=2.7.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/xrpl-lab/readme.png" width="500" alt="XRPL Lab">
</p>

<p align="center">
  <a href="https://github.com/mcp-tool-shop-org/xrpl-lab/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/xrpl-lab/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/mcp-tool-shop-org/xrpl-lab/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT License"></a>
  <a href="https://mcp-tool-shop-org.github.io/xrpl-lab/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
</p>

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.

<p align="center">
  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/xrpl-lab/main/docs/images/dashboard-hero.png" width="800" alt="XRPL Lab dashboard showing completed modules with quick actions and status panels">
</p>

## Install

```bash
pipx install xrpl-lab
```

Or with pip:

```bash
pip install xrpl-lab
```

Requires Python 3.11+.

## Quickstart

```bash
xrpl-lab start
```

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

### Offline mode

```bash
xrpl-lab start --dry-run
```

No network required. Simulated transactions for learning the workflow.

## Modules

<!-- BEGIN curriculum:auto readme-intro -->
<!-- generated by scripts/gen_docs.py — do not hand-edit; run the generator -->
28 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).
<!-- END curriculum:auto readme-intro -->

<!-- BEGIN curriculum:auto readme-table -->
<!-- generated by scripts/gen_docs.py — do not hand-edit; run the generator -->
| # | 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 | NFT Minting 101: Your First Game Asset | nfts | testnet | — | txid, report |
| 6 | NFT Marketplace 101: Trading Assets with Enforced Royalties | nfts | testnet | — | txid, report |
| 7 | Dynamic NFTs 101: A Game Item That Levels Up | nfts | testnet | — | txid, report |
| 8 | MPT Issuance 101: A Game Currency in One Transaction | tokens | testnet | — | txid, report |
| 9 | MPT Distribution 101: Getting the Currency to Players | tokens | testnet | MPT Issuance 101: A Game Currency in One Transaction | txid, report |
| 10 | Token Freeze 101: The Issuer's Pause Button | tokens | testnet | — | txid, report |
| 11 | Clawback 101: The Issuer Recall Lever | tokens | testnet | — | txid, report |
| 12 | Escrow 101: Time-Locked XRP | payments | testnet | — | txid, report |
| 13 | Escrow Finish 101: Releasing Locked XRP | payments | testnet | Escrow 101: Time-Locked XRP | txid, report |
| 14 | 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 |
| 15 | Payment Channels 101: Sign Many, Settle Once | payments | testnet | — | txid, report |
| 16 | Delivered Amount: The Partial-Payment Exploit | payments | testnet | Trust Lines 101: Issued Currencies as Relationships | txid, report |
| 17 | DID 101: On-Ledger Identity | identity | testnet | — | txid, report |
| 18 | Credentials 101 (XLS-70): On-Ledger KYC & Age Attestations | identity | testnet | DID 101: On-Ledger Identity | txid, report |
| 19 | Permissioned Domains & Gated DEX (XLS-80/81): Compliant, Credential-Gated Trading | identity | testnet | Credentials 101 (XLS-70): On-Ledger KYC & Age Attestations | txid, report |
| 20 | DEX Literacy: Offers, Order Books, and Cancellations | dex | testnet | Trust Lines 101: Issued Currencies as Relationships | txid, report |
| 21 | DEX Market Making 101: Earning Spread on the Order Book | dex | testnet | DEX Literacy: Offers, Order Books, and Cancellations | txid, report |
| 22 | DEX Inventory Guardrails: Don't Get Lopsided | dex | testnet | DEX Market Making 101: Earning Spread on the Order Book | txid, report |
| 23 | Reserves 101: Where Your XRP 'Went' | reserves | testnet | Trust Lines 101: Issued Currencies as Relationships | txid, report |
| 24 | Account Hygiene: Freeing Reserves and Cleaning Up Objects | reserves | testnet | Reserves 101: Where Your XRP 'Went' | txid, report |
| 25 | Audit Mode: Verify Receipts at Scale | audit | testnet | Receipt Literacy | report, audit_pack |
| 26 | AMM Liquidity 101: Providing Liquidity and Earning Fees | amm | dry-run | Trust Lines 101: Issued Currencies as Relationships | txid, report |
| 27 | 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 |
| 28 | 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 |
<!-- END curriculum:auto readme-table -->

The **Produces** column lists the artifact kinds each module emits (`txid`,
`report`, `audit_pack`); see each module's page in the
[handbook](https://mcp-tool-shop-org.github.io/xrpl-lab/handbook/modules/) for
the full skill walkthrough and what you prove on-ledger.

### Tracks

<!-- BEGIN curriculum:auto readme-tracks -->
<!-- generated by scripts/gen_docs.py — do not hand-edit; run the generator -->
- **foundations** — wallet, payments, trust lines, error handling
- **nfts** — NFT game assets: minting, marketplace settlement, dynamic NFTs (XLS-20)
- **tokens** — Multi-Purpose Token (MPT) game-currency issuance & clawback (XLS-33)
- **payments** — escrow & time-locked value
- **identity** — Decentralized Identifiers (DID, XLS-40)
- **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
<!-- END curriculum:auto readme-tracks -->

### Modes

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

## Commands

```text
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 proof generate     Export shareable proof pack (alias of proof-pack)
xrpl-lab proof verify <file>  Verify a proof pack's integrity (SHA-256)
xrpl-lab certificate        Export completion certificate
xrpl-lab cert-verify <file>   Verify a completion certificate's integrity
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 [--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 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.

<p align="center">
  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/xrpl-lab/main/docs/images/facilitator-active-runs.png" width="800" alt="Facilitator dashboard listing active learner runs with module IDs, dry-run badges, status, queue depth, and run IDs">
</p>

### Facilitator status

```bash
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

```bash
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:
```bash
xrpl-lab wallet create
xrpl-lab start --dry-run
```

**Mixed offline + testnet** — real transactions for basics, sandbox for advanced:
```bash
xrpl-lab wallet create
xrpl-lab fund
xrpl-lab start
```

**Camp → Lab progression** — continue from xrpl-camp:
```bash
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, protected by 0o600 file permissions and a 0o700 parent directory — 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, 0o700 directory + 0o600 wallet file. 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)
- 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](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](https://mcp-tool-shop.github.io/)
