DamageBDD Nostr Integration: Identities, Events and Verification

Share a result with an identity attached

A service can publish a useful status message without making that message easy to verify. Who announced the result? Which run does it describe? Where can another participant inspect the report?

Nostr represents messages as signed events exchanged through relays. An event's public key identifies its signing key, and its content and tags can carry references to other records. For DamageBDD, that offers a way to share a behaviour result together with the feature, report and release it describes.

The repository includes identity-backed clients, event construction and signing, publishing and retrieval helpers, relay configuration and dedicated remote-signing components. Applications can build on those interfaces while keeping signing authority, transport and test execution as explicit choices.

The September bunker acceptance report covers a particular remote-signing deployment. It is useful evidence for that path, rather than a general test of every posting, payment or retrieval helper listed below.

Identity and process model

damage_nostr:start_link/1 takes a secrets-store reference. Initialisation retrieves the stored NSEC, derives the public key and registers the process through gproc under that reference. The node's live acceptance client uses damage_nostr_nsec; it does not create a new identity on every test run.

The general client keeps signing material in its process state. That must be distinguished from using the dedicated bunker to sign under a separate policy and vault boundary. Calling a general Nostr helper does not automatically route all signing through nsecbunker.

The client identity, the remote signer identity and the event-signing identity also have distinct roles. They may coincide in a particular configuration, but applications should record what each returned public key identifies. The LodgeiT suite explicitly checks that its test client differs from the bunker identity.

Find the interface you need

Area Representative exported API Interpretation
Process lifecycle start_link/1, stop/1 Start or stop an identity-backed client
Public identity service_pubkey_hex/0, public_key_hex/0 Obtain public identity information
Events construct_event/5, finalize_event/2, create_signed_event/3 Build or sign event structures
Publishing post_note/2,4, post_bdd/1,2 Application posting entry points
Retrieval get_posts_since/2,3, get_metadata/2, fetch_event_by_id/2 Query event or profile information
Discovery get_nostr_json/0 Build the NIP-05 mapping used by the web layer
Zap support parse_zap_request/1, construct_zap_receipt/5 Parse or construct payment-related events
Remote signing helpers parse_nostrconnect_uri/1, nip46_send/3 Low-level remote-signing support
Relay setup configured_relays/0, open_relay_ws/2 Resolve configuration and open a connection

This is a code inventory, not a conformance certificate. Call signatures, process registration and configuration must match the deployed release.

When configuring a client, check the identity reference expected by its caller: post_bdd/1,2 looks up nostr_nsec, while the live bunker test uses damage_nostr_nsec. An integration must provision/start the expected process or deliberately update that path. The successful bunker suite does not test that posting helper's registration choice.

Relay configuration and transport

configured_relays/0 reads the damage application setting nostr_relays, then normalises entries. If no non-empty list exists it uses the module's defaults. Entries can carry URL, profile and proxy choices. This is more specific than the older admin page's single nostr_relay example; read the implementation used by the installed release when configuring it.

The bunker separately loads relays through its running nsecbunker configuration. An operator should inspect both paths rather than assume that changing one setting changes every client. damage_nostr:configured_relays/0 is useful for inspecting the general client's resolved configuration; bunker readiness and relay adapter status are separate observations.

Relay scoring and profiles in the source guide connection attempts. They are not live service-level measurements. Public relay acceptance can vary by event kind, authentication policy, source network and current service state. The reliability article explains why the acceptance suite checks actual publication, ingress and a correlated response.

Linking behaviour verification to events

Nostr provides an identity and communication surface for a verification workflow. DamageBDD supplies the feature, its execution and the resulting evidence. A useful application can associate an event with the feature CID, report CID and run identifier so another participant can inspect the exact claim and its result.

The existing node-admin documentation describes Nostr-triggered BDD handling. That workflow must still define caller authorisation, resource budgets and result correlation. Receiving a signed event identifies a key; it does not by itself authorise arbitrary feature execution or spending.

Similarly, a signed success announcement does not prove the feature passed. The reader needs the referenced result, the feature that was executed and the release identity. The source and run identifiers are the bridge between a message and reproducible evidence.

Lightning and adjacent helpers

The general client registers for Core Lightning invoice-paid events. Its receipt path parses an invoice description as a zap request, constructs a receipt, signs it and attempts publication. Exported functions also cover wallet-connect payload encoding/decoding and reporting events.

Those paths are outside the recorded bunker acceptance run. The module alone does not establish a complete wallet-connect service, successful payment settlement, all zap validation conditions or full reporting interoperability. A payment demonstration needs its own invoice, settlement and event-correlation evidence.

Blossom and ECAI have similarly separate boundaries. A signed event can refer to a file or a retrieved source, but Nostr authentication does not itself make that content confidential or its statements correct.

Give a consumer enough context to check the result

Whether the reader is a person or an automated client, keep the same core references together: the event ID and author, the feature and report IDs, the execution outcome and the release identity. This makes it possible to follow an announcement back to the observation it describes.

For a first integration, use a non-sensitive report and retrieve it through a second client. Check the event's signature and compare the report with the expected run. Treat missing attachments, refused execution and a failed test as distinct outcomes that remain visible to the reader.

The recorded bunker run covers encrypted ping/pong, public-key retrieval, restricted signing, rejection cases and audit correlation. General posting, payment and media workflows need their own acceptance scenarios.

Explore the implementation