OpenETR Generic Verifier Policy¶
This note documents the generic verifier policy used by the current OpenETR component and the direction for future verifier-policy work.
The core rule is:
A verifier policy enumerates the Evidence Graph according to its rules. A policy violation should normally produce a warning or non-recognition annotation, not make the signed event disappear.
OpenETR is an open signed-event system. Parties may publish events that are structurally valid but policy-questionable. The generic verifier should therefore distinguish between:
- events that cannot be verified or traversed at all
- events that can be verified as signed evidence but break a policy rule
- events that are recognized as effective under the verifier's selected policy
The baseline guard policy used by the OpenETR web app, CLI, and service layer is part of this model, but it is not a substitute for verifier recognition.
A guard can decide whether one implementation should publish an event. It cannot cryptographically prevent every other implementation from publishing a different event, and it cannot decide legal, institutional, contractual, or operational effect for every downstream party.
The verifier should therefore treat guard compliance as a reviewable policy input:
- Was the event produced through the expected baseline guard path?
- Would the selected verifier policy have allowed the same transition?
- Does the verifier require stricter domain-specific guards?
- Should a guard failure produce non-recognition, a warning, manual review, or limited-purpose recognition?
Baseline Policy¶
The generic verifier policy is the baseline policy for all OpenETR evaluations.
Every OpenETR domain should start from the same generic sequence:
- establish the Digital Artifact's byte identity, or identify the byte identity being queried
- retrieve the object graph
- verify cryptographic and structural correctness
- enumerate candidate chains
- apply or review baseline guard assumptions
- annotate policy issues
- derive candidate or recognized state according to the selected policy
- present the evidence and policy outcome separately
Where the verifier has the artifact bytes, it should hash those exact bytes and
match the result to the Evidence Graph o value. Where the verifier only has a digest or
durable link, it can verify the graph for that byte identity, but it has not
independently verified a file in hand.
Domain policies are overlays on this baseline.
A domain policy may add:
- additional safeguards
- stricter recognition requirements
- domain-specific actor rules
- required structured tags or schemas
- additional attestation requirements
- explicit exemptions from a generic warning condition
- alternative treatment of a warning within that domain
A domain policy should not replace the baseline enumeration behavior. Even where a domain policy refuses recognition, the verifier should still show the signed evidence and explain the policy reason.
Creation, Verification, Auditing, Monitoring, And Recognition¶
The generic policy should distinguish five related functions:
| Function | Result |
|---|---|
| Creation | Signed evidence is produced. |
| Verification | Supplied evidence is evaluated under identified cryptographic, structural, and transition rules. |
| Auditing | Evidence about the consistency of an evidence source or observed history is evaluated. |
| Monitoring | Later observations are compared with prior observations or stated expectations. |
| Recognition | An external rule book determines what significance or effect to give the evidence or derived state. |
One implementation may perform several functions. Their results shall remain separate. Verification does not establish population-wide observation; auditing does not establish actor intent; monitoring does not determine legal effect; and recognition does not alter the signed evidence.
Known Entity Baseline Warning¶
The baseline verifier policy should support a local known-entity check.
This check compares relevant signer and participant npub values in the OpenETR graph against the root-managed known_entities relay-backed record.
The intent is similar to an SSH client warning when connecting to an unknown host for the first time:
The cryptographic material may be structurally valid, but this verifier has not previously marked the signer or participant as known.
The known-entity check should be treated as a warning by default, not as a hard verification failure.
For example, if an Anchor Event is signed by an npub that is not in the verifier's known_entities list, the verifier may emit:
unknown_entity:
event_id: <event_id>
npub: <signer_npub>
role: issuer
message: signer is not in this root's known_entities record
recognition_effect: warning
This does not mean the event signature is invalid.
It means the verifier should make the unfamiliar identity visible before the user or policy gives the event recognition effect.
The baseline policy may check:
- origin issuer;
- evidence event signer;
- transferee or counterparty
ptags; - encumbrance beneficiary or releasing party;
- attestors;
- obligors or other action-specific participants.
Domain policies can decide whether unknown entities are:
- warning-only;
- accepted after user confirmation;
- accepted if another recognition input passes, such as TRQP;
- accepted if a WoT score or trusted assertion meets a threshold;
- blocked from recognition.
The important generic rule is that unknown-entity status should be explicit and inspectable.
KYC As A Recognition Concern¶
Know-your-customer (KYC), anti-money-laundering (AML), sanctions screening, regulated-entity status, and similar actor-recognition checks are outside the base OpenETR protocol.
The protocol-level OpenETR question is:
Which key signed which event concerning which object, and how does that event fit into the signed control graph?
KYC asks a different question:
Is this signer, profile, account, organization, or legal entity recognized by a particular relying system under a particular business, regulatory, contractual, or jurisdictional rule book?
OpenETR should support KYC-sensitive applications without enforcing one application-level KYC policy in the base protocol.
This is similar to the TCP/IP design boundary. TCP/IP supports applications such as email, web, banking, and video without embedding each application's business rules into the packet protocol. OpenETR should support warehouse receipt systems, trade finance platforms, registries, and compliance-sensitive workflows without making KYC a mandatory protocol condition for every signed event.
In OpenETR terms:
- OpenETR authenticates signed control evidence.
- KYC systems recognize actors.
- Verifier policy decides whether the recognition evidence is sufficient for a transaction, domain, organization, or jurisdiction.
An npub may therefore be KYC-attested or KYC-recognized by an integrating system.
Possible recognition inputs include:
- an OpenETR
attestevent from a recognized KYC provider; - a TRQP response from a trust registry;
- a root-managed
known_entitiesrecord; - a domain registry or account-system lookup;
- an enterprise customer or counterparty database;
- a regulator, consortium, bank, warehouse operator, or platform authority;
- a Web of Trust or reputation signal, where the selected policy permits it.
The base protocol should not decide:
- what KYC means;
- which KYC provider is acceptable;
- whether KYC is required for a particular action;
- when KYC expires;
- whether KYC must be refreshed for a transfer, encumbrance, discharge, or redemption;
- whether a KYC failure blocks recognition, produces a warning, or routes to manual review.
Those are verifier-policy and integration-layer questions.
A verifier may still surface KYC status in a structured way. For example:
kyc_recognition:
npub: <signer_npub>
role: issuer
source: <registry-or-attestor>
status: recognized
recognition_effect: accepted
Or, where the selected policy requires KYC and no recognized evidence is available:
kyc_recognition:
npub: <signer_npub>
role: transferee
status: missing
recognition_effect: policy_warning
The signature remains cryptographically valid if the key actually signed the event. The KYC result affects whether a verifier or relying application recognizes that event as effective for its own context.
Organizational Rule Books¶
Because OpenETR is an open signed-event system, no single implementation needs to be the only source of recognition rules.
Any organization can write its own verifier rule book that sits on top of OpenETR.
Examples include:
- a warehouse receipt registry
- a shipping platform
- a bank or secured lender
- a trade finance network
- an insurer
- a customs or port authority
- an enterprise document-management system
- a court, regulator, or dispute-resolution process
Each rule book can use the same OpenETR event evidence and ask its own recognition questions:
- Which issuers are recognized?
- Which profile keys map to approved legal entities or operational roles?
- Which relays, archives, or evidence sources are acceptable?
- Which event shapes are required for a complete transfer?
- Are transfer initiation and acceptance both required?
- Does an outstanding encumbrance block transfer recognition or merely require disclosure?
- Which attestors, registries, or external systems must confirm a state?
- Are missing profile records fatal, warning-only, or cured by another source?
- Which domain-specific fields or schemas are mandatory?
This is not a fork of the protocol.
The protocol remains the shared evidence substrate:
- signed events
- object identifiers
- evidence-event kinds
- tags
- relay-backed or locally stored event retrieval
- chain traversal through
elinks
The organizational rule book is the recognition layer applied to that substrate.
Recognition inputs can come from many places.
Examples include:
- root-managed
known_entitiesrecords; - formal trust registries queried through TRQP;
- Nostr Web of Trust graphs or NIP-85-style trusted assertions;
- OpenETR attestation events;
- domain registries;
- local allow lists or deny lists;
- enterprise account and role systems;
- contractual network rules;
- statutory or regulatory requirements.
These inputs complement OpenETR because they answer recognition questions, not base control-graph questions.
OpenETR establishes the signed evidence and candidate control state. The verifier policy decides which recognition inputs to consult and what effect to give them.
Two organizations may therefore inspect the same signed OpenETR graph and reach different policy conclusions. One may recognize a transfer as effective. Another may classify the same transfer as warning-only, pending attestation, blocked by an encumbrance, or outside its mandate.
That difference is expected. It is one of the reasons OpenETR keeps event publication, cryptographic verification, and recognition separate.
The generic verifier policy should make these differences visible rather than hiding them. A good verifier can show:
- the shared signed evidence
- the baseline OpenETR structural result
- the selected organizational rule book
- the warnings or policy failures under that rule book
- the resulting recognized or candidate state
This lets organizations innovate at the policy layer without needing to change the base OpenETR wire format.
Current Component Behavior¶
The current openetr query service is intentionally object-wide.
For a document digest / object id, it:
- queries Anchor Events using
kind = 1415and#o - queries evidence events using
kind = 1416and#o - groups candidate evidence events by
ereferences - builds summary control chains
- derives a candidate lifecycle state
- derives a candidate current controller
- summarizes encumbrances, discharges, and outstanding encumbrances
- includes profile metadata where available
- reports warning conditions such as multiple Anchor Events for the same object
This behavior is deliberately exploratory and evidentiary. It does not ask the relay or the first application that displays the record to decide final effect.
Instead, the component gives the verifier a structured view of the available signed evidence.
Historical State Derivation¶
Where sufficient evidence is available, a verifier should be capable of deriving Consequential State at an identified point in a candidate Evidence Graph path. The conceptual operations are:
derive_state(evidence_set, rule_set)
derive_state(evidence_set, rule_set, at_event=E)
An at_event result is relative to the supplied evidence set, identified
rules, and candidate path ending at E. It shall not be represented as a
globally authoritative state at the event's declared timestamp.
A historical-state result should identify:
- the terminal event or graph cut;
- the ancestor evidence used;
- the evidence sources and retrieval scope;
- the rule identifier and version;
- competing evidence present in the supplied evidence set;
- unresolved links and completeness limitations; and
- the derived state and warnings.
Signed timestamps do not create a trusted total order. Accepted Temporal Proofs may add time assurance as a separate verifier dimension.
Private Evidence And Proof Profiles¶
Design direction: future profiles may accept proofs of required propositions without full source disclosure. This is not a new baseline acceptance rule or a claim of implemented proof-verifier support. Current required event bodies, signatures, references, and ruleset checks remain necessary.
A profile should identify the exact proposition, evidence mechanism and version, public inputs, artifact/event/action binding, relevant time or graph cut, trust dependencies, and verification outcome. A verifier must distinguish an invalid proof, unsupported mechanism, missing material, and a verified negative proposition. Unresolved required evidence must not silently pass.
Absence proofs are scoped to an identified set or commitment. Its authority, coverage, and freshness require their own evidence; neither an empty relay response nor a proof about an incomplete set establishes global absence of encumbrances, revocations, or competing branches.
Historical verification requires preserved proof dependencies and applicable temporal evidence. A service verdict alone proves the service's assertion, not independent replay of the underlying proof. See Private Evidence And Verified Propositions for the proposed interface, durability requirements, and threat model.
Verifier Result Dimensions¶
A mature verifier should not collapse every conclusion into one valid
Boolean. It should report independent dimensions so that each conclusion says
only what its evidence supports.
At minimum, a verifier result model should be able to report:
| Dimension | Question |
|---|---|
| artifact integrity | Do the supplied bytes match the declared artifact digest? |
| event authenticity | Are event ids and signatures valid? |
| structural validity | Do events satisfy the required event shapes? |
| graph continuity | Do required e references resolve to the exact prior events? |
| historical continuity | Does later observed evidence extend an identified prior observation under the applicable proof procedure? |
| source consistency | Did queried evidence sources present compatible views for the stated scope? |
| transition validity | Do candidate transitions satisfy the selected state-transition rules? |
| consequential state | What state can be derived from the accepted candidate chain? |
| retrieval coverage | What did each queried evidence source report returning or withholding? |
| evidence sufficiency | Does the selected policy consider the available evidence adequate for its conclusion? |
| temporal proof | Does optional external evidence establish a temporal bound? |
| observation or attestation | What event, history, or procedure did an identified witness or auditor attest? |
| monitoring status | Was later evidence compared with prior observations or stated expectations? |
| actor recognition | Is a signer recognized for the relevant role or purpose? |
| system reliability | Is sufficient evidence available for an applicable reliable-system assessment? |
| recognition and effect | What effect does the selected external rule book give the result? |
Recommended outcome values are:
valid: the applicable check succeeded;invalid: available evidence contradicts or fails the applicable check;unverifiable: the verifier lacks evidence or capability needed to decide;conflicting: authentic or otherwise usable evidence supports incompatible candidate results;absent: the optional evidence type was not supplied or found;not_evaluated: the verifier did not perform the check; andnot_applicable: the check does not apply in the selected context.
These values are dimension-specific. An unavailable optional Temporal Proof does not make an otherwise valid Evidence Graph invalid. An authentic credential does not establish that its issuer is recognized for a purpose. A recognized actor does not cure a broken graph link.
Three Completeness Questions¶
The word complete should be qualified. A verifier should distinguish:
- retrieval coverage: whether a particular relay or repository reported that it returned all matching records it stores;
- graph continuity: whether every explicit prior-event link needed for a candidate chain resolves; and
- policy sufficiency: whether the selected verifier policy considers the collected evidence sufficient for its conclusion.
None of these, by itself, proves that no conflicting event exists anywhere. Absence from a query result shall not be represented as global non-existence.
Equivocation And Divergent Observations¶
Valid signatures do not establish that all observers received one globally consistent Evidence Graph. Evidence sources may return stale, incomplete, or different event sets. Authentic signed events may also form competing paths.
The verifier should compare source observations where that information is available and report findings such as:
- conflicting evidence;
- insufficient evidence;
- history divergence;
- unresolved candidate states; or
- evidence completeness unknown.
If the evidence and rules do not support a unique result, the verifier shall not manufacture one. The result should identify the evidence sources, retrieval scope, rules, and evaluation parameters on which it depends.
Hard Verification Errors¶
Some failures prevent a verifier from treating an event as usable OpenETR evidence.
Examples include:
- malformed object identifiers supplied to the query command
- malformed public keys supplied as filter inputs
- invalid event signatures
- invalid event ids
- missing required event shape tags
- events whose required object identity cannot be determined
- evidence events that cannot be associated with the queried object
These are structural or cryptographic problems. A verifier may reject those events from the candidate graph because they do not satisfy the minimum requirements for OpenETR event evidence.
In implementation terms, these failures may raise errors, cause the event to be excluded, or mark the event as structurally invalid.
Policy Warnings¶
Other conditions may break a policy rule but still leave the event as signed evidence.
These should generally be represented as warnings or policy annotations.
Examples include:
- more than one Anchor Event exists for the same object digest
- an evidence event is signed by someone other than the expected current controller
- an event would not have passed the baseline publishing guard used by the reference component
- a transfer initiation has no corresponding acceptance event
- a transfer acceptance appears without a recognized initiation
- an encumbrance exists before or during a transfer
- a discharge references an encumbrance that the verifier does not recognize
- a termination appears while an encumbrance remains outstanding
- multiple candidate chains compete for recognition
- a prior event referenced by an
etag is missing because the event is unavailable from the queried relays or local store - an Anchor Event appears to have been replaced after later evidence events already depended on its event id
- a participant profile is missing or does not satisfy the verifier's actor policy
- an event is structurally valid but lacks an attestation required by the selected policy
These conditions are not the same as invalid signatures or malformed events.
The event happened in the cryptographic sense: a key signed a statement, relays carried it, and the event can be retrieved. The question is whether a verifier's policy treats that statement as effective.
For that reason, the generic policy should not erase the event or treat the whole graph as failed. It should enumerate the graph and mark the relevant issue.
Warning Semantics¶
A warning means:
This event or transition is visible in the signed Evidence Graph, but the selected verifier policy has not accepted it as contributing cleanly to Consequential State.
A warning should include, where practical:
- the rule that was triggered
- the event or transition that triggered it
- whether the issue affects controller state, lifecycle state, encumbrance state, or only display confidence
- whether the policy ignored the event, accepted it with warning, or left multiple candidate states unresolved
Warnings should be machine-readable as well as human-readable where the component exposes structured output.
Recommended fields for future structured verifier output include:
| Field | Meaning |
|---|---|
code |
Stable warning code such as multiple_origin_events or unexpected_controller |
severity |
Suggested severity such as info, warning, or policy_blocked |
event_id |
Event that triggered the warning, if applicable |
prior_event_id |
Prior event involved in the transition, if applicable |
action |
Control action involved, if applicable |
message |
Human-readable explanation |
recognition_effect |
How the selected policy treated the event or transition |
Missing Prior Links And Legacy Replaceable Events¶
The generic verifier should treat broken e links as a first-class graph-continuity issue.
This is especially important because every OpenETR control transition links to
a specific prior event id. OpenETR Anchor Events and Evidence Events use regular
event kinds 1415 and 1416; they are not replaceable event slots.
The verifier should therefore distinguish:
- exact rebroadcast of the same event, where the event id remains the same
- replacement publication, where the event id changes
- missing prior-event evidence, where a later event references an event id that cannot be retrieved
The generic policy should not silently repair the graph by treating a newer replacement Anchor Event as the parent of older evidence events.
Instead, it should enumerate the available evidence and emit a warning such as:
broken_prior_link:
evidence event references prior event A,
but A was not available from the queried evidence sources
or:
origin_replaced_after_control:
newer Anchor Event B exists for the same author/kind/d slot,
but later evidence events reference older Anchor Event A
A domain or organizational rule book can decide the effect of that warning. It may:
- refuse recognition of the affected chain
- require archived evidence of the older event
- require attestation that the older event existed and was relied on
- recognize the chain only for limited purposes
- allow the replacement in a controlled correction workflow
The important generic rule is that event-id graph links are specific. A verifier should not treat replaceable-coordinate continuity as equivalent to event-id continuity.
Enumeration Before Recognition¶
The verifier should first enumerate the available graph before applying recognition effects.
The sequence is:
- retrieve candidate Anchor, control, and linked-evidence records for the object using the object query anchor, currently
#o - verify structural and cryptographic requirements
- index retrieved events by event id
- use
ereferences to reconstruct candidate paths inside the Evidence Graph - inspect
actionand action-specific tags to interpret graph nodes - apply the selected verifier policy to those chains
- annotate policy breaks as warnings
- derive recognized or candidate state from the policy result
- present both the evidence and the policy outcome
In compact form:
o = find the graph
e = walk the graph
action = understand each node
rules = determine what follows
recognition = decide effect
This lets the verifier answer two separate questions:
What signed evidence exists?
and:
What does this verifier's policy recognize as effective?
Both answers matter.
Current Generic Policy¶
The current generic policy is intentionally minimal.
It treats the graph as object-centric evidence and derives practical state for demonstration and integration purposes:
- the first candidate Anchor event is used as the initial basis
- multiple candidate Anchor events are reported as a warning condition
- evidence events are grouped and summarized through
ereferences - controller state is derived from controller-changing actions
- lifecycle state is derived from lifecycle-changing actions
- encumbrance state is derived by matching
encumberanddischargeevents - profile metadata is displayed where available but missing profile metadata does not erase the signed event
This is not a final legal recognition profile.
It is a generic component policy for making the signed graph legible.
Domain adapters and recognition profiles may apply stricter rules.
Publishing Guards Versus Verifier Recognition¶
The OpenETR component now exposes baseline publishing guards through a shared guard policy.
Those guards are useful because the CLI and web app can enforce the same ordinary publishing discipline. They help prevent accidental publication of events that the baseline OpenETR state model would treat as inconsistent, ambiguous, or unauthorized by the apparent current controller.
However, a published event remains only signed evidence until a verifier gives it recognition effect.
For example:
- a transfer event may be cryptographically signed and structurally valid;
- it may or may not have passed the reference component's publishing guard;
- it may still fail recognition under a warehouse receipt registry, secured lending policy, authority rule book, or private counterparty agreement;
- it may also be recognized under one context and rejected or warned under another.
This separation is intentional.
OpenETR should provide:
- cryptographic evidence that an event was signed by a key;
- graph evidence about where the event sits in relation to the digital artifact;
- guard evidence about whether a baseline or custom component policy would allow the transition;
- state-derivation output showing what follows under the identified rules; and
- recognition evidence showing what effect a relying party gives to the result.
The verifier should not collapse those into a single Boolean.
Domain-Specific Policy Profiles¶
A domain-specific policy profile applies on top of the generic verifier policy.
It may decide that a warning has stronger consequences within that domain.
For example, an MLWR warehouse receipt profile may decide:
- only a recognized warehouse operator may issue a receipt
- protected-holder status requires additional conditions
- transfer while an encumbrance is outstanding is not recognized
- delivery completion requires a warehouse-operator termination event
- particular structured tags or receipt fields are mandatory
It may also decide that a generic warning should be exempted or softened in a particular domain context.
For example:
- a closed trusted-counterparty profile may recognize transfer initiation without a separate acceptance event
- a warehouse receipt profile may allow a transfer while an encumbrance is outstanding but mark the encumbrance prominently
- a registry-backed profile may treat a registry attestation as curing a missing profile metadata warning
- a bearer-style redemption profile may recognize presentation by a valid presenter rather than ordinary controller transfer history
Those rules should still be reported as policy outcomes over the graph.
The underlying signed events remain evidence. The policy decides whether they are recognized.
Implementation Guidance¶
OpenETR implementations should prefer this behavior:
- raise errors for malformed inputs or structurally unusable events
- warn for policy-rule breaks in otherwise signed and retrievable events
- keep policy warnings visible in CLI and web outputs
- expose policy warnings in structured API responses where possible
- avoid collapsing warning-free display into legal effect
- avoid treating every policy breach as a publication failure
This supports the OpenETR principle:
Publish signed evidence openly. Verify structure cryptographically. Recognize effect under policy.
Relationship To Other Notes¶
This note complements:
- OPENETR_NOSTR_WIRE_FORMAT_SPEC.md
- OPENETR_KEY_TRANSPARENCY_LESSONS_DESIGN_NOTE.md
- CONTROL_EVENT_POLICY_GUARDS_DESIGN_NOTE.md
- CONTROL_EVENT_MINIMUM_SHAPES.md
- OPENETR_LAYERED_ARCHITECTURE_NOTE.md
The wire-format spec defines the event grammar. The evidence-event policy guards note explains hard and soft guards. This note defines how a generic verifier should enumerate and annotate the control graph under policy.