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

Ways to call actions

Choose between client methods, standalone actions and the Effect API; all three run the same actions with the same errors.

An action is one thing ensforge can do: record.getAddress, name.transfer, registration.register. Every action can be called three ways. They run the same code and return the same results; they differ only in how you import and call them.

WayLooks likeChoose it when
Client methodens.record.getAddress(options)Most apps. Short to write, everything in one place.
Standalone actionActions.record.getAddress(client, options)Bundle size matters, or you write helpers that take any client.
Effect APIyield* Actions.record.getAddress(client, options)Your app is an Effect program.

Client methods

Add actions to a client with extend, then call them on it. This is the form the docs use by default.

Example (Calling a Client Method)

client-method.ts
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(ensActions());

const url = await ens.record.getText({ name: "nick.eth", key: "url" });

ensActions() adds every action group. To keep a bundle small, add only the groups you use, such as recordActions(). See Create a client.

Standalone actions

Actions holds every action as a plain function that takes the client first. Bundlers keep only the actions you call, so this is the smallest form.

Example (Calling a Standalone Action)

standalone.ts
import { Actions, Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});

const url = await Actions.record.getText(ens, { name: "nick.eth", key: "url" });
  • The first argument is an ensforge client, or a bare viem client. A viem client gets an ensforge client with default options, created once and reused.
  • No extend is needed: the client carries only configuration.
  • @ensforge/sdk/actions exports the same actions by group: import { record } from "@ensforge/sdk/actions". See Entry points.

The Effect API

@ensforge/sdk/effect has the same actions, but each returns an Effect instead of a Promise. Its error channel is the action's typed error union, so you handle failures with Effect.catchTag and the other Effect tools.

Example (Calling an Action in an Effect Program)

effect.ts
import { Actions, Ensforge } from "@ensforge/sdk/effect";
import { Effect } from "effect";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const program = Effect.gen(function* () {
  const ens = yield* Ensforge.Ensforge;
  return yield* Actions.record.getText(ens, { name: "nick.eth", key: "url" });
});

const url = await Effect.runPromise(
  program.pipe(
    Effect.provide(
      Ensforge.layer({ publicClient: createPublicClient({ chain: mainnet, transport: http() }) }),
    ),
  ),
);
  • Ensforge.layer(options) creates the client as an Effect service, Ensforge.Ensforge.
  • Errors are the same instances in both APIs. Their _tag is the class name, so Effect.catchTag("NotFoundError", …) works.
  • You never need this API to use ensforge. See The Effect API.

Extra forms every action has

The three ways above call an action. Actions also carry a few related functions, the same in every way of calling.

FormOnWhat it does
action.request(options)Most readsDescribes the read without running it, for Actions.batch.
action.prepare(options)WritesBuilds the plan without sending anything.
action.simulate(options)WritesSimulates every call of the plan.
action.estimateGas(options)WritesEstimates the gas and ETH the plan needs.
actionSync(options)WritesSends, then waits for the receipts (record.setSync).
action.pathAllThe action's name, such as "record.get", for logs and cache keys.

Example (Batching Two Reads With Requests)

requests.ts
import { Actions, Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(ensActions());

const {
  results: [state, address],
} = await ens.batch({
  requests: [
    Actions.name.get.request({ name: "nick.eth" }),
    Actions.record.getAddress.request({ name: "nick.eth" }),
  ],
  allowFailure: false,
});
  • Requests are built from Actions, whichever way you call batch.
  • A list of requests returns a list of results; a record returns a record with the same keys.
  • With allowFailure: false the first failure rejects; by default each result carries its own status.

See Look up many at once and How writes work.

Mix them freely

The three ways share clients and errors, so you can mix them in one app: client methods in UI code, standalone actions in a small server function, the Effect API in an Effect service. The React hooks in @ensforge/react take the action itself, as in useRead(Actions.record.getText, options) and useReads, not its .request. See React.

Was this page helpful?