Entity reference

Every entity below mirrors Subgraph/schema.graphql 1-for-1. Field types use the GraphQL standard set (String, Int, BigInt, Boolean, ID); a trailing ! denotes a non-nullable field.

IDs are always namespaced by chainId. The composition is documented per entity below; any cross-chain key collision is impossible by construction.

Enums

enum ListingFormat {
  NONE      # Floor item — no owner/duration/floorMultiple
  LIQUID    # Liquid listing (above floor, prepaid Harberger tax)
  DUTCH     # Native dutch listing (declining price)
}
 
enum ListingActivityType {
  CREATED
  RELISTED
  FILLED
  TRANSFERRED
  CANCELLED
  EXTENDED
  REPRICED
  DEPOSITED   # Locker.TokenDeposit
  REDEEMED    # Locker.TokenRedeem
  SWAPPED     # Locker.TokenSwap / TokenSwapBatch
}
 
enum AirdropClaimType {
  ERC20
  ERC721
  ERC1155
  NATIVE
}

`Config`

Singleton per chain. id = chainId.

Field	Type	Source event
`chainId`	`Int!`	—
`ammFee`	`BigInt!`	`NFTXV4Hook.AMMFeeSet`
`ammBeneficiary`	`String!`	`NFTXV4Hook.AMMBeneficiarySet`
`defaultFee`	`BigInt!`	`NFTXV4Hook.DefaultFeeSet`
`locked`	`Boolean!`	`Locker.Paused` / `Locker.Unpaused`
`collectionShutdownContract`	`String!`	`Locker.CollectionShutdownContractUpdated`
`collectionCreationFee`	`BigInt!`	`Locker.CollectionCreationFeeUpdated`
`collectionCreationFeeRecipient`	`String!`	`Locker.CollectionCreationFeeRecipientUpdated`
`permissionlessCreateCollection`	`Boolean!`	`Locker.PermissionlessCreateCollectionUpdated`
`defaultTaxCalculator`	`String!`	`Listings.DefaultTaxCalculatorUpdated`
`defaultMaxFloorMultiple`	`Int!`	`Listings.DefaultListingConfigUpdated`
`defaultMinLiquidDuration`	`BigInt!`	`Listings.DefaultListingConfigUpdated`
`defaultMaxLiquidDuration`	`BigInt!`	`Listings.DefaultListingConfigUpdated`
`defaultMinDutchDuration`	`BigInt!`	`Listings.DefaultListingConfigUpdated`
`defaultMaxDutchDuration`	`BigInt!`	`Listings.DefaultListingConfigUpdated`
`defaultLiquidDutchDuration`	`BigInt!`	`Listings.DefaultListingConfigUpdated`
`updated`	`BigInt!`	last write timestamp

`Collection`

Created by Locker.CollectionCreated, finalised by Locker.CollectionInitialized. id = chainId-collection.

Field	Type	Notes
`collection`	`String!` (indexed)	NFT contract address
`collectionToken`	`String!` (indexed)	ERC-20 clone address (1 per collection)
`creator`	`String!`	Address that called `createCollection`
`poolKey`	`String`	Encoded V4 `PoolKey`; null until `initializeCollection`
`name` / `symbol`	`String!`	Mirrors the `CollectionToken` clone metadata
`sourceChainId`	`BigInt`	Bridge provenance — null for native collections
`sourceChainAddress`	`String`	Bridge provenance — null for native collections
`defaultFee`	`BigInt!`	From `NFTXV4Hook.DefaultFeeSet`
`poolFee`	`BigInt!`	From `NFTXV4Hook.PoolFeeSet` (overrides `defaultFee` when set)
`sqrtPriceX96` / `tick` / `liquidity`	optional	Latest pool state from `PoolStateUpdated`
`protocolFee` / `swapFee`	`BigInt`	Latest from `PoolStateUpdated`
`publicListings`	`Int!`	Liquid + dutch listings counter
`shutdownPrevented`	`Boolean!`	`CollectionShutdown.preventShutdown(_collection, true)`
`taxCalculator`	`String`	Per-collection override from `Listings.CollectionTaxCalculatorUpdated`; null = uses `Config.defaultTaxCalculator`
`maxFloorMultiple`	`Int`	Per-collection override from `Listings.CollectionListingConfigUpdated`; null = uses `Config` default
`minLiquidDuration` / `maxLiquidDuration`	`BigInt`	Per-collection override; null = uses `Config` default
`minDutchDuration` / `maxDutchDuration`	`BigInt`	Per-collection override; null = uses `Config` default
`liquidDutchDuration`	`BigInt`	Per-collection override; null = uses `Config` default
`createdAt` / `updatedAt`	`BigInt!`

Reverse relations: listings, poolFees, shutdown.

The per-collection override fields are all cleared back to null (fall back to the Config defaults) when Listings.CollectionListingConfigUpdated fires with maxFloorMultiple == 0.

`Listing`

id = chainId-collection-tokenId. There is only one Listing row per (collection, tokenId) — when a listing is filled or cancelled the row is updated/removed in place; the lifecycle log lives in ListingActivity.

Field	Type	Notes
`collection`	`Collection!` (indexed)	FK
`tokenId`	`BigInt!`
`owner`	`String`	null for `format = NONE` (floor)
`created` / `duration`	`BigInt`	null for floor
`floorMultiple`	`Int`	null for floor; 1.00x = 100 in pip units
`format`	`ListingFormat!`	See enum
`taxCaptured`	`BigInt!`	Cumulative `Listings.ListingFeeCaptured` for this listing
`createdAt` / `updatedAt`	`BigInt!`

⚠️

The frontend sometimes wants to display a listing as “DUTCH” once the listed duration has elapsed even though the on-chain format still reads LIQUID. This is intentional — Listings.getListingType() is the authoritative client-side resolver.

`ListingActivity`

One row per state-changing event. id is opaque (collection-tokenId-type-timestamp).

Field	Type	Notes
`listing`	`Listing!`	FK
`collection`	`Collection!`	denormalised for filter performance
`tokenId`	`BigInt!`	denormalised
`activityType`	`ListingActivityType!`	See enum
`txHash`	`String!`
`from` / `to`	`String?`	optional, depending on activity type
`floorMultiple`	`Int?`	new value after a `REPRICED`
`ethPrice`	`BigInt?`	sale price on `FILLED`
`created`	`BigInt!`

`LockerManager`

Approved Locker manager contracts (see LockerManager.ManagerSet). id = chainId-manager.

Field	Type
`manager`	`String!` (indexed)
`approved`	`Boolean!`
`updatedAt`	`BigInt!`

`TokenEscrow`

Per-payee, per-token claimable balance. Inherited by both Listings and NFTXV4Hook — the indexer aggregates writes from either source under a common (chainId, payee, token) key. id = chainId-payee-token.

Field	Type
`payee`	`String!` (indexed)
`token`	`String!` (indexed)
`amount`	`BigInt!`
`updated`	`BigInt!`

`PoolFees`

Per-collection lifetime + queued fee accounting. Amounts are denominated in the pool’s V4-sorted currency order — queuedAmount0/totalDonated0 correspond to whichever of (native token, collection token) sorts lower by address. Resolve via Collection.poolKey. id = chainId-collection.

Field	Type	Source
`collection`	`Collection!` (indexed)	FK
`queuedAmount0` / `queuedAmount1`	`BigInt!`	incremented by `PoolFeesQueued`, cleared by `PoolFeesDonated`
`totalDonated0` / `totalDonated1`	`BigInt!`	accumulated lifetime via `PoolFeesDonated`
`updatedAt`	`BigInt!`

`PoolFeeDonation`

One row per NFTXV4Hook.PoolFeesDonated.

Field	Type
`collection`	`Collection!`
`amount0` / `amount1`	`BigInt!`
`txHash`	`String!`
`triggeredBy`	`String?` (tx sender)
`created`	`BigInt!`

`FeeOverride`

Per-beneficiary flat-fee override. id = chainId-beneficiary.

Field	Type
`beneficiary`	`String!` (indexed)
`flatFee`	`BigInt?` (null when removed)
`updatedAt`	`BigInt!`

`CollectionShutdown`

The shutdown lifecycle: start → vote / reclaim → quorum → execute → claim (or cancel). id = chainId-collection.

Field	Type	Notes
`collection`	`Collection!` (indexed)	FK
`quorum`	`BigInt!`	Required vote weight
`liquidationPool`	`String?`	Created by `CollectionShutdownExecuted`
`liquidationPoolTokens`	`[BigInt!]!`	NFT tokenIds liquidated
`claimAvailable`	`BigInt!`	Incremented by `CollectionShutdownTokenLiquidated`
`startedAt` / `startedBy`	`BigInt!` / `String!`
`executedAt` / `executedBy`	`BigInt?` / `String?`
`quorumReachedAt`	`BigInt?`	If non-null, shutdown can be executed

Reverse relations: votes, claims.

`CollectionShutdownVote`

Field	Type	Notes
`shutdown`	`CollectionShutdown!`	FK
`voter`	`String!` (indexed)
`votes`	`BigInt!`	Signed — negative on `reclaimVote`
`createdAt`	`BigInt!`

`CollectionShutdownClaim`

Field	Type
`shutdown`	`CollectionShutdown!`
`claimant`	`String!` (indexed)
`tokensBurnt`	`BigInt!`
`ethReceived`	`BigInt!`
`txHash`	`String!`
`claimedAt`	`BigInt!`

`AirdropDistribution`

Created by AirdropRecipient.AirdropDistributed. id = chainId-merkle-claimType.

Field	Type
`merkle`	`String!`
`claimType`	`AirdropClaimType!`
`createdAt`	`BigInt!`

Reverse relation: claims.

`AirdropClaim`

Field	Type
`airdrop`	`AirdropDistribution!`
`recipient`	`String!` (indexed)
`target`	`String!`
`tokenId`	`BigInt!`
`amount`	`BigInt!`
`txHash`	`String!`
`claimedAt`	`BigInt!`

`AirdropTarget`

Owner-curated allowlist for AirdropRecipient.requestAirdrop targets. id = chainId-target.

Field	Type
`target`	`String!` (indexed)
`allowed`	`Boolean!`
`updatedAt`	`BigInt!`

`ListingsContract`

A Listings contract registered on the Locker (Locker.ListingsContractAdded / ListingsContractRemoved). approved is toggled rather than the row being deleted, so registry history is preserved. id = chainId-listings.

Field	Type
`listings`	`String!` (indexed)
`approved`	`Boolean!`
`updatedAt`	`BigInt!`

`AmmFeeTaken`

Append-only log of every NFTXV4Hook.AMMFeesTaken event. recipient may be address(0), indicating the cut was burnt.

Field	Type
`recipient`	`String!` (indexed)
`token`	`String!`
`amount`	`BigInt!`
`txHash`	`String!`
`created`	`BigInt!`

Overview & relationship diagram GraphQL recipes