From b504aff037b125b6e013932b1b44d7c711374b5b Mon Sep 17 00:00:00 2001 From: Patrick Mulligan Date: Fri, 23 Jan 2026 06:29:10 -0500 Subject: [PATCH] Update CLAUDE.md with current implementation status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Implementation Status section with completed/placeholder/planned breakdown - Mark architecture tree with completion status (✅, planned, placeholder) - Add Kind 21000 (Lightning.Pub RPC) to Nostr Event Kinds table - Fix Kind 30078 description: "Service Beacon" not "Machine Status" - Update Key Technologies table with current state - Remove NIP-17 (not currently used) Co-Authored-By: Claude Opus 4.5 --- lamassu-next/CLAUDE.md | 104 +++++++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 31 deletions(-) diff --git a/lamassu-next/CLAUDE.md b/lamassu-next/CLAUDE.md index a320da1..663bc5e 100644 --- a/lamassu-next/CLAUDE.md +++ b/lamassu-next/CLAUDE.md @@ -16,20 +16,45 @@ This file provides guidance to Claude Code when working with the Lamassu Next co ``` lamassu-next/ ├── apps/ -│ ├── machine/ # Tauri + Vue 3 ATM kiosk application -│ ├── dashboard/ # Vue 3 operator dashboard -│ └── relay/ # strfry relay configuration +│ ├── machine/ # Tauri + Vue 3 ATM kiosk application (planned) +│ ├── dashboard/ # Vue 3 operator dashboard (planned) +│ └── relay/ # strfry relay configuration (planned) ├── packages/ -│ ├── hal/ # Rust Hardware Abstraction Layer (napi-rs) -│ ├── nostr-client/ # Nostr client library -│ ├── clink/ # CLINK protocol implementation -│ ├── state-machine/ # XState v5 ATM state machine -│ ├── lightning/ # Lightning.Pub client -│ ├── cashu/ # Cashu ecash (offline mode) -│ └── ui-shared/ # Shared Vue components -└── docker/ # Development infrastructure +│ ├── hal/ # Rust Hardware Abstraction Layer (planned) +│ ├── nostr-client/ # Nostr client library ✅ +│ ├── clink/ # CLINK protocol implementation ✅ +│ ├── state-machine/ # XState v5 ATM state machine ✅ +│ ├── lightning/ # Lightning.Pub RPC client ✅ +│ ├── cashu/ # Cashu ecash (placeholder) +│ └── ui-shared/ # Shared Vue components (placeholder) +└── docker/ # Development infrastructure (planned) ``` +## Implementation Status + +### Completed Packages + +| Package | Description | Tests | +| ------------------------ | ------------------------------------------------------ | ----- | +| `@lamassu/nostr-client` | Nostr relay client with NIP-42 auth, NIP-44 encryption | 13 | +| `@lamassu/clink` | CLINK protocol (kinds 21001-21003), noffer encoding | 7 | +| `@lamassu/lightning` | Lightning.Pub RPC client (kind 21000) | 10 | +| `@lamassu/state-machine` | XState v5 ATM state machine (idle, cashIn, cashOut) | 9 | + +### Placeholder Packages + +| Package | Description | +| -------------------- | --------------------------------- | +| `@lamassu/cashu` | Cashu ecash for offline operation | +| `@lamassu/ui-shared` | Shared Vue 3 components | + +### Planned Components + +- **apps/machine** - Tauri 2.x ATM kiosk with Vue 3 UI +- **apps/dashboard** - Operator dashboard for fleet management +- **packages/hal** - Rust hardware drivers (bill validators, dispensers, printers) +- **docker/** - strfry relay + Lightning.Pub for development + ## Commands ```bash @@ -54,41 +79,49 @@ infra-down ## Key Technologies -| Component | Technology | Notes | -|-----------|------------|-------| -| Runtime | Node.js 22 LTS | Strict TypeScript | -| ATM Shell | Tauri 2.x | Rust core, Vue 3 UI | -| State Machine | XState v5 | Actor model | -| Hardware | Rust + napi-rs | Ported from lamassu-machine | -| Messaging | Nostr | NIP-01, NIP-17, NIP-42, NIP-44 | -| Payments | CLINK | Kind 21001/21002/21003 | -| Backend | Lightning.Pub | Nostr-native account system | +| Component | Technology | Notes | +| ------------- | -------------- | ------------------------------------- | +| Runtime | Node.js 22 LTS | Strict TypeScript, ESM | +| ATM Shell | Tauri 2.x | Rust core, Vue 3 UI (planned) | +| State Machine | XState v5 | Actor model, service injection | +| Hardware | Rust + napi-rs | Ported from lamassu-machine (planned) | +| Messaging | Nostr | NIP-01, NIP-42, NIP-44 | +| Payments | CLINK + RPC | Kind 21000 (RPC), 21001-21003 (CLINK) | +| Backend | Lightning.Pub | Nostr-native account system | ## Custom Skills The following skills are available for development assistance: ### `/security` - Security Review + Audit code for Bitcoin/Lightning/ATM-specific vulnerabilities. + ``` /security packages/lightning/src/ /security --staged ``` ### `/nostr-check` - Nostr Conformity + Validate NIP compliance and Nostr protocol implementation. + ``` /nostr-check packages/nostr-client/src/events.ts --nips NIP-01,NIP-44 ``` ### `/lightning-check` - Lightning.Pub Conformity + Validate CLINK protocol and Lightning.Pub integration. + ``` /lightning-check packages/clink/src/ --clink ``` ### `/test` - Testing Agent + Run tests, generate test cases, validate transaction flows. + ``` /test coverage packages/state-machine/ /test flow cash-out @@ -96,14 +129,18 @@ Run tests, generate test cases, validate transaction flows. ``` ### `/docs` - Documentation Agent + Keep documentation synchronized with code. + ``` /docs sync packages/clink/ /docs api packages/nostr-client/src/ ``` ### `/hal-check` - HAL Validation + Validate Rust HAL drivers against lamassu-machine implementations. + ``` /hal-check port id003 /hal-check safety packages/hal/src/dispensers/ @@ -112,18 +149,21 @@ Validate Rust HAL drivers against lamassu-machine implementations. ## Code Style ### TypeScript + - ESM only (`import`/`export`) - Strict mode with `strictNullChecks` and `noUncheckedIndexedAccess` - Zod for runtime validation - No `any` types ### Rust (HAL) + - Stable toolchain - `#![deny(unsafe_code)]` unless justified - Error handling with `thiserror` - Async with `tokio` ### Formatting + - Prettier for TypeScript (2 spaces, no semicolons, single quotes) - rustfmt for Rust - Pre-commit hooks enforce formatting @@ -132,13 +172,14 @@ Validate Rust HAL drivers against lamassu-machine implementations. Drivers are ported from `lamassu-machine/lib/`: -| Category | Drivers | -|----------|---------| +| Category | Drivers | +| ---------- | ------------------------------------------------------------ | | Validators | id003, ccnet, cashflow_sc, bnr_advance, genmega, hcm2, gsr50 | -| Dispensers | puloon, f56, genmega, hcm2, gsr50 | -| Printers | nippon, zebra, genmega | +| Dispensers | puloon, f56, genmega, hcm2, gsr50 | +| Printers | nippon, zebra, genmega | When porting: + 1. Read JS driver thoroughly 2. Document protocol from JS code 3. Implement Rust version @@ -147,13 +188,14 @@ When porting: ## Nostr Event Kinds -| Kind | Description | -|------|-------------| -| 21001 | CLINK Offer | -| 21002 | CLINK Debit | -| 21003 | CLINK Manage | -| 30078 | Machine Status (replaceable) | -| 30079 | Transaction Record (replaceable) | +| Kind | Description | +| ----- | ----------------------------------------------- | +| 21000 | Lightning.Pub RPC (generic request/response) | +| 21001 | CLINK Offer (invoice request/response) | +| 21002 | CLINK Debit (payment authorization) | +| 21003 | CLINK Manage (offer management) | +| 30078 | Service Beacon (replaceable, service discovery) | +| 30079 | Transaction Record (replaceable) | ## Security Priorities