# @zkp2p/indexer-schema

> GraphQL schema and TypeScript types for the ZKP2P on-chain indexer. Source of truth for all downstream consumers (curator, SDK, notification server).

ZKP2P is a peer-to-peer fiat-to-crypto exchange protocol on Base (chain 8453). Makers deposit USDC liquidity with conversion rates. Takers signal intents to buy, make off-chain fiat payments (Venmo, Wise, etc.), then submit TLS proofs to release escrowed funds on-chain.

## How to use this package

```ts
// TypeScript types for all indexed entities
import type { Deposit, Intent, QuoteCandidate, MethodCurrency } from '@zkp2p/indexer-schema';
import { DepositStatus, IntentStatus } from '@zkp2p/indexer-schema';

// Raw GraphQL SDL string
import { schemaSDL } from '@zkp2p/indexer-schema';

// For codegen configs: node_modules/@zkp2p/indexer-schema/dist/schema.graphql
```

## Reading Conventions

- `Deposit.id` is the canonical join key for deposit-scoped rows: `escrowAddress_depositId`.
- `Intent.id` is the canonical join key for intent-scoped rows: `chainId_intentHash`.
- `@derivedFrom` relationships exist only where the schema declares them. Most other relationships are implicit string joins.
- Amount fields are stored in the token's smallest unit. In practice this indexer is restricted to supported USDC deployments, so most token amounts are 6-decimal USDC amounts.
- Conversion-rate fields use 1e18 fixed-point precision unless noted otherwise.
- `BigInt` fields are serialized as **strings** (too large for JSON numbers).
- `Int` fields are **numbers**.
- Addresses and hashes are lowercase hex strings.
- Currency codes are bytes32 keccak hashes.
- Timestamps are Unix seconds as BigInt strings.
- Basis points: 10000 = 100%.

## Entity Relationship Map

```
Deposit (1)──────(N) DepositPaymentMethod
   │                        │
   │                        │ (shares paymentMethodHash)
   │                        │
   ├──(N) MethodCurrency ───┘  (1 per deposit × method × currency)
   │         │
   │         └── rates: minConversionRate, managerRate, conversionRate, takerConversionRate
   │             oracle: adapter, feed, oracleRate, effectiveOracleRate
   │
   ├──(N) Intent
   │         │── status: SIGNALED → FULFILLED | PRUNED | MANUALLY_RELEASED
   │         │── payment proof: paymentAmount, paymentCurrency, paymentId
   │         └── settlement: releasedAmount, takerAmountNetFees
   │
   ├──(N) DepositFundActivity  (append-only ledger)
   │
   └──(N) DepositDailySnapshot (daily rollup)

QuoteCandidate = denormalized join of Deposit + MethodCurrency + DepositPaymentMethod
                 (optimized for rate-first quoting queries)
OrderbookEntry = direct active QuoteCandidate projection
                 (optimized for orderbook/explorer display)

MakerStats ←── aggregated from Deposits + Intents (per maker address)
TakerStats ←── aggregated from Intents (per taker address)
TakerPlatformStats ←── per taker × payment method
MakerRolling90DayStats ←── per maker trailing 90 UTC days
MakerPlatformStats ←── per maker × payment method
MakerCurrencyStats ←── per maker × currency
MakerPeerPayStats / MakerPeerPayPlatformStats / MakerPeerPayRolling90DayStats
           ←── maker volume consumed by Peer Pay relayer takers (lifetime, per-rail, trailing 90d)
GlobalDailyActiveMaker ←── per-day per-maker presence (backs GlobalDailyStats.activeMakersCount)

RateManager (1)──(N) RateManagerRate (per method × currency)
     │
     ├──(N) ManagerStats (per deposit under this manager)
     ├──(1) ManagerAggregateStats (totals across all deposits)
     └──(N) ManagerDailySnapshot (daily TVL, volume, fees)

PriceSnapshot ←── daily FX rates (USD/EUR/GBP/etc.)
MakerProfitSnapshot ←── per-intent profit: quote rate vs oracle FX rate
ReferralFeeDistribution ←── per-intent referral fee breakdown
ReferralRecipientDepositorStats ←── per recipient × depositor cumulative referral fees
WhitelistEntry ←── per-deposit taker whitelist for private orderbooks
```

### Explicit Schema Edges

- `Deposit -> Intent` via `Intent.depositId` and `Deposit.intents @derivedFrom(field: "depositId")`
- `Deposit -> DepositPaymentMethod` via `DepositPaymentMethod.depositId`
- `Deposit -> MethodCurrency` via `MethodCurrency.depositId`
- `Deposit -> DepositFundActivity` via `DepositFundActivity.depositId`
- `Deposit -> DepositDailySnapshot` via `DepositDailySnapshot.depositId`

### Implicit Joins Used by Handlers and Consumers

- `DepositPaymentMethod <-> MethodCurrency` by `(depositId, paymentMethodHash)`
- `MethodCurrency <-> QuoteCandidate` by identical tuple identity; `QuoteCandidate.id` matches `MethodCurrency.id`
- `QuoteCandidate -> OrderbookEntry` by `(depositId, paymentPlatform, currencyCode)`; every active candidate maps directly to one row
- `Intent <-> ReferralFeeDistribution` by `ReferralFeeDistribution.intentId = Intent.id`
- `ReferralFeeDistribution -> ReferralRecipientDepositorStats` by `(chainId, feeRecipient, depositor)`
- `Deposit/Intent -> maker stats` by maker address (`Deposit.depositor`)
- `Intent -> taker stats` by taker address (`Intent.owner`)
- `Deposit/MethodCurrency/Intent -> rate-manager entities` by `(chainId, rateManagerAddress, rateManagerId)`
- `MakerProfitSnapshot -> PriceSnapshot` by `priceSnapshotId`

### Denormalized/Projection Entities

- `QuoteCandidate` is a read-optimized projection over `Deposit + DepositPaymentMethod + MethodCurrency`.
- `OrderbookEntry` is a direct projection of an active `QuoteCandidate`, shaped for orderbook/explorer display.
- `MakerStats`, `MakerRolling90DayStats`, `MakerPeerPayStats`, `MakerPeerPayPlatformStats`, `MakerPeerPayRolling90DayStats`, `DailyPlatformVolume`, `PlatformDailyStats`, `GlobalDailyStats`, `GlobalDailyActiveMaker`, `MakerDailySnapshot`, `MakerPlatformStats`, `MakerCurrencyStats`, `TakerStats`, `TakerPlatformStats`, `ReferralRecipientDepositorStats`, `ManagerAggregateStats`, `ManagerStats`, `DepositDailySnapshot`, and `ManagerDailySnapshot` are aggregation/snapshot entities, not raw event mirrors.
- `GlobalDailyCursor`, `PlatformDailyCursor`, `MakerDailyCursor`, `ManagerDailyCursor`, `DepositDailyCursor`, and `DailyPlatformVolumeCursor` are prefix-state cursors used by handlers to maintain cumulative daily rows.
- `DailyCapitalSweepCursor` tracks the latest completed UTC day whose capital-day denominators were swept by the block handler.

## Enum Reference

### `DepositStatus`

- `ACTIVE`: 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.
- `CLOSED`: Deposit has been explicitly closed on-chain. Quote candidates for closed deposits are deleted.

### `IntentStatus`

- `SIGNALED`: Intent exists and funds may be locked, but settlement is not final yet.
- `FULFILLED`: Intent completed normally.
- `PRUNED`: Intent was cancelled/unlocked on-chain.
- `MANUALLY_RELEASED`: Funds were released through the manual-release path rather than the normal verifier path.

### `PriceSnapshotStatus`

- `LIVE`: Snapshot was fetched during normal live indexing.
- `BACKFILL`: Snapshot was created during historical catch-up or another non-live backfill flow.

### `ProfitStatus`

- `COMPUTED`: Profit could be computed because a usable FX snapshot existed.
- `PENDING`: Profit row exists, but the oracle side of the comparison was unavailable at write time.

## Domain Entities — Full Field Reference

### `Deposit`

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.

**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

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Canonical deposit key `escrowAddress_depositId`. This exists because raw on-chain `depositId` is not globally unique across escrows. |
| `chainId` | `number` | Chain where the escrow contract lives. |
| `escrowAddress` | `string` | Escrow contract address that owns the deposit funds and scopes the deposit namespace. |
| `depositId` | `string (BigInt)` | Raw on-chain deposit identifier emitted by the escrow contract. |
| `depositor` | `string` | Maker address that created and owns the deposit. |
| `token` | `string` | ERC20 token being sold. In practice the indexer only materializes supported USDC addresses. |
| `delegate` | `string` | Address currently allowed to manage deposit settings on behalf of the maker. |
| `intentAmountMin` | `string (BigInt)` | Smallest token amount the maker will accept for a single intent. |
| `intentAmountMax` | `string (BigInt)` | Largest token amount the maker will accept for a single intent. |
| `acceptingIntents` | `boolean` | Explicit maker toggle. Quotes should be suppressed when this is `false` even if liquidity still exists. |
| `status` | `DepositStatus` | Coarse lifecycle state. `CLOSED` means the deposit was explicitly closed; it is stronger than merely having no liquidity. |
| `remainingDeposits` | `string (BigInt)` | Immediately available maker liquidity that can still be locked into new intents or withdrawn. |
| `outstandingIntentAmount` | `string (BigInt)` | Liquidity currently reserved by signaled intents that have not been fully resolved yet. |
| `totalAmountTaken` | `string (BigInt)` | All-time amount that actually left the deposit to takers through fulfillment or manual release. |
| `totalWithdrawn` | `string (BigInt)` | All-time amount withdrawn back to the maker through withdrawal events. |
| `realizedProfitUsdCents` | `string (BigInt)` | Per-deposit lifetime sum of computed `MakerProfitSnapshot.realizedProfitUsdCents` values for this deposit. |
| `aprBps` | `number?` | Per-deposit lifetime gross realized APR in basis points (`realizedProfitUsdCents * 365 * 10000 / (avgTvlUsdCents * daysSinceDepositCreated)`, clamped to [0, 10_000_000]). |
| `totalIntents` | `number` | Total number of intents ever locked against the deposit. |
| `signaledIntents` | `number` | Count of intent-lock events seen for this deposit. |
| `fulfilledIntents` | `number` | Count of intents that finished successfully or via manual release. |
| `prunedIntents` | `number` | Count of intents that were unlocked/cancelled without fulfillment. |
| `successRateBps` | `number` | Deposit-level quality score in basis points. New deposits start at `10000`; later it tracks `fulfilled / total` in basis points. |
| `blockNumber` | `string (BigInt)` | Block in which the deposit was first seen. |
| `timestamp` | `string (BigInt)` | Creation timestamp from the deposit-received event. |
| `txHash` | `string` | Transaction that created the deposit row. |
| `updatedAt` | `string (BigInt)` | Timestamp of the most recent mutation to this deposit row. |
| `rateManagerId` | `string?` | Optional delegated rate-manager identifier currently assigned to the deposit. |
| `rateManagerAddress` | `string?` | Optional rate-manager contract address paired with `rateManagerId`. |
| `delegatedAt` | `string? (BigInt)` | Timestamp when the current delegated manager assignment was applied. |

**Balance identity:** `balance = remainingDeposits + outstandingIntentAmount`
**Gross deposited (all-time):** `remainingDeposits + outstandingIntentAmount + totalAmountTaken + totalWithdrawn`

### `DepositPaymentMethod`

Deposit-scoped payment platform configuration. Each row says "this deposit accepts this payment-method hash, with these payee details and optional gating requirements."

**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`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `escrowAddress_depositId_paymentMethodHash`. |
| `chainId` | `number` | Chain where the parent deposit lives. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `depositIdOnContract` | `string (BigInt)` | Raw on-chain deposit id copied for convenience and external correlation. |
| `paymentMethodHash` | `string` | Canonical bytes32-like payment-method identifier used by contracts and quoting. |
| `intentGatingService` | `string` | Optional external service address/string that must authorize or gate takers before they can use this method. |
| `payeeDetailsHash` | `string` | Hash of the off-chain payee details that the taker must prove they paid. |
| `active` | `boolean` | Method-level on/off toggle. `QuoteCandidate.isActive` also depends on this value. |

### `MethodCurrency`

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.

**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

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `escrowAddress_depositId_paymentMethodHash_currencyCode`. |
| `chainId` | `number` | Chain where the parent deposit lives. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `depositIdOnContract` | `string (BigInt)` | Raw on-chain deposit id for cross-checking with contract logs. |
| `paymentMethodHash` | `string` | Payment-method component of the tuple. |
| `currencyCode` | `string` | Fiat currency component of the tuple. |
| `minConversionRate` | `string (BigInt)` | Maker-defined fixed floor for the tuple. In legacy flows this can also be the directly used static rate. |
| `managerRate` | `string? (BigInt)` | Delegated manager quote before floor enforcement and before manager fee is applied. |
| `managerFee` | `string? (BigInt)` | Delegated manager fee rate in 1e18 precision. This does not lower `conversionRate`; it is turned into a taker-facing markup when computing `takerConversionRate`. |
| `conversionRate` | `string? (BigInt)` | Final gross resolved rate used for intent validation and contract-aligned quote logic. |
| `takerConversionRate` | `string? (BigInt)` | Final all-in rate shown to takers. In delegated mode this incorporates manager fee on top of the gross rate. |
| `rateSource` | `string?` | Resolution reason for `conversionRate`: `MANAGER` \| `ORACLE` \| `ESCROW_FLOOR` \| `MANAGER_DISABLED` \| `ORACLE_HALTED` \| `NO_FLOOR`. |
| `rateManagerId` | `string?` | Delegated manager id that supplied the current delegated rate, if any. |
| `adapter` | `string?` | Oracle adapter contract address used to interpret `adapterConfig`. |
| `adapterConfig` | `string?` | Encoded adapter config bytes stored exactly as emitted. |
| `feed` | `string?` | Resolved oracle feed address or feed id after decoding the adapter config. |
| `feedDecimals` | `number?` | Feed decimals used to normalize oracle answers into the shared 1e18 rate format. |
| `spreadBps` | `number?` | Maker-configured markup applied to raw oracle output before final floor/manager resolution. |
| `maxStaleness` | `string? (BigInt)` | Maximum acceptable oracle age in seconds before the tuple is considered stale. |
| `invert` | `boolean?` | Whether the oracle answer must be inverted before being converted into the shared rate representation. |
| `oracleRate` | `string? (BigInt)` | Raw oracle-derived rate before spread markup. |
| `effectiveOracleRate` | `string? (BigInt)` | Oracle rate after applying `spreadBps`. |
| `lastOracleUpdatedAt` | `string? (BigInt)` | Timestamp of the latest accepted oracle datapoint used by this row. |
| `kind` | `string?` | Decoded oracle kind, currently `oracle_chainlink`, `oracle_pyth`, or `oracle_unknown`. |

**Rate resolution order:** Manager rate (if delegated) → Oracle rate (if configured) → Escrow floor (minConversionRate). The `rateSource` field records which path was taken.

### `Intent`

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`).

**Relationships:**
- Many-to-one to `Deposit`
- Parent of `ReferralFeeDistribution`
- Feeds `TakerStats`, maker stats rollups, profit snapshots, and manager aggregates

**Lifecycle:** `SIGNALED` → `FULFILLED` | `PRUNED` | `MANUALLY_RELEASED`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Canonical key `chainId_intentHash`. |
| `intentHash` | `string` | Raw on-chain intent hash. |
| `orchestratorAddress` | `string` | Contract address that coordinated the intent. In legacy v2 this is effectively the escrow address; in newer flows it is the orchestrator. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `verifier` | `string` | Verifier contract or address associated with the payment proof. In v21 it is updated again when payment verification arrives. |
| `paymentMethodHash` | `string?` | Payment-method hash associated with the intent. Optional because some legacy flows populate it indirectly. |
| `owner` | `string` | Taker wallet that owns the intent. |
| `toAddress` | `string` | Recipient address for the released token payout. |
| `amount` | `string (BigInt)` | Token amount signaled for the intent. This is the nominal amount, not necessarily the realized release amount. |
| `fiatCurrency` | `string` | Fiat currency signaled at quote time. |
| `conversionRate` | `string (BigInt)` | Quote-time rate captured on the intent. |
| `status` | `IntentStatus` | On-chain lifecycle state only. This does not encode off-chain expiry reconciliation. |
| `isExpired` | `boolean` | 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. |
| `signalTxHash` | `string` | Transaction that created/signaled the intent. |
| `signalTimestamp` | `string (BigInt)` | Signal timestamp taken from the emitted event/proof context. |
| `fulfillTxHash` | `string?` | Transaction that fulfilled or manually released the intent. |
| `fulfillTimestamp` | `string? (BigInt)` | Timestamp of fulfillment/manual release. |
| `pruneTxHash` | `string?` | Transaction that pruned/unlocked the intent. |
| `pruneTimestamp` | `string? (BigInt)` | Timestamp of prune/unlock. |
| `expiryTime` | `string (BigInt)` | Canonical expiry timestamp used by the block reconciler. It is refined by lock/extend events after the signal event. |
| `updatedAt` | `string (BigInt)` | Last mutation timestamp for this intent row. |
| `paymentAmount` | `string? (BigInt)` | Actual fiat amount proven by the verifier. This may differ from `amount` in partial-payment scenarios. |
| `paymentCurrency` | `string?` | Actual fiat currency proven by the verifier. This may differ from `fiatCurrency`. |
| `paymentTimestamp` | `string? (BigInt)` | Timestamp contained in the verified payment proof. |
| `paymentId` | `string?` | External payment identifier from the payment rail/provider. |
| `releasedAmount` | `string? (BigInt)` | Gross token amount released from escrow before protocol or referral fees. May differ from `amount`. |
| `takerAmountNetFees` | `string? (BigInt)` | Net token amount actually received by the taker after protocol and referrer deductions. |
| `rateManagerId` | `string?` | Snapshotted delegated manager id relevant to this intent, if a manager fee applied. |
| `managerFee` | `string? (BigInt)` | Snapshotted manager fee rate in 1e18 precision. |
| `managerFeeRecipient` | `string?` | Address that receives the manager fee on settlement. |
| `managerFeeAmount` | `string? (BigInt)` | Signal-time fee estimate based on the signaled intent amount. |
| `realizedManagerFeeAmount` | `string? (BigInt)` | Release-time manager fee based on the actual released amount. |
| `totalReferralFeeAmount` | `string? (BigInt)` | Sum of all `ReferralFeeDistribution.feeAmount` rows written for this intent. |

### `ReferralFeeDistribution`

Per-recipient referral-fee settlement rows for v2.2. The `Intent` stores the aggregate; this entity preserves recipient-level detail.

**Relationships:**
- Many-to-one to `Intent` through `intentId`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_intentHash_feeRecipient`. |
| `chainId` | `number` | Chain where the parent intent settled. |
| `intentHash` | `string` | Raw on-chain intent hash. |
| `intentId` | `string` | Foreign-key string to `Intent.id`. |
| `feeRecipient` | `string` | Address that received this referral-fee slice. |
| `feeAmount` | `string (BigInt)` | Actual token amount distributed to `feeRecipient`. |
| `txHash` | `string` | Transaction that emitted the distribution event. |
| `timestamp` | `string (BigInt)` | Settlement timestamp for this distribution row. |

### `ReferralRecipientDepositorStats`

Per-recipient, per-depositor cumulative referral-fee aggregate used by the Curator earnings API. Rolls up every referral-fee slice paid to one `feeRecipient` that originated from one `depositor`'s intents, attributing referral earnings back to the maker that generated them.

**Relationships:**
- Aggregates many `ReferralFeeDistribution` rows sharing the same `feeRecipient` and originating `depositor`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_feeRecipient_depositor` (all lowercased). |
| `chainId` | `number` | Chain where the referral fees settled. |
| `feeRecipient` | `string` | Address that received the referral-fee slices. |
| `depositor` | `string` | Maker/depositor whose intents generated the fees. |
| `totalFeeAmount` | `string (BigInt)` | Cumulative referral fee in USDC base units (6 decimals). |
| `distributionCount` | `number` | Number of distribution events aggregated into this row. |
| `lastDistributedAt` | `string (BigInt)` | Latest block timestamp (unix seconds) across the aggregated distributions. |

### `WhitelistEntry`

Per-deposit taker whitelist entry for private orderbooks. Created when the `WhitelistPreIntentHook` contract emits `TakerWhitelisted` and the hook matches the deposit's active `whitelistHookAddress`. Purged when the hook is rotated/cleared or the taker is removed.

**Relationships:**
- Many-to-one to `Deposit` via `depositId`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `escrowAddress_depositId_taker` (all lowercased). |
| `chainId` | `number` | Chain where the deposit lives. |
| `hookAddress` | `string` | WhitelistPreIntentHook contract address that emitted the event. |
| `escrowAddress` | `string` | Escrow contract address. |
| `depositId` | `string` | FK to `Deposit.id` (composite: `escrowAddress_depositId`). |
| `depositIdOnContract` | `string (BigInt)` | Raw on-chain deposit identifier. |
| `taker` | `string` | Lowercased address of the whitelisted taker. |
| `createdAt` | `string (BigInt)` | Timestamp when taker was first whitelisted. |
| `updatedAt` | `string (BigInt)` | Timestamp of most recent mutation. |

### `QuoteCandidate`

Read-optimized quoting view. This is intentionally denormalized so curator/quote APIs do not need to join `Deposit`, `DepositPaymentMethod`, and `MethodCurrency` at request time.

**Relationships:**
- Derived from exactly one `(Deposit, DepositPaymentMethod, MethodCurrency)` tuple
- `id` intentionally equals the corresponding `MethodCurrency.id`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Same composite identity as the backing `MethodCurrency`: `escrowAddress_depositId_paymentMethodHash_currencyCode`. |
| `chainId` | `number` | Chain where the quoteable deposit lives. |
| `depositIdOnContract` | `string (BigInt)` | Raw on-chain deposit id. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `escrowAddress` | `string` | Escrow contract address copied from `Deposit`. |
| `depositor` | `string` | Maker address copied from `Deposit`. |
| `token` | `string` | Token address copied from `Deposit`. |
| `paymentMethodHash` | `string` | Payment-method hash copied from the tuple. |
| `currencyCode` | `string` | Fiat currency copied from the tuple. |
| `conversionRate` | `string? (BigInt)` | Final gross resolved rate copied from `MethodCurrency`. |
| `takerConversionRate` | `string? (BigInt)` | Final all-in taker-facing rate copied from `MethodCurrency`. |
| `managerFee` | `string? (BigInt)` | Manager fee rate copied from `MethodCurrency`, defaulting to zero if absent. |
| `availableTokenAmount` | `string (BigInt)` | Current immediately available maker liquidity, copied from `Deposit.remainingDeposits`. |
| `maxTokenAvailablePerIntent` | `string (BigInt)` | `min(availableTokenAmount, intentAmountMax)`, used for quote ordering and max-per-intent checks. |
| `maxFiatAvailablePerIntent` | `string (BigInt)` | Fiat value of `maxTokenAvailablePerIntent` using the taker-facing rate. |
| `maxQuoteableFiat` | `string (BigInt)` | Fiat value of the full currently available liquidity using the taker-facing rate. |
| `intentAmountMin` | `string (BigInt)` | Minimum quoteable token amount copied from `Deposit`. |
| `intentAmountMax` | `string (BigInt)` | Maximum quoteable token amount copied from `Deposit`. |
| `successRateBps` | `number` | Deposit-level success signal copied from `Deposit`. |
| `payeeDetailsHash` | `string` | Hashed payee details copied from `DepositPaymentMethod`. |
| `intentGatingService` | `string?` | Optional gating service copied from `DepositPaymentMethod`. |
| `isActive` | `boolean` | 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. |
| `hasMinLiquidity` | `boolean` | Whether `availableTokenAmount >= intentAmountMin`. |
| `minFiatSupported` | `string (BigInt)` | Fiat value of `intentAmountMin` using the taker-facing rate. |
| `maxFiatSupported` | `string (BigInt)` | Fiat value of `intentAmountMax` using the taker-facing rate. |
| `maxFiatAvail` | `string (BigInt)` | Fiat value of `availableTokenAmount` using the taker-facing rate. |
| `updatedAt` | `string (BigInt)` | Last time the denormalized row was recomputed. |

### `OrderbookEntry`

Read-optimized, materialized orderbook row. Like `QuoteCandidate` it denormalizes a `(Deposit, DepositPaymentMethod, MethodCurrency)` tuple, but it is shaped for orderbook/explorer display. Each active `QuoteCandidate` maps directly to one orderbook row; unsupported payment-method hashes are omitted.

**Relationships:**
- Materialized directly from the active `QuoteCandidate` for each `(depositId, paymentPlatform, currencyCode)` tuple

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite identity `depositId_paymentPlatform_currencyCode` (currency as its normalized hash). |
| `chainId` | `number` | Chain where the deposit lives. |
| `depositIdOnContract` | `string (BigInt)` | Raw on-chain deposit id. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `escrowAddress` | `string` | Escrow contract address copied from `Deposit`. |
| `depositor` | `string` | Maker address copied from `Deposit`. |
| `token` | `string` | Token address copied from `Deposit`. |
| `paymentMethodHash` | `string` | Normalized payment-method hash of the materialized candidate. |
| `paymentPlatform` | `string` | Active payment method name resolved from `paymentMethodHash`. |
| `currencyCode` | `string` | Normalized fiat currency hash for this row. |
| `currency` | `string` | Human-readable ISO currency code resolved from `currencyCode`. |
| `price` | `string (BigInt)` | Taker-facing all-in conversion rate (`takerConversionRate`, falling back to `conversionRate`). |
| `availableTokenAmount` | `string (BigInt)` | Currently available maker liquidity in token base units. |
| `availableFiatAmount` | `string (BigInt)` | Fiat value of available liquidity at the taker-facing price. |
| `intentAmountMin` | `string (BigInt)` | Minimum quoteable token amount copied from `Deposit`. |
| `intentAmountMax` | `string (BigInt)` | Maximum quoteable token amount copied from `Deposit`. |
| `minFiatSupported` | `string (BigInt)` | Fiat value of `intentAmountMin` at the taker-facing price. |
| `maxFiatSupported` | `string (BigInt)` | Fiat value of `intentAmountMax` at the taker-facing price. |
| `hasMinLiquidity` | `boolean` | Whether `availableTokenAmount >= intentAmountMin`. |
| `successRateBps` | `number` | Deposit-level success signal copied from `Deposit`. |
| `payeeDetailsHash` | `string` | Hashed payee details copied from `DepositPaymentMethod`. |
| `whitelistHookAddress` | `string?` | Address of the active whitelist pre-intent hook for this deposit; null means public/non-gated. |
| `isActive` | `boolean` | Whether this orderbook row is currently quoteable/visible. |
| `updatedAt` | `string (BigInt)` | Last time the materialized row was recomputed. |

### `TakerStats`

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.

**Relationships:**
- Implicit many-to-one from all `Intent` rows whose `owner` matches `TakerStats.owner`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_owner`, with the owner lowercased. |
| `chainId` | `number` | Chain on which the taker activity occurred. |
| `owner` | `string` | Lowercased taker address used as the aggregation key. |
| `lifetimeSignaledCount` | `number` | Number of intents ever signaled by this taker. |
| `lifetimeFulfilledCount` | `number` | Number of non-manual intents that fulfilled successfully. |
| `lifetimeManualReleaseCount` | `number` | Number of intents that ended via manual release. |
| `lifetimePruneCount` | `number` | Number of intents that were pruned/cancelled. Same-tx prune-then-fulfill cases are rolled back. |
| `totalCancelledVolume` | `string (BigInt)` | Sum of token amount from cancelled/pruned intents, with rollback if a same-tx prune later fulfills. |
| `totalFulfilledVolume` | `string (BigInt)` | Sum of token amount from fulfilled/manual-release intents. |
| `lockScore` | `string (BigInt)` | Penalty-style score derived from cancelled intent lock duration. Currently meaningful only in the v21 path. |
| `lastIntentAt` | `string? (BigInt)` | Timestamp of the taker's most recent intent signal. |
| `lastFulfilledAt` | `string? (BigInt)` | Timestamp of the taker's most recent fulfillment/manual release. |
| `firstSeenAt` | `string? (BigInt)` | Timestamp of the taker's first observed intent. |
| `updatedAt` | `string (BigInt)` | Last time this aggregate row changed. |

### `TakerPlatformStats`

Per-taker, per-payment-method aggregate for make-to-take risk checks. It is updated from the same taker fulfill/manual-release and prune flows as `TakerStats`.

**Relationships:**
- Implicit aggregation over all `Intent` rows whose `owner` and `paymentMethodHash` match this row

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_taker_paymentMethodHash`, with the taker and method lowercased. |
| `chainId` | `number` | Chain on which the taker activity occurred. |
| `taker` | `string` | Lowercased taker address used as the aggregation key. |
| `paymentMethodHash` | `string` | Active payment-method hash used as the aggregation dimension. Missing or unsupported hashes do not create platform rows. |
| `totalAmountTaken` | `string (BigInt)` | Sum of fulfilled/manual-release volume for this taker-method pair. |
| `fulfilledIntents` | `number` | Count of fulfilled/manual-release intents for this pair. |
| `prunedIntents` | `number` | Count of pruned intents for this pair; same-tx prune-then-fulfill cases are rolled back. |
| `manualReleaseCount` | `number` | Count of manual-release fills for this pair. |
| `updatedAt` | `string (BigInt)` | Last time the row changed. |

### `MakerStats`

Per-maker aggregate across every deposit owned by the maker on a chain. This is deposit-derived state plus realized-profit rollups.

**Relationships:**
- Implicit aggregation over all `Deposit` rows where `Deposit.depositor = MakerStats.maker`
- Parent summary for `MakerPlatformStats` and `MakerCurrencyStats`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_maker`, with maker lowercased in the id. |
| `chainId` | `number` | Chain on which the maker operates. |
| `maker` | `string` | Maker/depositor address used as the aggregation key. |
| `totalAmountTaken` | `string (BigInt)` | Sum of `Deposit.totalAmountTaken` across the maker's deposits. |
| `grossDeposited` | `string (BigInt)` | All-time gross capital committed by the maker, derived per deposit as `remaining + outstanding + taken + withdrawn`. |
| `totalWithdrawn` | `string (BigInt)` | Sum of maker withdrawals across all deposits. |
| `outstandingIntentAmount` | `string (BigInt)` | Sum of liquidity currently locked in active intents across all deposits. |
| `activeDepositCount` | `number` | Number of deposits that are both `ACTIVE` and `acceptingIntents = true`. |
| `totalDepositCount` | `number` | Number of deposit rows ever created for the maker. |
| `fulfilledIntents` | `number` | Sum of `Deposit.fulfilledIntents` across the maker's deposits. |
| `prunedIntents` | `number` | Sum of `Deposit.prunedIntents` across the maker's deposits. |
| `signaledIntents` | `number` | Sum of `Deposit.signaledIntents` across the maker's deposits. |
| `totalIntents` | `number` | Sum of `Deposit.totalIntents` across the maker's deposits. |
| `manualReleaseCount` | `number` | Number of maker fills that happened through manual release. |
| `successRateBps` | `number` | Maker-level fulfillment rate in basis points, derived from aggregate `fulfilledIntents / totalIntents`. |
| `realizedProfitUsdCents` | `string (BigInt)` | Sum of computed realized profit across all maker profit snapshots. |
| `spreadBpsVolumeWeightedSum` | `string (BigInt)` | Lifetime sum of `MakerProfitSnapshot.spreadBps * amount` for computed maker profit snapshots. |
| `spreadWeightedVolumeUsdc` | `string (BigInt)` | Lifetime USDC base-unit volume denominator for maker average spread. |
| `aprBps` | `number?` | Lifetime gross realized APR in basis points (`realizedProfitUsdCents * 365 * 10000 / (avgTvlUsdCents * daysSinceFirstSeen)`, clamped to [0, 10_000_000]). |
| `firstSeenAt` | `string? (BigInt)` | Timestamp of the maker's earliest observed deposit. |
| `updatedAt` | `string (BigInt)` | Last time the aggregate changed. |

### `DailyPlatformVolume`

Daily fulfilled-volume rollup for one payee-details hash and payment platform.

**Relationships:**
- Implicitly keyed to payment configuration by `payeeDetailsHash` and `paymentPlatform`
- Tracks the maker that owned the payee details at the time of the write

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_payeeDetailsHash_paymentPlatform_dayTimestamp`. |
| `chainId` | `number` | Chain on which the fill occurred. |
| `payeeDetailsHash` | `string` | Lowercased payee-details hash for the filled payment method. |
| `maker` | `string` | Lowercased maker address that owned the payee details at write time. |
| `paymentPlatform` | `string` | Payment platform name used for the fill. |
| `dayTimestamp` | `string (BigInt)` | Start-of-day UTC bucket in seconds. |
| `fillCount` | `number` | Number of fulfilled/manual-release intents in this bucket. |
| `volumeUsdc` | `string (BigInt)` | Fulfilled/manual-release token volume for this bucket in USDC base units. |
| `cumulativeFillCount` | `number` | Cumulative fill count through this bucket for the platform key. |
| `cumulativeVolumeUsdc` | `string (BigInt)` | Cumulative volume through this bucket for the platform key. |
| `updateSequence` | `string (BigInt)` | Monotonic counter incremented on every row update. |
| `updatedAt` | `string (BigInt)` | Last mutation time for the day's bucket. |

### `DailyPlatformVolumeCursor`

Prefix cursor for one payee-details hash and payment platform.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_payeeDetailsHash_paymentPlatform`. |
| `chainId` | `number` | Chain on which the platform activity occurred. |
| `payeeDetailsHash` | `string` | Lowercased payee-details hash. |
| `paymentPlatform` | `string` | Payment platform name. |
| `maker` | `string` | Lowercased maker address at the latest write. |
| `lastDayTimestamp` | `string (BigInt)` | Latest UTC day bucket reflected by the cursor. |
| `cumulativeFillCount` | `number` | Cumulative fill count through `lastDayTimestamp`. |
| `cumulativeVolumeUsdc` | `string (BigInt)` | Cumulative volume through `lastDayTimestamp`. |
| `updatedAt` | `string (BigInt)` | Last cursor mutation timestamp. |

### `GlobalDailyStats`

Daily protocol-level fulfilled volume, PnL, fulfillment count, and vault fulfillment rollup.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_dayTimestamp`. |
| `chainId` | `number` | Chain on which the activity occurred. |
| `dayTimestamp` | `string (BigInt)` | Start-of-day UTC bucket in seconds. |
| `fulfilledVolumeUsdCents` | `string (BigInt)` | Fulfilled volume for this bucket in USD cents. |
| `realizedPnlUsdCents` | `string (BigInt)` | Realized maker PnL for this bucket in USD cents. |
| `fulfilledIntentCount` | `number` | Fulfilled/manual-release intent count for this bucket. |
| `vaultFulfilledVolumeUsdCents` | `string (BigInt)` | Fulfilled volume for delegated vault fills in this bucket. |
| `vaultFulfilledIntentCount` | `number` | Fulfilled delegated vault intent count for this bucket. |
| `activeMakersCount` | `number` | Count of unique makers with fills in this bucket. |
| `cumulativeFulfilledVolumeUsdCents` | `string (BigInt)` | Cumulative fulfilled volume through this bucket. |
| `cumulativeRealizedPnlUsdCents` | `string (BigInt)` | Cumulative realized PnL through this bucket. |
| `cumulativeFulfilledIntentCount` | `number` | Cumulative fulfilled intent count through this bucket. |
| `cumulativeVaultFulfilledVolumeUsdCents` | `string (BigInt)` | Cumulative delegated vault volume through this bucket. |
| `cumulativeVaultFulfilledIntentCount` | `number` | Cumulative delegated vault fulfilled-intent count through this bucket. |
| `updatedAt` | `string (BigInt)` | Last mutation time for the day's bucket. |

### `GlobalDailyCursor`

Prefix cursor for global daily stats on one chain.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Chain id as a string. |
| `chainId` | `number` | Chain tracked by the cursor. |
| `lastDayTimestamp` | `string (BigInt)` | Latest UTC day bucket reflected by the cursor. |
| `cumulativeFulfilledVolumeUsdCents` | `string (BigInt)` | Cumulative fulfilled volume through `lastDayTimestamp`. |
| `cumulativeRealizedPnlUsdCents` | `string (BigInt)` | Cumulative realized PnL through `lastDayTimestamp`. |
| `cumulativeFulfilledIntentCount` | `number` | Cumulative fulfilled intent count through `lastDayTimestamp`. |
| `cumulativeVaultFulfilledVolumeUsdCents` | `string (BigInt)` | Cumulative delegated vault volume through `lastDayTimestamp`. |
| `cumulativeVaultFulfilledIntentCount` | `number` | Cumulative delegated vault fulfilled-intent count through `lastDayTimestamp`. |
| `updatedAt` | `string (BigInt)` | Last cursor mutation timestamp. |

### `GlobalDailyActiveMaker`

Per-day, per-maker presence marker. One row is written the first time a maker fills within a UTC day bucket, letting `GlobalDailyStats.activeMakersCount` be maintained as a distinct count without re-scanning intents.

**Relationships:**
- Backs `GlobalDailyStats.activeMakersCount` for the same `chainId` and `dayTimestamp`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_dayTimestamp_maker`. |
| `chainId` | `number` | Chain on which the activity occurred. |
| `dayTimestamp` | `string (BigInt)` | Start-of-day UTC bucket in seconds. |
| `maker` | `string` | Lowercased maker address active in this bucket. |
| `updatedAt` | `string (BigInt)` | Last time the row was touched. |

### `PlatformDailyStats`

Daily per-payment-platform fill count, fulfilled volume, realized PnL, and time-weighted capital rollup.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_paymentPlatform_dayTimestamp`. |
| `chainId` | `number` | Chain on which the activity occurred. |
| `paymentPlatform` | `string` | Active payment method name (for example `venmo` or `zelle`); unsupported hashes are omitted from platform projections. |
| `dayTimestamp` | `string (BigInt)` | Start-of-day UTC bucket in seconds. |
| `fillCount` | `number` | Fulfilled/manual-release intent count for this bucket. |
| `volumeUsdc` | `string (BigInt)` | Fulfilled volume for this bucket in USDC base units. |
| `realizedPnlUsdCents` | `string (BigInt)` | Realized maker PnL attributed to this platform for this bucket in USD cents (0 when the settlement price snapshot was pending at fill time). |
| `capitalUsdCentsDays` | `string (BigInt)` | Time-weighted capital listed on this platform for this bucket in USD-cent-days; a deposit's full live balance accrues once per distinct platform it lists via active payment methods. |
| `cumulativeFillCount` | `number` | Cumulative fill count through this bucket. |
| `cumulativeVolumeUsdc` | `string (BigInt)` | Cumulative fulfilled volume through this bucket. |
| `cumulativeRealizedPnlUsdCents` | `string (BigInt)` | Cumulative realized PnL through this bucket. |
| `cumulativeCapitalUsdCentsDays` | `string (BigInt)` | Cumulative time-weighted capital through this bucket. |
| `updatedAt` | `string (BigInt)` | Last mutation time for the day's bucket. |

### `PlatformDailyCursor`

Prefix cursor for platform daily stats on one chain and payment platform.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_paymentPlatform`. |
| `chainId` | `number` | Chain tracked by the cursor. |
| `paymentPlatform` | `string` | Active payment method name. Unsupported hashes do not create platform cursors. |
| `lastDayTimestamp` | `string (BigInt)` | Latest UTC day bucket reflected by the cursor. |
| `cumulativeFillCount` | `number` | Cumulative fill count through `lastDayTimestamp`. |
| `cumulativeVolumeUsdc` | `string (BigInt)` | Cumulative fulfilled volume through `lastDayTimestamp`. |
| `cumulativeRealizedPnlUsdCents` | `string (BigInt)` | Cumulative realized PnL through `lastDayTimestamp`. |
| `cumulativeCapitalUsdCentsDays` | `string (BigInt)` | Cumulative time-weighted capital through `lastDayTimestamp`. |
| `updatedAt` | `string (BigInt)` | Last cursor mutation timestamp. |

### `MakerDailySnapshot`

Daily maker-level fulfillment, PnL, spread, and capital-denominator rollup.

**Relationships:**
- Implicit aggregation over fulfilled/manual-release intents for one maker and one UTC day
- Receives capital-day deltas from deposit balance updates owned by the maker

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_maker_dayTimestamp`. |
| `chainId` | `number` | Chain on which the maker activity occurred. |
| `maker` | `string` | Lowercased maker/depositor address. |
| `dayTimestamp` | `string (BigInt)` | Start-of-day UTC bucket in seconds. |
| `fillsToday` | `number` | Number of fulfilled/manual-release intents in this bucket. |
| `earnedTodayUsdCents` | `string (BigInt)` | Realized maker PnL credited to this bucket in USD cents. |
| `fulfilledVolumeUsdc` | `string? (BigInt)` | Fulfilled/manual-release volume in this bucket in USDC base units. |
| `spreadBpsVolumeWeightedSum` | `string? (BigInt)` | Sum of `spreadBps * fillAmountUsdc` for fills in this bucket. |
| `spreadWeightedVolumeUsdc` | `string? (BigInt)` | USDC base-unit denominator for average spread in this bucket. |
| `capitalUsdCentsDay` | `string? (BigInt)` | Time-weighted live balance denominator for period APR calculations. |
| `cumulativePnlUsdCents` | `string (BigInt)` | Cumulative realized PnL through this bucket. |
| `cumulativeVolumeUsdc` | `string (BigInt)` | Cumulative fulfilled/manual-release volume through this bucket. |
| `cumulativeFulfilledIntents` | `number` | Cumulative fulfilled/manual-release intent count through this bucket. |
| `cumulativeSpreadBpsVolumeWeightedSum` | `string (BigInt)` | Cumulative spread numerator through this bucket. |
| `cumulativeSpreadWeightedVolumeUsdc` | `string (BigInt)` | Cumulative spread denominator through this bucket. |
| `cumulativeCapitalUsdCentsDay` | `string (BigInt)` | Cumulative capital-days through this bucket. |
| `activeDeposits` | `number` | Maker active deposit count observed at the last bucket update. |
| `averageLivePct` | `number` | Maker live-balance ratio observed at the last bucket update. |
| `updateSequence` | `string (BigInt)` | Monotonic counter incremented on every row update. |
| `updatedAt` | `string (BigInt)` | Last mutation time for the day's bucket. |

### `MakerDailyCursor`

Prefix cursor for one maker's daily snapshot rows.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_maker`. |
| `chainId` | `number` | Chain on which the maker operates. |
| `maker` | `string` | Lowercased maker/depositor address. |
| `lastDayTimestamp` | `string (BigInt)` | Latest UTC day bucket reflected by the cursor. |
| `cumulativePnlUsdCents` | `string (BigInt)` | Cumulative realized PnL through `lastDayTimestamp`. |
| `cumulativeVolumeUsdc` | `string (BigInt)` | Cumulative fulfilled/manual-release volume through `lastDayTimestamp`. |
| `cumulativeFulfilledIntents` | `number` | Cumulative fulfilled/manual-release intent count through `lastDayTimestamp`. |
| `cumulativeSpreadBpsVolumeWeightedSum` | `string (BigInt)` | Cumulative spread numerator through `lastDayTimestamp`. |
| `cumulativeSpreadWeightedVolumeUsdc` | `string (BigInt)` | Cumulative spread denominator through `lastDayTimestamp`. |
| `cumulativeCapitalUsdCentsDay` | `string (BigInt)` | Cumulative capital-days through `lastDayTimestamp`. |
| `updatedAt` | `string (BigInt)` | Last cursor mutation timestamp. |

### `MakerRolling90DayStats`

Per-maker trailing 90 UTC-day fulfilled-volume aggregate used by curator fee-discount logic. It is recomputed from `MakerDailySnapshot` rows on maker fills and by the live maintenance sweep so stale volume ages out even when a maker has no new fills.

**Relationships:**
- Derived from `MakerDailySnapshot` rows for the same `chainId` and `maker`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_maker`, with maker lowercased in the id. |
| `chainId` | `number` | Chain on which the maker operates. |
| `maker` | `string` | Lowercased maker/depositor address. |
| `windowStartDayTimestamp` | `string (BigInt)` | UTC day bucket at the start of the included 90-day window. |
| `windowEndDayTimestamp` | `string (BigInt)` | UTC day bucket at the end of the included 90-day window. |
| `totalAmountTaken` | `string (BigInt)` | Sum of fulfilled/manual-release USDC base-unit volume across the included day buckets. |
| `fulfilledIntents` | `number` | Count of fulfilled/manual-release intents across the included day buckets. |
| `updatedAt` | `string (BigInt)` | Last time the rolling row was recomputed. |

### `MakerPeerPayStats`

Per-maker lifetime aggregate of maker liquidity consumed by configured Peer Pay relayer takers. Self-fills where the taker/owner equals the maker are excluded. Peer Pay relayers are configured via `PEER_PAY_RELAYER_ADDRESSES` (`ENVIO_PEER_PAY_RELAYER_ADDRESSES` on hosted Envio).

**Relationships:**
- Subset of `MakerStats` volume restricted to Peer Pay relayer takers, keyed per maker

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_maker`, with maker lowercased in the id. |
| `chainId` | `number` | Chain on which the maker operates. |
| `maker` | `string` | Lowercased maker/depositor address. |
| `ppLifetimeConsumed` | `string (BigInt)` | Monotone cumulative USDC base-unit volume from this maker consumed by Peer Pay relayer takers. |
| `ppTakenPostEarnCutover` | `string (BigInt)` | Peer Pay relayer-taker consumed USDC base-unit volume with `blockTimestamp >= 2026-07-01T00:00:00Z`. |
| `ppLifetimeFills` | `number` | Monotone fulfilled fill count consumed by Peer Pay relayer takers. |
| `updatedAt` | `string (BigInt)` | Last time the row changed. |

### `MakerPeerPayPlatformStats`

Per-maker per-payment-method lifetime aggregate of maker liquidity consumed by configured Peer Pay relayer takers. The per-rail partition of `MakerPeerPayStats`. Self-fills where the taker/owner equals the maker are excluded.

**Relationships:**
- Partition of `MakerPeerPayStats` by the intent payment method hash

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_maker_paymentMethodHash`, with maker and payment method hash lowercased in the id. |
| `chainId` | `number` | Chain on which the maker operates. |
| `maker` | `string` | Lowercased maker/depositor address. |
| `paymentMethodHash` | `string` | Lowercased payment method hash for the consumed fill. |
| `ppLifetimeConsumed` | `string (BigInt)` | Monotone cumulative USDC base-unit volume from this maker and payment rail consumed by Peer Pay relayer takers. |
| `ppLifetimeFills` | `number` | Monotone fulfilled fill count from this maker and payment rail consumed by Peer Pay relayer takers. |
| `updatedAt` | `string (BigInt)` | Last time the row changed. |

### `MakerPeerPayRolling90DayStats`

Per-maker trailing 90 UTC-day aggregate of maker liquidity consumed by configured Peer Pay relayer takers. Recomputed from `MakerDailySnapshot` Peer Pay fields on maker fills and by the same live maintenance sweep cadence as `MakerRolling90DayStats`, so stale volume ages out for dormant makers.

**Relationships:**
- Derived from `MakerDailySnapshot` rows for the same `chainId` and `maker`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_maker`, with maker lowercased in the id. |
| `chainId` | `number` | Chain on which the maker operates. |
| `maker` | `string` | Lowercased maker/depositor address. |
| `ppRecent90dConsumed` | `string (BigInt)` | Peer Pay relayer-taker fulfilled USDC base-unit volume across the trailing 90 UTC-day window. |
| `windowStartDayTimestamp` | `string (BigInt)` | UTC day bucket at the start of the included 90-day window. |
| `windowEndDayTimestamp` | `string (BigInt)` | UTC day bucket at the end of the included 90-day window. |
| `isSettledToZero` | `boolean?` | True once the dormant maker's trailing Peer Pay window is provably empty. |
| `nextSweepDayTimestamp` | `string? (BigInt)` | UTC day when the live sweep should next revisit this row. |
| `updatedAt` | `string (BigInt)` | Last time the row changed. |

### `MakerPlatformStats`

Per-maker, per-payment-method aggregate. This lets consumers break a maker's business down by payment rail or method hash.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_maker_paymentMethodHash`. |
| `chainId` | `number` | Chain on which the activity occurred. |
| `maker` | `string` | Maker address. |
| `paymentMethodHash` | `string` | Payment-method aggregation dimension. |
| `totalAmountTaken` | `string (BigInt)` | Sum of fulfilled/manual-release volume for this maker-method pair. |
| `totalAmountTakenPreEarnCutover` | `string (BigInt)` | Sum of fulfilled/manual-release volume for this maker-method pair with `blockTimestamp < 2026-07-01T00:00:00Z`. |
| `fulfilledIntents` | `number` | Count of fulfilled/manual-release intents for this pair. |
| `prunedIntents` | `number` | Count of pruned intents for this pair. |
| `manualReleaseCount` | `number` | Count of manual-release fills for this pair. |
| `realizedProfitUsdCents` | `string (BigInt)` | Sum of realized profit allocated to this maker-method pair. |
| `computedProfitSnapshots` | `number` | Number of profit snapshots that successfully contributed realized profit to this pair. |
| `updatedAt` | `string (BigInt)` | Last time the row changed. |

### `MakerCurrencyStats`

Per-maker, per-fiat-currency aggregate.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_maker_currencyCode`. |
| `chainId` | `number` | Chain on which the activity occurred. |
| `maker` | `string` | Maker address. |
| `currencyCode` | `string` | Fiat-currency aggregation dimension. |
| `totalAmountTaken` | `string (BigInt)` | Sum of fulfilled/manual-release volume for this maker-currency pair. |
| `fulfilledIntents` | `number` | Count of fulfilled/manual-release intents for this pair. |
| `prunedIntents` | `number` | Count of pruned intents for this pair. |
| `manualReleaseCount` | `number` | Count of manual releases for this pair. |
| `updatedAt` | `string (BigInt)` | Last time the row changed. |

### `PriceSnapshot`

Daily FX snapshot used to translate local-fiat quote rates into a USD-denominated profitability view.

**Relationships:**
- Referenced by `MakerProfitSnapshot.priceSnapshotId`
- Used indirectly by manager aggregate PnL computation

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `currencyCode_timestampDay`. |
| `currencyCode` | `string` | Normalized fiat currency code of the quote being converted to USD. |
| `timestampDay` | `string (BigInt)` | Start-of-day UTC bucket in seconds. |
| `rateUsd` | `string (BigInt)` | Provider-supplied fiat-to-USD conversion rate in provider precision. |
| `ratePrecision` | `number` | Precision/scaling factor associated with `rateUsd`. |
| `provider` | `string` | Upstream provider name used to fetch the quote. |
| `source` | `string` | Source string or provider endpoint label. |
| `status` | `PriceSnapshotStatus` | Whether this snapshot came from live indexing or backfill. |
| `effectiveAt` | `string (BigInt)` | Timestamp at which the provider says the quote is valid/effective. |
| `retrievedAt` | `string (BigInt)` | Timestamp when the indexer fetched the quote. |
| `createdAt` | `string (BigInt)` | First time this snapshot row was written. |
| `updatedAt` | `string (BigInt)` | Last time this snapshot row was written. Usually equal to `createdAt`. |

### `MakerProfitSnapshot`

Per-intent realized-profit record for makers. This is the bridge between intent settlement and USD-denominated reporting.

**Relationships:**
- One row per settled `Intent` (`id = intentId`)
- Many-to-one to `Deposit`
- Optional many-to-one to `PriceSnapshot`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Equal to `intentId`, enforcing one profit row per intent. |
| `chainId` | `number` | Chain where the intent settled. |
| `maker` | `string` | Maker address that owned the deposit. |
| `intentId` | `string` | Foreign-key string to `Intent.id`. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `fiatCurrency` | `string` | Fiat currency used for the quote/profit comparison. |
| `quoteConversionRate` | `string (BigInt)` | Quote-time rate captured from the intent. |
| `oracleRate` | `string? (BigInt)` | USD-derived market reference rate computed from the linked `PriceSnapshot`. |
| `spreadBps` | `number?` | Basis-point difference between `quoteConversionRate` and `oracleRate`. |
| `amount` | `string (BigInt)` | Token amount used for the profit calculation. |
| `notionalFiatUsdCents` | `string? (BigInt)` | USD-cent value of the local-fiat notional implied by the quote. |
| `feeUsd` | `string? (BigInt)` | Reserved fee field. It is currently written as zero. |
| `realizedProfitUsdCents` | `string? (BigInt)` | Realized profit in USD cents. Can be negative. |
| `priceSnapshotId` | `string?` | Optional reference to the `PriceSnapshot` used to compute `oracleRate`. |
| `status` | `ProfitStatus` | `COMPUTED` when an FX reference existed, `PENDING` otherwise. |
| `createdAt` | `string (BigInt)` | Timestamp when the profit row was created. |
| `updatedAt` | `string (BigInt)` | Last update timestamp for the profit row. |

### `RateManager`

Registry row for a delegated rate manager. A deposit can point at one of these via `(rateManagerAddress, rateManagerId)`.

**Relationships:**
- Parent of `RateManagerRate`
- Parent/source of `ManagerAggregateStats`, `ManagerDailySnapshot`, and `ManagerStats`
- Optional target of deposit delegation

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_rateManagerAddress_rateManagerId`. |
| `chainId` | `number` | Chain where the manager contract exists. |
| `rateManagerAddress` | `string` | Rate-manager contract address. |
| `rateManagerId` | `string` | On-contract manager identifier. |
| `manager` | `string` | Account recognized as the logical manager/operator. |
| `feeRecipient` | `string` | Account that receives manager fees on settlement. |
| `maxFee` | `string (BigInt)` | Maximum allowed fee configured at manager creation. |
| `fee` | `string (BigInt)` | Current fee rate in 1e18 precision. |
| `minLiquidity` | `string (BigInt)` | Configured minimum liquidity threshold advertised by the manager contract. |
| `name` | `string?` | Optional human-readable name. |
| `uri` | `string?` | Optional metadata URI. |
| `createdAt` | `string (BigInt)` | First-seen timestamp. |
| `updatedAt` | `string (BigInt)` | Last config update timestamp. |

### `RateManagerRate`

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`.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_rateManagerAddress_rateManagerId_paymentMethodHash_currencyCode`. |
| `chainId` | `number` | Chain where the manager contract exists. |
| `rateManagerAddress` | `string` | Manager contract address. |
| `rateManagerId` | `string` | Manager identifier. |
| `paymentMethodHash` | `string` | Payment-method dimension for the manager quote. |
| `currencyCode` | `string` | Fiat-currency dimension for the manager quote. |
| `managerRate` | `string (BigInt)` | Gross manager-provided rate before floor enforcement. |
| `updatedAt` | `string (BigInt)` | Timestamp of the last rate update event for this pair. |

### `ManagerAggregateStats`

Portfolio-level aggregate for one delegated rate manager. This is the top-level manager reporting row.

**Relationships:**
- One-to-one logical summary for one `RateManager`
- Source for `ManagerDailySnapshot`
- Updated from delegated deposit balance changes and fulfilled intents

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Same identity as the corresponding `RateManager.id`. |
| `chainId` | `number` | Chain on which the manager operates. |
| `rateManagerAddress` | `string` | Manager contract address. |
| `rateManagerId` | `string` | Manager identifier. |
| `manager` | `string` | Manager account/operator. |
| `totalFilledVolume` | `string (BigInt)` | Cumulative token volume filled across all delegated deposits. |
| `totalFeeAmount` | `string (BigInt)` | Cumulative manager fee amount actually earned across fills. |
| `totalPnlUsdCents` | `string (BigInt)` | Cumulative USD-cent PnL measured against daily FX snapshots. |
| `fulfilledIntents` | `number` | Number of fulfilled delegated intents. |
| `currentDelegatedBalance` | `string (BigInt)` | Current delegated TVL: sum of `remainingDeposits + outstandingIntentAmount` across delegated deposits. |
| `currentDelegatedDeposits` | `number` | Number of deposits currently delegated to this manager. |
| `firstSeenAt` | `string? (BigInt)` | First timestamp the manager aggregate was created. |
| `updatedAt` | `string (BigInt)` | Last time the aggregate changed. |

### `ManagerDailySnapshot`

Daily bucketed snapshot for `ManagerAggregateStats`.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_rateManagerAddress_rateManagerId_dayTimestamp`. |
| `chainId` | `number` | Chain on which the manager operates. |
| `rateManagerAddress` | `string` | Manager contract address. |
| `rateManagerId` | `string` | Manager identifier. |
| `dayTimestamp` | `string (BigInt)` | Start-of-day UTC bucket in seconds. |
| `tvl` | `string (BigInt)` | End-of-update delegated balance for that day. |
| `delegatedDeposits` | `number` | Number of currently delegated deposits at snapshot time. |
| `delegatedCapitalUsdCentsDays` | `string (BigInt)` | Time-weighted delegated capital denominator for period APR. |
| `activeDepositorsCount` | `number` | Count of distinct active depositors delegated to the manager. |
| `dailyVolume` | `string (BigInt)` | Volume filled during that day. |
| `dailyFees` | `string (BigInt)` | Manager fees earned during that day. |
| `dailyPnlUsdCents` | `string (BigInt)` | Daily PnL in USD cents. |
| `dailyFulfilledIntents` | `number` | Number of fulfilled intents on that day. |
| `cumulativeVolume` | `string (BigInt)` | Cumulative filled volume up to this snapshot. |
| `cumulativeFees` | `string (BigInt)` | Cumulative manager fees up to this snapshot. |
| `cumulativePnlUsdCents` | `string (BigInt)` | Cumulative PnL up to this snapshot. |
| `cumulativeFulfilledIntents` | `number` | Cumulative fulfilled-intent count up to this snapshot. |
| `cumulativeDelegatedCapitalUsdCentsDays` | `string (BigInt)` | Cumulative delegated capital-days up to this snapshot. |
| `updatedAt` | `string (BigInt)` | Last mutation time for the day's bucket. |

### `ManagerDailyCursor`

Prefix cursor for one delegated rate manager's daily rows.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_rateManagerAddress_rateManagerId`. |
| `chainId` | `number` | Chain on which the manager operates. |
| `rateManagerAddress` | `string` | Manager contract address. |
| `rateManagerId` | `string` | Manager identifier. |
| `lastDayTimestamp` | `string (BigInt)` | Latest UTC day bucket reflected by the cursor. |
| `lastCapitalAccruedAt` | `string (BigInt)` | Latest timestamp through which delegated capital-days were accrued. |
| `cumulativeVolume` | `string (BigInt)` | Cumulative delegated filled volume through `lastDayTimestamp`. |
| `cumulativeFees` | `string (BigInt)` | Cumulative manager fees through `lastDayTimestamp`. |
| `cumulativePnlUsdCents` | `string (BigInt)` | Cumulative PnL through `lastDayTimestamp`. |
| `cumulativeFulfilledIntents` | `number` | Cumulative fulfilled-intent count through `lastDayTimestamp`. |
| `cumulativeDelegatedCapitalUsdCentsDays` | `string (BigInt)` | Cumulative delegated capital-days through `lastDayTimestamp`. |
| `updatedAt` | `string (BigInt)` | Last cursor mutation timestamp. |

### `DailyCapitalSweepCursor`

Chain-level cursor for the UTC daily capital denominator sweep.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Same as `chainId`. |
| `chainId` | `number` | Chain being swept. |
| `lastSweptDayTimestamp` | `string (BigInt)` | Latest completed UTC day-start timestamp swept by the block handler. |
| `updatedAt` | `string (BigInt)` | Last sweep cursor mutation timestamp. |

### `DepositFundActivity`

Append-only normalized ledger of deposit funding activity. This is easier to query than replaying all raw event families.

**Relationships:**
- Many-to-one to `Deposit`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `txHash_logIndex`. |
| `chainId` | `number` | Chain where the activity happened. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `depositor` | `string` | Maker address that owns the deposit. |
| `activityType` | `string` | Normalized activity class: `DEPOSIT_RECEIVED`, `FUNDS_ADDED`, `WITHDRAWN`, or `CLOSED`. |
| `amount` | `string (BigInt)` | Token amount relevant to the activity. `CLOSED` can legitimately record zero amount. |
| `blockNumber` | `string (BigInt)` | Block number for the activity. |
| `timestamp` | `string (BigInt)` | Timestamp for the activity. |
| `txHash` | `string` | Transaction hash for the activity. |

### `DepositDailySnapshot`

Daily bucketed snapshot of one deposit's state and realized profitability.

**Relationships:**
- Many-to-one to `Deposit`
- Receives daily-volume and daily-PnL deltas from fulfillment flows

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `depositId_dayTimestamp`. |
| `chainId` | `number` | Chain where the deposit exists. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `depositor` | `string` | Maker address that owns the deposit. |
| `dayTimestamp` | `string (BigInt)` | Start-of-day UTC bucket in seconds. |
| `remainingDeposits` | `string (BigInt)` | Deposit liquidity available at the time of the last update to that bucket. |
| `outstandingIntentAmount` | `string (BigInt)` | Deposit liquidity currently locked in intents at the last update. |
| `totalAmountTaken` | `string (BigInt)` | Cumulative taken volume at the last update. |
| `totalWithdrawn` | `string (BigInt)` | Cumulative withdrawn volume at the last update. |
| `signaledIntents` | `number` | Cumulative signal count at the last update. |
| `fulfilledIntents` | `number` | Cumulative fulfillment count at the last update. |
| `prunedIntents` | `number` | Cumulative prune count at the last update. |
| `successRateBps` | `number` | Deposit success rate at the last update. |
| `dailyVolume` | `string (BigInt)` | Volume taken during that day only. |
| `dailyPnlUsdCents` | `string (BigInt)` | Realized PnL accrued during that day only. |
| `capitalUsdCentsDay` | `string (BigInt) \| undefined` | Time-weighted live balance denominator for period APR calculations. |
| `cumulativeVolume` | `string (BigInt)` | All-time volume through the deposit as of this bucket. |
| `cumulativePnlUsdCents` | `string (BigInt)` | All-time realized PnL through the deposit as of this bucket. |
| `cumulativeCapitalUsdCentsDay` | `string (BigInt)` | Cumulative capital-days through this bucket. |
| `updatedAt` | `string (BigInt)` | Last mutation time for the day's bucket. |

### `DepositDailyCursor`

Prefix cursor for one deposit's daily snapshot rows.

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Same as `depositId`, the canonical `Deposit.id`. |
| `chainId` | `number` | Chain where the deposit exists. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `depositor` | `string` | Maker address that owns the deposit. |
| `lastDayTimestamp` | `string (BigInt)` | Latest UTC day bucket reflected by the cursor. |
| `lastCapitalAccruedAt` | `string (BigInt)` | Latest timestamp through which deposit and maker capital-days were accrued for this deposit. |
| `cumulativeVolume` | `string (BigInt)` | Cumulative volume through `lastDayTimestamp`. |
| `cumulativePnlUsdCents` | `string (BigInt)` | Cumulative realized PnL through `lastDayTimestamp`. |
| `cumulativeCapitalUsdCentsDay` | `string (BigInt)` | Cumulative capital-days through `lastDayTimestamp`. |
| `updatedAt` | `string (BigInt)` | Last cursor mutation timestamp. |

### `ManagerStats`

Per-deposit stats row for a delegated manager. Where `ManagerAggregateStats` is portfolio-level, `ManagerStats` is deposit-level attribution.

**Relationships:**
- Many-to-one to `Deposit`
- Many-to-one to `RateManager`

| Field | Type | Meaning |
|-------|------|---------|
| `id` | `string` | Composite key `chainId_rateManagerAddress_rateManagerId_depositId`. |
| `chainId` | `number` | Chain on which the delegation exists. |
| `rateManagerAddress` | `string` | Manager contract address. |
| `rateManagerId` | `string` | Manager identifier. |
| `depositId` | `string` | Foreign-key string to `Deposit.id`. |
| `depositor` | `string` | Maker that owns the delegated deposit. |
| `currentDelegatedBalance` | `string (BigInt)` | Current delegated balance for this one deposit: `remainingDeposits + outstandingIntentAmount`. |
| `totalAmountTaken` | `string (BigInt)` | Deposit's all-time taken amount while tracked under the manager. |
| `totalWithdrawn` | `string (BigInt)` | Deposit's all-time withdrawn amount while tracked under the manager. |
| `fulfilledIntents` | `number` | Deposit-level fulfillment count. |
| `prunedIntents` | `number` | Deposit-level prune count. |
| `successRateBps` | `number` | Deposit-level success rate. |
| `updatedAt` | `string (BigInt)` | Last mutation time for the row. |

## ID Format Conventions

| Entity | ID Format |
|--------|-----------|
| Deposit | `{escrowAddress}_{depositId}` |
| Intent | `{chainId}_{intentHash}` |
| MethodCurrency | `{escrow}_{depositId}_{methodHash}_{currencyCode}` |
| QuoteCandidate | same as MethodCurrency |
| DepositPaymentMethod | `{escrow}_{depositId}_{paymentMethodHash}` |
| ReferralFeeDistribution | `{chainId}_{intentHash}_{feeRecipient}` |
| WhitelistEntry | `{escrowAddress}_{depositId}_{taker}` |
| MakerStats | `{chainId}_{makerAddress}` |
| TakerStats | `{chainId}_{ownerAddress}` |
| TakerPlatformStats | `{chainId}_{takerAddress}_{paymentMethodHash}` |
| DailyPlatformVolume | `{chainId}_{payeeDetailsHash}_{paymentPlatform}_{dayTimestamp}` |
| PlatformDailyStats | `{chainId}_{paymentPlatform}_{dayTimestamp}` |
| PlatformDailyCursor | `{chainId}_{paymentPlatform}` |
| MakerDailySnapshot | `{chainId}_{maker}_{dayTimestamp}` |
| MakerRolling90DayStats | `{chainId}_{maker}` |
| MakerPlatformStats | `{chainId}_{maker}_{paymentMethodHash}` |
| MakerCurrencyStats | `{chainId}_{maker}_{currencyCode}` |
| PriceSnapshot | `{currencyCode}_{timestampDay}` |
| MakerProfitSnapshot | `{intentId}` |
| RateManager | `{chainId}_{rateManagerAddress}_{rateManagerId}` |
| RateManagerRate | `{chainId}_{rateManagerAddress}_{rateManagerId}_{paymentMethodHash}_{currencyCode}` |
| ManagerAggregateStats | same as RateManager |
| ManagerDailySnapshot | `{chainId}_{rateManagerAddress}_{rateManagerId}_{dayTimestamp}` |
| ManagerStats | `{chainId}_{rateManagerAddress}_{rateManagerId}_{depositId}` |
| DepositFundActivity | `{txHash}_{logIndex}` |
| DepositDailySnapshot | `{depositId}_{dayTimestamp}` |

## Known Currency Hashes

| Currency | Hash |
|----------|------|
| USD | `0xc4ae21aac0c6549d71dd96035b7e0bdb6c79ebdba8891b666115bc976d16a29e` |
| EUR | `0xfff16d60be267153303bbfa66e593fb8d06e24ea5ef24b6acca5224c2ca6b907` |
| GBP | `0x90832e2dc3221e4d56977c1aa8f6a6706b9ad6542fbbdaac13097d0fa5e42e67` |
| CAD | `0x221012e06ebf59a20b82e3003cf5d6ee973d9008bdb6e2f604faa89a27235522` |
| SGD | `0xc241cc1f9752d2d53d1ab67189223a3f330e48b75f73ebf86f50b2c78fe8df88` |
