xrpl-lab 1.0.3__tar.gz

xrpl_lab-1.0.3/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    paths:
+      - "xrpl_lab/**"
+      - "modules/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+  pull_request:
+    paths:
+      - "xrpl_lab/**"
+      - "modules/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]" || pip install -e .
+          pip install ruff pytest pytest-asyncio
+
+      - name: Lint with ruff
+        run: ruff check xrpl_lab/ tests/
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

xrpl_lab-1.0.3/.github/workflows/pages.yml

@@ -0,0 +1,50 @@
+name: Deploy site to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+
+      - name: Install site dependencies
+        working-directory: site
+        run: npm ci
+
+      - name: Build site
+        working-directory: site
+        run: npm run build
+
+      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

xrpl_lab-1.0.3/.github/workflows/release-binaries.yml

@@ -0,0 +1,85 @@
+# Build platform binaries for npm distribution via @mcptoolshop/npm-launcher.
+# Asset naming convention (locked):
+#   xrpl-lab-<version>-<os>-<arch>[.exe]
+#   checksums-<version>.txt
+
+name: Release Binaries
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux-x64
+            ext: ""
+          - os: macos-latest
+            target: darwin-arm64
+            ext: ""
+          # darwin-x64 omitted: macos-13 deprecated, arm64 binary works via Rosetta
+          - os: windows-latest
+            target: win-x64
+            ext: ".exe"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3
+
+      - run: uv python install 3.12
+
+      - run: uv venv
+
+      - name: Install dependencies + PyInstaller
+        run: uv pip install . "pyinstaller>=6.9.0"
+
+      - name: Build binary
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          uv run pyinstaller --onefile --name "xrpl-lab" --console \
+            --collect-submodules rich \
+            --collect-submodules pydantic \
+            --collect-data xrpl \
+            --add-data "modules:modules" \
+            xrpl_lab/__main__.py
+          OUTNAME="xrpl-lab-${VERSION}-${{ matrix.target }}${{ matrix.ext }}"
+          mv "dist/xrpl-lab${{ matrix.ext }}" "dist/${OUTNAME}"
+          echo "ASSET_NAME=${OUTNAME}" >> "$GITHUB_ENV"
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: binary-${{ matrix.target }}
+          path: dist/${{ env.ASSET_NAME }}
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Generate checksums
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          cd artifacts
+          sha256sum * > "checksums-${VERSION}.txt"
+          cat "checksums-${VERSION}.txt"
+
+      - uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2
+        with:
+          files: artifacts/*

xrpl_lab-1.0.3/.github/workflows/smoke.yml

@@ -0,0 +1,70 @@
+name: Smoke Test (Testnet)
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  testnet-smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Install xrpl-lab
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install httpx
+
+      - name: Run smoke test
+        run: |
+          python -c "
+          import asyncio
+          import json
+          from xrpl.wallet import Wallet
+          from xrpl_lab.transport.xrpl_testnet import XRPLTestnetTransport
+
+          async def smoke():
+              transport = XRPLTestnetTransport()
+
+              # 1. Check network
+              info = await transport.get_network_info()
+              assert info.connected, f'RPC not connected: {info.rpc_url}'
+              print(f'RPC connected: ledger {info.ledger_index}')
+
+              # 2. Create temp wallet and fund
+              wallet = Wallet.create()
+              print(f'Temp wallet: {wallet.address}')
+
+              fund = await transport.fund_from_faucet(wallet.address)
+              assert fund.success, f'Faucet failed: {fund.message}'
+              print(f'Funded: {fund.balance} XRP')
+
+              # 3. Send self-payment
+              result = await transport.submit_payment(
+                  wallet.seed, wallet.address, '10', 'XRPLLAB|SMOKE'
+              )
+              assert result.success, f'Payment failed: {result.error}'
+              print(f'Payment OK: {result.txid[:24]}...')
+
+              # 4. Verify tx
+              tx = await transport.fetch_tx(result.txid)
+              assert tx.result_code == 'tesSUCCESS', f'Verify failed: {tx.result_code}'
+              print(f'Verified: {tx.result_code}, ledger {tx.ledger_index}')
+
+              print('Smoke test passed.')
+
+          asyncio.run(smoke())
+          "

xrpl_lab-1.0.3/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# XRPL Lab user state (never commit)
+.xrpl-lab/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing / Coverage
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Ruff
+.ruff_cache/
+site/.astro/
+site/dist/
+site/node_modules/
+.polyglot-cache.json
+.astro/
+node_modules/

xrpl_lab-1.0.3/CHANGELOG.md

@@ -0,0 +1,194 @@
+# Changelog
+
+## 1.0.3 — 2026-03-29
+
+Dogfood Swarm — comprehensive health pass, web dashboard, and 127 new tests.
+
+### Health Pass (Stage A-C)
+- Fixed 9 HIGH-severity logic bugs (trust line, AMM, runner, state, doctor, audit)
+- SHA-pinned all CI workflow actions across 4 workflows
+- Added defensive guards for all float/int conversions on network data
+- Exception boundary around module runner with state preservation
+- Graceful faucet failure handling with actionable messages
+- Corrupted state backup before reset
+- Step-level progress indicators and retry visibility
+- Wired XRPL_LAB_HOME env var for state directory override
+- Added `network_name` property to Transport ABC
+
+### Web Dashboard
+- FastAPI server layer with 9 REST endpoints + WebSocket module runner
+- `xrpl-lab serve` command starts API server with --dry-run support
+- Astro dashboard: module catalog, interactive runner, artifact viewer, doctor page
+- Real-time module execution via WebSocket with terminal-style output
+- 36-page site build (landing page + handbook + dashboard)
+
+### Feature Improvements
+- Module ordering by explicit order field (not alphabetical)
+- AMM modules require --dry-run with clear warning
+- Prerequisite enforcement with --force bypass
+- Richer module reports with action outcomes
+- Certificate includes titles, tx counts, summary line
+- `audit --no-pack` option to skip JSON pack
+- Fixed dex_market_making_101 step ordering bug
+
+### Test Coverage
+- 228 → 355 tests (+127)
+- New test files: wallet, verify, send/fund, errors, server, runner_ws, CLI serve
+- Fixed dry-run fidelity: per-address balances, instance-level counter, valid base58
+
+## 1.0.2 — 2026-03-25
+
+- SHA-pinned CI actions (checkout, setup-python)
+- Version test now uses dynamic `__version__` instead of hardcoded string
+
+## 1.0.1 — 2026-03-03
+
+Binary launcher fix: Windows UTF-8 encoding for Rich console output.
+
+- Fix: `UnicodeEncodeError` on Windows when Rich renders Unicode symbols (○, ✓, ✗)
+- `__main__.py` reconfigures stdout/stderr to UTF-8 before any imports
+- PyInstaller + npm-launcher: `npx @mcptoolshop/xrpl-lab` now works on Windows
+
+## 1.0.0 — 2026-03-03
+
+Shipcheck + Full Treatment — production-ready release.
+
+- Structured error contract: `LabError` + `LabException` with code/message/hint/cause/retryable
+- Exit code mapping: INPUT/CONFIG/STATE → 1, IO/DEP/RUNTIME → 2, PARTIAL → 3
+- Verify script: `verify.sh` (lint + test + build in one command)
+- README: logo, badges, full 12-module table, trust model paragraph
+- SECURITY.md: complete security policy with trust boundaries
+- SHIP_GATE.md: all hard gates (A-D) passing
+- Landing page: @mcptoolshop/site-theme
+- Translations: 8 languages via polyglot-mcp
+
+## 0.10.0 — 2026-03-03
+
+Strategy Track Complete: Inventory Guardrails + DEX vs AMM Capstone.
+
+- New module: DEX Inventory Guardrails — threshold-based quoting, only safe sides placed
+- New module: DEX vs AMM Risk Literacy — side-by-side comparison of DEX and AMM strategies
+- `check_inventory` — evaluate XRP spendable and token balance against thresholds
+- `InventoryCheck` dataclass with `can_bid`, `can_ask`, `sides_allowed`
+- Runner: `check_inventory` and `place_safe_sides` action handlers
+- New command: `xrpl-lab last-run` — show last module run info + audit command
+- Module completion panel now shows audit verification one-liner
+- Audit presets: `presets/strategy_inv.json`, `presets/strategy_compare.json`
+- 12 modules total — full strategy track (beginner → intermediate → advanced)
+
+## 0.9.0 — 2026-03-02
+
+DEX Market Making 101: Strategy Track Foundations.
+
+- New module: DEX Market Making 101 — bid/ask offers, position snapshots, cleanup hygiene
+- Strategy foundations: `PositionSnapshot`, `PositionComparison`, `HygieneSummary`
+- `snapshot_position` — extended account state (trust lines, offers, owner count, spendable estimate)
+- `compare_positions` — track owner count and offer deltas between snapshots
+- `cancel_module_offers` — batch cancel strategy offers by sequence
+- `hygiene_summary` — end-of-module cleanup verification (offers cleared, owner count baseline)
+- `write_last_run` — outputs `last_run_txids.txt` + `last_run_meta.json` for audit integration
+- Strategy memo convention: `XRPLLAB|STRAT|<MODULE>|<ACTION>|<RUNID>`
+- Audit preset: `presets/strategy_mm101.json` (OfferCreate/OfferCancel types, memo prefix)
+- Runner: 8 new action handlers (snapshot_position, strategy_offer_bid/ask, verify/cancel module offers, verify_position_delta, hygiene_summary)
+
+## 0.8.0 — 2026-03-02
+
+AMM Liquidity 101: Providing Liquidity and Earning Fees.
+
+- New module: AMM Liquidity 101 — create pool, deposit, verify LP, withdraw, verify
+- Transport: `get_amm_info`, `submit_amm_create`, `submit_amm_deposit`, `submit_amm_withdraw`, `get_lp_token_balance`
+- `AmmInfo` dataclass: pool balances, LP token, trading fee
+- Dry-run transport: full AMM simulation (pool registry, LP minting/burning, proportional math)
+- Actions: `ensure_amm_pair`, `amm_deposit`, `amm_withdraw`, `verify_lp_received`, `verify_withdrawal`
+- Runner: 7 new AMM action handlers
+- Testnet transport: AMM stubs (dry-run only for now, pending AMM amendment availability)
+
+## 0.7.0 — 2026-03-02
+
+Audit Mode: Verify Receipts at Scale.
+
+- New command: `xrpl-lab audit --txids txids.txt` — batch verify transactions
+- Expectation configs: JSON with defaults + per-tx overrides (require_validated, require_success, memo_prefix, types_allowed, expected_engine_result)
+- Failure vocabulary: NOT_FOUND, NOT_VALIDATED, ENGINE_RESULT_MISMATCH, TYPE_DISALLOWED, MEMO_MISSING
+- Reports: Markdown table, CSV, JSON audit pack with SHA-256 integrity hash
+- New module: Receipt Audit — hands-on audit mode walkthrough
+- Dry-run transport: tx fixture support for deterministic audit testing
+- Runner: `run_audit` action handler for module-driven audits
+
+## 0.6.0 — 2026-03-03
+
+Account Hygiene: Freeing Reserves and Cleaning Up Objects.
+
+- New module: Account Hygiene — create objects, cancel offers, remove trust lines, verify cleanup
+- Trust line removal: `submit_trust_set` with `limit=0` removes trust lines (balance must be 0)
+- Dry-run transport: smart trust line handling — no duplicates, limit updates, owner count decrement on removal
+- Actions: `remove_trust_line`, `verify_trust_line_removed`
+- Runner: `remove_trust_line` and `verify_trust_line_removed` action handlers
+- Non-zero balance guard: removal fails with `tecNO_PERMISSION` if tokens still held
+
+## 0.5.0 — 2026-03-02
+
+Reserves 101: Where Your XRP "Went" — account snapshots and owner count tracking.
+
+- New module: Reserves 101 — snapshot before/after, owner count delta, reserve explanation
+- Transport: `get_account_info` returns `AccountSnapshot` (balance, owner count, sequence)
+- `AccountSnapshot` dataclass for point-in-time account state
+- Actions: `snapshot_account`, `compare_snapshots` with `ReserveComparison` result
+- Runner: `snapshot_account` and `verify_reserve_change` action handlers
+- Dry-run transport tracks `_owner_count` across trust lines and offers
+- Helper: `_drops_to_xrp` for human-readable balance display
+
+## 0.4.0 — 2026-03-02
+
+DEX Literacy module — offers, order books, and cancellations.
+
+- New module: DEX Literacy — create offer, verify active, cancel, verify absent
+- Transport: `submit_offer_create`, `submit_offer_cancel`, `get_account_offers`
+- `OfferInfo` dataclass for DEX offer representation
+- Actions: `create_offer`, `cancel_offer`, `verify_offer_present`, `verify_offer_absent`
+- Runner: handles DEX action types (create_offer, cancel_offer, verify_offer_*)
+- Dry-run transport tracks offers with sequence numbers and supports cancellation
+- DEX notes: `docs/dex_notes.md` — taker pays/gets, partial fills, why cancel matters
+
+## 0.3.1 — 2026-03-03
+
+Debugging Reality: trust line failure module + ecosystem alignment.
+
+- New module: Debugging Trust Lines — intentional failure, error decode, fix, verify
+- Dry-run transport validates trust lines realistically (no trust line = tecPATH_DRY)
+- `xrpl-lab self-check` — alias for `doctor` (ecosystem verb alignment)
+- Proof pack receipt table: human-readable per-tx summary (txid, module, status, timestamp)
+- Runner: `issue_token_expect_fail` action with result code explanation
+
+## 0.3.0 — 2026-03-02
+
+Trust Lines module + feedback command.
+
+- New module: Trust Lines 101 — create issuer, set trust line, issue tokens, verify
+- Transport: `submit_trust_set`, `submit_issued_payment`, `get_trust_lines`
+- Trust line actions: `set_trust_line`, `issue_token`, `verify_trust_line`
+- `xrpl-lab feedback` — generates issue-ready markdown (doctor + env + proof pack)
+- Runner handles trust line action types (create_issuer_wallet, fund_issuer, etc.)
+
+## 0.2.0 — 2026-03-02
+
+Clinic & Proof Pack release.
+
+- `xrpl-lab doctor` — checklist diagnostic (wallet, state, RPC, faucet, env, last error)
+- XRPL result code reference with categories + actionable hints
+- Transport: timeouts, retries (max 2), friendly error messages
+- Proof pack upgrade: per-tx detail, endpoint, success/fail counts
+- `status` shows env overrides (XRPL_LAB_RPC_URL, XRPL_LAB_FAUCET_URL)
+- `reset` requires "RESET" (uppercase), adds `--keep-wallet` flag
+- Manual testnet smoke test workflow (workflow_dispatch)
+
+## 0.1.0 — 2026-03-02
+
+Initial release.
+
+- 2 modules: Receipt Literacy, Failure Literacy
+- CLI: `start`, `list`, `run`, `status`, `reset`, `proof-pack`, `certificate`
+- Standalone commands: `wallet create/show`, `fund`, `send`, `verify`
+- XRPL Testnet transport + dry-run (offline) transport
+- Proof packs and certificates (no secrets, SHA-256 integrity hash)
+- XRPL Camp soft-integration (certificate file detection)

xrpl_lab-1.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP Tool Shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xrpl_lab-1.0.3/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: xrpl-lab
+Version: 1.0.3
+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: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: xrpl-py>=4.0.0
+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="400" 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 — just competence and receipts.
+
+## 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
+
+12 modules across three tracks: Beginner, Intermediate, and Advanced.
+
+| # | Module | Track | What you learn | What you prove |
+|---|--------|-------|----------------|----------------|
+| 1 | Receipt Literacy | Beginner | Send a payment, read every receipt field | txid + verification report |
+| 2 | Failure Literacy | Beginner | Break a tx on purpose, diagnose, fix, resubmit | failed + fixed txid trail |
+| 3 | Trust Lines 101 | Beginner | Create issuer, set trust line, issue tokens | trust line + token balance |
+| 4 | Debugging Trust Lines | Beginner | Intentional trust line failure, error decode, fix | error → fix txid trail |
+| 5 | DEX Literacy | Intermediate | Create offers, read order books, cancel | offer create + cancel txids |
+| 6 | Reserves 101 | Intermediate | Account snapshots, owner count, reserve math | before/after snapshot delta |
+| 7 | Account Hygiene | Intermediate | Cancel offers, remove trust lines, free reserves | cleanup verification report |
+| 8 | Receipt Audit | Intermediate | Batch verify transactions with expectations | audit pack (MD + CSV + JSON) |
+| 9 | AMM Liquidity 101 | Advanced | Create pool, deposit, earn LP, withdraw | AMM lifecycle txids |
+| 10 | DEX Market Making 101 | Advanced | Bid/ask offers, position snapshots, cleanup | strategy txids + hygiene report |
+| 11 | Inventory Guardrails | Advanced | Threshold-based quoting, safe-side-only placement | inventory check + guarded txids |
+| 12 | DEX vs AMM Risk Literacy | Advanced | Side-by-side DEX and AMM lifecycle comparison | comparison report + audit trail |
+
+## Commands
+
+```
+xrpl-lab start              Guided launcher
+xrpl-lab list               Show all modules with status
+xrpl-lab run <module_id>    Run a specific module
+xrpl-lab status             Progress, wallet, recent txs
+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 issue-ready markdown
+xrpl-lab audit              Batch verify transactions
+xrpl-lab last-run           Show last module run + audit command
+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.
+
+## 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](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](https://mcp-tool-shop.github.io/)