Burn-to-mint NFT

burn-mint-nft v1: Burn your token to mint an NFT

An ERC-721 collection that people mint by paying with a token (and/or ETH). At mint time the payment is split along up to 4 **routes** that are fixed at deploy:

| Route | What happens to its share | |---|---| | **BURN** | `payToken.burn(amount)`: a real burn. The mint reverts unless total supply *and* the contract's balance both fall by exactly that amount. | | **WALLET** | Token: sent straight to the wallet. ETH: credited to `owedNative[wallet]`; anyone can call `withdraw(wallet)` to pay it out. | | **INSTANCE** | Token: forwarded into another Socket instance's `fund(poolId, amount)` (e.g. a staking vault), fee-exempt. |

ETH payments only go to WALLET routes, split pro rata by their shares. The last route always takes the remainder, so a split never leaves dust.

Also included: up to 8 timed **phases** (public, or a merkle allowlist), each with an ETH and/or token price, a per-wallet limit and a phase cap. There is an owner **reserve** held back from every phase, an ERC-2981 royalty (≤10%), an optional ERC-721C transfer validator, an optional **soulbound** mode (ERC-5192) and ERC-4906 metadata refresh events.

Config (`BurnMintNFTConfig`)

`name`, `symbol`, `maxSupply` (≥1), `reserve` (≤ maxSupply), `baseURI`, `uriSuffix` (".json" or ""), `payToken` (0 = ETH or free only), `phases` (≤8), `routes` (≤4, shares sum to 100%), `royaltyReceiver`, `royaltyBps` (≤1000), `transferValidator` (0 = off), `soulbound`, `metadataWriter` (0 = none).

**Locked after deploy:** everything except `baseURI` (until frozen) and `transferValidator`. Routes, prices, phases, supply, reserve and royalty can only change by redeploying.

Merkle leaf (OZ StandardMerkleTree, types `address,uint256,uint256,address,uint256`): `keccak256(bytes.concat(keccak256(abi.encode(nft, chainid, phaseId, wallet, allowance))))`. A proof only works on this contract, this chain and this phase. In a merkle phase a wallet can mint up to its allowance (or the phase's wallet limit if that is lower).

Roles

- **Owner:** `reserveMint`, `setBaseURI` (until `freezeMetadata`, one way), `freezeMetadata`, `setTransferValidator` (0 always restores plain transfers), `pause`/`unpause` (minting only), `rescue` (only tokens above custody, never owed ETH). - **Metadata writer** (optional): may only call `emitMetadataUpdate(id)` (ERC-4906 refresh for changing traits). - **Anyone:** `mint`, `mintWithToken`, `withdraw(wallet)` (pays the recorded wallet), `settle()`, `burn` (own or approved NFTs). - **A route wallet:** `withdrawTo(dest)` to receive its owed ETH elsewhere (for wallets that cannot take ETH).

Fee lanes

| Flow | When | |---|---| | MintProceeds (default 1%) | On every paid mint, on the full price, before the split. Tokens sent straight to the contract pay the same fee when `settle()` routes them. |

The module is published with `FLAG_CHARGES_INFLOW`: an INSTANCE route's target pulls from this contract and does not charge again. ETH sent outside a mint is never routed. It stays above custody and can be rescued.

Risks in plain English

- Routes are locked. If a WALLET route's wallet is lost, so is its share. A wallet that cannot receive ETH can still `withdrawTo` somewhere else. - A pay token that cannot really burn makes token mints with a BURN route revert. Test with a small mint first. - If an INSTANCE target is paused, halted, migrated or full, token mints revert until it reopens. ETH mints keep working. If *this* NFT is migrated or its module halted, the exemption lapses and `settle()` forwards would be charged again by the target. - A transfer validator can block transfers while it is set. The owner can always set it to 0. - Soulbound tokens can never be sold, transferred or staked. They can be burned. - Until `freezeMetadata`, the owner can repoint all metadata.

What if

- **My payout wallet cannot receive ETH?** It stays owed. That wallet calls `withdrawTo(dest)`. Nobody else can move it. - **The token's burn is fake (supply does not fall)?** The mint reverts with `FakeBurn` and nothing is spent. - **The vault I route to is paused?** Token mints revert (`EntriesClosed`) until it reopens; no tokens are lost. - **Someone sends tokens straight to the NFT?** `settle()` (anyone) charges the fee and splits them along the routes. - **Someone tries a proof from another collection, phase or chain?** It fails: the leaf binds all three.

Implementation notes (size)

The module sits at the EIP-170 limit next to the Socket base, so:

- `LeanERC721` is a minimal ERC-721 core with the same semantics as OpenZeppelin 5's `_update` hook and argless errors. It replaces OZ `ERC721`. ERC-2981 is a single `royaltyInfo`. - The **kit** (`BurnMintNFTPresets`, which is also the Presets contract) does the pure config work: decoding, validation, flattening into packed words (`PackLib`), name/symbol/tokenURI strings and the current-config re-encode. The implementation deploys it in its constructor (its first CREATE). Each clone derives its address from its own EIP-1167 code: `kit() == CREATE(implementation, nonce 1)`. It is only ever called with view calls and holds nothing. - `BurnMintNFTLens` serves phase status (`phaseInfo`, `phases`) and `paymentInfo` from `config()`, `info()` and the counters. - `name()`, `symbol()` and `tokenURI()` are views that go through the kit; they cost more gas but are free in `eth_call`.

Files

`BurnMintNFT.sol` (module), `BurnMintNFTTypes.sol` (structs, PackLib, kit interface), `BurnMintNFTPresets.sol` (kit + friendly presets: whole-token prices, gwei, percent routes, start time + hours, royalty per-mille), `BurnMintNFTLens.sol`, `LeanERC721.sol`, `ui-schema.json`.