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
ensforgeHCA

Upgrades and governance

Check and run an HCA upgrade as its owner, and approve or revoke implementations and upgrade paths as a governance account.

Experimental

@ensforge/hca is experimental for 1.0. The hcaAdmin actions are for governance accounts only, and their API can change in a minor release.

An HCA runs an implementation: the contract code behind the account. Governance accounts decide which implementations new accounts may use and which ones existing accounts may upgrade to. By the end of this guide you will have checked an upgrade, run it, and, as a governance account, approved a new implementation.

Upgrade your HCA (owners)

An upgrade keeps the HCA's address and its sessions. Only the owner can run it, only on a deployed HCA, and only to an implementation that passes two checks:

  1. The implementation is in the DAO's upgrade set, a list of allowed upgrade targets.
  2. The new implementation accepts the account's current implementation as its predecessor. The new implementation's own code decides this.

1. Check the upgrade

hca.getUpgrade reports each check, so you can tell the user which approval is missing.

check-upgrade.ts
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

const account = privateKeyToAccount(
  "0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
  walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
  .extend(ensActions())
  .extend(hcaActions());
const implementation = "0x0000000000000000000000000000000000000001"; // placeholder: the new implementation

const { allowed, inUpgradeSet, predecessorAllowed } = await ens.hca.getUpgrade({
  implementation,
});
FieldMeaning
allowedtrue when both checks pass.
currentThe account's current implementation, or null before deployment.
inUpgradeSetThe upgrade set includes the implementation.
predecessorAllowedThe implementation accepts current as its predecessor. false before deployment.

2. Run the upgrade

hca.upgrade is the owner's own transaction. It fails with HCA_UPGRADE_NOT_ALLOWED before sending when the HCA is not deployed or a check fails.

upgrade.ts
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

const account = privateKeyToAccount(
  "0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
  walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
  .extend(ensActions())
  .extend(hcaActions());
const implementation = "0x0000000000000000000000000000000000000001"; // placeholder
await ens.hca.upgradeSync({ implementation });

After an upgrade, ens.hca.get returns the new implementation. The account's initialImplementation, which its address derives from, does not change.

Inspect governance

hcaAdmin.getGovernance is a read anyone can run. Add hcaAdminActions() to the client first. See Installation.

FieldMeaning
factoryOwnerThe account that owns the HCA factory.
upgradeSetThe address of the upgrade set.
deploymentApprovedWhether the implementation may be used for new accounts. null when you pass no implementation.
upgradeApprovedWhether the upgrade set includes the implementation. null when you pass no implementation.

Approve implementations (governance accounts)

Each action is limited to the accounts in the table's second column. Each has a …Sync form that waits for the receipt.

ActionWhoWhat it does
setDeploymentApprovalFactory ownerApproves or revokes an implementation for new HCA deployments.
setUpgradeApprovalUpgrade-set role holdersApproves or revokes an implementation in the upgrade set.
grantUpgradeSetRolesRole adminsGrants root roles on the upgrade set to grantee (roles is a bitmap).
revokeUpgradeSetRolesRole adminsRevokes root roles on the upgrade set from grantee.
transferGovernanceFactory ownerTransfers ownership of the factory to newOwner, for example a DAO timelock.
renounceGovernanceFactory ownerGives up factory ownership.

Example (Allowing an Upgrade Target)

approve-upgrade.ts
import { hcaAdminActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

const account = privateKeyToAccount(
  "0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
  walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
  .extend(ensActions())
  .extend(hcaAdminActions());
const implementation = "0x0000000000000000000000000000000000000001"; // placeholder
await ens.hcaAdmin.setUpgradeApprovalSync({ implementation, approved: true });

const governance = await ens.hcaAdmin.getGovernance({ implementation });

Renouncing is permanent

renounceGovernance freezes the factory's implementation approvals. After it, nobody can add or retire an implementation for new HCAs. Use it only to make the set of deployable implementations permanent.

Troubleshooting

HCA_UPGRADE_NOT_ALLOWED

The HCA is not deployed, the upgrade set does not include the implementation, or the implementation does not accept the current one as predecessor. Run getUpgrade to see which. See HCA_UPGRADE_NOT_ALLOWED.

untrusted-implementation in problems

The account runs an implementation that is neither the factory's first one nor in the upgrade set. ensforge refuses to route writes through such an account. See How it works.

Was this page helpful?