Entities

Explore UNCX V2 subgraph entities, field types and relationships for lockers, locked pools, liquidity locks, tokens and fees.

Entities

Locker

Locker entity holds information about all UNCX lockers, each locker corresponding to a specific AMM.

Field	Type	Description
id	ID!	Locker Address
totalLocks	BigInt!	Total number of locks associated with the locker
totalTokens	BigInt!	Total number of tokens associated with the locker
feeWhitelist	[WhitelistedWallet!]!	Fee whitelisted wallets; these accounts do not pay flatrate fees on locking
fees	Fees!	Reference to the fee details associated with the locker

LockedPool

LockedPool encapsulates the overall lock data for a pool. Each pool can have multiple locks associated with it.

Field	Type	Description
id	ID!	Combination of Locker and Pair addresses
pool	Pool!	Pool address
locker	Locker!	Locker address
numberOfLocks	BigInt!	Total number of locks for a pair address
mainToken	Token!	Main token (does not follow token0 / token1 contract order)
baseToken	Token!	Core tokens like stablecoins, ETH, BNB etc. (does not follow token0 / token1 contract order)
lockIds	[String!]!	All lock IDs associated with the pool
locks	[Lock!]!	All locks for LP token derived from the ‘lockedPool’ field

Lock

Lock provides the base-level data for locked liquidity. Some properties starting with ‘locked..’ are non-withdrawable assets (i.e., unlockDate > current timestamp). Other properties describe withdrawable assets and their value.

Field	Type	Description
id	ID!	V2 contracts: Locker + Pair + LockID; V2.1 contracts: Locker + Nonce
lockID	BigInt!	LockID of the lock
amount0	BigDecimal!	Amount of token0 stored in the lock
amount1	BigDecimal!	Amount of token1 stored in the lock
liquidity	BigDecimal!	Amount of LP tokens vested in the lock
coreTotalUSD	BigDecimal!	Core token USD TVL stored in the lock (e.g., stablecoins, ETH, BNB)
lockedLiquidity	BigDecimal!	Liquidity stored in a lock (non-withdrawable)
lockedAmount0	BigDecimal!	Amount0 stored in a lock (non-withdrawable)
lockedAmount1	BigDecimal!	Amount1 stored in a lock (non-withdrawable)
lockedCoreUSD	BigDecimal!	USD value of the core asset locked (non-withdrawable)
lockedPercent	BigDecimal!	Locked percent of the active liquidity (non-withdrawable)
mainToken	Token!	Main token (does not follow token0 / token1 contract order)
baseToken	Token!	Core tokens like stablecoins, ETH, BNB, etc. (does not follow token0 / token1 contract order)
unlockDate	BigInt!	Unlock timestamp
owner	Wallet!	Lock owner address
countryCode	BigInt	Country code of the project (optional, introduced in V2.1)
lockedPool	LockedPool!	Locker + Address of the LP tokens locked
pool	Pool!	Address of the LP tokens locked
locker	Locker!	Locker address
blockNumber	BigInt!	Last update block
timestamp	BigInt!	Last update timestamp
eventSnapshots	[StateDiffSnapshot!]!	Collection of all event snapshots for a lock

WhitelistedWallet

WhitelistedWallet contains information about wallets that are whitelisted to not pay flat-rate fees on locking operations.

Field	Type	Description
id	ID!	Locker Address + Wallet Address
locker	Locker!	The locker address
wallet	Wallet!	The whitelisted wallet address

Wallet

Wallet provides an aggregated view of all locks and whitelisted lockers for a specific wallet address.

Field	Type	Description
id	ID!	Unique identifier for the wallet, usually the wallet’s address.
locks	[Lock!]	List of liquidity locks that this wallet owns.
whitelistedLockers	[WhitelistedWallet!]	List of all lockers where this wallet is fee whitelisted.

Token

The Token entity stores all information related to Total Value Locked (TVL) and LockedTVL (non-withdrawable assets) in a specific token. TVL is considered only if the token is paired with a liquid stablecoin or a sizable protocol/gas token like ETH, BTC, BNB, etc.

Field	Type	Description
id	ID!	Smart contract address of the token.
name	String!	Token name, usually mirrored from the smart contract.
symbol	String!	Token symbol, usually mirrored from the smart contract.
decimals	BigInt!	Number of decimal places this token uses, default is usually 18.
tvlUSD	BigDecimal!	Dollar value locked in this token across all pools and AMMs.
lockedUSD	BigDecimal!	Non-withdrawable dollar value locked in this token across all pools and AMMs.
baseTokens	[BaseToken!]	Checks if this token is considered a base token in the system.
blockNumber	BigInt!	Block number when the last update occurred.
timestamp	BigInt!	Timestamp when the last update occurred.
mainTokenReserves	[LockedPool!]	All reserves where this token is the main token.
baseTokenReserves	[LockedPool!]	All reserves where this token is considered a core or base token.
mainTokenLocks	[Lock!]	All locks where this token is the main token.
baseTokenLocks	[Lock!]	All locks where this token is considered a core or base token.
eventSnapshotsMainToken	[StateDiffSnapshot!]	Collection of all event snapshots where this token is the main token.
eventSnapshotsBaseToken	[StateDiffSnapshot!]	Collection of all event snapshots where this token is considered a core or base token.

BaseToken

The BaseToken entity represents a liquid stablecoin or a sizable protocol/gas token like ETH, BTC, BNB, etc. The base price of these assets is constantly updated via a Chainlink Oracle.

Field	Type	Description
id	ID!	Smart contract address of the token.
token	Token!	The actual Token entity containing more details.
basePrice	BigInt!	Current price of the asset, useful for TVL calculations.
lastBaseUpdatedTimestamp	BigInt!	Timestamp when the base price was last updated.

Pool

The Pool entity contains data related to liquidity pools. It provides information about the tokens involved, the liquidity provided, and other related parameters.

Field	Type	Description
id	ID!	Unique identifier for the pair address.
token0	Token!	Address of the first token in the pair.
token1	Token!	Address of the second token in the pair.
lockedPools	[LockedPool!]!	Array of Locked LP Tokens for this LP address.
reserve0	BigDecimal!	Total reserves of the first token (`token0`) in the pool.
reserve1	BigDecimal!	Total reserves of the second token (`token1`) in the pool.
totalSupply	BigDecimal!	Total supply of the ERC20 token for this liquidity pair.

Fees

The Fees entity contains data related to various fees in the UNCX ecosystem. This includes the base Ethereum fee, secondary token fees, liquidity fees, and referral discounts.

Field	Type	Description
id	ID!	Locker address identifier.
ethFee	BigInt!	Fee amount in Ethereum.
secondaryFeeToken	Token!	Secondary fee token, either UNCX or UNCL.
secondaryTokenFee	BigInt!	Fee amount for the secondary token, either UNCX or UNCL. (Optional)
secondaryTokenDiscount	BigInt!	Discount on liquidity fee when burning the secondary token.
liquidityFee	BigInt!	Fee imposed on Uniswap V2 (UNI-V2) liquidity tokens.
referralPercent	BigInt!	Percentage fee for referrals.
referralToken	Token!	The token that a referral wallet must hold to qualify as a referrer.
referralHold	BigInt!	Minimum balance of the referral token that a referral wallet must hold to qualify as a referrer.
referralDiscount	BigInt!	Discount on flat-rate fees for using a valid referral address.

Snapshots

LockSnapshot

The LockSnapshot entity is an immutable snapshot that captures the state of a lock at a specific event. This entity is comprehensive and includes data such as amounts, liquidity, and core token values.

The id field is constructed as follows:
Locker Address + 'Events' + EventType ('Lock') + EventType.eventsNumber (0..10000+) + 'Before / After' (depending on the order).

Field	Type	Description
id	ID!	Composite ID based on locker address, event type, and index.
lockID	BigInt	The ID of the lock.
amount0	BigDecimal	The amount of `token0` stored in the lock.
amount1	BigDecimal	The amount of `token1` stored in the lock.
liquidity	BigDecimal	The amount of LP tokens vested in the lock.
coreTotalUSD	BigDecimal	Core token USD TVL stored in the lock.
lockedLiquidity	BigDecimal	Liquidity stored in a lock that is non-withdrawable.
lockedAmount0	BigDecimal	Amount of `token0` stored in a lock that is non-withdrawable.
lockedAmount1	BigDecimal	Amount of `token1` stored in a lock that is non-withdrawable.
lockedCoreUSD	BigDecimal	USD value of the core asset locked that is non-withdrawable.
lockedPercent	BigDecimal	The percentage of the active liquidity that is non-withdrawable.
mainToken	TokenSnapshot!	The main token associated with the lock.
baseToken	TokenSnapshot!	Core tokens like stablecoins, ETH, BNB, etc.
unlockDate	BigInt	The timestamp at which the lock will be unlocked.
owner	Wallet	The owner address of the lock.
countryCode	BigInt	The country code of the project, introduced in V2.1 (optional).

TokenSnapshot

The TokenSnapshot entity is an immutable representation capturing the state of a token at a specific event in time. It includes values like the total dollar value locked in all pools as well as the non-withdrawable dollar value.

The id field is constructed as follows:
Locker Address + 'Events' + EventType (name) + EventType.eventsNumber (index) + 'Before / After' (depending on the order).

Field	Type	Description
id	ID!	Composite ID generated from the Locker Address, Events, EventType, and event index.
tvlUSD	BigDecimal!	Dollar value locked in this token across all pools.
lockedUSD	BigDecimal!	Non-withdrawable dollar value locked in this token across all pools.

StateDiffSnapshot

The StateDiffSnapshot entity stores all before and after event snapshots. Users can filter snapshots based on the event type using the eventType field.

Field	Type	Description
id	ID!	Locker address + event index
eventType	EventType!	Type of event
lockBefore	LockSnapshot!	Lock event snapshot before the transaction
lockAfter	LockSnapshot!	Lock event snapshot after the transaction
lock	Lock!	Reference to the lock
pool	Pool!	Reference to the pool
lockedPool	LockedPool!	Reference to the locked pool
locker	Locker!	Reference to the locker
mainToken	Token!	Reference to the main token
baseToken	Token!	Reference to the base token
transaction	Bytes!	Transaction hash
eventsCollection	EventCollection!	Reference to the event collection
blockNumber	BigInt!	Event block number
timestamp	BigInt!	Event timestamp

Events

EventCollection

The EventCollection entity serves as a repository for all event-related snapshots. It keeps track of the number of various events that modify or create locks, such as lock events, withdraw events, etc.

Field	Type	Description
id	ID!	Composite ID based on locker address and ‘Events’.
stateDiffSnapshots	[StateDiffSnapshot!]	Array of state differences captured by snapshots. These are derived from this `EventCollection`.
lockEventsNumber	BigInt	Total number of lock events.
withdrawEventsNumber	BigInt	Total number of withdraw events. (Commented out)
incrementEventsNumber	BigInt	Total number of increment lock events. (Commented out)
relockEventsNumber	BigInt	Total number of relock events. (Commented out)
splitLockEventsNumber	BigInt	Total number of split lock events. (Commented out)
transferLockOwnershipEventsNumber	BigInt	Total number of transfer lock ownership events. (Commented out)
migrateEventsNumber	BigInt	Total number of migrate events. (Commented out)

EventType

EventType is an enumeration that lists various types of events that can occur within the locker system.

Value	Description
`Lock`	Event corresponding to a new liquidity lock.
`Withdraw`	Event corresponding to a liquidity withdrawal.
`Increment`	Event corresponding to an increment of existing liquidity.
`Relock`	Event corresponding to a relocking of liquidity.
`SplitLock`	Event corresponding to the splitting of an existing lock.
`TransferLockOwnership`	Event corresponding to the transfer of lock ownership.

Search

TokenSearch

The tokenSearch is a full-text search schema over the “Token” entity. It enables users to locate specific “Token” entities by their symbols, names, or unique identifiers.

name	entity	fields
tokenSearch	Token	symbol, name, id

WalletSearch

The walletSearch is a full-text search schema over the “Wallet” entity. It enables users to locate specific “Wallet” entities by their unique identifiers.

name	entity	fields
walletSearch	Wallet	id