aiolabs/bitspire
9
0
Fork 0
Code Issues 52 Pull requests 2 Projects Releases Packages Wiki Activity Actions

docs: refresh deploy/nixos/README + flag obsolete flow docs

Browse source 
deploy/nixos/README.md was the most-stale doc in the tree: it still
talked about a `lamassu-atm` systemd unit, `/opt/lamassu-atm` paths,
nixos-install with a non-existent `lamassu-atm` flake output, and an
scp-the-built-electron-bundle workflow that hasn't been the deploy
path for many months. Replaced with a rewrite that documents the
actual current pipeline:

  - File layout: bitspire-atm.nix (not lamassu-atm.nix), live.nix,
    hardware/{douro,batm3,upboard}.nix, and the udev / helper scripts
  - Build pipeline: `nix build .#disk-image-<model>` and the four
    flake-output flavours per model (live config, installed config,
    iso, disk-image)
  - Full Sintra walkthrough end-to-end: prep a flashing USB on the
    dev box, boot Alpine live on the Sintra, identify the eMMC,
    dd with count= to skip the trailing USB padding, repair the
    GPT secondary header + grow root with parted, poweroff, boot,
    provision via provision-atm.sh. Every quirk we hit during the
    first real flash is now baked in (mdev for /dev nodes, parted
    Fix prompt, lbu-style notes).
  - Runtime layout cheat-sheet: /var/lib/bitspire/.env (0600
    lamassu:lamassu), state.db, /etc/bitspire/config.env, etc.
  - Common-operations playbook: re-provision, nixos-rebuild switch
    over SSH with --use-remote-sudo (much faster than reflashing),
    journalctl filtering, hardware-side health checks.
  - NixOS module reference for services.bitspire, including the
    LNbits-flavoured options (relayUrl, lnbitsServerPubkey,
    lnbitsHttpUrl) instead of the retired lightningPubUrl.
  - Sintra-specific gotchas section: eMMC-via-sdhci-acpi, the
    ttyS4 dispenser placement, the ttyS1..3 phantom-node issue.
  - Security-notes section updated to reflect passwordless sudo
    enabled for nixos-rebuild deploys, and the implications.

Auto-upgrade behaviour explained explicitly (the ?ref=dev pin) so
contributors understand why production ATMs on main don't pick up
dev branch changes.

docs/ndebit-cash-in-flow.md: added a header banner flagging the
document as historical — cash-in on dev is LNURL-withdraw +
subscribe_payments push, not ndebit. Original content kept as a
reference for any future revival of nostr-native cash-in.

docs/clink-protocol.md: same treatment — flagged as dormant on dev,
explaining which pieces still apply (kind-21003 management) and
which are unused (kinds 21001/21002). Protocol reference content
left intact since the wire format is unchanged upstream.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Padreug 2026-05-14 07:53:38 +02:00
commit 0b94bef4be
3 changed files with 234 additions and 122 deletions
Download patch file Download diff file Expand all files Collapse all files

23
docs/clink-protocol.md
View file

@ -1,5 +1,28 @@
# CLINK Protocol
> **Status on the `dev` branch: dormant.** The `@bitSpire/clink` package
> is still in the workspace, but `apps/machine/src/services/lightning.ts`
> no longer wires its offer/debit/management handlers — those were
> Lightning.Pub-paired and were removed when the backend switched to
> LNbits over the nostr-native-transport. The cash-out flow on dev uses
> BOLT11 + `subscribe_payments({payment_hash})`; the cash-in flow uses
> LNURL-withdraw + `subscribe_payments({tag, link_id})`. Both subsume
> CLINK's role for the ATM use case.
>
> This doc remains as the **protocol reference** — the wire format,
> event kinds, and encoding conventions are unchanged from the upstream
> [CLINK spec](https://github.com/shocknet/clink). Read it if you want
> to understand what kinds 21001-21003 mean, or if you're considering
> re-introducing CLINK flows on dev (e.g., a nostr-native cash-in path
> that doesn't go through LNURL).
>
> The `kind-21003` management surface (operator commands like "manual
> dispense") is the one piece of CLINK still actively wired on dev —
> `clink.onManagement` listens for those events and they have no LP
> dependency, so they survived the migration.
---
CLINK (Custodial Lightning Keys) is a Nostr-based protocol for Lightning payments. It enables wallets and services to communicate payment requests and authorizations through Nostr relays.
## Overview

19
docs/ndebit-cash-in-flow.md
View file

@ -1,5 +1,24 @@
# NDebit Cash-In Flow Implementation Guide
> **Historical reference — NOT the cash-in flow on the `dev` branch.**
>
> Cash-in on `dev` is **LNURL-withdraw + LNbits `subscribe_payments({tag:"withdraw", link_id})` push**, implemented in
> `apps/machine/src/services/lightning.ts → generateLnurlWithdraw()`.
> The ATM no longer renders ndebit URIs; `CashInView.vue` ignores
> `generateNdebit`'s output and shows the LNURL QR instead. The CLINK
> debit-approval listener and all kind-21002 handling were removed in
> commit `3c14eea` (the 3b.4 cleanup of LP-paired infrastructure).
>
> This doc is retained because it explains *why* the previous flow
> existed and what the ndebit/CLINK protocol surface looks like — useful
> if the project ever wants to reintroduce nostr-native cash-in that
> bypasses LNURL. The protocol itself (kinds 21001-21003) is unchanged;
> only our wiring of it has been removed. The `@bitSpire/clink` package
> still ships the encode/decode helpers if a future implementation needs
> them.
---
This document describes how to implement the ndebit scanning flow for ATM cash-in, where a user scans an ndebit QR code from an ATM to withdraw sats to their wallet.
## Overview