@zkp2p/indexer-schema

Consumer-facing GraphQL domain schema and TypeScript types for the ZKP2P indexer. The package is generated from schema/domain.graphql; raw audit-event entities are available in the live indexer but are not exported here.

Install

pnpm add @zkp2p/indexer-schema

Source vs Published Package

This repository currently declares 0.22.0. Publishing is an autonomous OIDC workflow after the focused version PR is merged and tagged; merging a schema change alone does not update npm.

Before depending on a newly merged entity or field, compare both versions:

jq -r .version packages/indexer-schema/package.json
npm view @zkp2p/indexer-schema version

Version 0.22.0 stabilizes the schema published as 0.22.0-rc.4. Do not assume the stable version or its reviewed documentation exists in the installed package until the trusted publish workflow completes.

Usage

import { schemaSDL } from "@zkp2p/indexer-schema";
import type {
  DisputeProtectionIntent,
  Deposit,
  Intent,
  QuoteCandidate,
} from "@zkp2p/indexer-schema/types";

The raw SDL is also exported at @zkp2p/indexer-schema/schema.graphql.

Exported types

• Orders and quotes: Deposit, DepositPaymentMethod, MethodCurrency, Intent, QuoteCandidate, OrderbookEntry, WhitelistEntry, ReferralFeeDistribution
• Statistics and activity: taker, maker, manager, platform, global, deposit, price, profit, referral, and daily cursor entities
• Delegated rates: RateManager, RateManagerRate, ManagerStats, ManagerAggregateStats, ManagerDailySnapshot
• Stake custody: TakerStakeState, StakeAccountState, ClaimAccountState, TakerStakeAuthorization, StakeLock, StakeActivity, StakeVaultConfig
• V3 disputes: DisputeProtectionIntent, DepositDisputeProtectionConfig, DisputeProtectionRiskWindow, DisputeProtectionPolicyState, IntentLifecycleHookState
• V3 registry state: OrchestratorRegistrationState
• Payment binding: PaymentIntentBinding
• Whitelist policy: AddressGroup, AddressGroupMember, DepositWhitelistPolicy, DepositWhitelistedAddress, DepositAllowedGroup

Transaction attribution

Version 0.20.0-rc.1 exposed canonical ERC-8021 attribution on deposit creation as well as every newly signaled V2, V2.1, V2.2, and V3 intent:

• Deposit.attributionCodes and Deposit.attributionSource identify the client that created the seller's deposit.
• Intent.attributionCodes preserves all decoded attribution codes in calldata order.
• Intent.attributionSource is the first code other than ZKP2P's Base builder code (bc_nbn6qkni), or null when no client/referrer code is present.
• Version 0.21.0-rc.0 retains at most five ordered codes and decodes either direct calldata or the address-matched ERC-4337 user operation's ERC-7579 execution payload.
• Missing, malformed, ambiguous, or unsupported suffixes fail closed to an empty code list and null source.

These fields replace calldata parsing in analytics consumers. They do not change deposit or intent identity, lifecycle, amounts, payment method, or fulfillment semantics.

Intent guardian

Version 0.21.0-rc.1 adds Deposit.intentGuardian and QuoteCandidate.intentGuardian for the guardian selected when a deposit was created:

• Both fields are lowercase-normalized.
• Legacy V2 deposits use the zero address as the non-null guardian sentinel.
• QuoteCandidate.intentGuardian is indexed for exact-equality and _in filtering with lowercase address values.

Orderbook gating service

Version 0.20.0 stabilizes the schema published and production-exercised as 0.20.0-rc.2, including OrderbookEntry.intentGatingService, projected from QuoteCandidate.intentGatingService:

• It is non-null. The zero address is the ungated sentinel, so "no gating service" never collapses with "value absent".
• It is lowercase-normalized, unlike its QuoteCandidate source, so consumers can compare addresses with exact equality.
• A non-zero value means the deposit's intents must be authorized by that gating service, so consumers that cannot produce its signature should exclude the row.

Method-scoped dispute protection and liquidity aggregates

Version 0.22.0 stabilizes the schema published as 0.22.0-rc.4, synchronizing the consumer projection with the method-scoped dispute stack and removing the retired Peer Curator accounting surface:

• QuoteCandidate.disputeProtectionOptedIn and OrderbookEntry.disputeProtectionOptedIn are hard-renamed to disputeProtectionOptedOut.
• Dispute protection is default-on for payment methods with a nonzero active-policy risk window. Only an explicit active-policy enabled: false row is opted out; missing config and enabled: true are not opted out.
• Projection fan-out is gated to the configured active policy. Passive or predecessor policy events retain raw/config rows without changing quote or orderbook admission.
• Staging and production now bind the dedicated-vault method-scoped dispute stack from contracts #293-#295 (fresh StakeVault), using @zkp2p/[email protected].
• CurrencyLiquidity and its deduplicated DepositCurrencyLiquidity contributions aggregate immediately available token liquidity by fiat currency.
• TokenLiquidity and its deduplicated DepositTokenLiquidity contributions aggregate immediately available liquidity by deposited token.
• CurrencyPlatformLiquidity and its deduplicated DepositCurrencyPlatformLiquidity contributions aggregate immediately available token liquidity by fiat currency and payment platform.
• MakerPeerPayStats is removed.
• MakerPlatformStats.totalAmountTakenPreEarnCutover is removed.
• Generic AddressGroup and method-scoped whitelist-policy entities remain supported for the Peer Pay merchant group.

Version 0.22.0-rc.2 scopes whitelist-group admission and dispute-protection opt-in to a deposit/payment-method tuple:

• DepositWhitelistPolicy, DepositAllowedGroup, and DepositDisputeProtectionConfig IDs now include paymentMethodHash.
• DepositWhitelistPolicy.paymentMethodHash, DepositAllowedGroup.paymentMethodHash, and DepositDisputeProtectionConfig.paymentMethodHash are required.
• Direct DepositWhitelistedAddress rows remain deposit-wide and no longer expose the invalid tuple-policy policyEntityId; whitelistedAddressCount is the deposit-wide count repeated on each method policy.
• Only the matching payment-method rows in QuoteCandidate and OrderbookEntry are refreshed by policy events.

Version 0.22.0-rc.1 made the dispute-admission projection a hard cut and added stable staking/dispute pagination fields. Its explicit opt-in semantics are superseded by 0.22.0-rc.3:

• The rc.1 fields represented explicit opt-in; rc.3 replaces them with the default-on disputeProtectionOptedOut projection described above.
• QuoteCandidate.disputeProtectionRequiresStake and OrderbookEntry.disputeProtectionRequiresStake are true only when the tuple is not opted out and has a nonzero active-policy risk window for the row's payment method.
• Staging and production bind only their configured active policy and vault; retired deployments are not indexed.
• DisputeProtectionIntent.disputedAtBlockNumber and disputedAtLogIndex record the exact DisputeResolved event cursor and remain null before a dispute.
• Stake and finalized-dispute records expose indexed fields for stable keyset pagination; page validation and query execution remain consumer responsibilities.

Missing DepositDisputeProtectionConfig rows are not opted out. An explicit active-policy enabled: false config records opt-out; enabled: true undoes it. Missing or zero payment-method risk windows do not require stake. The contracts remain authoritative for admission, collateral, maturity, attestation verification, and dispute settlement.

Merchant stake and dispute pagination

• StakeLock pages require exact chainId, vaultAddress, and stakeOwner filters plus optional status. Advance the opaque keyset with id > afterId and id ascending. maturesAt remains a surfaced UI value, but it is mutable and therefore not the cursor.
• StakeActivity pages require exact chainId and vaultAddress, merchant relevance (stakeOwner == merchant OR taker == merchant), and optional kind. Order (blockNumber, logIndex, id) ascending. After cursor (b, l, i), continue with blockNumber > b OR (blockNumber = b AND logIndex > l) OR (blockNumber = b AND logIndex = l AND id > i). StakeActivity cursor stability comes from immutable append-only event positions.
• Finalized dispute pages require exact chainId, status = DISPUTED, and the active policyAddress, with no merchant-address predicate. Order (disputedAtBlockNumber, disputedAtLogIndex, id) ascending. After cursor (b, l, i), continue with disputedAtBlockNumber > b OR (disputedAtBlockNumber = b AND disputedAtLogIndex > l) OR (disputedAtBlockNumber = b AND disputedAtLogIndex = l AND id > i). The two event cursor fields are non-null for rows admitted by the DISPUTED filter even though they remain nullable before dispute. Finalized DISPUTED cursor stability comes from terminal rows and immutable dispute event positions.

These keysets guarantee strict forward progress; use no offset pagination. Page sizes 1..100 are validated by the clients SDK; the indexer schema does not enforce a page-size limit.

V3 dispute boundary

Version 0.19.0-rc.0 was the contracts PR #219 hard cut:

• RiskManager entities, enums, intent-extension projections, deferred settlement state, and risk-exposure aggregates are removed.
• DisputeProtectionIntent records the PENDING -> CANCELLED | SETTLED -> RELEASED | DISPUTED lifecycle.
• DisputeProtectionRiskWindow records future-admission minimum holds per policy and payment method.
• DisputeProtectionPolicyState is the current pause flag plus the normalized, sorted set of authorized lifecycle hooks for one Policy deployment.
• OrchestratorRegistrationState is current Orchestrator membership in one registry deployment; removal overwrites the same row with registered: false.
• IntentLifecycleHookState records the hook snapshotted by OrchestratorV3.
• PaymentIntentBinding remains the canonical (chainId, registryAddress, nullifier) -> intentHash relationship.

TakerStakeState.selectedStakeOwner preserves the emitted preference. selectionAuthorized and stakeOwner are effective state: authorization makes the selection active, revocation immediately falls back to the taker's own stake, and unrelated authorization updates do not rewrite the row.

These current-state, split dispute-projection, and cursor fields require a clean staging and production reindex. Do not deploy a consumer that treats a missing field as opt-out against an older database.

EscrowIntentPeriodState remains part of the V2.2 Escrow surface and is not a DisputeProtectionPolicy or RiskManager entity.

See the bundled docs/schema-field-reference.md and llms.txt for identity and field semantics.

Breaking-change detection

The indexer CI runs check-schema-breaking.cjs on every PR that touches schema/. It fails if any fields, types, or enum values are removed or have incompatible type changes unless the package advances to a later RC on the same unreleased line, or to the next minor after a stable release.

When making intentional breaking changes:

1. Advance the RC while the release line is unstable; after stable, bump the minor version
2. Update downstream consumers before merging
3. Confirm the CI check reports the intentional version bump

Codegen Example

# codegen.yml
schema: node_modules/@zkp2p/indexer-schema/dist/schema.graphql
generates:
  src/__generated__/types.ts:
    plugins:
      - typescript
      - typescript-operations

Development and release

From the repository root:

pnpm install --frozen-lockfile
pnpm build:schema
pnpm schema-package:build
pnpm --dir packages/indexer-schema verify:release
cd packages/indexer-schema && npm pack --dry-run

Publishing is performed only by the protected GitHub Actions trusted-publishing workflow. It uses npm OIDC without a long-lived npm token and adds provenance whenever the source repository is public. See the release runbook.