---
title: "OverlayerOriginNFT"
description: "Solidity reference for OverlayerOriginNFT, the shared implementation for allowlisted, one-time-mint Overlayer Origin ERC-721 collections, covering whitelist phases, Merkle mints, price tiers and royalties."
keywords:
  - "OverlayerOriginNFT"
  - "Solidity"
  - "ERC-721"
  - "allowlist"
  - "Merkle"
  - "royalties"
canonical_url: https://docs.overlayer.fi/developer_guide/contracts/OverlayerOriginNFT
md_url: https://docs.overlayer.fi/developer_guide/contracts/OverlayerOriginNFT.md
last_updated: 2026-10-03T17:55:49.000Z
---

# OverlayerOriginNFT

> Solidity reference for OverlayerOriginNFT, the shared implementation for allowlisted, one-time-mint Overlayer Origin ERC-721 collections, covering whitelist phases, Merkle mints, price tiers and royalties.

Shared implementation for an allowlisted, one-time-mint ERC-721 collection.

_Mint eligibility is intentionally local to each chain deployment._

### MAX_ROYALTY_BPS

```solidity
uint96 MAX_ROYALTY_BPS
```

Maximum default royalty in basis points.

### WHITELIST_MINT_DURATION

```solidity
uint256 WHITELIST_MINT_DURATION
```

Duration of the initial whitelist-only mint phase for tier collections.

### whitelisted

```solidity
mapping(address => bool) whitelisted
```

Addresses eligible to mint during whitelist-only phases on this chain.

### freeMintWhitelisted

```solidity
mapping(address => bool) freeMintWhitelisted
```

Addresses eligible for a zero-price primary mint on this chain.

_Free mints still consume the next sequential token ID and price tier._

### hasMinted

```solidity
mapping(address => bool) hasMinted
```

Whether an address has already performed its one primary mint on this chain.

### nextTokenId

```solidity
uint256 nextTokenId
```

The ID assigned to the next primary mint.

### merkleRoot

```solidity
bytes32 merkleRoot
```

Merkle root for the scalable allowlist; zero disables proof-based mints.

### feeCollector

```solidity
address payable feeCollector
```

Wallet receiving ETH paid for primary mints; zero for free collections.

### initialMintPrice

```solidity
uint256 initialMintPrice
```

Mint price charged for token IDs in the first pricing unit.

### priceIncrement

```solidity
uint256 priceIncrement
```

Price added after every completed pricing unit.

### priceUnitDelta

```solidity
uint256 priceUnitDelta
```

Number of token IDs sold at each price level.

### maxSupply

```solidity
uint256 maxSupply
```

Maximum number of primary NFTs that can ever be minted; zero disables the cap.

### bonusNumerator

```solidity
uint256 bonusNumerator
```

Numerator of the collection's exact bonus fraction.

### bonusDenominator

```solidity
uint256 bonusDenominator
```

Denominator of the collection's exact bonus fraction, fixed at 100.

### mintStartTime

```solidity
uint256 mintStartTime
```

Unix timestamp at which allowlisted users can begin minting.

### mintEndTime

```solidity
uint256 mintEndTime
```

Unix timestamp at which all primary mints end; zero disables the deadline.

### publicMintStartTime

```solidity
uint256 publicMintStartTime
```

Unix timestamp at which direct mints become public until `{mintEndTime}`; zero keeps direct mints allowlisted.

### WhitelistUpdated

```solidity
event WhitelistUpdated(address account, bool isWhitelisted)
```

Emitted when an address's allowlist status changes.

### FreeMintWhitelistUpdated

```solidity
event FreeMintWhitelistUpdated(address account, bool isFreeMintWhitelisted)
```

Emitted when an address's free-mint eligibility changes.

### Minted

```solidity
event Minted(address account, uint256 tokenId)
```

Emitted after an eligible address mints its only primary token.

### BaseURIUpdated

```solidity
event BaseURIUpdated(string baseURI)
```

Emitted when the base token URI changes.

### RoyaltyUpdated

```solidity
event RoyaltyUpdated(address receiver, uint96 feeNumerator)
```

Emitted when default secondary-sale royalty terms change.

### MerkleRootUpdated

```solidity
event MerkleRootUpdated(bytes32 merkleRoot)
```

Emitted when the scalable allowlist root changes.

### MintPaymentCollected

```solidity
event MintPaymentCollected(address minter, address feeCollector, uint256 amount)
```

Emitted after a paid primary mint forwards ETH to the fee collector.

### MintPaymentRefunded

```solidity
event MintPaymentRefunded(address minter, uint256 amount)
```

Emitted after a paid mint returns excess ETH to the minter.

### NotWhitelisted

```solidity
error NotWhitelisted()
```

Reverts when an address is not allowed to mint.

### AlreadyMinted

```solidity
error AlreadyMinted()
```

Reverts when an address has already minted from this collection.

### ZeroAddress

```solidity
error ZeroAddress()
```

Reverts when an allowlist address is the zero address.

### InvalidRoyaltyConfiguration

```solidity
error InvalidRoyaltyConfiguration()
```

Reverts when the royalty receiver and fee are configured inconsistently.

### RoyaltyFeeTooHigh

```solidity
error RoyaltyFeeTooHigh(uint96 feeNumerator)
```

Reverts when a royalty fee exceeds the collection maximum.

### InvalidMerkleProof

```solidity
error InvalidMerkleProof()
```

Reverts when a caller cannot prove membership in the active Merkle allowlist.

### InvalidMintPricing

```solidity
error InvalidMintPricing()
```

Reverts when paid-mint pricing parameters are inconsistent.

### InsufficientMintPayment

```solidity
error InsufficientMintPayment(uint256 expected, uint256 received)
```

Reverts when a caller does not provide at least the active mint price.

### FeeTransferFailed

```solidity
error FeeTransferFailed()
```

Reverts when the configured fee collector rejects a mint payment.

### RefundFailed

```solidity
error RefundFailed()
```

Reverts when returning excess ETH to the minter fails.

### InvalidTokenId

```solidity
error InvalidTokenId()
```

Reverts when a caller requests a price for token ID zero.

### MaxSupplyReached

```solidity
error MaxSupplyReached(uint256 maxSupply)
```

Reverts when every token ID in the collection has been minted.

### MintNotStarted

```solidity
error MintNotStarted(uint256 mintStartTime, uint256 currentTime)
```

Reverts when minting is attempted before `{mintStartTime}`.

### MintEnded

```solidity
error MintEnded(uint256 mintEndTime, uint256 currentTime)
```

Reverts when minting is attempted at or after `{mintEndTime}`.

### InvalidMintSchedule

```solidity
error InvalidMintSchedule()
```

Reverts when a mint-window configuration is internally inconsistent.

### constructor

```solidity
constructor(string name_, string symbol_, address initialOwner_, string baseURI_, address royaltyReceiver_, uint96 royaltyFeeNumerator_, address payable feeCollector_, uint256 initialMintPrice_, uint256 priceIncrement_, uint256 priceUnitDelta_, uint256 maxSupply_, uint256 bonusNumerator_, uint256 mintStartTime_, uint256 mintEndTime_, uint256 publicMintStartTime_) internal
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| name_ | string | Collection name. |
| symbol_ | string | Collection symbol. |
| initialOwner_ | address | Owner allowed to administer the collection. |
| baseURI_ | string | Base URI used by `{tokenURI}`. |
| royaltyReceiver_ | address | Initial royalty recipient; use the zero address when no royalty is configured. |
| royaltyFeeNumerator_ | uint96 | Initial royalty in basis points. |
| feeCollector_ | address payable | Recipient of ETH paid for primary mints; use zero for a free collection. |
| initialMintPrice_ | uint256 | Price for the first `{priceUnitDelta_}` token IDs. |
| priceIncrement_ | uint256 | Price added after each complete pricing unit. |
| priceUnitDelta_ | uint256 | Number of token IDs per price level. |
| maxSupply_ | uint256 | Maximum primary NFTs that can ever be minted; use zero for no cap. |
| bonusNumerator_ | uint256 | Numerator of the collection's exact bonus fraction. |
| mintStartTime_ | uint256 | Unix timestamp at which allowlisted users can begin minting. |
| mintEndTime_ | uint256 | Unix timestamp at which all primary mints end; use zero for no deadline. |
| publicMintStartTime_ | uint256 | Unix timestamp at which direct mints become public until `{mintEndTime}`; use zero for never. |

### whenMintOpen

```solidity
modifier whenMintOpen()
```

_Restricts primary mints to the configured mint window._

### setWhitelist

```solidity
function setWhitelist(address account_, bool isWhitelisted_) external
```

Updates one address's eligibility to mint.

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| account_ | address | Address whose eligibility is changing. |
| isWhitelisted_ | bool | New eligibility status. |

### batchSetWhitelist

```solidity
function batchSetWhitelist(address[] accounts_, bool isWhitelisted_) external
```

Updates the eligibility of multiple addresses.

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| accounts_ | address[] | Addresses whose eligibility is changing. |
| isWhitelisted_ | bool | New eligibility status for every address. |

### setFreeMintWhitelist

```solidity
function setFreeMintWhitelist(address account_, bool isFreeMintWhitelisted_) external
```

Updates one address's zero-price mint eligibility.

_Free-mint eligibility also allows direct minting during a whitelist-only phase._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| account_ | address | Address whose free-mint eligibility is changing. |
| isFreeMintWhitelisted_ | bool | New free-mint eligibility status. |

### batchSetFreeMintWhitelist

```solidity
function batchSetFreeMintWhitelist(address[] accounts_, bool isFreeMintWhitelisted_) external
```

Updates zero-price mint eligibility for multiple addresses.

_Free-mint eligibility also allows direct minting during a whitelist-only phase._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| accounts_ | address[] | Addresses whose free-mint eligibility is changing. |
| isFreeMintWhitelisted_ | bool | New free-mint eligibility status for every address. |

### mint

```solidity
function mint() external payable returns (uint256 tokenId)
```

Mints the caller's sole primary NFT for this collection on this chain.

_Direct mints are allowlisted until `{publicMintStartTime}`, when configured._

#### Return Values

| Name | Type | Description |
| ---- | ---- | ----------- |
| tokenId | uint256 | The newly minted token ID. |

### mintWithProof

```solidity
function mintWithProof(bytes32[] proof_) external payable returns (uint256 tokenId)
```

Mints the caller's sole primary NFT using a Merkle allowlist proof.

_The leaf is `keccak256(bytes.concat(keccak256(abi.encode(account))))`._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| proof_ | bytes32[] | Sorted Merkle sibling hashes proving the caller is in `{merkleRoot}`. |

#### Return Values

| Name | Type | Description |
| ---- | ---- | ----------- |
| tokenId | uint256 | The newly minted token ID. |

### burn

```solidity
function burn(uint256 tokenId_) external
```

Burns a token owned by the caller or for which the caller is approved.

_This enables an approved future redemption contract to atomically consume source NFTs._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| tokenId_ | uint256 | Token ID to burn. |

### burnBatch

```solidity
function burnBatch(uint256[] tokenIds_) external
```

Burns multiple tokens owned by the caller or for which the caller is approved.

_Reverts atomically if any token does not exist or the caller is not authorized for it._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| tokenIds_ | uint256[] | Token IDs to burn. |

### setMerkleRoot

```solidity
function setMerkleRoot(bytes32 merkleRoot_) external
```

Replaces the Merkle root used by `{mintWithProof}`.

_Replacing the root never resets `{hasMinted}`; set the root to zero to disable proof-based mints._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| merkleRoot_ | bytes32 | Root generated from the eligible addresses. |

### setBaseURI

```solidity
function setBaseURI(string baseURI_) external
```

Updates the base URI used to resolve token metadata.

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| baseURI_ | string | New base URI. |

### setRoyalty

```solidity
function setRoyalty(address receiver_, uint96 feeNumerator_) external
```

Sets the default marketplace-readable secondary-sale royalty.

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| receiver_ | address | Recipient of the royalty payment. |
| feeNumerator_ | uint96 | Royalty in basis points. |

### clearRoyalty

```solidity
function clearRoyalty() external
```

Clears the default marketplace-readable secondary-sale royalty.

### pause

```solidity
function pause() external
```

Pauses direct and Merkle allowlist mints.

### unpause

```solidity
function unpause() external
```

Resumes direct and Merkle allowlist mints.

### mintPrice

```solidity
function mintPrice() public view returns (uint256)
```

Returns the exact ETH amount required to mint the next token ID.

### mintPriceForAccount

```solidity
function mintPriceForAccount(address account_) public view returns (uint256)
```

Returns the exact ETH amount an account must pay to mint the next token ID.

_A free-mint allowlisted account pays zero but still advances `{nextTokenId}`._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| account_ | address | Address requesting the primary mint. |

### bonus

```solidity
function bonus() public view returns (uint256 numerator, uint256 denominator)
```

Returns the collection's exact bonus fraction.

### isPublicMintOpen

```solidity
function isPublicMintOpen() public view returns (bool)
```

Returns whether direct mints are currently open to every address.

### mintPriceForTokenId

```solidity
function mintPriceForTokenId(uint256 tokenId_) public view returns (uint256)
```

Returns the price applicable to a given token ID.

_IDs 1 through `{priceUnitDelta}` use `{initialMintPrice}`; the next unit adds `{priceIncrement}`._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| tokenId_ | uint256 | Token ID whose primary mint price is being queried. |

### isMerkleWhitelisted

```solidity
function isMerkleWhitelisted(address account_, bytes32[] proof_) public view returns (bool)
```

Returns whether an address is included in the active Merkle allowlist.

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| account_ | address | Address whose membership is being checked. |
| proof_ | bytes32[] | Sorted Merkle sibling hashes for the address. |

### supportsInterface

```solidity
function supportsInterface(bytes4 interfaceId_) public view virtual returns (bool)
```

_See `{IERC165-supportsInterface}`._

### merkleLeaf

```solidity
function merkleLeaf(address account_) public pure returns (bytes32)
```

Computes the double-hashed leaf used by the Merkle allowlist.

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| account_ | address | Address to encode as an allowlist leaf. |

### _baseURI

```solidity
function _baseURI() internal view virtual returns (string)
```

_Base URI for computing `{tokenURI}`. If set, the resulting URI for each
token will be the concatenation of the `baseURI` and the `tokenId`. Empty
by default, can be overridden in child contracts._