docs: purge stale lamassu naming; fix the hal-check skill's provenance boundary
- @lamassu/clink import examples → @bitSpire/clink, the package's real name. - machine-installation.md: the service user is `bitspire`, not `lamassu` (renamed in configuration.nix long ago; the doc never followed). - README: clone aiolabs/bitspire, not lamassu-next; the fleet sentence claiming batm3/douro run `main` against Lightning.Pub was stale. - nostr-check skill: table headers say bitSpire. - hal-check skill: the boundary is c0b69d1, not v8.1.5 (CLAUDE.md corrected this 2026-07-04; the skill kept asserting the wrong tag), and the "forbidden operations" now reflect the recorded permission — reference over port, name the source commit — plus a rule born of the GTQ window: no value table without a test over it. Deliberately kept: every `aiolabs/lamassu-next#NN` issue citation, the provenance sections, "Ported from lamassu-machine" driver headers, and the hardware names "Lamassu Sintra/Tejo/Douro" — those are the machines.
This commit is contained in:
parent
6524cad7a8
commit
723553522c
6 changed files with 26 additions and 26 deletions
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
## Purpose
|
||||
|
||||
Validate HAL driver implementations in `packages/hal/` against published hardware protocol specs (JCM ID003, Fujitsu F56 DLE/STX, Puloon LCDM, MEI EBDS, etc.) and against the v8.1.5 release line of `lamassu-machine` — which is the **last** lamassu-machine release published under a fully-open license.
|
||||
Validate HAL driver implementations in `packages/hal/` against published hardware protocol specs (JCM ID003, Fujitsu F56 DLE/STX, Puloon LCDM, MEI EBDS, etc.) and against the public-domain tree of `lamassu-machine` (commit `c0b69d1` and earlier) — which is the **last** lamassu-machine release published under a fully-open license.
|
||||
|
||||
> **Provenance boundary.** Drivers in `packages/hal/` derive from `lamassu-machine` at v8.1.5 and earlier (plus hardware-vendor protocol specs). Lamassu Industries AG transitioned to a proprietary source-available license on 2024-01-26 with v8.1.6+ gated behind a paid Operator Support Agreement. **Do not** reference, port, or diff against v8.1.6+ — the only safe upstream tree for porting is `v8.1.5` or earlier. See [CLAUDE.md → Provenance + legal status](../../CLAUDE.md#provenance--legal-status) for the operating rules.
|
||||
> **Provenance.** Drivers in `packages/hal/` derive from `lamassu-machine` up to commit `c0b69d1` (2023-09-19, v8.6.0-beta.9), the last public-domain commit; `a9234d124d` added Lamassu's Appendix A licence the same day, so every 8.1.5+ *tag* is proprietary — the old "v8.1.5 is the boundary" was wrong. Since 2026-10-09 we hold permission to use the post-boundary code as prior art too (see CLAUDE.md → Provenance): reference over port, and name the source commit when a block is ported verbatim.
|
||||
|
||||
> **Language note.** ADR-001 selected TypeScript-in-Electron over Rust-in-Tauri for the HAL. Earlier versions of this skill referenced Rust patterns; that's obsolete. All checks below are TypeScript-flavored.
|
||||
|
||||
|
|
@ -16,7 +16,7 @@ Validate HAL driver implementations in `packages/hal/` against published hardwar
|
|||
|
||||
Commands:
|
||||
|
||||
- `port` — Validate that a driver matches its lamassu-machine v8.1.5 reference (where the driver was ported from one)
|
||||
- `port` — Validate that a driver matches its lamassu-machine reference (`c0b69d1` tree unless the port names a later commit) (where the driver was ported from one)
|
||||
- `protocol` — Check protocol implementation against published vendor specs
|
||||
- `safety` — Type safety, error handling, hardware safety review
|
||||
- `mock` — Validate mock implementation completeness
|
||||
|
|
@ -31,9 +31,9 @@ Drivers:
|
|||
|
||||
### Source reference
|
||||
|
||||
Each TS driver in `packages/hal/` maps to (at most) one JS source in lamassu-machine v8.1.5 (the last fully-open release):
|
||||
Each TS driver in `packages/hal/` maps to (at most) one JS source in lamassu-machine at `c0b69d1` (the last public-domain commit):
|
||||
|
||||
| TS Driver | JS Source (v8.1.5 release tree) |
|
||||
| TS Driver | JS Source (`c0b69d1` tree) |
|
||||
|---|---|
|
||||
| `validators/id003/*.ts` | `lib/id003/*.js` |
|
||||
| `validators/ccnet/*.ts` | `lib/ccnet/*.js` |
|
||||
|
|
@ -156,7 +156,7 @@ function buildPacket(data: Uint8Array): Uint8Array {
|
|||
Against the v8.1.5 JS reference (line numbers may vary by tag):
|
||||
|
||||
```javascript
|
||||
// lamassu-machine v8.1.5 — lib/id003/id003rs232.js
|
||||
// lamassu-machine c0b69d1 — lib/id003/id003rs232.js
|
||||
function buildPacket(data) {
|
||||
const buf = Buffer.alloc(data.length + 4)
|
||||
buf[0] = 0x02 // SYNC
|
||||
|
|
@ -234,6 +234,6 @@ A discrepancy here (different CRC polynomial, different framing, different endia
|
|||
|
||||
## Forbidden operations
|
||||
|
||||
- Diff or read `lamassu-machine` source at v8.1.6 or later. Only `v8.1.5` (and the historical commit range leading up to it) is permissible to reference.
|
||||
- "Backport" any fix or feature from v8.1.6+ JS sources into TypeScript. If a bug fix is needed, implement from the protocol spec or hardware traces.
|
||||
- Port a post-`c0b69d1` block without naming its source commit in the commit message. The permission to reference that code is recorded in CLAUDE.md; the provenance of anything carried over must be recoverable from `git log`.
|
||||
- Copy a value table (note lengths, timings) without a test over it — `bills.ts` carried a wrong GTQ window for months precisely because nothing asserted it.
|
||||
- Include attribution comments pointing at v8.1.6+ files even if the implementation is your own — readers should be able to trust file-header attributions as accurate.
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ Where `target` can be:
|
|||
## Relevant NIPs for bitSpire
|
||||
|
||||
### Core NIPs (Must Implement)
|
||||
| NIP | Description | Usage in Lamassu |
|
||||
| NIP | Description | Usage in bitSpire |
|
||||
|-----|-------------|------------------|
|
||||
| NIP-01 | Basic protocol | Event structure, relay communication |
|
||||
| NIP-19 | bech32 entities | npub, nsec, nprofile encoding |
|
||||
|
|
@ -26,7 +26,7 @@ Where `target` can be:
|
|||
| NIP-59 | Gift wrapping | Anonymous message delivery |
|
||||
|
||||
### Application NIPs
|
||||
| NIP | Description | Usage in Lamassu |
|
||||
| NIP | Description | Usage in bitSpire |
|
||||
|-----|-------------|------------------|
|
||||
| NIP-17 | Private DMs | Receipt delivery |
|
||||
| NIP-47 | Nostr Wallet Connect | Potential wallet integration |
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
A Nostr-native Lightning ATM. KYC-free, open source, auditable. Talks to its Lightning backend over the nostr-native-transport (kind-21000 NIP-44 v2) on a relay — never HTTP — so the kiosk has no admin tokens to leak and no API surface to attack.
|
||||
|
||||
> Originally `lamassu-next`. Renamed during the LNbits-backend transition on the `dev` branch (commits leading up to 2026-05-13). Production ATMs (`batm3`, `douro`) still run from `main` against Lightning.Pub until cutover; this README describes the `dev` branch state.
|
||||
> Originally `lamassu-next`. Renamed during the LNbits-backend transition on the `dev` branch (commits leading up to 2026-05-13). Every live machine now runs `dev` against LNbits; `main` is the Lightning.Pub-era history (see CLAUDE.md → Branch model).
|
||||
|
||||
## What the ATM actually does
|
||||
|
||||
|
|
@ -26,8 +26,8 @@ The `nostrrelay` extension inside LNbits is what the ATM connects to — there i
|
|||
|
||||
```bash
|
||||
# 1. Clone
|
||||
git clone ssh://forgejo@git.atitlan.io/aiolabs/lamassu-next.git
|
||||
cd lamassu-next # repo name kept for now — rename to bitSpire is a follow-up
|
||||
git clone ssh://forgejo@git.atitlan.io/aiolabs/bitspire.git
|
||||
cd bitspire
|
||||
git checkout dev
|
||||
|
||||
# 2. Enter the dev environment
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ noffer1<bech32-encoded-data>
|
|||
The ATM wants to receive payment from a customer:
|
||||
|
||||
```typescript
|
||||
import { encodeNoffer } from '@lamassu/clink'
|
||||
import { encodeNoffer } from '@bitSpire/clink'
|
||||
|
||||
// ATM creates a noffer for receiving payment
|
||||
const noffer = encodeNoffer({
|
||||
|
|
@ -134,7 +134,7 @@ ndebit1<bech32-encoded-data>
|
|||
The ATM wants to pay the customer (customer inserted cash, wants Bitcoin):
|
||||
|
||||
```typescript
|
||||
import { encodeNdebit, formatNdebitUri } from '@lamassu/clink'
|
||||
import { encodeNdebit, formatNdebitUri } from '@bitSpire/clink'
|
||||
|
||||
// ATM creates an ndebit for the customer to authorize withdrawal
|
||||
const ndebit = encodeNdebit({
|
||||
|
|
@ -438,14 +438,14 @@ import {
|
|||
CLINKClient,
|
||||
createOfferSuccess,
|
||||
createOfferError,
|
||||
} from '@lamassu/clink'
|
||||
} from '@bitSpire/clink'
|
||||
```
|
||||
|
||||
### Reference Implementation
|
||||
|
||||
- [CLINK Protocol Spec](https://github.com/shocknet/clink)
|
||||
- [Lightning.Pub](https://github.com/shocknet/Lightning.Pub)
|
||||
- [@lamassu/clink](../packages/clink/) - TypeScript implementation
|
||||
- [@bitSpire/clink](../packages/clink/) - TypeScript implementation
|
||||
|
||||
## Related NIPs
|
||||
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ Conceptually:
|
|||
| Layer | Source | Purpose |
|
||||
|---|---|---|
|
||||
| **Kernel + initrd** | `nixpkgs` 24.11 + `upboard.nix` initrd modules | Boot the Sintra hardware (eMMC via `sdhci-acpi`, validator/dispenser at `ttyJ5`/`ttyJ7`) |
|
||||
| **NixOS base** | `nixpkgs` 24.11 | systemd, Xorg, openbox, the `lamassu` user, sshd for provisioning |
|
||||
| **NixOS base** | `nixpkgs` 24.11 | systemd, Xorg, openbox, the `bitspire` user, sshd for provisioning |
|
||||
| **bitspire.service** | `deploy/nixos/bitspire-atm.nix` | systemd unit that launches the Electron kiosk |
|
||||
| **The Electron app** | `apps/machine` built into a nix derivation | The actual ATM UI + state machine + Lightning client |
|
||||
| **Hardware-specific config** | `deploy/nixos/hardware/upboard.nix` (or `douro.nix`, `batm3.nix`) | udev rules, kernel modules, panel calibration |
|
||||
|
|
@ -82,11 +82,11 @@ Before flashing a Sintra you'll want:
|
|||
|
||||
Once the kiosk is up, useful things to know:
|
||||
|
||||
- **Service status:** `ssh lamassu@<atm> 'sudo systemctl status bitspire'`
|
||||
- **Live log tail:** `ssh lamassu@<atm> 'sudo journalctl -u bitspire -f'`
|
||||
- **Service status:** `ssh bitspire@<atm> 'sudo systemctl status bitspire'`
|
||||
- **Live log tail:** `ssh bitspire@<atm> 'sudo journalctl -u bitspire -f'`
|
||||
- **Re-provision (e.g., wrong relay URL):** rerun `provision-atm.sh` from the dev box with the new env vars
|
||||
- **Push a code change without reflashing:** `nixos-rebuild switch --flake .#sintra-installed --target-host lamassu@<atm> --use-remote-sudo`
|
||||
- **Inspect transaction history:** `ssh lamassu@<atm> 'sudo bash /etc/nixos/atm-transactions.sh'` (queries `/var/lib/bitspire/state.db`)
|
||||
- **Push a code change without reflashing:** `nixos-rebuild switch --flake .#sintra-installed --target-host bitspire@<atm> --use-remote-sudo`
|
||||
- **Inspect transaction history:** `ssh bitspire@<atm> 'sudo bash /etc/nixos/atm-transactions.sh'` (queries `/var/lib/bitspire/state.db`)
|
||||
|
||||
## Related documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -139,7 +139,7 @@ export const NDEBIT_REGEX = new RegExp(
|
|||
|
||||
```typescript
|
||||
// In lib/types/parse.ts
|
||||
import type { DebitPointer } from '@lamassu/clink'
|
||||
import type { DebitPointer } from '@bitSpire/clink'
|
||||
import type { Satoshi } from './units'
|
||||
|
||||
export enum InputClassification {
|
||||
|
|
@ -159,7 +159,7 @@ export interface ParsedNdebitInput {
|
|||
|
||||
```typescript
|
||||
// In lib/parse.ts
|
||||
import { decodeNdebit } from '@lamassu/clink'
|
||||
import { decodeNdebit } from '@bitSpire/clink'
|
||||
|
||||
// Add to VALIDATORS array:
|
||||
{
|
||||
|
|
@ -209,7 +209,7 @@ case InputClassification.NDEBIT: {
|
|||
```typescript
|
||||
// In State/scoped/backups/sources/history/claimNdebitThunk.ts
|
||||
import { getNostrClient } from '@/Api/nostr'
|
||||
// Note: SendNdebitRequest is wallet-side code, not part of @lamassu/clink
|
||||
// Note: SendNdebitRequest is wallet-side code, not part of @bitSpire/clink
|
||||
// This example shows the wallet's implementation pattern
|
||||
import { finalizeEvent } from 'nostr-tools'
|
||||
import { SimplePool } from 'nostr-tools'
|
||||
|
|
@ -849,7 +849,7 @@ See "Single-Use Protection" section above for implementation details.
|
|||
|
||||
```json
|
||||
{
|
||||
"@lamassu/clink": "workspace:*",
|
||||
"@bitSpire/clink": "workspace:*",
|
||||
"nostr-tools": "^2.x.x",
|
||||
"@noble/hashes": "^1.x.x",
|
||||
"qrcode": "^1.x.x"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue