Selector compatibility

Two facets that export the same selector cannot both Add it to one diamond: the second cut reverts with CannotAddFunctionToDiamondThatAlreadyExists(selector). A Replace does not revert. It silently routes the selector to the later facet. This page lists every selector that two or more release facets export, and how to treat each one. The composition hazards table explains the cases that cost more than a failed deploy.

The table is generated. SelectorCompatibilityTest deploys every facet in FacetInventory, reads each one's ERC-8153 exportSelectors(), and checks the result against its hand classification. A new shared selector, a change in which facets share one, or a row that no longer clashes fails the test. After updating the classification, regenerate the table with the command below and paste the printed rows under Matrix. The test loads every inventory facet's artifact by path, so build the whole project first; a filtered forge test compiles only the files the test imports.

forge build && forge test --match-test test_EverySharedSelectorIsClassified -vv

Classes

A selector with mixed relations takes the most restrictive class, and its note names the others. For example, transferFrom is an ERC-20 override seam and also an ERC-20/ERC-721 standard clash, so it is Incompatible.

Today's 99 shared selectors: 19 Variant, 14 Override, 2 Identical, 36 One per diamond, 28 Incompatible.

Scope and decisions

• Inventory facets only. The test covers the 129 facets in FacetInventory. Every facet in src/ that exports its selectors (ERC-8153) is in the inventory (#176), so the table covers them all.
• Strategy adapters are their own diamonds. AaveV3Adapter, CompoundV3Adapter, CurveStableSwapAdapter, ERC4626Adapter, LidoAdapter and UniswapV3Adapter share the IStrategy, IProtocolAdapter and IAdapterOperator surface, so a diamond holds one of them. CurveStableSwapAdapter and UniswapV3Adapter also share pool(), slippageBps() and setSlippageBps(uint256). The adapters also clash with the vault side (asset() with ERC4626; harvest() and vault() with StrategyManager), so a vault diamond registers an adapter diamond as a strategy instead of cutting it in.
• ERC1363 shares no selector but is still exclusive. Its six *AndCall selectors clash with nothing, so this table cannot list it. It moves tokens through ERC20Lib, past the transfer/transferFrom that ERC20Pausable, ERC20Votes and GovernedVault replace, so decision D25 on #234 declares it mutually exclusive with all three. CompositionHazardsTest pins the bypass.
• The ERC-721 receiver seam. ERC721Wrapper serves onERC721Received (0x150b7a02) and accepts only its underlying collection. UniswapV3Adapter serves the same selector to receive position NFTs. The two are Incompatible: never cut both into one diamond. #201 tracks declaring seams like this one.
• Exclusions the table cannot show (D25). ERC721Enumerable and ERC721Votes keep their state in step only when every token movement goes through their own library. ERC721Burnable and ERC721Wrapper mint and burn through ERC721Lib instead, and share no selector with either, so the cut succeeds and the state drifts. Never combine them; ERC721Pausable next to them leaves burns and wraps unpaused. The same holds for app code: the standalone CCTPHookReceipt example mints through ERC721Lib._mint, so a fork of it that adds enumeration or votes must mint, burn and transfer through ERC721EnumerableLib or ERC721VotesLib. CompositionHazardsTest pins each facet case, and the composition hazards table lists them.
• Lattice-chosen names are listed, not renamed. getConfig(), getForwarder() and the GovernedSafeDiamondCut operation views clash because of names Lattice picked. Renaming them changes selectors, and renaming the GovernedSafe views also changes ERC-165 id 0xacb1aeb6 (coordinate with #206). The decision on #240 is to keep the names and record them in this table. A rename before 1.0 would need its own issue, coordinated with #206.

Token extension hook model

Decision D25 on #234 (option (a), for 0.5.0) fixes how token extensions that change transfer, mint or burn behaviour compose:

1. Base libraries run no hooks. ERC20Lib._update, ERC721Lib._update and ERC1155Lib._update move balances and emit the standard events. They call no extension and read no extension flag. OpenZeppelin composes its extensions through virtual _update overrides. A Lattice library cannot dispatch virtually, and a hook in the base library would cost every token an SLOAD per movement. The one exception is ERC-721 batch minting (ERC721ConsecutiveLib, #236), which has no selector to replace because its batches exist only as ownership checkpoints. ERC721Lib._ownerOf falls back to those checkpoints for an id with no stored owner, and ERC721Lib._update bans single mints during a batch-minting diamond's first initialization and marks burned batch ids. On a diamond without batches that reads one storage slot on each mint and burn, and none on a transfer of a stored token. A batch-minting diamond also reads the initializable slot on each mint, and resolves an untransferred batch token through the burn bitmap and the checkpoint search. It lets every path, base or extension, see batch-minted tokens.

2. A movement-replacing extension replaces the base selectors it gates. An extension that must see or gate every transfer (Pausable, Votes, Enumerable, Supply) exports its own versions of the standard's public movement selectors. Its recipe cuts it with Replace, or excludes the base copies with _cutExcept.

3. Two extensions that replace the same selectors are mutually exclusive. Every member of a standard's family replaces all of that standard's movement selectors, so any two members collide. Add reverts with CannotAddFunctionToDiamondThatAlreadyExists. A Replace routes the selectors to the later facet with no error and drops the earlier facet's logic: Pausable over Votes stops moving votes, and Votes over Pausable ignores the pause.

4. A direct mover bypasses the family. A facet that mints, burns or moves balances by calling the base library (_mint, _burn, _update) and does not apply the extension's logic itself never goes through the replaced selectors. It shares no selector with a movement-replacing extension, so the cut succeeds with no signal and the diamond silently loses pause or vote accounting on that path. Treat every such direct mover as mutually exclusive with every movement-replacing extension of its standard.

5. A mint-gating extension holds only on its own mint path. ERC20Capped checks its cap inside the internal _mint a composing facet calls, not in ERC20Lib._mint, and exports only cap(). Every shipped facet that mints through the base library directly lifts the supply past the cap, so each is mutually exclusive with ERC20Capped.

6. The escape is a combined facet. A diamond that needs two behaviours on one path gets one facet that does both. The minimal combined facets are the sanctioned mint and burn paths that the recipes leave to the integrator, since DeployERC20Pausable, DeployERC20Votes and DeployERC20Capped expose no mint:

   • Pausable: call PausableLib.checkNotPaused() before ERC20Lib._mint/_burn.
   • Votes: call ERC20VotesLib._mint/_burn, which checkpoint voting units and enforce the uint208 supply bound.
   • Capped: call ERC20Capped's internal _mint, or ERC20CappedLib._checkCap(totalSupply + value) before ERC20Lib._mint.
   • Two of them on one path: apply each check in one function, for example _checkCap then ERC20VotesLib._mint.

   GovernedVault is the shipped example of a full combined facet: its transfer/transferFrom and ERC-4626 mutators move ERC-20 balances and voting units together, and DeployGovernedVault routes those selectors to it with _cutExcept.

7. Option (b), a hook in each base library, is revisited only with ERC-3643 (#172). It would append to the released ERC20Storage.

ERC-20

The movement selectors are transfer (0xa9059cbb) and transferFrom (0x23b872dd).

The vote-aware ERC20VotesLib._mint is a direct minter for ERC20Capped too: it enforces only the uint208 bound.

CompositionHazardsTest section 3 pins this:

• test_MovementReplacingFamilyClaimsTheTransferPair: every family member replaces both movement selectors.
• test_PausableAddedToVotesRevertsAtCut: Add of a second member reverts.
• test_PausableReplacingVotesDesyncsVotes and test_VotesReplacingPausableBypassesPause: Replace is silent.
• test_BurnableNextToVotesDesyncsVotes and test_BurnableNextToPausableBurnsWhilePaused: a direct mover bypasses the family.
• test_ERC1363BypassesPause and test_ERC1363BypassesVoteCheckpoints: ERC1363 moves tokens past the pause and the vote checkpoints.
• test_DirectMinterNextToCappedExceedsCap: ERC7802 next to the capped recipe mints past the cap, while a composing mint over _checkCap still reverts.

The matrix below classifies transfer as One per diamond and transferFrom as Incompatible (it is also the ERC-721 selector), each with a D25 note.

ERC-721 and ERC-1155

ERC721Enumerable, ERC721Pausable and ERC721Votes each replace the three ERC-721 movement selectors, so a diamond takes at most one; Enumerable and Votes move tokens only through their own libs. ERC1155Pausable replaces both ERC-1155 movement selectors and serves pause-gated burn/burnBatch. ERC1155Supply replaces no movement selector; it serves supply-tracking burn/burnBatch and mints through ERC1155SupplyLib. ERC1155Burnable, ERC1155Pausable and ERC1155Supply share the burn selectors, so a diamond takes one of the three. The ERC-721 movement selectors are transferFrom (0x23b872dd) and both safeTransferFrom overloads (0x42842e0e, 0xb88d4fde). The ERC-1155 movement selectors are safeTransferFrom (0xf242432a) and safeBatchTransferFrom (0x2eb2c2d6). The shipped direct movers are ERC721Burnable (burn), ERC721Wrapper (depositFor, withdrawTo, onERC721Received) and ERC1155Burnable (burn, burnBatch). Each is mutually exclusive with every movement-replacing extension of its standard.

ERC-721 Consecutive is not a family member. It ships no facet and no selector: ERC721ConsecutiveInit mints ERC-2309 batches in the diamond's first initialization only (an upgrade cut's reinitializer window cannot), and the base library resolves their owners (item 1 above). So it composes with ERC721Pausable, ERC721Burnable, ERC721URIStorage, ERC721Wrapper and ERC2981. Two extensions exclude it:

• ERC721Enumerable, as OpenZeppelin forbids: a batch would skip the lists. Both init orders revert ERC721EnumerableForbiddenBatchMint.
• ERC721Votes, unlike OpenZeppelin, which moves batch-minted voting units through _increaseBalance. ERC721VotesLib cannot see a batch, so the batch would vote while the supply checkpoint (and a Governor quorum read from it) missed it, and a vote-aware burn of a batch token would underflow that checkpoint. Both init orders, and ERC721VotesInit in a later upgrade cut, revert ERC721VotesForbiddenBatchMint.

CompositionHazardsTest pins both (test_ERC721ConsecutiveAndEnumerableRevertInEitherOrder, test_ERC721ConsecutiveAndVotesRevertInEitherOrder).

ERC-721 Pausable, Enumerable and Votes and ERC-1155 Pausable and Supply follow the ERC-20 pattern. Each one:

• replaces all of its standard's movement selectors, so any two members collide on Add;
• joins a family test like test_MovementReplacingFamilyClaimsTheTransferPair for its standard;
• has its shared selectors classified in SelectorCompatibilityTest with a D25 note;
• pins its exclusivity with each shipped direct mover in CompositionHazardsTest, or replaces that mover's selectors too, or ships a combined facet;
• names in its NatSpec the selectors it replaces and the extensions it excludes.

Matrix