> 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/locker.md).

# Locker

The `Locker` holds every deposited ERC-721 and issues a fungible ERC-20 **collection token** in return. It deliberately separates token storage from listing logic so that listing managers can be upgraded without migrating the NFTs themselves. Manager contracts must be approved for token access; when a vault is removed, those permissions are revoked.

Function signatures and parameter descriptions below come from the `ILocker` interface. Entry and exit (`deposit` / `redeem`) are feeless — fees live in the [Listings](/contracts/listings.md) and [Hook](/contracts/nftx-v4-hook.md) layers.

## Core vault operations

### `deposit`

Takes approved ERC-721s from the caller and mints the ERC-20 equivalent (one collection token per NFT). The recipient overload sends the minted tokens to a different address.

```solidity
function deposit(address _collection, uint[] calldata _tokenIds) external;
function deposit(address _collection, uint[] calldata _tokenIds, address _recipient) external;
```

**Access:** `nonReentrant`, `whenNotPaused`, collection must exist.

| Parameter     | Type      | Description                                                |
| ------------- | --------- | ---------------------------------------------------------- |
| `_collection` | `address` | The address of the token collection                        |
| `_tokenIds`   | `uint[]`  | The IDs of the tokens being deposited                      |
| `_recipient`  | `address` | The address receiving the ERC-20 (recipient overload only) |

**Returns:** None.

### `redeem`

Burns collection tokens and returns specific ERC-721s to the caller (or a recipient). Reverts if any requested token is an active listing rather than a floor item.

```solidity
function redeem(address _collection, uint[] calldata _tokenIds) external;
function redeem(address _collection, uint[] calldata _tokenIds, address _recipient) external;
```

**Access:** `nonReentrant`, `whenNotPaused`, collection must exist.

| Parameter     | Type      | Description                                                  |
| ------------- | --------- | ------------------------------------------------------------ |
| `_collection` | `address` | The address of the token collection                          |
| `_tokenIds`   | `uint[]`  | The IDs of the tokens being redeemed                         |
| `_recipient`  | `address` | The address receiving the ERC-721s (recipient overload only) |

**Returns:** None.

### `swap`

Swaps a token held by the caller for a floor token in the vault in a single call — effectively a combined `deposit` and `redeem`, more gas-efficient than running both. The token being redeemed must be of floor value, not a listing.

```solidity
function swap(address _collection, uint _tokenIdIn, uint _tokenIdOut) external;
```

**Access:** `nonReentrant`, `whenNotPaused`, collection must exist. Reverts if `_tokenIdIn == _tokenIdOut` or if `_tokenIdOut` is an active listing.

| Parameter     | Type      | Description                           |
| ------------- | --------- | ------------------------------------- |
| `_collection` | `address` | The address of the token collection   |
| `_tokenIdIn`  | `uint`    | The ID of the token being swapped in  |
| `_tokenIdOut` | `uint`    | The ID of the token being swapped out |

**Returns:** None.

### `swapBatch`

The batched form of `swap` — exchanges a set of tokens for an equal-sized set of floor tokens from the same collection in one call.

```solidity
function swapBatch(address _collection, uint[] calldata _tokenIdsIn, uint[] calldata _tokenIdsOut) external;
```

**Access:** `nonReentrant`, `whenNotPaused`, collection must exist. Reverts if the input and output arrays differ in length, or if any output token is an active listing.

| Parameter      | Type      | Description                             |
| -------------- | --------- | --------------------------------------- |
| `_collection`  | `address` | The address of the token collection     |
| `_tokenIdsIn`  | `uint[]`  | The IDs of the tokens being swapped in  |
| `_tokenIdsOut` | `uint[]`  | The IDs of the tokens being swapped out |

**Returns:** None.

## Collection lifecycle

### `createCollection`

Registers a collection and deploys its underlying `CollectionToken` clone. When a launch gate is set, the gate decides who may create a collection at the current stage; when unset, anyone can register a collection by paying the `collectionCreationFee`.

```solidity
function createCollection(address _collection, string calldata _name, string calldata _symbol) external payable returns (address);
```

**Access:** `payable`, `whenNotPaused`, `nonReentrant`. Reverts if `msg.value` doesn't match the creation fee, if the collection already exists or was previously sunset, or if it isn't a valid ERC-721.

| Parameter     | Type      | Description                         |
| ------------- | --------- | ----------------------------------- |
| `_collection` | `address` | The address of the token collection |
| `_name`       | `string`  | The name of the ERC-20 token        |
| `_symbol`     | `string`  | The symbol for the ERC-20 token     |

| Return    | Type      | Description                              |
| --------- | --------- | ---------------------------------------- |
| (unnamed) | `address` | The address of the ERC-20 token deployed |

### `initializeCollection`

Sets a base price and injects the collection's initial liquidity into the Uniswap V4 pool. Requires at least `MINIMUM_TOKEN_IDS` (10) NFTs; any unused collection-token headroom from `_tokenSlippage` is refunded to the caller.

```solidity
function initializeCollection(address _collection, uint _eth, uint[] calldata _tokenIds, uint _tokenSlippage, uint160 _sqrtPriceX96) external;
```

**Access:** `nonReentrant`, `whenNotPaused`, collection must exist. Reverts if the collection is already initialized or fewer than 10 token IDs are supplied.

| Parameter        | Type      | Description                                                          |
| ---------------- | --------- | -------------------------------------------------------------------- |
| `_collection`    | `address` | The address of the collection                                        |
| `_eth`           | `uint`    | The amount of ETH-equivalent (native) tokens to commit               |
| `_tokenIds`      | `uint[]`  | An array of NFTs the caller is depositing as liquidity               |
| `_tokenSlippage` | `uint`    | Additional collection-token headroom; any unused portion is refunded |
| `_sqrtPriceX96`  | `uint160` | The initial price of the token position                              |

**Returns:** None.

### `setCollectionTokenMetadata`

Lets the contract owner update a collection token's name and symbol — a safety valve for tokens created with malformed, unintelligible, or offensive metadata.

```solidity
function setCollectionTokenMetadata(address _collection, string calldata _name, string calldata _symbol) external;
```

**Access:** `onlyOwner`, collection must exist.

| Parameter     | Type      | Description                  |
| ------------- | --------- | ---------------------------- |
| `_collection` | `address` | The collection address       |
| `_name`       | `string`  | The new name for the token   |
| `_symbol`     | `string`  | The new symbol for the token |

**Returns:** None.

### `sunsetCollection`

Permanently removes a collection from the platform. This is important during a shutdown so that holders can't keep listing assets into a vault that's being wound down. It's callable only by the [Collection Shutdown](/contracts/collection-shutdown.md) contract.

```solidity
function sunsetCollection(address _collection) external;
```

**Access:** collection must exist; only callable by the configured `CollectionShutdown` contract. Flags the collection as sunset to block re-registration.

| Parameter     | Type      | Description                   |
| ------------- | --------- | ----------------------------- |
| `_collection` | `address` | The address of the collection |

**Returns:** None.

## Listings registry and views

### `collectionToken`

Returns the deployed `CollectionToken` for a collection (the zero address if the collection has none).

```solidity
function collectionToken(address _collection) external view returns (ICollectionToken);
```

| Parameter     | Type      | Description            |
| ------------- | --------- | ---------------------- |
| `_collection` | `address` | The collection address |

| Return    | Type               | Description                   |
| --------- | ------------------ | ----------------------------- |
| (unnamed) | `ICollectionToken` | The collection's ERC-20 token |

### `isListing`

Checks across every authorised Listings contract whether a given token is currently an active listing.

```solidity
function isListing(address _collection, uint _tokenId) external view returns (bool);
```

| Parameter     | Type      | Description                           |
| ------------- | --------- | ------------------------------------- |
| `_collection` | `address` | The collection address of the listing |
| `_tokenId`    | `uint`    | The tokenId of the listing            |

| Return    | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| (unnamed) | `bool` | Whether the listing exists (`true`) or not (`false`) |

### `listingsAt` / `listingsLength`

Enumerate the authorised Listings contracts. `listingsLength` returns the count; `listingsAt` returns the contract at a given index (reverts if out of range).

```solidity
function listingsAt(uint _index) external view returns (IListings);
function listingsLength() external view returns (uint);
```

| Parameter | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| `_index`  | `uint` | The index of the listings contract to retrieve |

| Return      | Type        | Description                                |
| ----------- | ----------- | ------------------------------------------ |
| `IListings` | `IListings` | The listings contract at the given index   |
| `uint`      | `uint`      | The count of registered listings contracts |

### `addListings` / `removeListings`

Register or de-register an authorised Listings contract.

```solidity
function addListings(address _listings_) external;
function removeListings(address _listings_) external;
```

**Access:** `onlyOwner`. `addListings` reverts on the zero address or a duplicate; `removeListings` reverts if the contract isn't registered.

| Parameter    | Type      | Description                                                    |
| ------------ | --------- | -------------------------------------------------------------- |
| `_listings_` | `address` | The address of the Listings contract to register / de-register |

**Returns:** None.

## Manager operations

{% hint style="warning" %}
These functions are callable only by an approved [Locker Manager](/contracts/supporting.md#lockermanager) and can mint or withdraw without a matching NFT. Managers are trusted to keep the collection token fully backed; misuse can break a collection.
{% endhint %}

### `unbackedDeposit`

Mints underlying collection tokens and hands them to an approved manager, trusting the manager not to break the backing count.

```solidity
function unbackedDeposit(address _collection, uint _amount) external;
```

**Access:** approved managers only, `nonReentrant`, `whenNotPaused`, collection must exist.

| Parameter     | Type      | Description                         |
| ------------- | --------- | ----------------------------------- |
| `_collection` | `address` | The address of the token collection |
| `_amount`     | `uint`    | The amount of ERC-20 tokens to mint |

**Returns:** None.

### `withdrawToken`

Lets an approved manager withdraw an ERC-721 from the Locker.

```solidity
function withdrawToken(address _collection, uint _tokenId, address _recipient) external;
```

**Access:** approved managers only.

| Parameter     | Type      | Description                      |
| ------------- | --------- | -------------------------------- |
| `_collection` | `address` | The collection address           |
| `_tokenId`    | `uint`    | The tokenId to withdraw          |
| `_recipient`  | `address` | The address to receive the token |

**Returns:** None.

## Administration

All of the following are `onlyOwner`.

### `setCollectionShutdownContract`

Sets the `ICollectionShutdown` contract — the only contract permitted to call `sunsetCollection`.

```solidity
function setCollectionShutdownContract(address payable _collectionShutdown) external;
```

| Parameter             | Type              | Description              |
| --------------------- | ----------------- | ------------------------ |
| `_collectionShutdown` | `address payable` | The new contract address |

### `setImplementation`

Sets the `INFTXV4Hook` implementation used by the Locker.

{% hint style="warning" %}
This can only be set **once**, to a non-zero address. It reverts if the implementation is already set.
{% endhint %}

```solidity
function setImplementation(address _implementation) external;
```

| Parameter         | Type      | Description                   |
| ----------------- | --------- | ----------------------------- |
| `_implementation` | `address` | The new `INFTXV4Hook` address |

### Fees, gate, and pausing

```solidity
function setCollectionCreationFee(uint _collectionCreationFee) external;
function setCollectionCreationFeeRecipient(address _collectionCreationFeeRecipient) external;
function setLaunchGate(address _launchGate) external;
function pause(bool _paused) external;
```

| Function                            | Parameter                                     | Description                                                                               |
| ----------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `setCollectionCreationFee`          | `_collectionCreationFee` (`uint`)             | The new collection creation fee, in ETH                                                   |
| `setCollectionCreationFeeRecipient` | `_collectionCreationFeeRecipient` (`address`) | The address that receives the creation fee (reverts on zero address)                      |
| `setLaunchGate`                     | `_launchGate` (`address`)                     | The launch gate to consult; pass `address(0)` to detach it and make launches unrestricted |
| `pause`                             | `_paused` (`bool`)                            | Pause (`true`) or unpause (`false`) all Locker activity                                   |