Event Taxonomy

Status: draft
Version: 0.1.0

Purpose

Define canonical event names and envelopes across the platform, including the Meridian Clear instruction workflow layer, the Meridian Vault custody / authorization layer above it, the Meridian Registry checkpoint / distribution / funding / payout / reconciliation / redemption / notice / ballot servicing layer, the Meridian Proof evidence / bundle layer above replayable Meridian state, the Meridian Chronicle historical reconstruction layer above that replayable event surface, the Meridian Foundry manifest / launch layer that turns governed instrument setup into launchable runtime state, the Meridian Pulse delivery layer that turns accepted runtime events into governed subscription and delivery history, the Meridian operator activity ledger that records attributable protected-write outcomes after scoped Gateway operator auth succeeds, the Meridian Watch derived operational layer that reads those replayable records without appending new events, the Meridian Bridge translation layer that turns stored Meridian events into governed external delivery records while Bridge+ deepens that surface through adapter catalog discovery and controlled delivery replay without adding new event types, the Meridian Relay execution layer that records governed signer-adapter requests and outcomes around one real settlement path including Vault-backed submit and Fireblocks-backed pending external execution, and the Meridian Veil private workflow layer that records rooms, grants, revocations, and export lineage above Proof and Chronicle.

Envelope fields

event id
event type
correlation id
subject id
visibility
occurred at
evidence ref

Canonical event types

tenant.registered
venue.registered
instrument.created
instrument.issued
instruction.recorded
instruction.affirmed
instruction.ready
instruction.cancelled
instruction.expired
instruction.settled
redemption.declared
redemption.executed
instrument.redeemed
instrument.frozen
instrument.unfrozen
webhook.registered
participant.registered
claim-issuer.registered
claim.issued
claim.revoked
policy-set.registered
policy-evaluated
custody.delegated
custody.revoked
operator.granted
operator.revoked
portfolio.registered
portfolio.operator.bound
approval.requested
approval.decided
checkpoint.recorded
notice.published
ballot.opened
vote.cast
ballot.closed
ballot.outcome.determined
proxy.assigned
proxy.revoked
manifest.updated
instrument.document.linked
collection.registered
record.minted
record.transferred
record.retired
instrument.split
instrument.matured
distribution.declared
distribution.closed
distribution.claimed
distribution.funding.recorded
distribution.payout.recorded
distribution.reconciled
evidence.recorded
evidence.linked
evidence-bundle.created
manifest.registered
launch.executed
bridge.registered
bridge.delivery.recorded
relay.execution.requested
relay.execution.resolved
operator.activity.recorded
veil.room.opened
veil.grant.issued
veil.grant.revoked
veil.export.recorded
delivery.recorded
webhook.delivery.attempted
webhook.delivery.dead-lettered
mediator.affirmed
mediator.paused
mediator.escalated
mediator.resumed
anchor.submitted
anchor.failed
hold.placed
hold.released

Phase BD event notes

anchor.submitted records that a settled instruction was broadcast to Kaspa (txId); it carries chainFinalityMs, the broadcast-to-acknowledgement latency surfaced by GET /v1/stats/settlement-latency. NOTE: the default RPC adapter resolves on submit-acknowledgement; true on-chain block-finality polling is a documented future enhancement, so chainFinalityMs is not yet a measure of confirmed finality.
anchor.failed records a failed anchor attempt with a sanitized reason code (never raw RPC/URL text); settlement is NOT rolled back — anchoring is an additive attestation, not a settlement precondition.
Anchoring runs after settlement is committed and the write lock is released, so a slow/hung kaspad never blocks other gateway writes. With no KASPA_RPC_URL (and no injected adapter) the settle path emits neither event.

Phase BA event notes

Meridian Clear instructions may carry a mediatorIds set on instruction.recorded. Every listed mediator must affirm before the instruction can settle.
mediator.affirmed records one mediator participant’s affirmation; settlement is gated until all assigned mediators have affirmed.
mediator.paused and mediator.escalated record mediator-imposed control over an instruction; both block settlement (instruction_paused_by_mediator / instruction_escalated_by_mediator) until lifted.
mediator.resumed lifts a prior pause/escalation (mediator status returns to active), returning the instruction to the normal affirmation flow; prior mediator affirmations are retained.
Mediator decisions are operator-gated under the mediator-affirmation operation and are only accepted for a mediator actually assigned to the instruction.

Phase AO event notes

instruction.recorded may carry fromPortfolioId and toPortfolioId when Meridian Clear records one portfolio-aware settlement instruction.
instruction.settled may carry the same linked portfolio ids so replay, directory routes, and Chronicle reconstruction preserve the original portfolio context.
Phase AO adds no new event families; it enriches the existing Clear event payloads.