Update CLAUDE.md with current implementation status

- 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 <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan 2026-01-23 06:29:10 -05:00
commit b504aff037

View file

@ -16,20 +16,45 @@ This file provides guidance to Claude Code when working with the Lamassu Next co
``` ```
lamassu-next/ lamassu-next/
├── apps/ ├── apps/
│ ├── machine/ # Tauri + Vue 3 ATM kiosk application │ ├── machine/ # Tauri + Vue 3 ATM kiosk application (planned)
│ ├── dashboard/ # Vue 3 operator dashboard │ ├── dashboard/ # Vue 3 operator dashboard (planned)
│ └── relay/ # strfry relay configuration │ └── relay/ # strfry relay configuration (planned)
├── packages/ ├── packages/
│ ├── hal/ # Rust Hardware Abstraction Layer (napi-rs) │ ├── hal/ # Rust Hardware Abstraction Layer (planned)
│ ├── nostr-client/ # Nostr client library │ ├── nostr-client/ # Nostr client library ✅
│ ├── clink/ # CLINK protocol implementation │ ├── clink/ # CLINK protocol implementation ✅
│ ├── state-machine/ # XState v5 ATM state machine │ ├── state-machine/ # XState v5 ATM state machine ✅
│ ├── lightning/ # Lightning.Pub client │ ├── lightning/ # Lightning.Pub RPC client ✅
│ ├── cashu/ # Cashu ecash (offline mode) │ ├── cashu/ # Cashu ecash (placeholder)
│ └── ui-shared/ # Shared Vue components │ └── ui-shared/ # Shared Vue components (placeholder)
└── docker/ # Development infrastructure └── 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 ## Commands
```bash ```bash
@ -55,13 +80,13 @@ infra-down
## Key Technologies ## Key Technologies
| Component | Technology | Notes | | Component | Technology | Notes |
|-----------|------------|-------| | ------------- | -------------- | ------------------------------------- |
| Runtime | Node.js 22 LTS | Strict TypeScript | | Runtime | Node.js 22 LTS | Strict TypeScript, ESM |
| ATM Shell | Tauri 2.x | Rust core, Vue 3 UI | | ATM Shell | Tauri 2.x | Rust core, Vue 3 UI (planned) |
| State Machine | XState v5 | Actor model | | State Machine | XState v5 | Actor model, service injection |
| Hardware | Rust + napi-rs | Ported from lamassu-machine | | Hardware | Rust + napi-rs | Ported from lamassu-machine (planned) |
| Messaging | Nostr | NIP-01, NIP-17, NIP-42, NIP-44 | | Messaging | Nostr | NIP-01, NIP-42, NIP-44 |
| Payments | CLINK | Kind 21001/21002/21003 | | Payments | CLINK + RPC | Kind 21000 (RPC), 21001-21003 (CLINK) |
| Backend | Lightning.Pub | Nostr-native account system | | Backend | Lightning.Pub | Nostr-native account system |
## Custom Skills ## Custom Skills
@ -69,26 +94,34 @@ infra-down
The following skills are available for development assistance: The following skills are available for development assistance:
### `/security` - Security Review ### `/security` - Security Review
Audit code for Bitcoin/Lightning/ATM-specific vulnerabilities. Audit code for Bitcoin/Lightning/ATM-specific vulnerabilities.
``` ```
/security packages/lightning/src/ /security packages/lightning/src/
/security --staged /security --staged
``` ```
### `/nostr-check` - Nostr Conformity ### `/nostr-check` - Nostr Conformity
Validate NIP compliance and Nostr protocol implementation. Validate NIP compliance and Nostr protocol implementation.
``` ```
/nostr-check packages/nostr-client/src/events.ts --nips NIP-01,NIP-44 /nostr-check packages/nostr-client/src/events.ts --nips NIP-01,NIP-44
``` ```
### `/lightning-check` - Lightning.Pub Conformity ### `/lightning-check` - Lightning.Pub Conformity
Validate CLINK protocol and Lightning.Pub integration. Validate CLINK protocol and Lightning.Pub integration.
``` ```
/lightning-check packages/clink/src/ --clink /lightning-check packages/clink/src/ --clink
``` ```
### `/test` - Testing Agent ### `/test` - Testing Agent
Run tests, generate test cases, validate transaction flows. Run tests, generate test cases, validate transaction flows.
``` ```
/test coverage packages/state-machine/ /test coverage packages/state-machine/
/test flow cash-out /test flow cash-out
@ -96,14 +129,18 @@ Run tests, generate test cases, validate transaction flows.
``` ```
### `/docs` - Documentation Agent ### `/docs` - Documentation Agent
Keep documentation synchronized with code. Keep documentation synchronized with code.
``` ```
/docs sync packages/clink/ /docs sync packages/clink/
/docs api packages/nostr-client/src/ /docs api packages/nostr-client/src/
``` ```
### `/hal-check` - HAL Validation ### `/hal-check` - HAL Validation
Validate Rust HAL drivers against lamassu-machine implementations. Validate Rust HAL drivers against lamassu-machine implementations.
``` ```
/hal-check port id003 /hal-check port id003
/hal-check safety packages/hal/src/dispensers/ /hal-check safety packages/hal/src/dispensers/
@ -112,18 +149,21 @@ Validate Rust HAL drivers against lamassu-machine implementations.
## Code Style ## Code Style
### TypeScript ### TypeScript
- ESM only (`import`/`export`) - ESM only (`import`/`export`)
- Strict mode with `strictNullChecks` and `noUncheckedIndexedAccess` - Strict mode with `strictNullChecks` and `noUncheckedIndexedAccess`
- Zod for runtime validation - Zod for runtime validation
- No `any` types - No `any` types
### Rust (HAL) ### Rust (HAL)
- Stable toolchain - Stable toolchain
- `#![deny(unsafe_code)]` unless justified - `#![deny(unsafe_code)]` unless justified
- Error handling with `thiserror` - Error handling with `thiserror`
- Async with `tokio` - Async with `tokio`
### Formatting ### Formatting
- Prettier for TypeScript (2 spaces, no semicolons, single quotes) - Prettier for TypeScript (2 spaces, no semicolons, single quotes)
- rustfmt for Rust - rustfmt for Rust
- Pre-commit hooks enforce formatting - Pre-commit hooks enforce formatting
@ -133,12 +173,13 @@ Validate Rust HAL drivers against lamassu-machine implementations.
Drivers are ported from `lamassu-machine/lib/`: Drivers are ported from `lamassu-machine/lib/`:
| Category | Drivers | | Category | Drivers |
|----------|---------| | ---------- | ------------------------------------------------------------ |
| Validators | id003, ccnet, cashflow_sc, bnr_advance, genmega, hcm2, gsr50 | | Validators | id003, ccnet, cashflow_sc, bnr_advance, genmega, hcm2, gsr50 |
| Dispensers | puloon, f56, genmega, hcm2, gsr50 | | Dispensers | puloon, f56, genmega, hcm2, gsr50 |
| Printers | nippon, zebra, genmega | | Printers | nippon, zebra, genmega |
When porting: When porting:
1. Read JS driver thoroughly 1. Read JS driver thoroughly
2. Document protocol from JS code 2. Document protocol from JS code
3. Implement Rust version 3. Implement Rust version
@ -148,11 +189,12 @@ When porting:
## Nostr Event Kinds ## Nostr Event Kinds
| Kind | Description | | Kind | Description |
|------|-------------| | ----- | ----------------------------------------------- |
| 21001 | CLINK Offer | | 21000 | Lightning.Pub RPC (generic request/response) |
| 21002 | CLINK Debit | | 21001 | CLINK Offer (invoice request/response) |
| 21003 | CLINK Manage | | 21002 | CLINK Debit (payment authorization) |
| 30078 | Machine Status (replaceable) | | 21003 | CLINK Manage (offer management) |
| 30078 | Service Beacon (replaceable, service discovery) |
| 30079 | Transaction Record (replaceable) | | 30079 | Transaction Record (replaceable) |
## Security Priorities ## Security Priorities