Padreug 53b0d382e8 docs: finish the LNbits-era doc sweep across docs/ + .claude/skills/

Second + final batch of the doc refresh. README + CLAUDE went out in
8c9ae29; deploy/nixos/README + obsolete-flow flags in 924844f. This
commit covers everything left.

docs/machine-installation.md
  Was describing a manual AppImage scp deploy + a `lamassu-kiosk`
  systemd unit that hasn't been the deployment path for months.
  Replaced with a high-level "what the pipeline does and why"
  overview that points at deploy/nixos/README.md for the full
  command-by-command walkthrough. Includes the BATM3 chassis-mod
  note (custom Dell OptiPlex retrofit, not a stock Dell).

docs/architecture-comparison.md
  Rewrote the comparison to be lamassu-server (≤ v8.1.5) vs bitSpire
  (LNbits-backed) instead of the original lamassu-server vs LP-backed
  lamassu-next framing. Updated the cash-out + cash-in flow diagrams
  to show the actual nostr-transport path (LNbits-bundled nostrrelay
  extension at ws://<host>:5001/nostrrelay/test, no separate strfry
  container). Replaced the migration-path section with a softer
  "when to choose what" framing that includes Lamassu's current
  commercial offering as a legitimate third option. Added a header
  pointer to the Acknowledgements section.

docs/business-model.md
  Light touch-ups: Lightning.Pub → LNbits where it appeared, swapped
  the [[ndebit-cash-in-flow]] link for [[architecture-comparison]],
  noted the kind-30078 service beacon for availability broadcasts.

docs/device-configuration.md
  Dropped "Lamassu" branding from the machine-model headings
  (Sintra / tejo / douro / batm3 are referenced by hardware identity
  here, not by Lamassu's product line). Added the Sintra-specific
  ttyS4-vs-placeholder-ttyS1..3 gotcha we hard-learned during the
  first flash. Corrected the BATM3 entry: stock GeneralBytes chassis
  with a Dell OptiPlex 9030 AIO motherboard physically grafted in,
  NOT a Dell out of the box. Updated the example /dev/ttyJ* symlink
  output to match what a healthy Sintra actually shows.

docs/adr/001-hal-architecture.md
  ADRs are historical artifacts — kept the original decision text
  intact. Added a postscript noting:
    - The package rename @lamassu/hal → @bitSpire/hal
    - The v8.1.5 boundary on any lamassu-machine source-tree
      references (Lamassu's 2024-01-26 license transition)
    - That the "Remaining Work" list is complete and the first
      successful Sintra hardware integration ran on 2026-05-13

.claude/skills/lightning-check.md
  Rewrote end-to-end. Was Lightning.Pub-flavoured with CLINK kinds
  21001/21002 as the primary flows; now validates the LNbits nostr-
  transport surface (kind-21000 envelope, NIP-44 v2 encryption,
  subscribe_payments filter discipline, lnurlw link composition).
  Preserved a --clink mode for the still-live kind-21003 operator-
  management surface. Includes a "what to check" rubric for cash-out
  vs cash-in flows that mirrors the actual code in
  apps/machine/src/services/lightning.ts.

.claude/skills/hal-check.md
  Two pivots: (1) acknowledge ADR-001's TypeScript-not-Rust choice
  and reframe all the safety checklists in TS-flavour (type safety,
  discriminated unions, single-writer serial, bounded emitters)
  instead of Rust-flavour (unsafe, borrow checker). (2) Add explicit
  v8.1.5 provenance boundary plus a "forbidden operations" section
  that prohibits diffing or porting from v8.1.6+ lamassu-machine
  source. Updated the port-validation source-reference table to
  list TS file paths under packages/hal/ instead of Rust paths.

.claude/skills/docs.md
  @lamassu/* → @bitSpire/*. Replaced the Lightning.Pub mermaid
  diagram with a current cash-out flow showing the nostr-transport
  RPC + subscribe_payments push path. Left the createOffer noffer
  example in the API-docs template section since it's illustrative
  ("here's what a good TSDoc block looks like") rather than current
  reference documentation.

.claude/skills/test.md
  One-line: @lamassu/nostr-client → @bitSpire/nostr-client in the
  pnpm-filter example.

deploy/nixos/README.md
  Single touch-up: clarified the douro/batm3 hardware-module comments
  to reflect that BATM3 is a custom-installed Dell board in a
  GeneralBytes BATM3 chassis (not a Dell OEM).

Files NOT touched in this sweep (intentionally):
  - packages/hal/src/**/*.ts attribution comments — those reference
    "lamassu-machine" in their port-source headers. Those are
    factually accurate (the drivers ARE ported from there, up to
    v8.1.5) and constitute necessary license/attribution metadata.
    Editing them would erase the provenance trail.
  - .claude/skills/{nostr-check,security}.md — already protocol-
    neutral, no LP/lamassu references to clean up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-06-01 19:08:03 +02:00

4.8 KiB

Raw Permalink Blame History

Business Model

How we place ATMs at locations and make them sustainable for everyone involved.

Principles

No KYC — more users, less friction, preserves privacy
Good energy locations — we seek places with community trust and genuine intent
Bitcoin-native infrastructure — Lightning, Nostr, Cashu — no legacy payment rails
Operator sovereignty — locations can choose how much they want to manage themselves

Deployment Models

Managed (we run it)

We own the machine and handle all operations. The location provides power, internet, and floor space.

Aspect	Details
Machine ownership	Us
Liquidity	Our Lightning channels + cash servicing
Software updates	Us (remote via Nostr)
Cash management	Us (periodic servicing visits)
Fee configuration	Us
Revenue to location	Fixed monthly hosting fee OR % of tx fees

Best for locations that want passive income with zero involvement.

Self-Sovereign (they run it)

The location buys (or finances) the machine and runs their own stack.

Aspect	Details
Machine ownership	Them
Liquidity	Their own Lightning node + LNbits
Software updates	Them (we provide releases)
Cash management	Them
Fee configuration	Them
Revenue	100% theirs

Best for bitcoiners who want to run infrastructure and keep full control. We provide the software, hardware, and support.

Machine Financing

For the self-sovereign model, we can offer financing:

We purchase the machine upfront
Location pays it off over time (from ATM revenue)
Once paid off, they own it outright
We provide support during the financing period

Revenue Models

Fixed Hosting Fee

We pay the location a flat monthly fee for hosting
Simpler accounting, predictable income for location
We take all transaction fee revenue
Works well for locations that just want passive income

Location receives a % of transaction fees
Aligns incentives — they benefit from higher volume
More attractive to engaged locations
Requires transparent reporting (could be on-chain/Nostr-verifiable)

Foot Traffic Value

Beyond direct revenue, the ATM provides:

People visit specifically to use the ATM, then browse/buy at the location
Bitcoin-friendly branding signals to the community
Conversation starter — draws curious newcomers
Community hub potential — meetup anchor point

Location Criteria

We're selective about where we place machines. The goal is to find locations with good energy — places where the community is genuine and the environment discourages misuse.

Ideal locations

Coffee shops, cafes, local restaurants
Co-working spaces, maker spaces
Bitcoin meetup venues, hackerspaces
Surf shops, yoga studios, wellness centers
Local/independent businesses (not chains)
Places where the owner is curious about or already into Bitcoin

What we look for

Owner alignment — understands or wants to understand Bitcoin
Community trust — regulars know each other, self-policing
Foot traffic — enough people to make the machine worthwhile
Stable internet + power
Visible but not exposed — inside the business, not on the street

What we avoid

High-crime areas
Anonymous/transient locations (gas stations on highways, etc.)
Businesses with no community connection
Anywhere the owner is purely financially motivated with no alignment

Technical Requirements

For the managed model to work at scale, we need:

Remote monitoring — machine status, cash levels, error alerts over nostr (kind-30078 service beacons + kind-21003 management commands)
Operator dashboard — manage cassettes, view transactions, update config remotely (planned)
Multi-machine support — one LNbits instance can host wallets for many ATMs; each ATM auto-creates its own wallet from its nostr pubkey
Fee configuration — per-machine fee % set by operator
Availability broadcast — public kind-30078 events indicating cash-in/cash-out availability and reserves

device-configuration — hardware setup for different machine models
machine-installation — deployment overview for ATM hardware
Deploy/NixOS README — full deployment walkthrough
architecture-comparison — bitSpire vs traditional lamassu-server

4.8 KiB Raw Permalink Blame History