Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

Wrap and unwrap a name

Wrap an ENSv1 name in the Name Wrapper, optionally burning fuses on the way, and unwrap it again when you need the registry back.

This page is about ENSv1 only, because the Name Wrapper does not exist on ENSv2. You will wrap an ENSv1 name, which turns it into an ERC-1155 token, and unwrap it back. See What wrapped names are.

Prerequisites

1. Wrap the name

wrapper.wrap wraps a name. wrapper.wrapSync also waits for the receipt.

Example (Wrapping a Name)

wrap.ts
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const transport = http(process.env.SEPOLIA_RPC_URL);

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport }),
  walletClient: createWalletClient({ account, chain: sepolia, transport }),
}).extend(ensActions());

const { hash } = await ens.wrapper.wrapSync({ name: "ensforge-docs-demo.eth" });
OptionTypeDefaultDescription
namestringrequiredThe ENSv1 name.
ownerstringthe current holder, else the signerOwner of the wrapped name.
fusesFuse.Name[]noneFuses to burn while wrapping. .eth second-level names only.
resolverstringthe current resolverResolver to set.
  • A .eth name is wrapped in one transaction from the registrant, which may burn owner fuses (cannotUnwrap first).
  • Any other name needs its registry owner to approve the NameWrapper first. ensforge adds the approval when it is needed.
  • The wrapped name stays with its current holder unless you pass owner. This also holds when an approved operator wraps it.

If the name's manager is not the signer, the manager must approve the NameWrapper first. An operator of the manager cannot approve it for them, and the write fails with NOT_APPROVED.

2. Unwrap the name

wrapper.unwrap returns a wrapped name to the ENSv1 registry and, for .eth names, to the registrar. owner becomes the registry owner and, for .eth names, the registrant. It defaults to the signer.

Example (Unwrapping a Name)

unwrap.ts
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const transport = http(process.env.SEPOLIA_RPC_URL);

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport }),
  walletClient: createWalletClient({ account, chain: sepolia, transport }),
}).extend(ensActions());

await ens.wrapper.unwrapSync({ name: "ensforge-docs-demo.eth" });

A locked name cannot be unwrapped

Once cannotUnwrap is burned, unwrap fails with FUSE_BURNED until the name expires. See Lock permissions with fuses.

Check the result

Read the name with wrapper.getFuses. It returns null when the name is not wrapped. Or use name.get and read wrapped. See Get a name's owner, expiry and status.

Troubleshooting

NAME_WRAPPED or NAME_NOT_WRAPPED

You wrapped a name that is already wrapped, or unwrapped one that is not. See NAME_WRAPPED and NAME_NOT_WRAPPED.

NAME_EXPIRED or NAME_NOT_REGISTERED

Only registered names can be wrapped. See NAME_EXPIRED and NAME_NOT_REGISTERED.

NOT_OWNER or NOT_APPROVED

The account does not own the name, or the manager has not approved the NameWrapper. See NOT_OWNER and NOT_APPROVED.

FUSE_BURNED

A burned fuse forbids it, such as cannotUnwrap. See FUSE_BURNED.

INVALID_RECORD_VALUE

A fuse name is not valid. See INVALID_RECORD_VALUE.

Was this page helpful?