# From ensforge 0.x

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

Move an app from ensforge 0.x (@ensforge/core and the Ensforge class) to the 1.0 client and actions, with before and after code.

Source: https://ensforge.com/docs/sdk/from-ensforge-0x

ensforge 1.0 is a new API. Reads and writes are simpler and more uniform, and errors are typed by
code. This guide maps every 0.x concept to its 1.0 form, with before and after code. The code
marked `before` is the 0.x API as published in `@ensforge/sdk@0.6.1` and `@ensforge/core@0.6.1`.

Code blocks that mark lines with `[!code --]` and `[!code ++]` are diffs: they show the old and the new line together, so the docs build does not compile them.

## What changed [#what-changed]

| 0.x                                                                                             | 1.0                                                                                                                                                 |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@ensforge/core` (actions) and `@ensforge/sdk` (the `Ensforge` class)                           | One package, `@ensforge/sdk`. `@ensforge/core` is gone.                                                                                             |
| `new Ensforge({ network, publicClient })` or `createConfig`                                     | `Ensforge.create({ publicClient })`. The chain of the public client picks the deployment.                                                           |
| Groups on the instance: `sdk.records`, `sdk.name`, `sdk.resolution`, `sdk.reverse` …            | Decorators you add: `.extend(ensActions())`. Groups are `record`, `name`, `resolver`, `primaryName`, `registration`, `subname`, `wrapper` and more. |
| One setter per record kind (`setText`, `setAddress`, `setContentHash` …)                        | One action, `record.set`, with `texts`, `addresses`, `contentHash` and more.                                                                        |
| Writes that waited for the receipt by default, with `status`, `hash` and `receipt`              | Writes resolve once submitted with `Write.Result` (`hash`, `hashes`, `id`, `plan`). The `…Sync` form waits for receipts.                            |
| `writes: { simulation, confirmation }` in the config                                            | `simulate` and `…Sync` per call or per client.                                                                                                      |
| Workflows (`sdk.workflows`)                                                                     | [Plans](/docs/reference/glossary#plan) (`plan.get`, `plan.list`, `plan.resume`).                                                                    |
| `ContractError`, `RpcError`, `NameError` …                                                      | `Errors.*` classes with stable codes.                                                                                                               |
| `createEnsforge` from `@ensforge/sdk/wagmi`, or `createWagmiConfig` from `@ensforge/core/wagmi` | `Ensforge.fromWagmi` from `@ensforge/sdk/wagmi`.                                                                                                    |
| [HCA](/docs/reference/glossary#hca) actions on `sdk.hca`                                        | The `@ensforge/hca` package, as `ens.hca.*` and `via: hca()`.                                                                                       |

## 1. Update the packages [#1-update-the-packages]

```sh title="terminal"
pnpm remove @ensforge/core
pnpm add @ensforge/sdk@latest
```

Also update `@ensforge/react` and `@ensforge/contracts` to 1.x. The public packages version together.

## 2. Create the client [#2-create-the-client]

The 0.x `network` option is gone. The public client's chain picks the deployment (Ethereum mainnet or
Sepolia). For another chain, pass `deployment`.

```ts no-check title="client.ts"
import { Ensforge } from "@ensforge/sdk"; // [!code --]
import { Ensforge, ensActions } from "@ensforge/sdk"; // [!code ++]
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const publicClient = createPublicClient({ chain: mainnet, transport: http() });

const sdk = new Ensforge({ network: "mainnet", publicClient }); // [!code --]
const ens = Ensforge.create({ publicClient }).extend(ensActions()); // [!code ++]
```

Other options moved too:

| 0.x                                                        | 1.0                                                                                                                                     |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `network`                                                  | Gone. The public client's chain picks the deployment, or pass `deployment`.                                                             |
| `walletClient`                                             | `walletClient` (also a function for wallets that connect later)                                                                         |
| `reads: { concurrency, multicallBatchSize }`               | `batch: { multicall: { batchSize, wait } }`. See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways).                              |
| `gateways` (allowed hosts and limits for gateway requests) | No counterpart. 1.0 `gateways` sets storage gateways for avatars and content hashes, and `ccipRead` sets the off-chain lookup gateways. |
| `writes.simulation: "required" \| "skip"`                  | `simulate: true \| false`                                                                                                               |
| `writes.confirmation`                                      | The `…Sync` form of a write, with `confirmations` and `timeout`.                                                                        |
| `storage` (workflow storage)                               | `storage` (plan storage). See [Save and resume plans](/docs/sdk/save-and-resume-plans).                                                 |
| `indexer` (GraphQL endpoints) or `false`                   | `indexer: bigname()`, `goldsky()`, `fallback([...])` from `@ensforge/sdk/indexer`. Without it, no indexer.                              |
| `hca`                                                      | The `@ensforge/hca` package.                                                                                                            |

## 3. Reads [#3-reads]

Reads return the value, not a wrapper. A missing value is `null`.

```ts no-check title="reads.ts"
const { address } = await sdk.records.getAddress({ name: "nick.eth" }); // [!code --]
const address = await ens.record.getAddress({ name: "nick.eth" }); // [!code ++]

const { owner } = await sdk.name.getOwner({ name: "nick.eth" }); // [!code --]
const { owner } = await ens.name.get({ name: "nick.eth" }); // [!code ++]

const primary = await sdk.reverse.getPrimaryName({ address }); // [!code --]
const primary = await ens.primaryName.get({ address }); // [!code ++]
```

- `getAddress` took `coinType`. 1.0 takes `coin`: a symbol (`"btc"`), a chain (`{ chainId: 8453 }`)
  or a coin type. See [Get a name's address](/docs/sdk/get-an-address).
- `getPrimaryName` returned `{ name, match }` or `null`. 1.0 returns the name, or `null`, and checks that the
  name resolves back to the address by default (`verify`).
- `name.get` returns the whole state in one call: `owner`, `manager`, `registrant`, `expiry`,
  `resolver`, `wrapped`, `available`, `renewable` and more. The single-fact reads of 0.x
  (`getOwner`, `getExpiry`, `isWrapped` …) map to its fields. See
  [Get a name's owner, expiry and status](/docs/sdk/get-name-details).

### Batched reads [#batched-reads]

`readBatch` returned a record of values. `batch` returns `{ results }`, where each result is
`{ status: "success", result }` or `{ status: "failure", error }` by default. `readBatchSettled`
returned `{ status, value }` outcomes; 1.0 names the field `result`.

```ts no-check title="batch.ts"
const profile = await sdk.batch.readBatch({
  // [!code --]
  owner: sdk.name.getOwner.request({ name: "nick.eth" }), // [!code --]
}); // [!code --]
const { results } = await ens.batch({
  // [!code ++]
  requests: { owner: Actions.name.get.request({ name: "nick.eth" }) }, // [!code ++]
  allowFailure: false, // [!code ++]
}); // [!code ++]
```

`Actions` comes from `@ensforge/sdk`. Settled results are now the default (`allowFailure: true`), and
`allowFailure: false` behaves like `readBatch`.
See [Look up many at once](/docs/sdk/look-up-many-at-once).

## 4. Writes [#4-writes]

One `record.set` replaces the setters. 0.x writes waited for the receipt by default
(`confirmation: { type: "confirmed" }`). 1.0 writes resolve once submitted. Use `…Sync` to wait for
the receipt, as the examples below do.

```ts no-check title="writes.ts"
await sdk.records.setText({
  name: "ensforge-docs-demo.eth",
  key: "url",
  value: "https://example.com",
}); // [!code --]
await ens.record.setSync({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } }); // [!code ++]

await sdk.records.setAddress({ name: "ensforge-docs-demo.eth", coinType: 60n, address }); // [!code --]
await ens.record.setSync({ name: "ensforge-docs-demo.eth", addresses: { eth: address } }); // [!code ++]
```

See [Set records](/docs/sdk/set-records) and [Send a transaction](/docs/sdk/send-a-transaction).

### Where each 0.x action went [#where-each-0x-action-went]

| 0.x group and actions                                                                                    | 1.0                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `records.get*`                                                                                           | [`record.get`](/docs/reference/sdk/record/get), `record.getText`, `record.getAddress`, `record.getAvatar`, `record.getContentHash`     |
| `records.set*`, `records.clearRecords`, `records.clearAvatar`                                            | [`record.set`](/docs/reference/sdk/record/set) (`null` deletes a value; `clear: true` deletes everything first)                        |
| `name.getOwner`, `getManager`, `getRegistrant`, `getExpiry`, `getNameState`, `isWrapped`, `isMigrated` … | [`name.get`](/docs/reference/sdk/name/get)                                                                                             |
| `name.isAvailable`                                                                                       | `registration.isAvailable`                                                                                                             |
| `resolution.getResolver`, `resolve*`                                                                     | `resolver.get`, `resolver.resolve`                                                                                                     |
| `records.setAlias`, `resolution.getAlias`                                                                | `resolver.link`, `resolver.getLink`. See [Resolvers and shared records](/docs/sdk/resolvers-and-shared-records).                       |
| `resolution.setResolver`, `setResolverAndRecords`, `createResolver`, `upgradeResolver`                   | `resolver.set`, `record.set({ resolver })`, `resolver.create`, `resolver.upgrade`                                                      |
| `reverse.setPrimaryName`, `clearPrimaryName`, `setPrimaryNameForAddress`, `setContractPrimaryName`       | [`primaryName.set`](/docs/reference/sdk/primary-name/set) (`name: null` clears)                                                        |
| `registration.registerName(s)`, `commitName`, `completeRegistration`                                     | `registration.register` (several names in one call), `registration.commit`; finish with the result's `secret`                          |
| `registration.getRegistrationPrice`, `getRenewalPrice`, `getCommitmentStatus`                            | `registration.getPrice`, `getRenewalPrice`, `getCommitmentStatus`                                                                      |
| `registration.renewName(s)`                                                                              | `registration.renew`                                                                                                                   |
| `ownership.transferName`, `transferRegistrant`, `reclaimName`, `setManager`, `setTtl`                    | `name.transfer` (`role: "registrant"`), `name.reclaim`, `name.setManager`, `name.setTtl`                                               |
| `subnames.*`                                                                                             | `subname.create`, `subname.update`, `subname.remove`                                                                                   |
| `wrapping.*`                                                                                             | `wrapper.wrap`, `unwrap`, `getFuses`, `setFuses`, `setChildFuses`                                                                      |
| `migration.*`                                                                                            | `migration.get`, `migration.migrate`                                                                                                   |
| `dns.*`                                                                                                  | `dns.getStatus`, `dns.claim`, `dns.getProof`, `dns.getRecords`, `dns.setRecords`                                                       |
| `events.*`                                                                                               | `event.get`, `event.watch`, `event.decode`                                                                                             |
| `permissions.*`, `capabilities.*`                                                                        | `permission.check`, `permission.get`, `permission.setRecordAccess`, `role.get`, `role.grant`, `role.revoke`, `approval.*`              |
| `indexer.*`                                                                                              | `indexer.*` (19 actions; add `indexerActions()`)                                                                                       |
| `batch.prepareCalls`, `simulateCalls`, `estimateCalls`, `sendCalls`, `executeWritePlan`                  | `.prepare`, `.simulate`, `.estimateGas` on any write, and `plan.send`. See [Preview before sending](/docs/sdk/preview-before-sending). |
| `batch.getCallsStatus`, `resumeCalls`, `workflows.*`                                                     | `plan.get`, `plan.list`, `plan.resume`, `plan.reconcile`. See [Continue after a failure](/docs/sdk/continue-after-a-failure).          |
| `hca.*`, `hcaAdmin`                                                                                      | `@ensforge/hca`. See [Use smart accounts](/docs/sdk/use-smart-accounts).                                                               |

Some 0.x helpers, such as `resolution.predictResolverAddress` and `name.getProtocol`, have no
action of their own in 1.0: `resolver.create.prepare` returns the address in `plan.deploys`, and
`name.get` returns `protocol`. Browse the [reference](/docs/reference/sdk/record) for what
exists.

## 5. Errors [#5-errors]

0.x errors were Effect `TaggedError`s per area (`ContractError`, `RpcError`, `NameError`,
`TransactionError` …) with codes such as `REVERTED`. 1.0 errors are `Errors.*` classes with stable
codes (`CONTRACT_REVERTED`, `NOT_OWNER`, `RECORD_NOT_FOUND`) that Promise and Effect users receive as
the same instance.

```ts no-check title="errors.ts"
if (error._tag === "ContractError" && error.code === "REVERTED") {
  /* … */
} // [!code --]
if (Errors.hasCode("CONTRACT_REVERTED")(error)) {
  /* … */
} // [!code ++]
```

Each action now documents its errors, and `Errors.describe` gives user-safe copy. See
[Handle errors](/docs/sdk/handle-errors).

## 6. wagmi [#6-wagmi]

```ts no-check title="wagmi.ts"
import { createEnsforge } from "@ensforge/sdk/wagmi"; // [!code --]
import { Ensforge } from "@ensforge/sdk/wagmi"; // [!code ++]
import { ensActions } from "@ensforge/sdk"; // [!code ++]

const sdk = createEnsforge({ network: "mainnet", wagmiConfig }); // [!code --]
const ens = Ensforge.fromWagmi(wagmiConfig).extend(ensActions()); // [!code ++]
```

`Ensforge.fromWagmi(config, { chainId?, switchChain? })` reads through wagmi's transports and writes
through the connected wallet, switching chain when needed.

## 7. Effect users [#7-effect-users]

0.x actions in `@ensforge/core` returned Effects. In 1.0 the Effect API is `@ensforge/sdk/effect`, and
Promises are the default. See [The Effect API](/docs/sdk/effect-api).

## Check the result [#check-the-result]

Build and run your tests. TypeScript flags every renamed action and option. Read a name, change a
record on Sepolia, and confirm the read-back.

## Troubleshooting [#troubleshooting]

### `ens.records is undefined` [#ensrecords-is-undefined]

The group is called `record` in 1.0. See the table above.

### `UNKNOWN_CHAIN` [#unknown_chain]

0.x took `network: "mainnet"`. In 1.0 the public client needs a `chain`, or you pass `deployment`.
See [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN).

### Receipts are missing from a write result [#receipts-are-missing-from-a-write-result]

Writes resolve on submission. Use the `…Sync` form for `receipt` and `receipts`.