[ryanio]

Adds ERC721SeaDropAgents, an extension for collections whose tokens are AI agents, modeled on what MUSEGOD's Muses contract added to ERC721SeaDrop on Robinhood Chain. The ERC-8048 code is a separate module in src/lib, so other token contracts can reuse it.

Agent registration

registerAgents(firstTokenId, lastTokenId, prefix, suffix) registers an ERC-8004 agent for each token through an ERC-8217 adapter, with agent URI prefix + id + suffix. Whoever holds the token controls the agent. The adapter is a constructor argument, since it is only deployed on some networks.

• Owner only, and only for tokens not minted yet (up to the max supply). The adapter lets a token contract register only tokens without an owner. MUSEGOD's version allowed it only before the first mint; this allows registering in ranges as a drop goes.
• The adapter doesn't stop a token from being registered twice, so the contract records each agent id and skips tokens already registered. agentOf(tokenId) returns it.

ERC-8048 onchain metadata

ERC8048OnchainMetadata stores string keys with bytes values per token and implements ERC-8048's optional Metadata Authority extension in its collection-wide form (ethereum/ERCs#2174). The authority and three settings pack into one storage slot.

• tokenMetadataAuthority() returns the one address that can write every token, including before mint, or zero when none is set. While it is set it is the only writer, as the ERC requires: the owner and holders write only through it. supportsInterface(0x04f90b41) returns true, and every change of the address emits TokenMetadataAuthoritySet(address indexed authority).
• While the authority is blank, the settings decide. The owner (owner(), so it follows ownership) writes any token unless ownerCannotWrite is on. holderCanWrite lets a token's current holder (ownerOf at write time) write that token. Transfers need no claim: the buyer writes right away and the seller can't. ERC-721 operators can't write for the holder.
• authorityLocked stops the owner from calling setCollectionAuthority, including while the owner writes as the blank authority. A set authority can still call it, so a locked policy can hand itself on. A blank authority can be locked, which fixes the settings for good and blocks adding a policy later.
• setCollectionAuthority(authority, holderCanWrite, ownerCannotWrite, authorityLocked) sets everything and emits CollectionAuthoritySettingsUpdated(holderCanWrite, ownerCannotWrite, authorityLocked), so indexers see flag changes too. collectionAuthoritySettings() returns the flags. They default to false, so a new collection starts owner-only.
• There are no key locks. Prem's follow-up pointed out that a key lock also freezes the key for tokens not minted yet: an artist who signs the first tokens and locks artist.signature leaves every later token unsigned. Freezing is left to a policy set as the authority, which can freeze per token. A collection that wants every record frozen locks a blank authority with ownerCannotWrite on and holderCanWrite off (testFreezeEverything).
• Every write emits MetadataSet. A write to a minted token also emits ERC-4906 MetadataUpdate, since OpenSea refreshes on ERC-4906 events. The library calls a _emitMetadataUpdate hook and the token declares the event, so the library also works next to OpenZeppelin's IERC4906. Writes before mint skip it. A batch emits one MetadataUpdate per run of entries for the same token, and reverts if the caller can't write any entry.

The settings cover these states, each with a test:

State	Authority, settings	Test
Owner only. The owner writes and can change the settings	blank, all off	testOwnerOnlyByDefault
Owner and holders. The owner can change the settings	blank, holderCanWrite	testHoldersWrite
Locked blank, owner and holders for good	blank, holderCanWrite, authorityLocked	testLockedBlankOwnerAndHolders
Locked blank, holders only for good	blank, holderCanWrite, ownerCannotWrite, authorityLocked	testLockedBlankHoldersOnly
Locked blank, nobody writes	blank, ownerCannotWrite, authorityLocked	testFreezeEverything
A policy. Only the policy writes, the owner can replace it	policy	testPolicyAuthority, testAuthorityIsOnlyWriter
A locked policy. Only the policy writes and hands it on	policy, authorityLocked	testLockedPolicy

This replaces the earlier per-token Metadata Authority design. lockMetadataKey, metadataKeyLocked, MetadataKeyLocked, MetadataKeyIsLocked, setMetadataAuthority, the per-token authority mapping, metadata writers (setMetadataWriter), the clear-on-transfer hook, and ERC-165 support for the per-token Metadata Authority draft (0xf9cb127d) are gone. The token reports ERC-8048 (0xdf670be1), its collection-wide Metadata Authority extension (0x04f90b41), and ERC-4906 (0x49064906). Transfers no longer touch metadata storage.

Reference policy

src/lib/MetadataWriterPolicy.sol is a small example to set as the collection authority, so nothing the per-token design offered is lost. The token doesn't depend on it.

• Its admin (TwoStepOwnable owner) allows several writer addresses with setWriter, replacing setMetadataWriter.
• A token's current holder delegates their token's writes to one address with setDelegate, such as their agent's wallet. The delegation records the holder who set it and counts only while that address is still ownerOf, so it lapses on transfer (and counts again if the token returns to that holder).
• Write-once keys, from Prem's follow-up. The admin marks a key with setWriteOnceKey(key, bool), and a write to that key reverts with WriteOnceValueSet(tokenId, key) when the token already has a non-empty value, read through the token's metadata(tokenId, key). setMetadataBatch applies the same rule and also counts earlier entries in the batch, so a batch can't set a value and overwrite it. Tokens minted later can still be written once (testPolicyWriteOnceKey, testPolicyWriteOnceKeyBatch). The admin can unmark a key, so a lasting freeze locks the authority to the policy and renounces the policy. While the policy is the authority, holders can't write past it whatever holderCanWrite says.
• setMetadata and setMetadataBatch check the caller and forward to the token. The batch checks array lengths first (BatchLengthMismatch), since it now reads each entry. setCollectionAuthority is an admin passthrough, so a policy can hand the authority on. renounceOwnership also cancels a pending ownership transfer, as the token does, so a renounced policy stays renounced.

The module reserves no keys. ERC-8048 is a draft and its agent profile (ERC-721T) may still change, so the keys are only listed in the doc. Token id 0 is not special.

Docs

docs/AgentNFTs.md covers deployment, the adapter addresses on Ethereum, Base, Robinhood Chain and Sepolia (each confirmed to have code), registration, the metadata authority and its common setups, the reference policy, and how OpenSea shows agent NFTs. The README and the bring-your-own-token doc link to it.

Size and gas

• ERC721SeaDropAgents runtime code is 23,472 bytes, 1,104 bytes under EIP-170.
• Registration costs about 200,000 gas per token, or about 240,000 once the agent URI is longer than 31 bytes. Ethereum and Base cap a transaction at 16,777,216 gas (EIP-7825), so the docs say to register about 60 tokens per transaction.

Tests

• test/foundry/ERC721SeaDropAgents.t.sol: 32 tests (31 run, 1 fork test skipped in CI) covering the states above, settings permissions, when TokenMetadataAuthoritySet fires, a set authority as the only writer, ownerCannotWrite while unlocked, a locked authority clearing itself to a locked blank state, writes before mint, holder writes across transfer, safe transfer and burn, batches, the reference policy's writers, holder delegation and write-once keys (single and batch) through the token, registration ranges and skips (including a collection whose ids start past 1), interface ids, and the library next to OpenZeppelin's ERC721URIStorage. forge coverage --ir-minimum reports 100% line and branch coverage of ERC8048OnchainMetadata and ERC721SeaDropAgents, and 100% branch coverage of MetadataWriterPolicy (its two-line renounceOwnership shows as unhit lines under --ir-minimum, though testPolicyRenounceCancelsPendingOwner calls it).
• src/test/MockAgentAdapter.sol applies the real adapter's registration rule.
• testRegisterAgentsWithDeployedAdapter forks the chain AGENT_ADAPTER_FORK_URL names and registers through that chain's deployed adapter. It is skipped in CI. It passes locally on Ethereum, Base, Robinhood Chain and Sepolia against public RPCs.

Audit

An independent review of the earlier version found no critical, high or medium issues. Its changes that still apply: the library doesn't declare MetadataUpdate (so it compiles next to OpenZeppelin's IERC4906), and the docs cover the 16,777,216-gas transaction cap, that nobody can change an agent URI before mint, that agent URIs are public once registered, that the agent's URI and wallet carry over a sale, and that the adapters are upgradeable proxies a 3-of-4 Safe controls on Ethereum and Base. Its findings about clearing per-token authorities on transfer, batches failing on tokens with an authority, and writers surviving an ownership transfer no longer apply: there is no per-token authority, the collection authority can write every batch entry, key locks are gone, and writers now live in a policy contract with its own admin.

Not in this PR

• Upgradeable and clone versions.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

No active review issues block approval of the agent NFT extension.

No open issues 🎉

What changed in this PR

Adds an agent NFT extension to SeaDrop, combining pre-mint agent registration with reusable ERC-8048 onchain metadata while retaining existing minting and token URI behavior.

Changes:

• Adds range-based agent registration through an ERC-8217 adapter, with tracking to skip previously registered tokens.
• Introduces metadata writers, holder-controlled authorities, permanent key locks, and authority clearing on transfers and burns.
• Adds tests, an optional Base fork integration test, and deployment and usage documentation.

File	Description
test/​foundry/​ERC721SeaDropAgents.t.sol	Tests metadata permissions, authority lifecycle, registration, and interface support.
src/​test/​MockAgentAdapter.sol	Provides an adapter mock enforcing registration permissions.
src/​lib/​ERC8048OnchainMetadata.sol	Implements reusable metadata storage, permissions, locks, and update events.
src/​interfaces/​IERC8048MetadataAuthority.sol	Defines the metadata authority getter and event.
src/​interfaces/​IERC8048Metadata.sol	Defines the metadata getter and write event.
src/​interfaces/​IAgentAdapter.sol	Defines the adapter registration interface.
src/​extensions/​ERC721SeaDropAgents.sol	Integrates agent registration and metadata into SeaDrop tokens.
README.md	Links to the agent NFT guide.
docs/​BringYourOwnTokenContract.md	Introduces the Agents extension and links its guide.
docs/​AgentNFTs.md	Documents deployment, registration, metadata rules, and OpenSea behavior.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Network-specific ERC-8217 adapter compatibility and the narrow EIP-170 bytecode margin require independent runtime validation, while dependency-based and fork tests could not be run in this review environment.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Irreversible registrations through external upgradeable adapters and narrow EIP-170 headroom require deployed-adapter compatibility and compiled-bytecode size validation unavailable in this source-only review.

No open issues 🎉

_{Review effort: Balanced}

[ryanio]

On the two points Copilot's latest review couldn't check from source alone (head 6f2cb27):

• Deployed adapter compatibility: testRegisterAgentsWithDeployedAdapter forks the chain and registers through that chain's live ERC-8217 adapter. On this head it passes against Base, Ethereum and Sepolia. Robinhood Chain passed on an earlier head, and registerAgents hasn't changed since. The test checks the binding and that the holder controls the agent after mint.
• Size: with Foundry 1.9.0, forge build --sizes gives ERC721SeaDropAgents 23,564 bytes of runtime code, 1,012 under EIP-170, and 24,980 bytes of init code.

Nothing to change.

[Copilot]

🟢 Approval recommended

No active review issues remain for the agent registration and onchain metadata changes.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Renouncing ownership leaves a pending successor able to reclaim policy administration and modify a locked collection’s writers, key locks, and authority.

1 open issue

• Renouncing ownership leaves pending successor able to reclaim policy admin · New

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Irreversible metadata locks and authority policies cross an upgradeable-adapter trust boundary, warranting human security review, with deployed-adapter integration and the narrow EIP-170 code-size margin not independently validated.

No open issues 🎉

1 resolved since last review

• Renouncing ownership leaves pending successor able to reclaim policy admin

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Irreversible metadata-authority locks and reliance on deployed upgradeable adapters warrant human security review because the cited audit covered an earlier authority design.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The registration upper-bound check ignores the virtual starting token ID, potentially rejecting mintable IDs or accepting unmintable IDs in derived collections.

1 open issue

• Registration bounds ignore the collection’s starting token ID · New

_{Review effort: Balanced}