Padreug
53b0d382e8
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>
121 lines
4.8 KiB
Markdown
121 lines
4.8 KiB
Markdown
# 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
|
|
|
|
### Profit Sharing
|
|
|
|
- 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
|
|
|
|
## Related
|
|
|
|
- [[device-configuration]] — hardware setup for different machine models
|
|
- [[machine-installation]] — deployment overview for ATM hardware
|
|
- [Deploy/NixOS README](../deploy/nixos/README.md) — full deployment walkthrough
|
|
- [[architecture-comparison]] — bitSpire vs traditional lamassu-server
|