aiolabs/spirekeeper
8
0
Fork 0
Code Issues 23 Pull requests Projects Releases Packages Wiki Activity Actions

Epic: bitSpire integration & multi-tenant overhaul (v2) #5

New issue
Open
opened 2026-06-14 07:08:41 +00:00 by padreug · 0 comments
padreug commented 2026-06-14 07:08:41 +00:00
Owner
Copy link

Migrated from aiolabs/satmachineadmin#9 (2026-06-13). Issue numbers were reassigned in this repo; cross-refs updated.

Context

The current satmachineadmin extension is superuser-only on a single LNbits instance with one ATM, built against the legacy Lamassu (SSH-tunneled PostgreSQL cash_out_txs polling). The upstream ATM has been rebuilt as bitSpire (aiolabs/lamassu-next dev branch), which is Nostr-native (kind-21000 NIP-44 v2 encrypted RPC between the ATM and LNbits, auto-account-creation from npub, decentralized relay-based discovery). Legacy Lamassu's PostgreSQL is gone.

Three planned-feature streams converge into this overhaul:

  • aiolabs/lamassu-next#22 — LNbits as Nostr-native UI layer (LNbits nostr-transport branch — what we depend on).
  • aiolabs/lamassu-next#42 — Nostr-native operator dashboard + seed-URL onboarding + kind-30079 telemetry.
  • aiolabs/lamassu-next#43 — Enriched kind-30078 beacon (name/location/fees/limits/denominations). Note: not yet shipped (verified on dev commit 2b712af — current payload is only {cash_in, cash_out, cash_level, fiat, model}).
  • aiolabs/lamassu-next#44 — upstream dependency filed as part of this overhaul: carry the principal/commission split end-to-end via Payment.extra on cash-out invoices and LNURL-withdraw links.

Goal

Rebuild Satoshi Machine to support a decentralized network of bitSpire ATMs that can plug into any LNbits instance, with three first-class actors:

  1. Super — LNbits instance admin; sets a global platform-fee % (read-only to operators).
  2. Operator — LNbits user who owns one or more bitSpire machines; installs satmachineadmin; configures the remainder split (after super) across their wallets (self / employee / maintenance fund).
  3. Liquidity Provider (LP) — LNbits user who deposits fiat at machines and receives proportional BTC distributions, aggregated across operators. (Note: LP UI is migrating to ~/dev/webapp, so satmachineclient is in maintenance mode.)

satmachineadmin absorbs the operator dashboard role when an operator is on LNbits — apps/dashboard in lamassu-next becomes the self-host-without-LNbits fallback.

Key design decisions (2026-05-14)

  • Identity: 1 LNbits user = 1 operator. N machines = N wallets, each tagged with the machine's npub. Aggregation native via Payment.tag.
  • Platform fee = two-stage hybrid split: super sets super_fee_pct (read-only to operator). Operator's split rules apply to the remainder (commission_sats * (1 - super_fee_pct)).
    • Example: 100 sats commission, super=30% → 30 sats to super; operator splits remaining 70 sats per their config (e.g. 50/30/20 → 35/21/14 sats).
  • Customer discounts (post-v1): deferred, but v1 schema already stores platform_fee_sats and operator_fee_sats as separate absolute BIGINT values (Stripe Connect pattern) so v2's promo engine ships without a breaking migration.
  • No backwards compatibility: operators on the previous schema must wipe and re-onboard.
  • Branch: v2-bitspire (created from main).

Phased delivery

Phase Scope Gating
P0 Schema (m005) + models + operator-scoped CRUD + stub legacy entry points —
P1 Nostr kind-21000 subscription manager + machine add-by-npub + idempotent settlement landing P0
P2 Two-stage commission split (super → operator-defined remainder) + super-only platform fee endpoint P1
P3 Operator UX: manual tx, partial dispense (#1), balance settlement (#2), abandoned-tx queue P2
P4 Kind-30078 beacon ingestion (degrade gracefully — most fields blocked on lamassu-next#43) P1
P5 Seed-URL onboarding wizard P4 + lamassu-next#42
P6 LP auto-forward (closes #4) P2
P7 satmachineclient maintenance pass (cross-extension reads; README points LP audience to webapp) P2
P8 Kind-30079 telemetry ingestion (read-only) lamassu-next#42

Sub-issues (will be filed phase-by-phase as work picks up)

  • P1: Nostr kind-21000 subscription manager (replaces SSH/PostgreSQL polling)
  • P1: Machine CRUD + add-by-npub + per-operator scoping across all endpoints
  • P2: Two-stage commission split implementation
  • P2: Super-only platform fee config endpoint
  • P3: Partial transaction processing (closes #1)
  • P3: Balance settlement at current rate (closes #2)
  • P3: Abandoned-transaction queue
  • P4: Kind-30078 beacon ingestion (graceful degradation; blocked on aiolabs/lamassu-next#43)
  • P5: Seed-URL machine onboarding wizard (mirrors aiolabs/lamassu-next#42)
  • P6: LP auto-forward to LN address (closes #4)
  • P7: satmachineclient v2 maintenance pass
  • P8: Kind-30079 telemetry ingestion
  • v2: customer discount/promotion engine (post-v1; schema hooks already in m005)

Upstream coordination

  • aiolabs/lamassu-next#42 — fleet management plane, seed-URL onboarding (we mirror the seed-URL design).
  • aiolabs/lamassu-next#43 — beacon enrichment (we ingest opportunistically).
  • aiolabs/lamassu-next#44 — Payment.extra split metadata (eliminates back-derivation).

P0 status — IN PROGRESS on branch v2-bitspire

Commits so far:

  • ae4e241 feat(v2): add m005 satmachine_v2 schema for bitSpire + multi-tenant
  • 013e3d5 feat(v2): rewrite models.py for v2 schema
  • 937749f feat(v2): operator-scoped CRUD + stub legacy entry points

Verified: clean import against LNbits 1.4 nostr-transport; 22/23 tests pass (calculations math suite intact; 1 async-test fail is env-only — pytest-asyncio missing in borrowed venv).

Local plan: ~/.claude/plans/snug-gliding-shamir.md.

> _Migrated from aiolabs/satmachineadmin#9 (2026-06-13). Issue numbers were reassigned in this repo; cross-refs updated._ ## Context The current `satmachineadmin` extension is **superuser-only on a single LNbits instance with one ATM**, built against the legacy Lamassu (SSH-tunneled PostgreSQL `cash_out_txs` polling). The upstream ATM has been rebuilt as **bitSpire** (`aiolabs/lamassu-next` `dev` branch), which is Nostr-native (kind-21000 NIP-44 v2 encrypted RPC between the ATM and LNbits, auto-account-creation from npub, decentralized relay-based discovery). Legacy Lamassu's PostgreSQL is gone. Three planned-feature streams converge into this overhaul: - `aiolabs/lamassu-next#22` — LNbits as Nostr-native UI layer (LNbits `nostr-transport` branch — what we depend on). - `aiolabs/lamassu-next#42` — Nostr-native operator dashboard + seed-URL onboarding + kind-30079 telemetry. - `aiolabs/lamassu-next#43` — Enriched kind-30078 beacon (name/location/fees/limits/denominations). **Note: not yet shipped** (verified on `dev` commit `2b712af` — current payload is only `{cash_in, cash_out, cash_level, fiat, model}`). - `aiolabs/lamassu-next#44` — **upstream dependency** filed as part of this overhaul: carry the principal/commission split end-to-end via `Payment.extra` on cash-out invoices and LNURL-withdraw links. ## Goal Rebuild Satoshi Machine to support a **decentralized network of bitSpire ATMs that can plug into any LNbits instance**, with three first-class actors: 1. **Super** — LNbits instance admin; sets a global platform-fee % (read-only to operators). 2. **Operator** — LNbits user who owns one or more bitSpire machines; installs satmachineadmin; configures the *remainder* split (after super) across their wallets (self / employee / maintenance fund). 3. **Liquidity Provider (LP)** — LNbits user who deposits fiat at machines and receives proportional BTC distributions, aggregated across operators. *(Note: LP UI is migrating to `~/dev/webapp`, so satmachineclient is in maintenance mode.)* satmachineadmin **absorbs the operator dashboard role** when an operator is on LNbits — `apps/dashboard` in lamassu-next becomes the self-host-without-LNbits fallback. ## Key design decisions (2026-05-14) - **Identity**: 1 LNbits user = 1 operator. N machines = N wallets, each tagged with the machine's npub. Aggregation native via `Payment.tag`. - **Platform fee = two-stage hybrid split**: super sets `super_fee_pct` (read-only to operator). Operator's split rules apply to the **remainder** (`commission_sats * (1 - super_fee_pct)`). - Example: 100 sats commission, super=30% → 30 sats to super; operator splits remaining 70 sats per their config (e.g. 50/30/20 → 35/21/14 sats). - **Customer discounts (post-v1)**: deferred, but v1 schema *already* stores `platform_fee_sats` and `operator_fee_sats` as separate absolute BIGINT values (Stripe Connect pattern) so v2's promo engine ships without a breaking migration. - **No backwards compatibility**: operators on the previous schema must wipe and re-onboard. - **Branch**: `v2-bitspire` (created from `main`). ## Phased delivery | Phase | Scope | Gating | |---|---|---| | **P0** | Schema (m005) + models + operator-scoped CRUD + stub legacy entry points | — | | **P1** | Nostr kind-21000 subscription manager + machine add-by-npub + idempotent settlement landing | P0 | | **P2** | Two-stage commission split (super → operator-defined remainder) + super-only platform fee endpoint | P1 | | **P3** | Operator UX: manual tx, partial dispense (#1), balance settlement (#2), abandoned-tx queue | P2 | | **P4** | Kind-30078 beacon ingestion (degrade gracefully — most fields blocked on `lamassu-next#43`) | P1 | | **P5** | Seed-URL onboarding wizard | P4 + `lamassu-next#42` | | **P6** | LP auto-forward (closes #4) | P2 | | **P7** | satmachineclient maintenance pass (cross-extension reads; README points LP audience to webapp) | P2 | | **P8** | Kind-30079 telemetry ingestion (read-only) | `lamassu-next#42` | ## Sub-issues (will be filed phase-by-phase as work picks up) - [ ] P1: Nostr kind-21000 subscription manager (replaces SSH/PostgreSQL polling) - [ ] P1: Machine CRUD + add-by-npub + per-operator scoping across all endpoints - [ ] P2: Two-stage commission split implementation - [ ] P2: Super-only platform fee config endpoint - [ ] P3: Partial transaction processing (closes #1) - [ ] P3: Balance settlement at current rate (closes #2) - [ ] P3: Abandoned-transaction queue - [ ] P4: Kind-30078 beacon ingestion (graceful degradation; blocked on `aiolabs/lamassu-next#43`) - [ ] P5: Seed-URL machine onboarding wizard (mirrors `aiolabs/lamassu-next#42`) - [ ] P6: LP auto-forward to LN address (closes #4) - [ ] P7: satmachineclient v2 maintenance pass - [ ] P8: Kind-30079 telemetry ingestion - [ ] v2: customer discount/promotion engine (post-v1; schema hooks already in m005) ## Upstream coordination - `aiolabs/lamassu-next#42` — fleet management plane, seed-URL onboarding (we mirror the seed-URL design). - `aiolabs/lamassu-next#43` — beacon enrichment (we ingest opportunistically). - `aiolabs/lamassu-next#44` — `Payment.extra` split metadata (eliminates back-derivation). ## P0 status — IN PROGRESS on branch `v2-bitspire` Commits so far: - `ae4e241` feat(v2): add m005 satmachine_v2 schema for bitSpire + multi-tenant - `013e3d5` feat(v2): rewrite models.py for v2 schema - `937749f` feat(v2): operator-scoped CRUD + stub legacy entry points Verified: clean import against LNbits 1.4 `nostr-transport`; 22/23 tests pass (`calculations` math suite intact; 1 async-test fail is env-only — `pytest-asyncio` missing in borrowed venv). Local plan: `~/.claude/plans/snug-gliding-shamir.md`.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
v0.1.3
v0.1.2
v0.1.1
v0.1.0
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
aiolabs/spirekeeper#5
No description provided.