aiolabs/satmachineadmin

Fork 0

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

New issue

Closed

opened 2026-06-02 09:09:37 +00:00 by padreug · 1 comment

padreug commented

2026-06-02 09:09:37 +00:00

Owner

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/satmachineadmin#17 (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/satmachineadmin#17 — 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/satmachineadmin#17 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

## 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/satmachineadmin#17` (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/satmachineadmin#17` — 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/satmachineadmin#17` 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`

padreug referenced this issue from a commit

2026-06-13 07:28:15 +00:00

docs(security-pathway): flag kind:21001 CLINK collision + rotation

padreug referenced this issue from aiolabs/spirekeeper

2026-06-14 07:08:48 +00:00

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

padreug commented

2026-06-14 07:09:47 +00:00

Author

Owner

➡️ Migrated to aiolabs/spirekeeper#20 (aiolabs/spirekeeper#20).

The v2-bitspire line of this extension now lives in its own repo, aiolabs/spirekeeper. Tracking for this issue continues there; closing here. (Issue numbers were reassigned in the new repo.)

➡️ **Migrated to https://git.atitlan.io/aiolabs/spirekeeper/issues/20 (aiolabs/spirekeeper#20).** The v2-bitspire line of this extension now lives in its own repo, `aiolabs/spirekeeper`. Tracking for this issue continues there; closing here. (Issue numbers were reassigned in the new repo.)

padreug closed this issue

2026-06-14 07:09:48 +00:00

No labels

No milestone

No project

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/satmachineadmin#44

No description provided.

Rows
Columns