> For the complete documentation index, see [llms.txt](https://docs-v4.nftx.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-v4.nftx.io/contracts/contracts.md).

# Overview

The NFTX v4 on-chain contracts — what each one does, how they fit together, and where they're deployed.

NFTX v4 is a set of **non-upgradeable** Solidity contracts that turn an NFT collection into a fungible, liquid market on top of **Uniswap V4**. This section is the on-chain reference: an architecture overview, the [deployment addresses](/contracts/addresses.md) per chain, and a page per contract documenting its public functions, inputs, and return values.

{% hint style="info" %}
Built with Foundry on Solidity `^0.8.26`. Key dependencies: Uniswap V4 core/periphery and hooks, Permit2, OpenZeppelin (including upgradeable ERC20 primitives for the clone-based collection token), and Solady.
{% endhint %}

For collections with enforced creator-token transfers, see [Creator Token Approvals](/contracts/creator-token-approvals.md) for the operator addresses to send to the collection team.

## How the pieces fit together

At the center is the **Locker**, which custodies every deposited ERC-721 and mints a fungible ERC-20 **collection token** (the collection's floor token) in return. Redeeming burns the token and returns an NFT. Everything else builds on that core:

* [**Locker**](/contracts/locker.md) — the vault. Holds the NFTs, mints/burns collection tokens, and exposes the core `deposit` / `redeem` / `swap` operations plus collection creation. Entry and exit are feeless; fees live in the listing and AMM layers.
* [**Collection Token**](/contracts/collection-token.md) — the ERC-20 that represents a collection. Deployed as a minimal-proxy clone per collection; mint and burn are restricted to the Locker.
* [**Listings**](/contracts/listings.md) — the self-assessed listing system. Sellers list non-floor items at a chosen floor multiple (liquid or Dutch), paying a tax that scales with price and duration.
* [**Tax Calculator**](/contracts/tax-calculator.md) — prices that listing tax from the floor multiple and duration, with a softening kink above `2.00x`.
* [**NFTX V4 Hook**](/contracts/nftx-v4-hook.md) — the Uniswap V4 hook. The single integration point for pool fees and swaps, including per-collection fees and fee exemptions.
* [**NFTX Flex Hook**](/contracts/nftx-flex-hook.md) — the second hook. Permissionless pools pairing a collection token with any whitelisted pair token, sharing the canonical hook's fee logic.
* [**Zap**](/contracts/zap.md) — convenience entry point for atomic ETH ↔ NFT flows.
* [**Migrator Zap**](/contracts/migrator-zap.md) — one-transaction migration from the legacy NFTX v2/v3 vaults into v4, with a 1:1 dust escrow for sub-unit legacy balances (Ethereum Mainnet only).
* [**Collection Shutdown**](/contracts/collection-shutdown.md) — a community-driven wind-down path for collections that have become illiquid.
* [**Supporting Contracts**](/contracts/supporting.md) — the Locker Manager, collection launch gates, the liquidation bonding curve, and token escrow.
* [**NFTXGacha**](/contracts/gacha.md) and [**NFTXGachaVault**](/contracts/gacha-vault.md) — the gacha machines: depositors stake floor NFTs and earn the house edge as yield, while spinners pay an emergent price for a verifiably random (Chainlink VRF) pull. Pre-mainnet — an Ethereum Sepolia rehearsal only. See the [Gacha](/gacha/gacha.md) section for the full picture.

## A typical flow

```
Deposit:  NFT  → Locker → mint collection token   (feeless)
Redeem:   collection token → Locker → NFT         (feeless)
List:     NFT  → Listings → collection token now, sale later (tax applies)
Trade:    ETH  ⇄ collection token via the Uniswap V4 pool (Hook charges fees)
```

## Contract reference

<table data-view="cards"><thead><tr><th>Contract</th><th></th><th data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Deployment Addresses</strong></td><td>Deployed addresses per chain</td><td><a href="/contracts/addresses.md">Deployment Addresses</a></td></tr><tr><td><strong>Locker</strong></td><td>The vault: deposit, redeem, swap, create</td><td><a href="/contracts/locker.md">Locker</a></td></tr><tr><td><strong>Collection Token</strong></td><td>The per-collection ERC-20</td><td><a href="/contracts/collection-token.md">Collection Token</a></td></tr><tr><td><strong>Listings</strong></td><td>Self-assessed liquid &#x26; Dutch listings</td><td><a href="/contracts/listings.md">Listings</a></td></tr><tr><td><strong>Tax Calculator</strong></td><td>The listing fee curve</td><td><a href="/contracts/tax-calculator.md">Tax Calculator</a></td></tr><tr><td><strong>NFTX V4 Hook</strong></td><td>Uniswap V4 fee &#x26; swap integration</td><td><a href="/contracts/nftx-v4-hook.md">NFTX V4 Hook</a></td></tr><tr><td><strong>NFTX Flex Hook</strong></td><td>Permissionless pair-token pools</td><td><a href="/contracts/nftx-flex-hook.md">NFTX Flex Hook</a></td></tr><tr><td><strong>Zap</strong></td><td>Atomic ETH ↔ NFT flows</td><td><a href="/contracts/zap.md">Zap</a></td></tr><tr><td><strong>Collection Shutdown</strong></td><td>Wind-down for illiquid collections</td><td><a href="/contracts/collection-shutdown.md">Collection Shutdown</a></td></tr><tr><td><strong>Supporting Contracts</strong></td><td>Manager, gates, curve, escrow</td><td><a href="/contracts/supporting.md">Supporting Contracts</a></td></tr><tr><td><strong>NFTXGacha</strong></td><td>Gacha spinning, pricing &#x26; VRF (pre-mainnet)</td><td><a href="/contracts/gacha.md">NFTXGacha</a></td></tr><tr><td><strong>NFTXGachaVault</strong></td><td>Gacha custody, deposits &#x26; rewards (pre-mainnet)</td><td><a href="/contracts/gacha-vault.md">NFTXGachaVault</a></td></tr></tbody></table>