@zkp2p/indexer-schema 0.1.3 → 0.2.0

package/README.md

@@ -1,67 +1,67 @@
 # @zkp2p/indexer-schema
 
-Exports the GraphQL schema used by the ZKP2P indexer.
+GraphQL schema and TypeScript types for the ZKP2P indexer. Single source of truth for all downstream consumers (SDK, curator, etc.).
+
+## Install
 
-Install
 ```
 pnpm add @zkp2p/indexer-schema
 ```
 
-Usage
+## Usage
+
+### TypeScript Types
+
+```typescript
+import { Deposit, Intent, QuoteCandidate, DepositStatus } from '@zkp2p/indexer-schema';
+
+// Or import types only
+import type { MethodCurrency, MakerStats } from '@zkp2p/indexer-schema/types';
 ```
-// Load the SDL string (GraphQL schema) in Node
+
+### Raw SDL String
+
+```typescript
 import { schemaSDL } from '@zkp2p/indexer-schema';
-// or CommonJS: const { schemaSDL } = require('@zkp2p/indexer-schema');
+```
+
+### Schema File (for codegen configs)
 
-// Path reference for codegen configs
+```yaml
 schema: node_modules/@zkp2p/indexer-schema/dist/schema.graphql
 ```
 
-Notes
-- Includes: Deposit, Intent, DepositPaymentMethod, MethodCurrency.
-- The file is generated at publish time from the indexer repo.
+## Exported Types
 
+**Domain entities:** Deposit, DepositPaymentMethod, MethodCurrency, Intent, QuoteCandidate, ReferralFeeDistribution
 
-## Backend Codegen Example (using domain.graphql)
+**Stats:** TakerStats, MakerStats, MakerPlatformStats, MakerCurrencyStats, ManagerStats, ManagerAggregateStats, ManagerDailySnapshot
 
-This is a minimal example to generate TypeScript types from the exported domain schema.
+**Rate management:** RateManager, RateManagerRate
 
-### 1) Install codegen tooling
+**Price/Profit:** PriceSnapshot, MakerProfitSnapshot
 
-```
-pnpm add -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations
-```
+**Activity:** DepositFundActivity, DepositDailySnapshot
 
-### 2) Add a codegen config (codegen.yml)
+**Enums:** DepositStatus, IntentStatus, PriceSnapshotStatus, ProfitStatus
 
-```
-schema: node_modules/@zkp2p/indexer-schema/dist/schema.graphql
-# Alternatively, if using a workspace dependency:
-# schema: ../zkp2p-indexer/dist/schema.graphql
+## Breaking Change Detection
 
+The indexer CI runs `check-schema-breaking.js` on every PR that touches `schema/`. It fails if any fields, types, or enum values are removed or have incompatible type changes.
+
+When making intentional breaking changes:
+1. Bump the package version (minor for breaking)
+2. Update downstream consumers before merging
+3. The CI check will flag the change — this is expected
+
+## Codegen Example
+
+```yaml
+# codegen.yml
+schema: node_modules/@zkp2p/indexer-schema/dist/schema.graphql
 generates:
   src/__generated__/types.ts:
     plugins:
       - typescript
       - typescript-operations
-    config:
-      avoidOptionals: true
 ```
-
-### 3) Add an npm script
-
-```
-"scripts": {
-  "codegen": "graphql-codegen --config codegen.yml"
-}
-```
-
-### 4) Use the generated types
-
-- Import `Deposit`, `Intent`, etc. operation and type definitions from `src/__generated__/types.ts`.
-- If you serve GraphQL in the backend, you can build an executable schema from `domain.graphql` and provide resolvers that read from the indexer’s DB.
-- If you serve REST, use the generated types to type DTOs and service responses.
-
-Notes
-- We export the schema needed by backend consumers (no raw event entities). It matches the data model our handlers populate.
-- When the schema changes in a breaking way (e.g., a field becomes non‑null), bump the schema package version and update your backend accordingly.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+// Auto-generated from schema/domain.graphql
+export declare const schemaSDL: string;
+export * from './types';

package/dist/index.js

@@ -1,4 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 const fs = require('fs');
 const path = require('path');
 const schemaSDL = fs.readFileSync(path.join(__dirname, 'schema.graphql'), 'utf8');
-module.exports = { schemaSDL };
+exports.schemaSDL = schemaSDL;
+// Re-export enums with static assignments for Node CJS-to-ESM named export detection
+const types = require('./types');
+exports.DepositStatus = types.DepositStatus;
+exports.IntentStatus = types.IntentStatus;
+exports.PriceSnapshotStatus = types.PriceSnapshotStatus;
+exports.ProfitStatus = types.ProfitStatus;

package/dist/schema.graphql

@@ -1,22 +1,52 @@
 # Domain types
 
+enum DepositStatus {
+  ACTIVE
+  CLOSED
+}
+
+enum IntentStatus {
+  SIGNALED
+  FULFILLED
+  PRUNED
+  MANUALLY_RELEASED
+}
+
+enum PriceSnapshotStatus {
+  LIVE
+  BACKFILL
+}
+
+enum ProfitStatus {
+  COMPUTED
+  PENDING
+}
+
 type Deposit {
   id: ID!  # escrowAddress_depositId
   chainId: Int!
   escrowAddress: String!
+
+  # Static Deposit details
   depositId: BigInt!
   depositor: String!
   token: String!
-  amount: BigInt!
-  remainingDeposits: BigInt!
+  
+  # Deposit details (can be updated)
+  delegate: String!
   intentAmountMin: BigInt!
   intentAmountMax: BigInt!
   acceptingIntents: Boolean!
-  status: String!  # ACTIVE | CLOSED | WITHDRAWN
+  status: DepositStatus!
   
-  # Pre-calculated fields
-  outstandingIntentAmount: BigInt!
-  availableLiquidity: BigInt!
+  # Deposit amounts used for quote calculations
+  # Notes/identities:
+  # - balance = remainingDeposits + outstandingIntentAmount
+  # - grossDeposited (all-time) = remainingDeposits + outstandingIntentAmount + totalAmountTaken + totalWithdrawn
+  remainingDeposits: BigInt!        # Total USDC immediately available to be taken / withdrawn
+  outstandingIntentAmount: BigInt!  # Total USDC locked in pending intents
+  totalAmountTaken: BigInt!         # Total USDC taken by intents (incl. manual release)
+  totalWithdrawn: BigInt!           # Total USDC withdrawn via DepositWithdrawn events
 
   # Intent counters 
   totalIntents: Int!
@@ -24,47 +54,101 @@ type Deposit {
   fulfilledIntents: Int!
   prunedIntents: Int!
   
+  # Quality signal (basis points 0–10000; new deposits start at 10000)
+  successRateBps: Int!
+  
   # Metadata
   blockNumber: BigInt!
   timestamp: BigInt!
   txHash: String!
   updatedAt: BigInt!
+
+  # V2.2 delegated rate manager assignment (optional)
+  rateManagerId: String @index
+  rateManagerAddress: String
+  delegatedAt: BigInt
+
+  # Reverse links for convenience in GraphQL (via @derivedFrom)
+  intents: [Intent!]! @derivedFrom(field: "depositId")
+  paymentMethods: [DepositPaymentMethod!]! @derivedFrom(field: "depositId")
+  currencies: [MethodCurrency!]! @derivedFrom(field: "depositId")
+  fundActivities: [DepositFundActivity!]! @derivedFrom(field: "depositId")
+  dailySnapshots: [DepositDailySnapshot!]! @derivedFrom(field: "depositId")
 }
 
 type DepositPaymentMethod {
   id: ID!  # escrowAddress_depositId_paymentMethodHash
   chainId: Int!
+
+  # Corresponding Deposit details
+  depositId: String! @index # escrowAddress_depositId (foreign key)
   depositIdOnContract: BigInt!
-  depositId: String!
+
+  # Payment method details
   paymentMethodHash: String!
-  verifierAddress: String!
   intentGatingService: String!
   payeeDetailsHash: String!
+  active: Boolean!
 }
 
 type MethodCurrency {
   id: ID!  # escrowAddress_depositId_paymentMethodHash_currencyCode
-  chainId: Int!
-  depositIdOnContract: BigInt!
-  depositId: String!
-  paymentMethodHash: String!
-  currencyCode: String!
-  minConversionRate: BigInt!  # Currently contract emits this field as conversionRate; todo: update it on contract 
+  chainId: Int!               # Chain where the deposit lives
+
+  # Corresponding Deposit details
+  depositId: String! @index   # Foreign key to Deposit.id (escrowAddress_depositId)
+  depositIdOnContract: BigInt! # Raw on-chain deposit id
+
+  # Payment method details
+  paymentMethodHash: String!  # Payment method bytes32 hash for this tuple
+  currencyCode: String!       # Fiat currency bytes32 hash for this tuple
+
+  # Rate state
+  minConversionRate: BigInt!  # Depositor-set fixed floor only; not oracle-adjusted and not fee-adjusted
+  managerRate: BigInt         # Delegated manager quote before floor enforcement and before fee
+  managerFee: BigInt          # 1e18 manager fee rate charged separately by OrchestratorV2 on token release
+  conversionRate: BigInt      # Final gross resolved rate; contract-aligned and used for intent validation
+  takerConversionRate: BigInt # Final taker-facing all-in rate derived from conversionRate
+  rateSource: String          # Binding source/reason for conversionRate: MANAGER | ORACLE | ESCROW_FLOOR | MANAGER_DISABLED | ORACLE_HALTED | NO_FLOOR
+  rateManagerId: String       # Delegated rate manager id when this tuple is manager-controlled
+
+  # Oracle rate config and state
+  adapter: String             # Oracle adapter contract address
+  adapterConfig: String       # Encoded adapter configuration bytes
+  feed: String                # Resolved oracle feed address or feed id
+  feedDecimals: Int           # Feed decimals used to scale oracle answers
+  spreadBps: Int              # Depositor-configured spread markup in basis points
+  maxStaleness: BigInt        # Maximum accepted oracle age in seconds
+  invert: Boolean             # Whether the oracle answer must be inverted before scaling
+  oracleRate: BigInt          # Raw oracle rate before spread is applied
+  effectiveOracleRate: BigInt # Oracle rate after spread is applied
+  lastOracleUpdatedAt: BigInt # Timestamp of the last accepted oracle snapshot
+  kind: String @index         # Oracle kind: oracle_chainlink | oracle_pyth | oracle_unknown
 }
 
 type Intent {
   id: ID!  # chainId_intentHash
   intentHash: String!
-  depositId: String!
-  escrowAddress: String!
+  orchestratorAddress: String!
+
+  # Corresponding Deposit details
+  depositId: String! @index # escrowAddress_depositId (foreign key)  
+  
+  # Verifier details
   verifier: String!
+  paymentMethodHash: String # Association to payment method
+  
+  # Recipient details
   owner: String!
   toAddress: String!
+
+  # Payment details
   amount: BigInt!
   fiatCurrency: String!
   conversionRate: BigInt!
-  status: String!  # SIGNALED | FULFILLED | PRUNED
-  
+  status: IntentStatus! @index  # SIGNALED | FULFILLED | PRUNED | MANUALLY_RELEASED (on-chain states only)
+  isExpired: Boolean!     # Set by off-chain reconciler when expiryTime has passed
+
   # Tx hashes and timestamps
   signalTxHash: String!
   signalTimestamp: BigInt!
@@ -72,8 +156,301 @@ type Intent {
   fulfillTimestamp: BigInt
   pruneTxHash: String
   pruneTimestamp: BigInt
+  expiryTime: BigInt! @index
   updatedAt: BigInt!
 
-  # Association to payment method
-  paymentMethodHash: String
+  # Verified payment details (from UnifiedVerifier_V21_PaymentVerified)
+  # These capture the "real" fiat payment details which may differ from signaled values
+  # for partial payments or wrong currency scenarios
+  paymentAmount: BigInt              # Actual fiat amount paid (may be partial)
+  paymentCurrency: String            # Actual currency paid (may differ from fiatCurrency)
+  paymentTimestamp: BigInt           # When payment was made (from proof)
+  paymentId: String                  # External payment ID (platform-specific)
+
+  # Released USDC amount (from Escrow_V21_FundsUnlockedAndTransferred)
+  # May differ from signaled `amount` for partial payments
+  releasedAmount: BigInt             # Actual USDC released (gross, before protocol fees)
+
+  # Net USDC received by taker (from Orchestrator_V21_IntentFulfilled)
+  # This is after protocol and referrer fees are deducted
+  takerAmountNetFees: BigInt         # Actual USDC taker received (net, after fees)
+
+  # V2.2 manager fee snapshot (set via IntentManagerFeeSnapshotted)
+  rateManagerId: String              # Snapshotted delegated manager id for this intent
+  managerFee: BigInt                 # Snapshotted manager fee rate in 1e18 precision
+  managerFeeRecipient: String        # Recipient that receives the manager fee on release
+  managerFeeAmount: BigInt           # Signal-time estimate: intent.amount * managerFee / 1e18
+  realizedManagerFeeAmount: BigInt   # Release-time realized fee: releasedAmount * managerFee / 1e18
+
+  # Referral fee distribution (set via IntentReferralFeeDistributed at fulfill time)
+  totalReferralFeeAmount: BigInt     # Sum of all referral fee USDC amounts distributed at fulfill
+}
+
+type ReferralFeeDistribution {
+  id: ID!              # chainId_intentHash_feeRecipient
+  chainId: Int!
+  intentHash: String!
+  intentId: String! @index    # FK -> Intent.id (chainId_intentHash)
+  feeRecipient: String!
+  feeAmount: BigInt!           # Actual USDC amount distributed to this recipient
+  txHash: String!
+  timestamp: BigInt!
+}
+
+# Per-owner aggregates used by Curator to compute tiers (v0: stats only)
+type TakerStats {
+  id: ID!              # chainId_owner (owner lowercased)
+  chainId: Int!
+  owner: String!
+
+  # Lifetime counters
+  lifetimeSignaledCount: Int!
+  lifetimeFulfilledCount: Int!
+  lifetimeManualReleaseCount: Int!
+  lifetimePruneCount: Int!
+  totalCancelledVolume: BigInt!
+  totalFulfilledVolume: BigInt!
+  lockScore: BigInt!
+
+  # Current state
+  lastIntentAt: BigInt
+  lastFulfilledAt: BigInt
+  firstSeenAt: BigInt
+
+  # Metadata
+  updatedAt: BigInt!
+}
+
+type MakerStats {
+  id: ID!              # chainId_maker (maker lowercased)
+  chainId: Int!
+  maker: String!
+
+  totalAmountTaken: BigInt!
+  grossDeposited: BigInt!
+  totalWithdrawn: BigInt!
+  outstandingIntentAmount: BigInt!
+
+  activeDepositCount: Int!
+  totalDepositCount: Int!
+
+  fulfilledIntents: Int!
+  prunedIntents: Int!
+  signaledIntents: Int!
+  totalIntents: Int!
+  manualReleaseCount: Int!
+
+  successRateBps: Int!
+  realizedProfitUsdCents: BigInt!
+  aprBps: Int
+
+  firstSeenAt: BigInt
+  updatedAt: BigInt!
+}
+
+type MakerPlatformStats {
+  id: ID!              # chainId_maker_paymentMethodHash
+  chainId: Int!
+  maker: String!
+  paymentMethodHash: String!
+
+  totalAmountTaken: BigInt!
+  fulfilledIntents: Int!
+  prunedIntents: Int!
+  manualReleaseCount: Int!
+  realizedProfitUsdCents: BigInt!
+  computedProfitSnapshots: Int!
+  updatedAt: BigInt!
+}
+
+type MakerCurrencyStats {
+  id: ID!              # chainId_maker_currencyCode
+  chainId: Int!
+  maker: String!
+  currencyCode: String!
+
+  totalAmountTaken: BigInt!
+  fulfilledIntents: Int!
+  prunedIntents: Int!
+  manualReleaseCount: Int!
+  updatedAt: BigInt!
+}
+
+type PriceSnapshot {
+  id: ID!              # currencyCode_timestampHour
+  currencyCode: String!
+  timestampDay: BigInt!
+  rateUsd: BigInt!
+  ratePrecision: Int!
+  provider: String!
+  source: String!
+  status: PriceSnapshotStatus!
+  effectiveAt: BigInt!
+  retrievedAt: BigInt!
+  createdAt: BigInt!
+  updatedAt: BigInt!
+}
+
+type MakerProfitSnapshot {
+  id: ID!              # intentId
+  chainId: Int!
+  maker: String!
+  intentId: String!
+  depositId: String!
+  fiatCurrency: String!
+  quoteConversionRate: BigInt!
+  oracleRate: BigInt
+  spreadBps: Int
+  amount: BigInt!
+  notionalFiatUsdCents: BigInt
+  feeUsd: BigInt
+  realizedProfitUsdCents: BigInt
+  priceSnapshotId: String
+  status: ProfitStatus!
+  createdAt: BigInt!
+  updatedAt: BigInt!
+}
+
+type RateManager {
+  id: ID!              # chainId_rateManagerAddress_rateManagerId
+  chainId: Int!
+  rateManagerAddress: String! @index
+  rateManagerId: String! @index
+  manager: String!
+  feeRecipient: String!
+  maxFee: BigInt!
+  fee: BigInt!
+  minLiquidity: BigInt!
+  name: String
+  uri: String
+  createdAt: BigInt!
+  updatedAt: BigInt!
+}
+
+type RateManagerRate {
+  id: ID!              # chainId_rateManagerAddress_rateManagerId_paymentMethodHash_currencyCode
+  chainId: Int!
+  rateManagerAddress: String! @index
+  rateManagerId: String! @index
+  paymentMethodHash: String!
+  currencyCode: String!
+  managerRate: BigInt!
+  updatedAt: BigInt!
+}
+
+type ManagerAggregateStats {
+  id: ID!              # chainId_rateManagerAddress_rateManagerId
+  chainId: Int!
+  rateManagerAddress: String! @index
+  rateManagerId: String! @index
+  manager: String!
+  totalFilledVolume: BigInt!
+  totalFeeAmount: BigInt!
+  totalPnlUsdCents: BigInt!
+  fulfilledIntents: Int!
+  currentDelegatedBalance: BigInt!
+  currentDelegatedDeposits: Int!
+  firstSeenAt: BigInt
+  updatedAt: BigInt!
+}
+
+type ManagerDailySnapshot {
+  id: ID!              # chainId_rateManagerAddress_rateManagerId_dayTimestamp
+  chainId: Int!
+  rateManagerAddress: String! @index
+  rateManagerId: String! @index
+  dayTimestamp: BigInt! @index
+  tvl: BigInt!
+  delegatedDeposits: Int!
+  dailyVolume: BigInt!
+  dailyFees: BigInt!
+  dailyPnlUsdCents: BigInt!
+  dailyFulfilledIntents: Int!
+  cumulativeVolume: BigInt!
+  cumulativeFees: BigInt!
+  cumulativePnlUsdCents: BigInt!
+  cumulativeFulfilledIntents: Int!
+  updatedAt: BigInt!
+}
+
+type DepositFundActivity {
+  id: ID!                        # txHash_logIndex
+  chainId: Int!
+  depositId: String! @index      # FK -> Deposit.id
+  depositor: String!
+  activityType: String! @index   # DEPOSIT_RECEIVED | FUNDS_ADDED | WITHDRAWN | CLOSED
+  amount: BigInt!
+  blockNumber: BigInt!
+  timestamp: BigInt! @index
+  txHash: String!
+}
+
+type DepositDailySnapshot {
+  id: ID!                        # depositId_dayTimestamp
+  chainId: Int!
+  depositId: String! @index      # FK -> Deposit.id
+  depositor: String!
+  dayTimestamp: BigInt! @index
+  remainingDeposits: BigInt!
+  outstandingIntentAmount: BigInt!
+  totalAmountTaken: BigInt!
+  totalWithdrawn: BigInt!
+  signaledIntents: Int!
+  fulfilledIntents: Int!
+  prunedIntents: Int!
+  successRateBps: Int!
+  dailyVolume: BigInt!           # USDC taken via fulfillments that day
+  dailyPnlUsdCents: BigInt!      # Realized profit that day
+  cumulativeVolume: BigInt!
+  cumulativePnlUsdCents: BigInt!
+  updatedAt: BigInt!
+}
+
+type ManagerStats {
+  id: ID!              # chainId_rateManagerAddress_rateManagerId_depositId
+  chainId: Int!
+  rateManagerAddress: String! @index
+  rateManagerId: String! @index
+  depositId: String! @index
+  depositor: String!
+  currentDelegatedBalance: BigInt!
+  totalAmountTaken: BigInt!
+  totalWithdrawn: BigInt!
+  fulfilledIntents: Int!
+  prunedIntents: Int!
+  successRateBps: Int!
+  updatedAt: BigInt!
+}
+
+"""
+Denormalized view that joins Deposit, MethodCurrency, and DepositPaymentMethod for rate-first quoting.
+"""
+type QuoteCandidate {
+  id: ID!                     # escrowAddress_depositId_paymentMethodHash_currencyCode
+  chainId: Int!               # Chain where the quoteable deposit lives
+  depositIdOnContract: BigInt! # Raw on-chain deposit id
+  depositId: String! @index   # Foreign key to Deposit.id
+  escrowAddress: String!      # Escrow address holding the deposit
+  depositor: String!          # Maker address that owns the deposit
+  token: String!              # ERC20 token address being sold
+  paymentMethodHash: String!  # Payment method bytes32 hash
+  currencyCode: String!       # Fiat currency bytes32 hash
+  conversionRate: BigInt      # Final gross resolved rate copied from MethodCurrency
+  takerConversionRate: BigInt # Final taker-facing all-in rate copied from MethodCurrency
+  managerFee: BigInt          # 1e18 manager fee rate applied separately at fulfillment
+  availableTokenAmount: BigInt! # Maker liquidity currently available for new intents
+  maxTokenAvailablePerIntent: BigInt!  # min(availableTokenAmount, intentAmountMax) for nearby token quote ordering
+  maxFiatAvailablePerIntent: BigInt!   # maxTokenAvailablePerIntent converted using takerConversionRate
+  maxQuoteableFiat: BigInt!   # availableTokenAmount converted using takerConversionRate
+  intentAmountMin: BigInt!    # Minimum token amount the maker will accept per intent
+  intentAmountMax: BigInt!    # Maximum token amount the maker will accept per intent
+  successRateBps: Int!        # Maker success rate for deposit-level filtering
+  payeeDetailsHash: String!   # Hashed payee details required for verification
+  intentGatingService: String # Optional gating service that must authorize takers
+  isActive: Boolean!          # Whether this tuple is currently quoteable for takers
+  hasMinLiquidity: Boolean!   # Whether availableTokenAmount is at least intentAmountMin
+  minFiatSupported: BigInt!   # intentAmountMin converted using takerConversionRate
+  maxFiatSupported: BigInt!   # intentAmountMax converted using takerConversionRate
+  maxFiatAvail: BigInt!       # availableTokenAmount converted using takerConversionRate
+  updatedAt: BigInt!          # Last time the denormalized row was refreshed
 }