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