# Entities

## Entities <a href="#locker" id="locker"></a>

### Locker <a href="#locker" id="locker"></a>

`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 <a href="#lockedpool" id="lockedpool"></a>

`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 <a href="#lock" id="lock"></a>

`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 <a href="#whitelistedwallet" id="whitelistedwallet"></a>

`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 <a href="#wallet" id="wallet"></a>

`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 <a href="#token" id="token"></a>

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 <a href="#basetoken" id="basetoken"></a>

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 <a href="#pool" id="pool"></a>

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 <a href="#fees" id="fees"></a>

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 <a href="#snapshots" id="snapshots"></a>

### LockSnapshot <a href="#locksnapshot" id="locksnapshot"></a>

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 <a href="#tokensnapshot" id="tokensnapshot"></a>

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 <a href="#statediffsnapshot" id="statediffsnapshot"></a>

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 <a href="#events" id="events"></a>

### EventCollection <a href="#eventcollection" id="eventcollection"></a>

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 <a href="#eventtype" id="eventtype"></a>

`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 <a href="#search" id="search"></a>

### TokenSearch <a href="#tokensearch" id="tokensearch"></a>

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 <a href="#walletsearch" id="walletsearch"></a>

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     |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.uncx.network/guides/for-developers/liquidity-lockers/lockers-v2/subgraphs/entities.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.