> For the complete documentation index, see [llms.txt](https://docs.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.nftx.io/contracts/royalty-gate.md).

# Royalty Gate

The royalty-charging entrance to the Locker for ERC721-C collections that enforce creator royalties on NFTX.

`RoyaltyGate` lets an ERC721-C collection enforce its ERC-2981 creator royalty on NFTX without any change to the Locker, the hooks, Listings, or the Zap. The collection's creator lists the gate as an **authorizer** on the collection's transfer validator and leaves the Locker **off** its operator whitelist. From then on, every NFT that enters the vault comes through the gate, and the gate pays the royalty.

The gate has no owner and holds nothing between transactions. It works on any registered collection; where a collection hasn't enforced royalties, entries through the gate pay the royalty voluntarily.

{% hint style="info" %}
The Royalty Gate is live on every mainnet at `0xB1C4E21393b3F9A3f75F3a7c7AbC18Cd07FBba4F`: Ethereum, Base, Arbitrum One, Ink, Arc, ApeChain and Robinhood Chain. It isn't deployed on the testnets. See the [Deployment Addresses](https://docs.nftx.io/contracts/addresses.md).
{% endhint %}

Signatures, events and errors below come from the `IRoyaltyGate` interface, which integrators should build against.

## Why enforcement lives on the way in

ERC721-C validators decide who may move a collection's NFTs. Two kinds of transfer reach them, and they're treated very differently:

* **Operator transfers** (`caller != from`) are checked against the collection's operator whitelist, or a temporary grant from a listed authorizer. The Locker pulls NFTs this way on every deposit.
* **Owner transfers** (`caller == from`) are allowed at every security level that permits over-the-counter (OTC) transfers. The Locker sends NFTs this way on every exit: redeems, listing fills and cancels, and shutdowns.

So a validator can gate the way **in** but never the way **out**. With the Locker off the whitelist, each transfer is admitted like this:

| Transfer                                         | Caller | From   | Admitted because                            |
| ------------------------------------------------ | ------ | ------ | ------------------------------------------- |
| Holder → gate                                    | gate   | holder | the gate's temporary grant                  |
| Gate → Locker (deposit)                          | Locker | gate   | the same grant, which also names the Locker |
| Locker → anyone (redeem, fill, cancel, shutdown) | Locker | Locker | an owner moving its own NFT                 |
| Bare `Locker.deposit`                            | Locker | holder | nothing: refused                            |

Behind the scenes, the gate grants permission for exactly the token IDs being deposited, and for the operator doing the pulling, just before the gate pulls them. It clears every grant as soon as the Locker holds the NFTs. If the validator refuses to clear a grant the gate made, the whole entry reverts (`AuthorizationNotCleared`), so no permission outlives the deposit. The gate only ever pulls from the caller, so it can't move an NFT its caller doesn't own.

## What the royalty is

One NFT entering the vault mints one whole floor token, so the gate prices each NFT at `1e18` and pays every receiver `royaltyInfo(tokenId, 1e18)` in floor tokens. Royalties are read per token and combined per receiver, so a collection with different receivers for different tokens pays each of them for their own tokens.

For example: a collection with a 9% royalty. Depositing one NFT mints 1 floor token; 0.09 goes to the creator and 0.91 to the depositor.

* The depositor pays, as ERC-2981 intends for a seller. Each NFT pays once per trip into the vault; buying it back out is free.
* A royalty can never exceed the floor it's charged on. A collection whose `royaltyInfo` reverts, or names nobody, owes nothing.
* Floor tokens have no transfer hook, so no receiver can block an entry.

## Entry points

### `deposit`

Deposits the caller's NFTs, pays the royalty out of the minted floor tokens, and sends the rest to `_recipient`. The caller must have approved the gate for the token IDs.

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

| Parameter       | Type      | Description                                                                                          |
| --------------- | --------- | ---------------------------------------------------------------------------------------------------- |
| `_collection`   | `address` | The ERC721 collection                                                                                |
| `_tokenIds`     | `uint[]`  | The IDs to deposit, owned by the caller                                                              |
| `_recipient`    | `address` | Receives the floor tokens left after royalties                                                       |
| `_minTokensOut` | `uint`    | Reverts `InsufficientOutput` if the recipient would receive less. Pass `quoteDeposit`'s first return |

| Return       | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| `tokensOut_` | `uint` | Floor tokens sent to `_recipient` |

### `sellNFTsForETH`

Deposits the caller's NFTs, pays the royalty as `deposit` does, sells the rest for ETH through the [Zap](https://docs.nftx.io/contracts/zap.md) and pays the caller. Flow: `NFT → gate → Locker → royalty paid in floor tokens → remainder sold for ETH`.

```solidity
function sellNFTsForETH(address _collection, uint[] calldata _tokenIds, uint _minETHReceived) external returns (uint ethReceived_);
```

| Parameter         | Type      | Description                                                                                                                             |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `_collection`     | `address` | The ERC721 collection                                                                                                                   |
| `_tokenIds`       | `uint[]`  | The IDs to sell, owned by the caller                                                                                                    |
| `_minETHReceived` | `uint`    | Reverts `InsufficientOutput` if the caller would receive less. Quote it on the floor tokens left after the royalty, not on whole tokens |

| Return         | Type   | Description            |
| -------------- | ------ | ---------------------- |
| `ethReceived_` | `uint` | ETH sent to the caller |

## Views

### `quoteDeposit`

What `deposit` would pay out at the collection's current royalty terms.

```solidity
function quoteDeposit(address _collection, uint[] calldata _tokenIds) external view returns (uint tokensOut_, uint royalty_);
```

| Return       | Type   | Description                                     |
| ------------ | ------ | ----------------------------------------------- |
| `tokensOut_` | `uint` | Floor tokens the recipient would receive        |
| `royalty_`   | `uint` | Floor tokens that would go to royalty receivers |

### `isAuthorizerFor`

Whether the collection lists this gate as an authorizer on its transfer validator. Never reverts.

```solidity
function isAuthorizerFor(address _collection) external view returns (bool);
```

### `isBypassable`

Whether the Locker can still pull the collection's NFTs without the gate, which makes the royalty voluntary. Never reverts, and reads `true` whenever it can't tell.

```solidity
function isBypassable(address _collection) external view returns (bool);
```

It answers in this order:

1. No transfer validator: bypassable.
2. The collection's own `isTransferAllowed(locker, holder, locker)`, where the collection has one (Creator Token Standards collections do).
3. The validator's policy: security level 1 (no restrictions), or level 2 (a blacklist) without the Locker on it, is bypassable.
4. Otherwise the Locker whitelisted by address, or by codehash on Limit Break v3, is bypassable.

**A collection enforces royalties on NFTX when `isAuthorizerFor` is `true` and `isBypassable` is `false`.** That's the check the NFTX app uses to route a collection through the gate.

### `locker` / `zap`

The Locker every entry is deposited into, and the Zap `sellNFTsForETH` sells through. Both are fixed at deployment: the Locker is the same on every chain, and the Zap is each chain's `NFTXZap` from the [Deployment Addresses](https://docs.nftx.io/contracts/addresses.md).

## Events

| Event                                                                                                                                      | Emitted when                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `RoyaltyPaid(address indexed _collection, address indexed _receiver, uint _amount)`                                                        | Once per distinct royalty receiver on an entry, in floor tokens |
| `GatedDeposit(address indexed _collection, uint[] _tokenIds, address indexed _sender, address _recipient, uint _tokensOut, uint _royalty)` | NFTs enter through `deposit`                                    |
| `GatedSale(address indexed _collection, uint[] _tokenIds, address indexed _seller, uint _ethReceived, uint _royalty)`                      | NFTs enter through `sellNFTsForETH`                             |

## Errors

| Error                              | Cause                                                                                                                                    |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `NoTokenIds()`                     | No token IDs given                                                                                                                       |
| `ZeroAddress()`                    | A zero recipient                                                                                                                         |
| `CollectionNotRegistered(address)` | The collection has no floor token on the Locker                                                                                          |
| `InsufficientOutput(uint, uint)`   | The payout fell below the caller's minimum                                                                                               |
| `UnauthorizedETHSender()`          | ETH arrived from anything but the Zap                                                                                                    |
| `AuthorizationNotCleared(address)` | The validator refused to clear a grant the gate made                                                                                     |
| `ExitsBlocked(address, uint)`      | The collection's security level (4, 7, 8 or 9) blocks owner transfers, so a vaulted NFT could never leave. The gate refuses to let it in |

## Supported validators

| Validator                                          | Address                                      | Notes                                                      |
| -------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------- |
| OpenSea `StrictAuthorizedTransferSecurityRegistry` | `0xA000027A9B2802E1ddf7000061001e5c005A0000` | Level 3 with authorization and wildcard enabled            |
| Limit Break `CreatorTokenTransferValidator` v3     | `0x721C002B0059009a671D00aD1700c9748146cd1B` | Authorization mode on; wildcard operators may be on or off |

Both token-ID-based and older caller-only collections work on both. Validators without authorizers (Limit Break v1 and v2, OpenSea's Operator Filter Registry) can't host the gate; a collection on one of them would first move to a supported validator. See [Creator Token Approvals](https://docs.nftx.io/contracts/creator-token-approvals.md#enforced-royalties-with-the-royalty-gate) for the onboarding steps.

## Launchpad collections

New launchpad collections created with an enforced template list the gate as an authorizer and never whitelist the Locker, so their royalties are enforced on NFTX from the first trade. The launchpad and its settlement contract move the NFTs they mint straight into the vault without the gate. A holder-rewards variant names the collection itself as its royalty receiver: floor-token royalties from the gate collect on the collection until anyone sells them for ETH (at no less than the pool's 30-minute TWAP, minus 5%) and stream that ETH to holders.

## Sources

Implementation: [`RoyaltyGate.sol`](https://github.com/flayerlabs/nftx-v4-protocol/blob/main/src/contracts/utils/RoyaltyGate.sol) and [`IRoyaltyGate.sol`](https://github.com/flayerlabs/nftx-v4-protocol/blob/main/src/interfaces/utils/IRoyaltyGate.sol). The design notes, including what the gate can and can't enforce, are in [`ROYALTIES.md`](https://github.com/flayerlabs/nftx-v4-protocol/blob/main/ROYALTIES.md).
