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

Rotate settlement-receipt event kind off 21001 (CLINK Offers collision) #20

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

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

Summary

The Nostr event kind chosen for settlement-receipt events — locked to kind:21001 in the design ratified across aiolabs/lnbits#22 (producer) and aiolabs/spirekeeper#11 (consumer) — conflicts directly with the CLINK Offers spec, which has claimed kind:21001 for its Offer Request / Offer Response events.

Discovery happened on 2026-06-02 while reviewing CLINK in detail for forward-looking ATM cash-in/cash-out adoption. The original kind selection (2026-05-26) predated our exposure to CLINK's allocation table.

The collision

CLINK's three sub-protocols claim:

kind CLINK protocol Spec
21001 Offers (Offer Request/Response) refs/repos/nostr/shocknet/CLINK/specs/clink-offers.md
21002 Debits (Debit Request/Response) clink-debits.md
21003 Manage (Management Delegation) clink-manage.md

CLINK events carry a mandatory ["clink_version", "1"] tag, so well-behaved CLINK consumers will filter our settlement receipts out by absence-of-tag. But:

  • On-the-wire, both event types occupy the same kind — relays carry them together, our subscribers see CLINK Offers traffic they have to filter out, and CLINK subscribers see our settlement receipts they have to filter out.
  • We plan to adopt CLINK for cash-in (Debits) and cash-out (Offers) at the ATM. Maintaining a same-kind collision while we're also consumers of CLINK is the wrong posture.
  • CLINK may add resource types in adjacent kinds (21010, 21020, …). Squatting in the same band makes us a worse Nostr citizen and a worse CLINK collaborator.

The rotation

Per the workspace-level rule documented in ~/dev/CLAUDE.md → "Nostr kind allocations — avoid the CLINK band":

Rule: aiolabs-specific kind:21001–kind:21099 is OFF-LIMITS.

Suggested aiolabs band: 22000–22099 for non-replaceable application events specific to our stack (settlement receipts, fee-policy broadcasts that don't fit kind:30078 replaceable semantics, etc.).

Recommended kind selection (pick one, document the choice in this issue body once decided):

  • 22001 — settlement-receipt events (per-tx fact stating "this payment_hash settled with these business-direction totals")

Other 22xxx allocations can be claimed incrementally as we add new event types. Each allocation should be added to the workspace doc's allocations table.

Affected code & issues

Blocked by this rotation (will need to land before either ships):

  • aiolabs/lnbits#22 — producer-side: lnbits-instance publishes signed settlement-receipt events.
  • aiolabs/spirekeeper#11 — consumer-side: subscription + reconciliation.

Not affected (separate namespace):

  • Kind:30078 NIP-78 replaceable events (fee_config, cassette state, fleet roster) live in a different range and don't overlap with CLINK. Continue as-is.
  • Existing kind:21000 nostr-transport RPCs (aiolabs/lnbits core) are NOT in conflict — CLINK explicitly notes 21000 is unclaimed by CLINK and our adjacency choice there stands.

Action items

  • Pick the canonical replacement kind (recommendation: 22001 for settlement receipts).
  • Update aiolabs/lnbits#22 issue body + any draft code to use the new kind.
  • Update aiolabs/spirekeeper#11 issue body + any draft code to use the new kind.
  • Add the allocation to ~/dev/CLAUDE.md's kind-allocations subsection (a running table of aiolabs-claimed 22xxx kinds + their purposes).
  • Cross-check that no other in-flight design currently uses kind:21001 for aiolabs purposes (the relevant memory in this repo was updated to flag the supersession on 2026-06-02; check coord log entries and any open PRs for the same number).

Cross-references

  • Memory note: ~/.claude/projects/-home-padreug-dev-shared-extensions-satmachineadmin/memory/feedback_nostr_kind_allocations.md
  • Original (now superseded) kind:21001 rationale: feedback_respect_nostr_protocol_semantics.md
  • Coord log archive: ~/dev/coordination/archive/2026-05-31-pre-rotation.md:511 (the 2026-05-26 lock)
  • Workspace rule: ~/dev/CLAUDE.md → "Nostr kind allocations — avoid the CLINK band"
  • CLINK primer prepared 2026-06-02: ~/Documents/clink-primer/clink-primer.pdf
> _Migrated from aiolabs/satmachineadmin#44 (2026-06-13). Issue numbers were reassigned in this repo; cross-refs updated._ ## Summary The Nostr event kind chosen for settlement-receipt events — locked to **`kind:21001`** in the design ratified across `aiolabs/lnbits#22` (producer) and `aiolabs/spirekeeper#11` (consumer) — **conflicts directly with the CLINK Offers spec**, which has claimed `kind:21001` for its Offer Request / Offer Response events. Discovery happened on 2026-06-02 while reviewing CLINK in detail for forward-looking ATM cash-in/cash-out adoption. The original kind selection (2026-05-26) predated our exposure to CLINK's allocation table. ## The collision CLINK's three sub-protocols claim: | kind | CLINK protocol | Spec | |---|---|---| | `21001` | Offers (Offer Request/Response) | `refs/repos/nostr/shocknet/CLINK/specs/clink-offers.md` | | `21002` | Debits (Debit Request/Response) | `clink-debits.md` | | `21003` | Manage (Management Delegation) | `clink-manage.md` | CLINK events carry a mandatory `["clink_version", "1"]` tag, so well-behaved CLINK consumers will filter our settlement receipts out by absence-of-tag. But: - On-the-wire, both event types occupy the same kind — relays carry them together, our subscribers see CLINK Offers traffic they have to filter out, and CLINK subscribers see our settlement receipts they have to filter out. - We **plan to adopt CLINK** for cash-in (Debits) and cash-out (Offers) at the ATM. Maintaining a same-kind collision while we're also consumers of CLINK is the wrong posture. - CLINK may add resource types in adjacent kinds (21010, 21020, …). Squatting in the same band makes us a worse Nostr citizen and a worse CLINK collaborator. ## The rotation Per the workspace-level rule documented in `~/dev/CLAUDE.md` → "Nostr kind allocations — avoid the CLINK band": > **Rule: aiolabs-specific kind:21001–kind:21099 is OFF-LIMITS.** > > **Suggested aiolabs band: 22000–22099** for non-replaceable application events specific to our stack (settlement receipts, fee-policy broadcasts that don't fit kind:30078 replaceable semantics, etc.). **Recommended kind selection** (pick one, document the choice in this issue body once decided): - `22001` — settlement-receipt events (per-tx fact stating "this payment_hash settled with these business-direction totals") Other 22xxx allocations can be claimed incrementally as we add new event types. Each allocation should be added to the workspace doc's allocations table. ## Affected code & issues **Blocked by this rotation** (will need to land before either ships): - `aiolabs/lnbits#22` — producer-side: lnbits-instance publishes signed settlement-receipt events. - `aiolabs/spirekeeper#11` — consumer-side: subscription + reconciliation. **Not affected (separate namespace):** - Kind:30078 NIP-78 replaceable events (fee_config, cassette state, fleet roster) live in a different range and don't overlap with CLINK. Continue as-is. - Existing kind:21000 nostr-transport RPCs (`aiolabs/lnbits` core) are NOT in conflict — CLINK explicitly notes 21000 is unclaimed by CLINK and our adjacency choice there stands. ## Action items - [ ] Pick the canonical replacement kind (recommendation: `22001` for settlement receipts). - [ ] Update `aiolabs/lnbits#22` issue body + any draft code to use the new kind. - [ ] Update `aiolabs/spirekeeper#11` issue body + any draft code to use the new kind. - [ ] Add the allocation to `~/dev/CLAUDE.md`'s kind-allocations subsection (a running table of aiolabs-claimed 22xxx kinds + their purposes). - [ ] Cross-check that no other in-flight design currently uses `kind:21001` for aiolabs purposes (the relevant memory in this repo was updated to flag the supersession on 2026-06-02; check coord log entries and any open PRs for the same number). ## Cross-references - Memory note: `~/.claude/projects/-home-padreug-dev-shared-extensions-satmachineadmin/memory/feedback_nostr_kind_allocations.md` - Original (now superseded) kind:21001 rationale: `feedback_respect_nostr_protocol_semantics.md` - Coord log archive: `~/dev/coordination/archive/2026-05-31-pre-rotation.md:511` (the 2026-05-26 lock) - Workspace rule: `~/dev/CLAUDE.md` → "Nostr kind allocations — avoid the CLINK band" - CLINK primer prepared 2026-06-02: `~/Documents/clink-primer/clink-primer.pdf`
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#20
No description provided.