A Beginner's Guide to ENS Name Wrapper: Key Things to Know

Introduction to the ENS Name Wrapper

The Ethereum Name Service (ENS) has long provided a decentralized naming system for blockchain addresses, content hashes, and metadata. However, managing subdomains and transferring ownership of names historically required complex smart contract interactions or reliance on the registry's multi-step approval flow. The ENS Name Wrapper, introduced as part of the ENSIP-10 standard and widely deployed in 2023, fundamentally changes this by enabling "wrapping" an ENS name into an ERC-1155 token. This unlocks new capabilities: subdomain management, atomic transfers, and fine-grained control over name properties — all within a single, composable interface.

For developers and power users, understanding the Name Wrapper is essential for building applications that leverage ENS beyond simple address resolution. This guide covers the mechanics, practical benefits, and key considerations you must know before integrating or using wrapped ENS names.

What Is the ENS Name Wrapper and How Does It Work?

At its core, the Name Wrapper is a smart contract that "wraps" an existing ENS name (e.g., example.eth) into an ERC-1155 token. This token represents full ownership and control of that name, including all its subdomains. The wrapper replaces the traditional ENS registry model where name ownership is recorded as a simple mapping. Instead, the wrapper contract becomes the owner of the name in the ENS registry, and the token holder — the user — controls it via the wrapper's interface.

Key technical details:

• ERC-1155 tokenization: Each wrapped name is a unique non-fungible token (NFT) under the ERC-1155 standard, which supports batch transfers, approvals, and metadata. This makes it compatible with existing NFT wallets, marketplaces, and DeFi protocols.
• Subdomain management: The wrapper allows the name owner to create and manage subdomains (e.g., sub.example.eth) without needing to interact with the registry directly. Subdomains can be transferred, burned, or further wrapped — all controlled by the parent name's token.
• Fuses: The wrapper introduces a mechanism called "fuses" — immutable flags that permanently disable certain capabilities on a name. For example, you can burn the fuse that allows transferring the parent name, making it effectively non-transferable. This is crucial for creating permanent records or locked domains.
• Approval flow: Instead of the old setSubnodeOwner and setResolver pattern, the wrapper uses standard ERC-1155 safeTransferFrom and setApprovalForAll. This aligns with existing developer tooling.

The wrapper is not retroactive — only names explicitly wrapped become ERC-1155 tokens. Unwrapped names continue to work via the legacy ENS registry, but they lack subdomain flexibility and composability. Wrapping is done by calling the wrapETH2LD or wrapDomain functions on the Name Wrapper contract, with the name's current owner approving the transfer.

Key Benefits for Developers and Power Users

The Name Wrapper introduces several improvements that directly impact how you build with or use ENS:

1. Subdomain Portability

Before the wrapper, subdomain ownership was tied to the parent name's registrar. Transferring a subdomain required the parent name owner to approve individual operations on the registry. Now, subdomains are fully independent tokens. You can sell a subdomain like alice.example.eth to someone else without giving them control over the entire parent name. This opens up use cases like subdomain marketplaces, team-based naming, and hierarchical DNS-like structures.

2. Atomic Operations and Composability

Because wrapped names are ERC-1155 tokens, they integrate seamlessly with Ethereum's DeFi ecosystem. You can:

• Wrap multiple names and transfer them in a single transaction using batch transfers.
• Use name tokens as collateral in lending protocols (e.g., for NFT-backed loans).
• List wrapped names on any ERC-1155 compatible marketplace without custom ENS listing logic.
• Combine name ownership with other tokens in a single smart contract interaction.

This composability reduces integration friction. For instance, a DAO can hold a wrapped name and its subdomains as a single asset class, simplifying treasury management.

3. Fuse-Controlled Names

Fuses are the most powerful feature for advanced use cases. Currently, the wrapper exposes several fuse types:

• CANNOT_UNWRAP — permanently locks the name as a wrapped token.
• CANNOT_BURN_FUSES — prevents burning any additional fuses.
• CANNOT_TRANSFER — makes the name non-transferable (e.g., for a permanent identity).
• CANNOT_SET_RESOLVER — prevents changing the resolver contract.
• CANNOT_SET_TTL — freezes the caching TTL.

Burning a fuse is a one-way operation. Once burned, that capability is permanently disabled. This is ideal for creating immutable records (e.g., a name that permanently resolves to a specific smart contract) or preventing future tampering of subdomain hierarchies. When evaluating which fuses to burn, consider your long-term governance needs — burning the wrong fuse can lock you out of future changes. For details on pricing and fuse limitations across different name tiers, see the ENS premium tiers documentation.

Practical Steps to Wrap a Name

If you own an ENS name (like yourname.eth), wrapping it is straightforward. Here is the typical flow:

1. Ensure compatibility: Your name must be registered with a registrar that supports wrapping. Most .eth names from the current permanent registrar are eligible. Legacy .eth names (registered before 2021) may require an upgrade first.
2. Approve the wrapper: The wrapper contract needs permission to take ownership of your name from the ENS registry. You do this by calling the ENS registry's setApprovalForAll function, targeting the Name Wrapper contract address.
3. Call the wrap function: Use the wrapper's wrapETH2LD function (for .eth names) or wrapDomain (for other TLDs like .xyz or .eth subdomains). This transfers ownership of the name to the wrapper contract and mints an ERC-1155 token to your wallet.
4. Manage fuses (optional): After wrapping, you can burn fuses using the setFuses function. This is irreversible, so test on a testnet first. For instance, you might burn CANNOT_TRANSFER to lock the name to your identity.
5. Use subdomains: Once wrapped, you can create subdomains by calling setSubnodeOwner on the wrapper. Subdomains will also be ERC-1155 tokens and can be transferred independently.

A practical example: if you own myname.eth and wrap it, you could then create team.myname.eth and transfer it to a teammate. The teammate holds that subdomain as a standalone NFT, and you retain control over the parent name. This is impossible under the legacy registry without complex resolver and registry interactions.

For a step-by-step walkthrough with real transaction examples, refer to the v3ensdomains.com that demonstrates wrapping, fuse management, and subdomain creation on the Sepolia testnet. The tutorial covers edge cases like names with existing subdomain records and resolver migrations.

Key Considerations and Tradeoffs

While the Name Wrapper offers significant advantages, it introduces new considerations:

Gas Costs

Wrapping a name requires two transactions (approval + wrap) and typically costs 100,000–150,000 gas. Burning fuses adds another 40,000–60,000 gas per fuse. On mainnet at 50 gwei, this totals approximately $5–15 per name. Batch wrapping multiple names reduces per-name costs, but the initial overhead is non-trivial for high-frequency operations.

Name Unwrapping

You can always unwrap a name (unless you burn the CANNOT_UNWRAP fuse). Unwrapping reverts the name to legacy registry ownership and destroys the ERC-1155 token. However, subdomains created while wrapped remain valid — they are independent tokens. This means you cannot unwrap a parent name if it still owns subdomains (unless you transfer or burn them first). Plan your subdomain hierarchies accordingly.

Resolver Compatibility

Wrapped names can use any ENS resolver, but the default flow requires setting the resolver after wrapping. Some resolvers (e.g., the public resolver) require the wrapper to be the resolver's owner. If you use a custom resolver, ensure it supports the Name Wrapper's permission model. In practice, the ENS team maintains an "offchain resolver" that works natively with wrapped names, supporting records like addr, text, and contenthash.

Security Risks

The Name Wrapper is audited (OpenZeppelin and ConsenSys Diligence have both reviewed it), but any smart contract introduces risk. Key risks include:

• Phantom functions: The wrapper's setFuses and setSubnodeOwner are powerful — a malicious dApp could trick you into burning fuses you didn't intend. Always verify the calldata.
• Lost approvals: If you approve the wrapper contract to manage your name but never wrap it, an attacker could theoretically call wrapETH2LD with your approval. Use approval.setApprovalForAll carefully and revoke after wrapping.
• Subdomain hijacking: While the wrapper protects parent names, a subdomain owner could burn fuses to lock subdomains. This is by design, but consider it when delegating subdomain ownership.

Ecosystem Support

As of early 2025, most major ENS frontends (like app.ens.domains) support wrapping natively. NFT marketplaces like OpenSea and Rarible display wrapped names as ERC-1155 items. However, some legacy tools (e.g., older ENS manager UIs) may not recognize wrapped names. Always check that your dApp's ENS integration handles both wrapped and unwrapped states. The ENS SDK (ethers.js v6) includes a NameWrapper class for convenient querying.

Future Outlook and Integration Patterns

The Name Wrapper is a cornerstone of ENS's "Layer 2" strategy. By tokenizing names, ENS becomes more than just a naming system — it becomes a platform for decentralized identity, permissioned subdomain registries, and cross-chain name resolution. Key trends to watch:

• Cross-chain wrappers: The Name Wrapper contract is deployed on Ethereum mainnet, but Layer 2 solutions (e.g., Arbitrum, Optimism) are likely to host wrapper instances for L2-specific names.
• Name Wrapper as a Service: Protocols like ENS Domains offer bulk wrapping for enterprises managing large name inventories, with features like automated fuse management and subdomain event logging.
• Integration with ERC-3668 (CCIP Read): Wrapped names can use offchain metadata resolvers, enabling large-scale DNS-like hierarchies without onchain storage costs.

For developers, the recommended integration pattern is to treat all names as potentially wrapped. When resolving an ENS name, first check if it is an ERC-1155 token (via the wrapper's ownerOf function). If so, use the wrapper's getData function to retrieve the resolver and owner. If not, fall back to the legacy registry's resolver() and owner(). This dual-support approach ensures compatibility with both wrapped and unwrapped names.

In summary, the ENS Name Wrapper is not merely an upgrade — it is a paradigm shift. It transforms ENS from a static directory into a programmable, composable asset system. Whether you are building a dApp that issues subdomains, managing a portfolio of ENS names, or designing a decentralized identity protocol, mastering the Name Wrapper is now a prerequisite for advanced ENS development. Start with a testnet wrapper deployment, experiment with fuses, and integrate the wrapper's ERC-1155 interface into your toolchain. The future of ENS is wrapped.