Finding Witness Records for OpenETR
Integration model and implementation status
An application can present an OpenETR Anchor Record with a collection of corresponding Witness Records. In this guide, Witness Record is the application-facing name for a relay-signed observation receipt, not a new OpenETR Anchor Event or Publisher Notice.
The relationship is one-to-many: each witness signs its own assertion about observing the exact signed subject. The same approach applies to kind 1416 Publisher Notices, each referenced by its own event ID.
Spurline currently implements service commissioning, witness authorization, signed renewal and revocation, and local suspension. Automatic receipt generation and application trust evaluation remain pending. The frozen experimental kind is 1418; wire/binding checks and a test fixture are implemented in Spurline. The formats and queries below describe the intended integration contract. They do not make an existing OpenETR verifier recognize these records automatically.
Example Witness Record
The outer object is a standard signed event whose author is the witnessing
relay. This schematic uses experimental kind 1418 and placeholder IDs and
signatures. It is not a publishable test vector; see the
frozen profile and fixture for executable wire checks.
This example is version 1. Version 2 instead explicitly
reports unspecified accuracy; its null uncertainty must never be treated as zero.
Queries using the v1 t marker alone exclude v2 receipts. Query by kind and e
reference to discover both, then validate each version explicitly.
{
"id": "<receipt event id>",
"pubkey": "<witness relay hex pubkey>",
"created_at": 1800000002,
"kind": 1418,
"tags": [
["e", "<anchor event id>"],
["p", "<anchor publisher hex pubkey>"],
["k", "1415"],
["t", "spurline-observation-receipt-v1"]
],
"content": "<canonical JSON string of the receipt body below>",
"sig": "<witness relay signature>"
}
The decoded content would look like this. On the wire it is a string encoded with sorted keys and compact JSON separators, not a nested JSON object:
{
"authorization_event_id": "<operator-signed witness authorization id>",
"clock_uncertainty_ms": 1000,
"event_id": "<anchor event id>",
"issued_at_ms": 1800000002000,
"observation_mode": "live",
"observed_at_ms": 1800000000000,
"schema": "org.spurline.observation-receipt",
"schema_version": 1,
"signed_event_digest": "<commitment to anchor event id AND anchor signature>",
"subject_profile": "nostr-schnorr-secp256k1-v1",
"validation": "event-id-and-signature",
"witness_policy_digest": "<sha256 of exact witness policy bytes>"
}
These times and the one-second uncertainty are illustrative, not a recommended
clock guarantee. created_at describes receipt issuance. observed_at_ms
describes the relay's observation after verification. Neither is the anchor's
self-declared creation time.
The signed-subject commitment is defined in the receipt design. It includes the subject signature to prevent an old commitment to unsigned contents being presented as evidence that a later signature already existed.
For a Publisher Notice, replace the subject ID and author with the notice's own
values and use "1416" in the k tag. A receipt for an anchor does not witness
its subsequent notices or an entire Evidence Graph.
Query after finding an anchor
First discover and validate an Anchor Event using the existing OpenETR process. Then query configured evidence relays using its exact event ID:
["REQ", "anchor-witnesses", {
"kinds": [1418],
"#e": ["<anchor event id>"],
"#t": ["spurline-observation-receipt-v1"],
"limit": 100
}]
Replace the placeholder with the actual ID. This deliberately omits authors
to discover receipts from multiple witnesses. To restrict retrieval to a known
set, add authors containing their hex public keys. Kind 1418 is experimental,
not a registered allocation. Schema and kind
validation still happen after retrieval; discovery tags are not proof.
The same query can run against multiple relays. A relay that stores a receipt need not be the relay that signed it. Querying a relay does not cause it to witness the anchor. To obtain multiple independent receipts, the subject must actually reach multiple authorized, operational witnesses.
A client may subscribe before publication and receive receipts as they arrive.
The original event's OK acknowledgment is not a receipt. EOSE means the end
of stored results for that subscription, not that all possible witnesses have
responded or that discovery is globally complete. Close the subscription when
the application's monitoring window ends.
For several anchors or notices, an #e list can contain their IDs; associate
each returned receipt with its validated subject. Bound query size, responses,
timeouts, and validation work. A finite limit may truncate results. If more
retrieval is needed, use a tested bounded retrieval strategy and report its
scope rather than claiming an exhaustive witness list.
Validate before accepting the timestamp
For every candidate Witness Record:
- Verify its event ID and signature, supported kind, schema, and profile.
- Validate the exact subject ID and signature. Check that its ID, author, and
kind match the receipt content and discovery tags, and recompute the
signed-subject commitment. An
etag match alone is insufficient. - Retrieve the exact
authorization_event_id, witness request, commissioning chain, and policy artifact. Match the policy digest and service key; do not substitute the latest mutable authorization or descriptor for referenced evidence. Report missing evidence rather than treating it as authorization. - Verify that the commissioned operator signed permission for this service, witness role, policy, subject kind, and relevant interval. Evaluate the signed lifecycle and applicable compromise policy, including conflicting branches and retrieval limitations.
- Apply the application's trust policy to the commissioning operator and the witness's stated clock practices. A valid signature from an unrecognized operator remains an attributable claim, not an accepted timestamp.
- Check observation and issuance times, uncertainty, allowed issuance delay,
and
liveversusbackfillmode under that policy. Report the accepted time conclusion separately from the OpenETR ruleset result.
Retrieve dependencies from configured relays or supplied evidence packages. Treat any advertised service URL as untrusted input subject to the application's network policy, not an instruction to fetch arbitrary destinations.
For a recognized version 1 bounded-time receipt, the proposed accepted time conclusion is an upper bound: the signed subject
existed no later than observed_at_ms + clock_uncertainty_ms, conditional on
the recognized witness and policy. Preserve the stated uncertainty. This does
not establish exact creation time, content truth, legal authority, or the
consequential effect of the OpenETR event.
Version 2 does not support that numeric upper-bound calculation. Report its observation time as operator-asserted operational time with unspecified accuracy; do not use it alone to prove strict UTC deadlines or ordering across relays.
Multiple witnesses and duplicate copies
Deduplicate identical receipts by receipt event ID, but retain the list of retrieval sources. Group verified receipts by subject commitment and witness public key. Multiple different receipts from one key are not independent witnesses; preserve discrepancies rather than silently selecting a preferred timestamp. Different keys under one operator may also share infrastructure or clock sources, so independence is a policy assessment, not just a key count.
| Retrieved evidence | Application interpretation |
|---|---|
| Same receipt from three hosting relays | One signed witness assertion, three observed copies |
| Different valid receipts from three witness keys | Three witness assertions; assess trust and independence separately |
| Receipt signed by an unrecognized witness | Verifiable claim, but no accepted time conclusion under current policy |
| Receipt with unavailable authorization | Incomplete supporting evidence, not an accepted timestamp |
| Two differing receipts from one witness | Preserve both and evaluate the discrepancy |
| No receipt retrieved | No witness evidence found within this retrieval scope |
Different observation times are expected when relays receive an event at different times. Do not average them, treat the newest as authoritative, or use a simple majority to resolve OpenETR notice conflicts. A policy may select the earliest accepted upper bound, but should retain the supporting receipt and all relevant qualifications rather than presenting an unexplained single timestamp.
Suggested application presentation
Keep the Anchor Record's existing verification result intact and add a separate Witness Records section. Suggested fields per receipt are:
- Witness service identity and commissioning operator.
- Observation time, uncertainty, and receipt issuance time.
- Signature validity, authorization findings, and time-witness trust decision.
- Policy and authorization references, observation mode, and receipt ID.
- Retrieval sources and any unresolved evidence or conflicting claims.
Use separate counts for discovered receipts and recognized distinct witnesses. An empty state should say “No Witness Records found in the queried sources”, not “unwitnessed,” “invalid,” or “never existed.” Do not turn a valid anchor into an invalid one merely because this optional supporting evidence is absent.
The same component can appear alongside Publisher Notices. Witness Records support observation and time assessment; the OpenETR ruleset continues to govern anchors, notices, missing links, and conflicting branches.
Integration milestones
The receipt profile and cryptographic fixture are now defined, alongside the operational version 2 profile. Local generation, clock gates, and publication are implemented. Before apps rely on this flow, implement application-level lifecycle and trust evaluation. Test one witness, multiple witnesses, duplicate hosting, missing authorization, invalid signatures, mismatched subject signatures, expiry, delayed publication, backfill, and partial relay failure.
The operator runbook covers the authorization preparation that is available now. No changes to an OpenETR application are implemented by this guide.