# subname.create

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Options, result, errors and examples for subname.create.

Source: https://ensforge.com/docs/reference/sdk/subname/create

<ApiMeta kind="Write" stability="stable" since="1.0.0" source="packages/sdk/src/actions/subname/create/index.ts#L74" />

Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the transaction is submitted.

## When to use [#when-to-use]

Use to give out names under one you own, such as `pay.alice.eth`. Use [`createSync`](/docs/reference/sdk/subname/create#wait-for-the-receipt-with-createsync) to wait for the receipt.

## Details [#details]

- ENSv2 parents: the child is registered in the parent's subregistry. A parent without one
  gets a UserRegistry deployed and attached in the same plan (`plan.deploys`).
- ENSv2 children never expire by default and their owner gets the roles the `.eth`
  registrar grants (resolver, subregistry, transfers); `roles` and `expiry` override them.
- ENSv1 parents use `setSubnodeRecord`; wrapped parents take `fuses` and an `expiry`.
- By default the child gets its own PermissionedResolver with `records` written at creation;
  `resolver: "parent"` shares the parent's resolver, `null` creates it without one.
- `upsert` updates an existing child's resolver and records instead of failing.

<Callout type="warn" title="Gotchas">
- A subregistry deployed here is not emancipated unless `emancipate` is set: its owners can
  remove and repoint children.
- Under a wrapped parent, `parentCannotControl` and `canExtendExpiry` need `cannotUnwrap`
  burned on the parent ([`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE)), and an emancipated child cannot be updated
  until it expires ([`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED)).
</Callout>

## Signature [#signature]

```ts
function create(
  client: Like,
  options: create.Options & Write.Options,
): Promise<create.ReturnType>
```

Call it as `ens.subname.create(options)` on a client, or `Actions.subname.create(client, options)`.

In React, use [`useCreateSubname`](/docs/reference/react/use-create-subname).

## Parameters [#parameters]

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | Full name of the child, e.g. `pay.alice.eth`. Normalized automatically. |
| `owner` | `string` | the signing account | Owner of the child. |
| `resolver` | `string \| "parent" \| null` |  | Resolver of the child. By default it gets its own PermissionedResolver; `"parent"` uses the parent's resolver and `null` none. |
| `records` | `Omit<recordSet.Options, "name" \| "resolver" \| "clear" \| "pubkey">` |  | Records of the child. |
| `expiry` | `bigint` | never for ENSv2 children; for wrapped children, the maximum when `parentCannotControl` is burned, else none | Expiry as a Unix timestamp. |
| `fuses` | `readonly Fuse.Name[]` |  | NameWrapper fuses to burn on the child (wrapped ENSv1 parents). |
| `roles` | `readonly Role.Name[] \| bigint` |  | ENSv2 roles for the child's owner, by name or bitmap. |
| `emancipate` | `boolean` |  | Emancipate the parent's subregistry if this plan deploys it. |
| `upsert` | `boolean` |  | Update the child's resolver and records if it already exists. |

Also takes the [write options](/docs/reference/sdk/client#write-options).

## Returns [#returns]

Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.

| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |

## Errors [#errors]

| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS), [`INVALID_ROLES`](/docs/reference/errors/INVALID_ROLES), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_NOT_AVAILABLE`](/docs/reference/errors/NAME_NOT_AVAILABLE), [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED), [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED) | the child exists or the parent is not registered. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | the parent is reserved or ENSv2 resolution no longer reaches it. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | `roles` on ENSv1 or `fuses` on unwrapped parents. |
| [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES), [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not create children. |
| [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. |
| [`UserRejectedError`](/docs/reference/errors/user-rejected-error) | [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | the user rejects the request. |
| [`WalletError`](/docs/reference/errors/wallet-error) | [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH), [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND) | the wallet is on another chain or has no account to sign with. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |

It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).

See [How errors work](/docs/sdk/errors-explained).

## Examples [#examples]

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Creating a subname"
const { hash } = await ens.subname.create({ name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } })
```
</Tab>

<Tab>
```ts title="Creating a subname with a standalone call"
import { Actions } from "@ensforge/sdk"

await Actions.subname.create(ens, { name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } })
```
</Tab>

<Tab>
```ts title="Creating a subname in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

yield* Actions.subname.create(ens, { name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } })
```
</Tab>
</Tabs>

## Plan methods [#plan-methods]

Each method takes the same options as `subname.create` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).

| Method | Description |
| --- | --- |
| `subname.create.prepare(options)` | Builds the plan without sending anything. |
| `subname.create.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `subname.create.estimateGas(options)` | Estimates the gas and ETH the plan needs. |

## Wait for the receipt with `createSync` [#wait-for-the-receipt-with-createsync]

Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the receipt is in.

Use when the next step depends on the change being on-chain.

`subname.createSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).

Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Creating a subname and waiting"
const { receipt } = await ens.subname.createSync({ name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } })
```
</Tab>

<Tab>
```ts title="Waiting with a standalone call"
import { Actions } from "@ensforge/sdk"

await Actions.subname.createSync(ens, { name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } })
```
</Tab>

<Tab>
```ts title="Waiting in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

yield* Actions.subname.createSync(ens, { name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } })
```
</Tab>
</Tabs>

## See also [#see-also]

- [`subname.remove`](/docs/reference/sdk/subname/remove) to remove it