Architecture — Events

This page lists the canonical events your indexers and UIs should watch. It focuses on names, arguments, and when they fire—keeping ABIs and addresses to the Addresses & ABIs page and contract implementation details to Contracts.

Event names and fields are stable across networks. All numeric timestamps are milliseconds since Unix epoch unless stated otherwise.

AccessRegistry

RequestCreated

Emitted when a PPC lock creates a new request context.

Args

• requestId (bytes32, indexed)
• apiId (bytes32, indexed)
• consumer (address, indexed)
• requestHash (bytes32)
• expiresAtMs (uint64)
• nonce (uint256) — per (consumer, apiId)

When: APIEscrow.lockForCall(...) triggers AccessRegistry to create a request entry.

DescriptorUpdated

Emitted when a provider updates the API descriptor.

Args

• apiId (bytes32, indexed)
• uri (string)
• contentHash (bytes32)
• updatedAt (uint64)
• version (uint32)

When: Provider or owner updates metadata.

PlanUpdated

Emitted when plan metadata changes.

Args

• apiId (bytes32, indexed)
• accessType (uint8) — 0 = PPC, 1 = Subscription
• price (uint256)
• duration (uint256)
• callLimit (uint256)
• active (bool)

When: Admin/provider updates plan.

APIConsensus

RequestRegistered

Emitted when a request is registered with consensus.

Args

• requestId (bytes32, indexed)
• apiId (bytes32, indexed)
• consumer (address, indexed)
• expiresAtMs (uint64)
• nonce (uint256)

ResponseSubmitted

Emitted per node submission of a provider‑signed snapshot.

Args

• requestId (bytes32, indexed)
• apiId (bytes32, indexed)
• node (address, indexed)
• seqNo (uint256)
• providerTs (uint64)
• ttl (uint64)
• contentHash (bytes32)
• msgHash (bytes32) — EIP‑712 digest of the Snapshot
• pointerURI (string) — optional off‑chain hint

ProviderEquivocation

A provider has signed two different contents for the same (apiId, seqNo).

Args

• apiId (bytes32, indexed)
• seqNo (uint256)
• firstHash (bytes32)
• secondHash (bytes32)

RequestFinalized

The request has a winning digest (success path).

Args

• requestId (bytes32, indexed)
• apiId (bytes32, indexed)
• seqNo (uint256)
• providerTs (uint64)
• contentHash (bytes32)
• msgHash (bytes32)
• votes (uint256)

RequestFailed

The request has failed to finalize successfully.

Args

• requestId (bytes32, indexed)
• apiId (bytes32, indexed)
• reason (uint8) — 1 = NoQuorum, 2 = InactiveAPI

APIEscrow

Locked

Funds locked for a PPC request.

Args

• requestId (bytes32, indexed)
• apiId (bytes32, indexed)
• consumer (address, indexed)
• price (uint256)
• expiresAtMs (uint64)

Settled

Escrow settled successfully (after consensus success).

Args

• requestId (bytes32, indexed)
• apiId (bytes32, indexed)
• success (bool) — always true for this event
• providerShare (uint256)
• nodeShare (uint256)
• platformShare (uint256)

Refunded

Escrow refunded the consumer (after consensus failure).

Args

• requestId (bytes32, indexed)
• apiId (bytes32, indexed)
• reason (uint8) — mirrors APIConsensus failure reason
• amount (uint256)

Withdrawn

Recipient withdrew accumulated balances.

Args

• account (address, indexed)
• amount (uint256)

NodeRegistry (when enabled)

Staked

• node (address, indexed)
• amount (uint256)

Unstaked

• node (address, indexed)
• amount (uint256)

Slashed

• node (address, indexed)
• amount (uint256)
• reason (uint8)

Rewarded

• node (address, indexed)
• amount (uint256)

Event sequencing (UI guidance)

A typical PPC request will generate events in roughly this order:

1. AccessRegistry.RequestCreated
2. APIEscrow.Locked
3. APIConsensus.RequestRegistered
4. One or more APIConsensus.ResponseSubmitted
5. APIConsensus.RequestFinalized or APIConsensus.RequestFailed
6. APIEscrow.Settled or APIEscrow.Refunded
7. (Later) APIEscrow.Withdrawn

UIs should be event‑driven and tolerant of reorgs/duplication. Treat settlements as idempotent and confirm balances via reads.

Topics & indexing tips

• Always index by requestId and apiId for cross‑contract joins.
• Keep a local table of (msgHash → contentHash) to display results for finalized requests.
• Record (node → digest) from ResponseSubmitted to compute rewards/slashing.
• Derive end‑to‑end latency from RequestCreated.expiresAtMs, RequestFinalized.providerTs, and block times.

Out of scope for this page

• Contract addresses → Addresses & ABIs
• Admin events (ownership/upgrade/pauses) → Contracts per contract
• How to subscribe to events in Wagmi → Integrations