@zkp2p/indexer-schema 0.2.0 → 0.2.3

package/dist/types.d.ts

@@ -1,379 +1,888 @@
 // Auto-generated from schema/domain.graphql
 
 export enum DepositStatus {
+  /** Deposit can still participate in the maker lifecycle. Whether it is currently quoteable also depends on `acceptingIntents`, remaining liquidity, payment-method activity, and a non-zero resolved rate. */
   ACTIVE = 'ACTIVE',
+  /** Deposit has been explicitly closed on-chain. Quote candidates for closed deposits are deleted. */
   CLOSED = 'CLOSED',
 }
 
 export enum IntentStatus {
+  /** Intent exists and funds may be locked, but settlement is not final yet. */
   SIGNALED = 'SIGNALED',
+  /** Intent completed normally. */
   FULFILLED = 'FULFILLED',
+  /** Intent was cancelled/unlocked on-chain. */
   PRUNED = 'PRUNED',
+  /** Funds were released through the manual-release path rather than the normal verifier path. */
   MANUALLY_RELEASED = 'MANUALLY_RELEASED',
 }
 
 export enum PriceSnapshotStatus {
+  /** Snapshot was fetched during normal live indexing. */
   LIVE = 'LIVE',
+  /** Snapshot was created during historical catch-up or another non-live backfill flow. */
   BACKFILL = 'BACKFILL',
 }
 
 export enum ProfitStatus {
+  /** Profit could be computed because a usable FX snapshot existed. */
   COMPUTED = 'COMPUTED',
+  /** Profit row exists, but the oracle side of the comparison was unavailable at write time. */
   PENDING = 'PENDING',
 }
 
+/**
+ * Canonical maker-owned escrow position. This is the root entity for most business queries. Deposit rows are created from deposit-received events and then mutated by funding, withdrawal, closing, intent lock/unlock, delegated-rate-manager, and oracle-resolution flows.
+ * 
+ * @id escrowAddress_depositId
+ * 
+ * **Relationships:**
+ * - Parent of `Intent`, `DepositPaymentMethod`, `MethodCurrency`, `DepositFundActivity`, and `DepositDailySnapshot`
+ * - Indirect source for `QuoteCandidate`
+ * - Optional many-to-one relationship to `RateManager`
+ * - Source record for `MakerStats`, `ManagerStats`, and manager aggregate balances
+ */
 export interface Deposit {
+  /** Canonical deposit key `escrowAddress_depositId`. This exists because raw on-chain `depositId` is not globally unique across escrows. */
   id: string;
+  /** Chain where the escrow contract lives. */
   chainId: number;
+  /** Escrow contract address that owns the deposit funds and scopes the deposit namespace. */
   escrowAddress: string;
+  /** Raw on-chain deposit identifier emitted by the escrow contract. */
   depositId: string;
+  /** Maker address that created and owns the deposit. */
   depositor: string;
+  /** ERC20 token being sold. In practice the indexer only materializes supported USDC addresses. */
   token: string;
+  /** Address currently allowed to manage deposit settings on behalf of the maker. */
   delegate: string;
+  /** Smallest token amount the maker will accept for a single intent. */
   intentAmountMin: string;
+  /** Largest token amount the maker will accept for a single intent. */
   intentAmountMax: string;
+  /** Explicit maker toggle. Quotes should be suppressed when this is `false` even if liquidity still exists. */
   acceptingIntents: boolean;
+  /** Coarse lifecycle state. `CLOSED` means the deposit was explicitly closed; it is stronger than merely having no liquidity. */
   status: DepositStatus;
+  /** Immediately available maker liquidity that can still be locked into new intents or withdrawn. */
   remainingDeposits: string;
+  /** Liquidity currently reserved by signaled intents that have not been fully resolved yet. */
   outstandingIntentAmount: string;
+  /** All-time amount that actually left the deposit to takers through fulfillment or manual release. */
   totalAmountTaken: string;
+  /** All-time amount withdrawn back to the maker through withdrawal events. */
   totalWithdrawn: string;
+  /** Total number of intents ever locked against the deposit. */
   totalIntents: number;
+  /** Count of intent-lock events seen for this deposit. */
   signaledIntents: number;
+  /** Count of intents that finished successfully or via manual release. */
   fulfilledIntents: number;
+  /** Count of intents that were unlocked/cancelled without fulfillment. */
   prunedIntents: number;
+  /** Deposit-level quality score in basis points. New deposits start at `10000`; later it tracks `fulfilled / total` in basis points. */
   successRateBps: number;
+  /** Block in which the deposit was first seen. */
   blockNumber: string;
+  /** Creation timestamp from the deposit-received event. */
   timestamp: string;
+  /** Transaction that created the deposit row. */
   txHash: string;
+  /** Timestamp of the most recent mutation to this deposit row. */
   updatedAt: string;
+  /** Optional delegated rate-manager identifier currently assigned to the deposit. */
   rateManagerId?: string;
+  /** Optional rate-manager contract address paired with `rateManagerId`. */
   rateManagerAddress?: string;
+  /** Timestamp when the current delegated manager assignment was applied. */
   delegatedAt?: string;
+  /** Optional address of the active whitelist pre-intent hook for private orderbooks. When set, only whitelisted takers can signal intents against this deposit. */
+  whitelistHookAddress?: string;
 }
 
+/**
+ * Deposit-scoped payment platform configuration. Each row says "this deposit accepts this payment-method hash, with these payee details and optional gating requirements."
+ * 
+ * @id escrowAddress_depositId_paymentMethodHash
+ * 
+ * **Relationships:**
+ * - Many-to-one to `Deposit` through `depositId`
+ * - Logical sibling of `MethodCurrency` on `(depositId, paymentMethodHash)`
+ * - One of the three source entities used to materialize `QuoteCandidate`
+ */
 export interface DepositPaymentMethod {
+  /** Composite key `escrowAddress_depositId_paymentMethodHash`. */
   id: string;
+  /** Chain where the parent deposit lives. */
   chainId: number;
+  /** Foreign-key string to `Deposit.id`. */
   depositId: string;
+  /** Raw on-chain deposit id copied for convenience and external correlation. */
   depositIdOnContract: string;
+  /** Canonical bytes32-like payment-method identifier used by contracts and quoting. */
   paymentMethodHash: string;
+  /** Optional external service address/string that must authorize or gate takers before they can use this method. */
   intentGatingService: string;
+  /** Hash of the off-chain payee details that the taker must prove they paid. */
   payeeDetailsHash: string;
+  /** Method-level on/off toggle. `QuoteCandidate.isActive` also depends on this value. */
   active: boolean;
 }
 
+/**
+ * Per `(deposit, payment method, fiat currency)` pricing configuration. This is the most important rate-resolution entity in the schema. It stores the depositor's fixed floor, delegated manager input, oracle configuration and snapshots, and the final resolved rate that quoting and validation use.
+ * 
+ * @id escrowAddress_depositId_paymentMethodHash_currencyCode
+ * 
+ * **Relationships:**
+ * - Many-to-one to `Deposit`
+ * - Logical many-to-one to `DepositPaymentMethod` by `(depositId, paymentMethodHash)`
+ * - Optional many-to-one to `RateManager` through `rateManagerId` plus the deposit's `rateManagerAddress`
+ * - Source record for `QuoteCandidate`; the quote row reuses this entity's identity
+ */
 export interface MethodCurrency {
+  /** Composite key `escrowAddress_depositId_paymentMethodHash_currencyCode`. */
   id: string;
+  /** Chain where the parent deposit lives. */
   chainId: number;
+  /** Foreign-key string to `Deposit.id`. */
   depositId: string;
+  /** Raw on-chain deposit id for cross-checking with contract logs. */
   depositIdOnContract: string;
+  /** Payment-method component of the tuple. */
   paymentMethodHash: string;
+  /** Fiat currency component of the tuple. */
   currencyCode: string;
+  /** Maker-defined fixed floor for the tuple. In legacy flows this can also be the directly used static rate. */
   minConversionRate: string;
+  /** Delegated manager quote before floor enforcement and before manager fee is applied. */
   managerRate?: string;
+  /** Delegated manager fee rate in 1e18 precision. This does not lower `conversionRate`; it is turned into a taker-facing markup when computing `takerConversionRate`. */
   managerFee?: string;
+  /** Final gross resolved rate used for intent validation and contract-aligned quote logic. */
   conversionRate?: string;
+  /** Final all-in rate shown to takers. In delegated mode this incorporates manager fee on top of the gross rate. */
   takerConversionRate?: string;
+  /** Resolution reason for `conversionRate`, such as `MANAGER`, `ORACLE`, `ESCROW_FLOOR`, `MANAGER_DISABLED`, `ORACLE_HALTED`, or `NO_FLOOR`. */
   rateSource?: string;
+  /** Delegated manager id that supplied the current delegated rate, if any. */
   rateManagerId?: string;
+  /** Oracle adapter contract address used to interpret `adapterConfig`. */
   adapter?: string;
+  /** Encoded adapter config bytes stored exactly as emitted. */
   adapterConfig?: string;
+  /** Resolved oracle feed address or feed id after decoding the adapter config. */
   feed?: string;
+  /** Feed decimals used to normalize oracle answers into the shared 1e18 rate format. */
   feedDecimals?: number;
+  /** Maker-configured markup applied to raw oracle output before final floor/manager resolution. */
   spreadBps?: number;
+  /** Maximum acceptable oracle age in seconds before the tuple is considered stale. */
   maxStaleness?: string;
+  /** Whether the oracle answer must be inverted before being converted into the shared rate representation. */
   invert?: boolean;
+  /** Raw oracle-derived rate before spread markup. */
   oracleRate?: string;
+  /** Oracle rate after applying `spreadBps`. */
   effectiveOracleRate?: string;
+  /** Timestamp of the latest accepted oracle datapoint used by this row. */
   lastOracleUpdatedAt?: string;
+  /** Decoded oracle kind, currently `oracle_chainlink`, `oracle_pyth`, or `oracle_unknown`. */
   kind?: string;
 }
 
+/**
+ * Canonical taker intent row. An `Intent` starts when the taker signals intent and ends in fulfillment or prune. This entity intentionally separates on-chain lifecycle (`status`) from off-chain expiry reconciliation (`isExpired`).
+ * 
+ * @id chainId_intentHash
+ * 
+ * **Relationships:**
+ * - Many-to-one to `Deposit`
+ * - Parent of `ReferralFeeDistribution`
+ * - Feeds `TakerStats`, maker stats rollups, profit snapshots, and manager aggregates
+ */
 export interface Intent {
+  /** Canonical key `chainId_intentHash`. */
   id: string;
+  /** Raw on-chain intent hash. */
   intentHash: string;
+  /** Contract address that coordinated the intent. In legacy v2 this is effectively the escrow address; in newer flows it is the orchestrator. */
   orchestratorAddress: string;
+  /** Foreign-key string to `Deposit.id`. */
   depositId: string;
+  /** Verifier contract or address associated with the payment proof. In v21 it is updated again when payment verification arrives. */
   verifier: string;
+  /** Payment-method hash associated with the intent. Optional because some legacy flows populate it indirectly. */
   paymentMethodHash?: string;
+  /** Taker wallet that owns the intent. */
   owner: string;
+  /** Recipient address for the released token payout. */
   toAddress: string;
+  /** Token amount signaled for the intent. This is the nominal amount, not necessarily the realized release amount. */
   amount: string;
+  /** Fiat currency signaled at quote time. */
   fiatCurrency: string;
+  /** Quote-time rate captured on the intent. */
   conversionRate: string;
+  /** On-chain lifecycle state only. This does not encode off-chain expiry reconciliation. */
   status: IntentStatus;
+  /** Off-chain reconciler flag that says the lock has timed out and liquidity was already unlocked off-chain. An intent can be `status = SIGNALED` and `isExpired = true` at the same time. */
   isExpired: boolean;
+  /** Transaction that created/signaled the intent. */
   signalTxHash: string;
+  /** Signal timestamp taken from the emitted event/proof context. */
   signalTimestamp: string;
+  /** Transaction that fulfilled or manually released the intent. */
   fulfillTxHash?: string;
+  /** Timestamp of fulfillment/manual release. */
   fulfillTimestamp?: string;
+  /** Transaction that pruned/unlocked the intent. */
   pruneTxHash?: string;
+  /** Timestamp of prune/unlock. */
   pruneTimestamp?: string;
+  /** Canonical expiry timestamp used by the block reconciler. It is refined by lock/extend events after the signal event. */
   expiryTime: string;
+  /** Last mutation timestamp for this intent row. */
   updatedAt: string;
+  /** Actual fiat amount proven by the verifier. This may differ from `amount` in partial-payment scenarios. */
   paymentAmount?: string;
+  /** Actual fiat currency proven by the verifier. This may differ from `fiatCurrency`. */
   paymentCurrency?: string;
+  /** Timestamp contained in the verified payment proof. */
   paymentTimestamp?: string;
+  /** External payment identifier from the payment rail/provider. */
   paymentId?: string;
+  /** Gross token amount released from escrow before protocol or referral fees. May differ from `amount`. */
   releasedAmount?: string;
+  /** Net token amount actually received by the taker after protocol and referrer deductions. */
   takerAmountNetFees?: string;
+  /** Snapshotted delegated manager id relevant to this intent, if a manager fee applied. */
   rateManagerId?: string;
+  /** Snapshotted manager fee rate in 1e18 precision. */
   managerFee?: string;
+  /** Address that receives the manager fee on settlement. */
   managerFeeRecipient?: string;
+  /** Signal-time fee estimate based on the signaled intent amount. */
   managerFeeAmount?: string;
+  /** Release-time manager fee based on the actual released amount. */
   realizedManagerFeeAmount?: string;
+  /** Sum of all `ReferralFeeDistribution.feeAmount` rows written for this intent. */
   totalReferralFeeAmount?: string;
 }
 
+/**
+ * Per-recipient referral-fee settlement rows for v2.2. The `Intent` stores the aggregate; this entity preserves recipient-level detail.
+ * 
+ * @id chainId_intentHash_feeRecipient
+ * 
+ * **Relationships:**
+ * - Many-to-one to `Intent` through `intentId`
+ */
 export interface ReferralFeeDistribution {
+  /** Composite key `chainId_intentHash_feeRecipient`. */
   id: string;
+  /** Chain where the parent intent settled. */
   chainId: number;
+  /** Raw on-chain intent hash. */
   intentHash: string;
+  /** Foreign-key string to `Intent.id`. */
   intentId: string;
+  /** Address that received this referral-fee slice. */
   feeRecipient: string;
+  /** Actual token amount distributed to `feeRecipient`. */
   feeAmount: string;
+  /** Transaction that emitted the distribution event. */
   txHash: string;
+  /** Settlement timestamp for this distribution row. */
   timestamp: string;
 }
 
+/**
+ * Per-owner behavioral aggregate. This row is updated from signaled, fulfilled/manual-release, and prune flows. In v21 it also carries a `lockScore` penalty based on how long cancelled intents kept liquidity locked.
+ * 
+ * @id chainId_owner (owner lowercased)
+ * 
+ * **Relationships:**
+ * - Implicit many-to-one from all `Intent` rows whose `owner` matches `TakerStats.owner`
+ */
 export interface TakerStats {
+  /** Composite key `chainId_owner`, with the owner lowercased. */
   id: string;
+  /** Chain on which the taker activity occurred. */
   chainId: number;
+  /** Lowercased taker address used as the aggregation key. */
   owner: string;
+  /** Number of intents ever signaled by this taker. */
   lifetimeSignaledCount: number;
+  /** Number of non-manual intents that fulfilled successfully. */
   lifetimeFulfilledCount: number;
+  /** Number of intents that ended via manual release. */
   lifetimeManualReleaseCount: number;
+  /** Number of intents that were pruned/cancelled. Same-tx prune-then-fulfill cases are rolled back. */
   lifetimePruneCount: number;
+  /** Sum of token amount from cancelled/pruned intents, with rollback if a same-tx prune later fulfills. */
   totalCancelledVolume: string;
+  /** Sum of token amount from fulfilled/manual-release intents. */
   totalFulfilledVolume: string;
+  /** Penalty-style score derived from cancelled intent lock duration. Currently meaningful only in the v21 path. */
   lockScore: string;
+  /** Timestamp of the taker's most recent intent signal. */
   lastIntentAt?: string;
+  /** Timestamp of the taker's most recent fulfillment/manual release. */
   lastFulfilledAt?: string;
+  /** Timestamp of the taker's first observed intent. */
   firstSeenAt?: string;
+  /** Last time this aggregate row changed. */
   updatedAt: string;
 }
 
+/**
+ * Per-maker aggregate across every deposit owned by the maker on a chain. This is deposit-derived state plus realized-profit rollups.
+ * 
+ * @id chainId_maker (maker lowercased)
+ * 
+ * **Relationships:**
+ * - Implicit aggregation over all `Deposit` rows where `Deposit.depositor = MakerStats.maker`
+ * - Parent summary for `MakerPlatformStats` and `MakerCurrencyStats`
+ */
 export interface MakerStats {
+  /** Composite key `chainId_maker`, with maker lowercased in the id. */
   id: string;
+  /** Chain on which the maker operates. */
   chainId: number;
+  /** Maker/depositor address used as the aggregation key. */
   maker: string;
+  /** Sum of `Deposit.totalAmountTaken` across the maker's deposits. */
   totalAmountTaken: string;
+  /** All-time gross capital committed by the maker, derived per deposit as `remaining + outstanding + taken + withdrawn`. */
   grossDeposited: string;
+  /** Sum of maker withdrawals across all deposits. */
   totalWithdrawn: string;
+  /** Sum of liquidity currently locked in active intents across all deposits. */
   outstandingIntentAmount: string;
+  /** Number of deposits that are both `ACTIVE` and `acceptingIntents = true`. */
   activeDepositCount: number;
+  /** Number of deposit rows ever created for the maker. */
   totalDepositCount: number;
+  /** Sum of `Deposit.fulfilledIntents` across the maker's deposits. */
   fulfilledIntents: number;
+  /** Sum of `Deposit.prunedIntents` across the maker's deposits. */
   prunedIntents: number;
+  /** Sum of `Deposit.signaledIntents` across the maker's deposits. */
   signaledIntents: number;
+  /** Sum of `Deposit.totalIntents` across the maker's deposits. */
   totalIntents: number;
+  /** Number of maker fills that happened through manual release. */
   manualReleaseCount: number;
+  /** Maker-level fulfillment rate in basis points, derived from aggregate `fulfilledIntents / totalIntents`. */
   successRateBps: number;
+  /** Sum of computed realized profit across all maker profit snapshots. */
   realizedProfitUsdCents: string;
+  /** Reserved APR-style metric. It is present in the schema but not currently maintained by handlers. */
   aprBps?: number;
+  /** Timestamp of the maker's earliest observed deposit. */
   firstSeenAt?: string;
+  /** Last time the aggregate changed. */
   updatedAt: string;
 }
 
+/**
+ * Per-maker, per-payment-method aggregate. This lets consumers break a maker's business down by payment rail or method hash.
+ * 
+ * @id chainId_maker_paymentMethodHash
+ * 
+ * **Relationships:**
+ * - Implicit aggregation over intents/fills for one maker and one `paymentMethodHash`
+ */
 export interface MakerPlatformStats {
+  /** Composite key `chainId_maker_paymentMethodHash`. */
   id: string;
+  /** Chain on which the activity occurred. */
   chainId: number;
+  /** Maker address. */
   maker: string;
+  /** Payment-method aggregation dimension. */
   paymentMethodHash: string;
+  /** Sum of fulfilled/manual-release volume for this maker-method pair. */
   totalAmountTaken: string;
+  /** Count of fulfilled/manual-release intents for this pair. */
   fulfilledIntents: number;
+  /** Count of pruned intents for this pair. */
   prunedIntents: number;
+  /** Count of manual-release fills for this pair. */
   manualReleaseCount: number;
+  /** Sum of realized profit allocated to this maker-method pair. */
   realizedProfitUsdCents: string;
+  /** Number of profit snapshots that successfully contributed realized profit to this pair. */
   computedProfitSnapshots: number;
+  /** Last time the row changed. */
   updatedAt: string;
 }
 
+/**
+ * Per-maker, per-fiat-currency aggregate.
+ * 
+ * @id chainId_maker_currencyCode
+ * 
+ * **Relationships:**
+ * - Implicit aggregation over intents/fills for one maker and one fiat currency
+ */
 export interface MakerCurrencyStats {
+  /** Composite key `chainId_maker_currencyCode`. */
   id: string;
+  /** Chain on which the activity occurred. */
   chainId: number;
+  /** Maker address. */
   maker: string;
+  /** Fiat-currency aggregation dimension. */
   currencyCode: string;
+  /** Sum of fulfilled/manual-release volume for this maker-currency pair. */
   totalAmountTaken: string;
+  /** Count of fulfilled/manual-release intents for this pair. */
   fulfilledIntents: number;
+  /** Count of pruned intents for this pair. */
   prunedIntents: number;
+  /** Count of manual releases for this pair. */
   manualReleaseCount: number;
+  /** Last time the row changed. */
   updatedAt: string;
 }
 
+/**
+ * Daily FX snapshot used to translate local-fiat quote rates into a USD-denominated profitability view.
+ * 
+ * @id currencyCode_timestampHour
+ * 
+ * **Relationships:**
+ * - Referenced by `MakerProfitSnapshot.priceSnapshotId`
+ * - Used indirectly by manager aggregate PnL computation
+ */
 export interface PriceSnapshot {
+  /** Composite key `currencyCode_timestampDay`. */
   id: string;
+  /** Normalized fiat currency code of the quote being converted to USD. */
   currencyCode: string;
+  /** Start-of-day UTC bucket in seconds. */
   timestampDay: string;
+  /** Provider-supplied fiat-to-USD conversion rate in provider precision. */
   rateUsd: string;
+  /** Precision/scaling factor associated with `rateUsd`. */
   ratePrecision: number;
+  /** Upstream provider name used to fetch the quote. */
   provider: string;
+  /** Source string or provider endpoint label. */
   source: string;
+  /** Whether this snapshot came from live indexing or backfill. */
   status: PriceSnapshotStatus;
+  /** Timestamp at which the provider says the quote is valid/effective. */
   effectiveAt: string;
+  /** Timestamp when the indexer fetched the quote. */
   retrievedAt: string;
+  /** First time this snapshot row was written. */
   createdAt: string;
+  /** Last time this snapshot row was written. Usually equal to `createdAt`. */
   updatedAt: string;
 }
 
+/**
+ * Per-intent realized-profit record for makers. This is the bridge between intent settlement and USD-denominated reporting.
+ * 
+ * @id intentId
+ * 
+ * **Relationships:**
+ * - One row per settled `Intent` (`id = intentId`)
+ * - Many-to-one to `Deposit`
+ * - Optional many-to-one to `PriceSnapshot`
+ */
 export interface MakerProfitSnapshot {
+  /** Equal to `intentId`, enforcing one profit row per intent. */
   id: string;
+  /** Chain where the intent settled. */
   chainId: number;
+  /** Maker address that owned the deposit. */
   maker: string;
+  /** Foreign-key string to `Intent.id`. */
   intentId: string;
+  /** Foreign-key string to `Deposit.id`. */
   depositId: string;
+  /** Fiat currency used for the quote/profit comparison. */
   fiatCurrency: string;
+  /** Quote-time rate captured from the intent. */
   quoteConversionRate: string;
+  /** USD-derived market reference rate computed from the linked `PriceSnapshot`. */
   oracleRate?: string;
+  /** Basis-point difference between `quoteConversionRate` and `oracleRate`. */
   spreadBps?: number;
+  /** Token amount used for the profit calculation. */
   amount: string;
+  /** USD-cent value of the local-fiat notional implied by the quote. */
   notionalFiatUsdCents?: string;
+  /** Reserved fee field. It is currently written as zero. */
   feeUsd?: string;
+  /** Realized profit in USD cents. Can be negative. */
   realizedProfitUsdCents?: string;
+  /** Optional reference to the `PriceSnapshot` used to compute `oracleRate`. */
   priceSnapshotId?: string;
+  /** `COMPUTED` when an FX reference existed, `PENDING` otherwise. */
   status: ProfitStatus;
+  /** Timestamp when the profit row was created. */
   createdAt: string;
+  /** Last update timestamp for the profit row. */
   updatedAt: string;
 }
 
+/**
+ * Registry row for a delegated rate manager. A deposit can point at one of these via `(rateManagerAddress, rateManagerId)`.
+ * 
+ * @id chainId_rateManagerAddress_rateManagerId
+ * 
+ * **Relationships:**
+ * - Parent of `RateManagerRate`
+ * - Parent/source of `ManagerAggregateStats`, `ManagerDailySnapshot`, and `ManagerStats`
+ * - Optional target of deposit delegation
+ */
 export interface RateManager {
+  /** Composite key `chainId_rateManagerAddress_rateManagerId`. */
   id: string;
+  /** Chain where the manager contract exists. */
   chainId: number;
+  /** Rate-manager contract address. */
   rateManagerAddress: string;
+  /** On-contract manager identifier. */
   rateManagerId: string;
+  /** Account recognized as the logical manager/operator. */
   manager: string;
+  /** Account that receives manager fees on settlement. */
   feeRecipient: string;
+  /** Maximum allowed fee configured at manager creation. */
   maxFee: string;
+  /** Current fee rate in 1e18 precision. */
   fee: string;
+  /** Configured minimum liquidity threshold advertised by the manager contract. */
   minLiquidity: string;
+  /** Optional human-readable name. */
   name?: string;
+  /** Optional metadata URI. */
   uri?: string;
+  /** First-seen timestamp. */
   createdAt: string;
+  /** Last config update timestamp. */
   updatedAt: string;
 }
 
+/**
+ * Per-manager quote sheet. Each row is a manager-supplied rate for one payment-method/currency pair. Deposits delegated to that manager read these rows when resolving `MethodCurrency.conversionRate`.
+ * 
+ * @id chainId_rateManagerAddress_rateManagerId_paymentMethodHash_currencyCode
+ */
 export interface RateManagerRate {
+  /** Composite key `chainId_rateManagerAddress_rateManagerId_paymentMethodHash_currencyCode`. */
   id: string;
+  /** Chain where the manager contract exists. */
   chainId: number;
+  /** Manager contract address. */
   rateManagerAddress: string;
+  /** Manager identifier. */
   rateManagerId: string;
+  /** Payment-method dimension for the manager quote. */
   paymentMethodHash: string;
+  /** Fiat-currency dimension for the manager quote. */
   currencyCode: string;
+  /** Gross manager-provided rate before floor enforcement. */
   managerRate: string;
+  /** Timestamp of the last rate update event for this pair. */
   updatedAt: string;
 }
 
+/**
+ * Portfolio-level aggregate for one delegated rate manager. This is the top-level manager reporting row.
+ * 
+ * @id chainId_rateManagerAddress_rateManagerId
+ * 
+ * **Relationships:**
+ * - One-to-one logical summary for one `RateManager`
+ * - Source for `ManagerDailySnapshot`
+ * - Updated from delegated deposit balance changes and fulfilled intents
+ */
 export interface ManagerAggregateStats {
+  /** Same identity as the corresponding `RateManager.id`. */
   id: string;
+  /** Chain on which the manager operates. */
   chainId: number;
+  /** Manager contract address. */
   rateManagerAddress: string;
+  /** Manager identifier. */
   rateManagerId: string;
+  /** Manager account/operator. */
   manager: string;
+  /** Cumulative token volume filled across all delegated deposits. */
   totalFilledVolume: string;
+  /** Cumulative manager fee amount actually earned across fills. */
   totalFeeAmount: string;
+  /** Cumulative USD-cent PnL measured against daily FX snapshots. */
   totalPnlUsdCents: string;
+  /** Number of fulfilled delegated intents. */
   fulfilledIntents: number;
+  /** Current delegated TVL, computed as the sum of `remainingDeposits + outstandingIntentAmount` across delegated deposits. */
   currentDelegatedBalance: string;
+  /** Number of deposits currently delegated to this manager. */
   currentDelegatedDeposits: number;
+  /** First timestamp the manager aggregate was created. */
   firstSeenAt?: string;
+  /** Last time the aggregate changed. */
   updatedAt: string;
 }
 
+/**
+ * Daily bucketed snapshot for `ManagerAggregateStats`.
+ * 
+ * @id chainId_rateManagerAddress_rateManagerId_dayTimestamp
+ */
 export interface ManagerDailySnapshot {
+  /** Composite key `chainId_rateManagerAddress_rateManagerId_dayTimestamp`. */
   id: string;
+  /** Chain on which the manager operates. */
   chainId: number;
+  /** Manager contract address. */
   rateManagerAddress: string;
+  /** Manager identifier. */
   rateManagerId: string;
+  /** Start-of-day UTC bucket in seconds. */
   dayTimestamp: string;
+  /** End-of-update delegated balance for that day. */
   tvl: string;
+  /** Number of currently delegated deposits at snapshot time. */
   delegatedDeposits: number;
+  /** Volume filled during that day. */
   dailyVolume: string;
+  /** Manager fees earned during that day. */
   dailyFees: string;
+  /** Daily PnL in USD cents. */
   dailyPnlUsdCents: string;
+  /** Number of fulfilled intents on that day. */
   dailyFulfilledIntents: number;
+  /** Cumulative filled volume up to this snapshot. */
   cumulativeVolume: string;
+  /** Cumulative manager fees up to this snapshot. */
   cumulativeFees: string;
+  /** Cumulative PnL up to this snapshot. */
   cumulativePnlUsdCents: string;
+  /** Cumulative fulfilled-intent count up to this snapshot. */
   cumulativeFulfilledIntents: number;
+  /** Last mutation time for the day's bucket. */
   updatedAt: string;
 }
 
+/**
+ * Append-only normalized ledger of deposit funding activity. This is easier to query than replaying all raw event families.
+ * 
+ * @id txHash_logIndex
+ * 
+ * **Relationships:**
+ * - Many-to-one to `Deposit`
+ */
 export interface DepositFundActivity {
+  /** Composite key `txHash_logIndex`. */
   id: string;
+  /** Chain where the activity happened. */
   chainId: number;
+  /** Foreign-key string to `Deposit.id`. */
   depositId: string;
+  /** Maker address that owns the deposit. */
   depositor: string;
+  /** Normalized activity class: `DEPOSIT_RECEIVED`, `FUNDS_ADDED`, `WITHDRAWN`, or `CLOSED`. */
   activityType: string;
+  /** Token amount relevant to the activity. `CLOSED` can legitimately record zero amount. */
   amount: string;
+  /** Block number for the activity. */
   blockNumber: string;
+  /** Timestamp for the activity. */
   timestamp: string;
+  /** Transaction hash for the activity. */
   txHash: string;
 }
 
+/**
+ * Daily bucketed snapshot of one deposit's state and realized profitability.
+ * 
+ * @id depositId_dayTimestamp
+ * 
+ * **Relationships:**
+ * - Many-to-one to `Deposit`
+ * - Receives daily-volume and daily-PnL deltas from fulfillment flows
+ */
 export interface DepositDailySnapshot {
+  /** Composite key `depositId_dayTimestamp`. */
   id: string;
+  /** Chain where the deposit exists. */
   chainId: number;
+  /** Foreign-key string to `Deposit.id`. */
   depositId: string;
+  /** Maker address that owns the deposit. */
   depositor: string;
+  /** Start-of-day UTC bucket in seconds. */
   dayTimestamp: string;
+  /** Deposit liquidity available at the time of the last update to that bucket. */
   remainingDeposits: string;
+  /** Deposit liquidity currently locked in intents at the last update. */
   outstandingIntentAmount: string;
+  /** Cumulative taken volume at the last update. */
   totalAmountTaken: string;
+  /** Cumulative withdrawn volume at the last update. */
   totalWithdrawn: string;
+  /** Cumulative signal count at the last update. */
   signaledIntents: number;
+  /** Cumulative fulfillment count at the last update. */
   fulfilledIntents: number;
+  /** Cumulative prune count at the last update. */
   prunedIntents: number;
+  /** Deposit success rate at the last update. */
   successRateBps: number;
+  /** Volume taken during that day only. */
   dailyVolume: string;
+  /** Realized PnL accrued during that day only. */
   dailyPnlUsdCents: string;
+  /** All-time volume through the deposit as of this bucket. */
   cumulativeVolume: string;
+  /** All-time realized PnL through the deposit as of this bucket. */
   cumulativePnlUsdCents: string;
+  /** Last mutation time for the day's bucket. */
   updatedAt: string;
 }
 
+/**
+ * Per-deposit stats row for a delegated manager. Where `ManagerAggregateStats` is portfolio-level, `ManagerStats` is deposit-level attribution.
+ * 
+ * @id chainId_rateManagerAddress_rateManagerId_depositId
+ * 
+ * **Relationships:**
+ * - Many-to-one to `Deposit`
+ * - Many-to-one to `RateManager`
+ */
 export interface ManagerStats {
+  /** Composite key `chainId_rateManagerAddress_rateManagerId_depositId`. */
   id: string;
+  /** Chain on which the delegation exists. */
   chainId: number;
+  /** Manager contract address. */
   rateManagerAddress: string;
+  /** Manager identifier. */
   rateManagerId: string;
+  /** Foreign-key string to `Deposit.id`. */
   depositId: string;
+  /** Maker that owns the delegated deposit. */
   depositor: string;
+  /** Current delegated balance for this one deposit: `remainingDeposits + outstandingIntentAmount`. */
   currentDelegatedBalance: string;
+  /** Deposit's all-time taken amount while tracked under the manager. */
   totalAmountTaken: string;
+  /** Deposit's all-time withdrawn amount while tracked under the manager. */
   totalWithdrawn: string;
+  /** Deposit-level fulfillment count. */
   fulfilledIntents: number;
+  /** Deposit-level prune count. */
   prunedIntents: number;
+  /** Deposit-level success rate. */
   successRateBps: number;
+  /** Last mutation time for the row. */
   updatedAt: string;
 }
 
+/**
+ * Read-optimized quoting view. This is intentionally denormalized so curator/quote APIs do not need to join `Deposit`, `DepositPaymentMethod`, and `MethodCurrency` at request time.
+ * 
+ * @id escrowAddress_depositId_paymentMethodHash_currencyCode
+ * 
+ * **Relationships:**
+ * - Derived from exactly one `(Deposit, DepositPaymentMethod, MethodCurrency)` tuple
+ * - `id` intentionally equals the corresponding `MethodCurrency.id`
+ */
 export interface QuoteCandidate {
+  /** Same composite identity as the backing `MethodCurrency`: `escrowAddress_depositId_paymentMethodHash_currencyCode`. */
   id: string;
+  /** Chain where the quoteable deposit lives. */
   chainId: number;
+  /** Raw on-chain deposit id. */
   depositIdOnContract: string;
+  /** Foreign-key string to `Deposit.id`. */
   depositId: string;
+  /** Escrow contract address copied from `Deposit`. */
   escrowAddress: string;
+  /** Maker address copied from `Deposit`. */
   depositor: string;
+  /** Token address copied from `Deposit`. */
   token: string;
+  /** Payment-method hash copied from the tuple. */
   paymentMethodHash: string;
+  /** Fiat currency copied from the tuple. */
   currencyCode: string;
+  /** Final gross resolved rate copied from `MethodCurrency`. */
   conversionRate?: string;
+  /** Final all-in taker-facing rate copied from `MethodCurrency`. */
   takerConversionRate?: string;
+  /** Manager fee rate copied from `MethodCurrency`, defaulting to zero if absent. */
   managerFee?: string;
+  /** Current immediately available maker liquidity, copied from `Deposit.remainingDeposits`. */
   availableTokenAmount: string;
+  /** `min(availableTokenAmount, intentAmountMax)`, used for quote ordering and max-per-intent checks. */
   maxTokenAvailablePerIntent: string;
+  /** Fiat value of `maxTokenAvailablePerIntent` using the taker-facing rate. */
   maxFiatAvailablePerIntent: string;
+  /** Fiat value of the full currently available liquidity using the taker-facing rate. */
   maxQuoteableFiat: string;
+  /** Minimum quoteable token amount copied from `Deposit`. */
   intentAmountMin: string;
+  /** Maximum quoteable token amount copied from `Deposit`. */
   intentAmountMax: string;
+  /** Deposit-level success signal copied from `Deposit`. */
   successRateBps: number;
+  /** Hashed payee details copied from `DepositPaymentMethod`. */
   payeeDetailsHash: string;
+  /** Optional gating service copied from `DepositPaymentMethod`. */
   intentGatingService?: string;
+  /** Optional whitelist hook address denormalized from `Deposit`. When non-null, this deposit is private and only whitelisted takers can access it. */
+  whitelistHookAddress?: string;
+  /** Final quoteability flag. It is `true` only when the payment method is active, the deposit is accepting intents, and the taker-facing rate is non-zero. */
   isActive: boolean;
+  /** Whether `availableTokenAmount >= intentAmountMin`. */
   hasMinLiquidity: boolean;
+  /** Fiat value of `intentAmountMin` using the taker-facing rate. */
   minFiatSupported: string;
+  /** Fiat value of `intentAmountMax` using the taker-facing rate. */
   maxFiatSupported: string;
+  /** Fiat value of `availableTokenAmount` using the taker-facing rate. */
   maxFiatAvail: string;
+  /** Last time the denormalized row was recomputed. */
+  updatedAt: string;
+}
+
+/**
+ * Per-deposit taker whitelist entry for private orderbooks. Created when the `WhitelistPreIntentHook` contract emits a `TakerWhitelisted` event and the emitting hook matches the deposit's active `whitelistHookAddress`. Purged when the hook is rotated/cleared via `DepositWhitelistHookSet` or when the taker is explicitly removed.
+ * 
+ * @id escrowAddress_depositId_taker
+ * 
+ * **Relationships:**
+ * - Many-to-one to `Deposit` via `depositId`
+ */
+export interface WhitelistEntry {
+  /** Composite key `escrowAddress_depositId_taker` (all lowercased). */
+  id: string;
+  /** Chain where the deposit lives. */
+  chainId: number;
+  /** Address of the `WhitelistPreIntentHook` contract that emitted the event. */
+  hookAddress: string;
+  /** Escrow contract address scoping the deposit. */
+  escrowAddress: string;
+  /** Foreign-key string to `Deposit.id` (composite: `escrowAddress_depositId`). */
+  depositId: string;
+  /** Raw on-chain deposit identifier. */
+  depositIdOnContract: string;
+  /** Lowercased address of the whitelisted taker. */
+  taker: string;
+  /** Timestamp when the taker was first whitelisted. */
+  createdAt: string;
+  /** Timestamp of the most recent mutation to this entry. */
   updatedAt: string;
 }