Rhinestone
Run HCA executions as Rhinestone intents, signed by the owner or run without a prompt with a session, and set a refund token.
Experimental
@ensforge/hca is experimental for 1.0. The Rhinestone executor needs a Rhinestone SDK with
standalone HCA support, and ensforge only tests its wiring, not Rhinestone's orchestrator.
Rhinestone is an intent network. The rhinestone() executor sends HCA executions as Rhinestone intents, either signed by the owner or, with a session, signed by a session key without a wallet prompt. By the end of this page you will have an executor ready for both.
Prerequisites
- A Rhinestone SDK instance that supports the standalone ENS HCA (account type
hca, versionens-standalone-1.1.0). Stock@rhinestone/sdk3.2.0 knows only an older HCA account type, so it needs a build with standalone HCA support, as the ENS app uses. Create the instance in your app. ensforge does not depend on the SDK. - For sessions, the session key's signer (a viem account) and an authorized session. See Sessions.
Create the executor
| Option | Type | Default | Description |
|---|---|---|---|
sdk | RhinestoneSdk | none | A Rhinestone SDK instance with standalone HCA support. |
sessionSigner | Account | none | The session key's signer. Required for session executions. |
sponsored | boolean | true | Sponsor executions. When false, fees are paid in the session's refund token. |
Example (A Prompt-Free Route)
import { hca, rhinestone, type HcaSession, type RhinestoneSdk } from "@ensforge/hca";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
declare const sdk: RhinestoneSdk; // created by your app from Rhinestone's SDK
declare const session: HcaSession; // from ens.hca.authorizeSession
const sessionSigner = privateKeyToAccount(generatePrivateKey());
const via = hca({ executors: [rhinestone({ sdk, sessionSigner })], session });Pass via to a write the session allows. See Sessions for what that includes.
Owner-signed executions
Without a session, rhinestone({ sdk }) sends owner-signed, sponsored intents.
import { hca, rhinestone, type RhinestoneSdk } from "@ensforge/hca";
declare const sdk: RhinestoneSdk;
const via = hca({ executors: [rhinestone({ sdk })] });Pay fees in the refund token
With sponsored: false, a session execution pays its fees in the session's refund token. The session sets the token and its ceilings when you authorize it.
import { rhinestone, type RhinestoneSdk } from "@ensforge/hca";
import type { Account } from "viem";
declare const sdk: RhinestoneSdk;
declare const sessionSigner: Account;
const executor = rhinestone({ sdk, sessionSigner, sponsored: false });What ensforge checks
- Before signing, ensforge checks every session call against the HCA policy. A call outside it fails with
HCA_ACTION_NOT_ALLOWEDand nothing is signed. - The SDK account must derive the same HCA address as ensforge. Otherwise the executor fails with
HCA_SDK_UNSUPPORTEDbefore it signs anything. - Status follows the intent until it has a fill transaction. An intent that is
FAILEDorEXPIREDreports as failed.
Troubleshooting
HCA_SDK_UNSUPPORTED
The Rhinestone SDK derives a different address than the owner's HCA. Use an SDK release with standalone HCA support (ens-standalone-1.1.0). See HCA_SDK_UNSUPPORTED.
HCA_EXECUTOR_UNSUPPORTED
The write has no wallet account, the chain has no HCA deployment, or a session execution has no sessionSigner. hca() also throws it when you pass a session and no executor in the list runs sessions. See HCA_EXECUTOR_UNSUPPORTED.
Was this page helpful?