| name | ritual-dapp-frontend |
| description | Frontend development for Ritual dApps with async transaction state machines, wagmi/viem hooks, and event subscriptions. Use when building React/Next.js frontends for Ritual. |
| version | 1.0.0 |
Ritual dApp Frontend
Build React/Next.js frontends for Ritual Chain dApps. Use wagmi v2 (^2.12.0) + viem v2. The encoding logic (viem) is framework-agnostic; the hooks below are React-specific.
Critical: writeContractAsync Breaks on Async Precompiles
Async precompiles (HTTP 0x0801, LLM 0x0802, etc.) are not deployed contracts — they are handled at the EVM level. wagmi's writeContractAsync runs simulateContract (which uses eth_call) before sending, and eth_call against a precompile returns "call to non-contract address".
Any useWriteContract call to a function that internally calls an async precompile will always revert in simulation.
Use useSendTransaction with encodeFunctionData instead to skip simulation:
import { encodeFunctionData } from "viem";
import { useSendTransaction } from "wagmi";
const { sendTransactionAsync } = useSendTransaction();
const data = encodeFunctionData({
abi: contractAbi,
functionName: "yourAsyncFunction",
args: [executor, ttl],
});
const hash = await sendTransactionAsync({
to: contractAddress,
data,
gas: 2_000_000n,
});
This applies to ANY contract function that calls an async precompile internally. Use useWriteContract only for pure reads or functions that don't touch async precompiles.
1. Chain Configuration
Define the Ritual chain ONCE and reference everywhere:
import { defineChain } from "viem";
export const ritualChain = defineChain({
id: 1979,
name: "Ritual",
nativeCurrency: { name: "RITUAL", symbol: "RITUAL", decimals: 18 },
rpcUrls: {
default: {
http: [process.env.NEXT_PUBLIC_RPC_URL ?? "https://rpc.ritualfoundation.org"],
},
},
blockExplorers: {
default: { name: "Ritual Explorer", url: "https://explorer.ritualfoundation.org" },
},
});
ChainGuard — Block UI on Wrong Chain
import { useAccount, useSwitchChain } from "wagmi";
import { ritualChain } from "@/lib/chain";
export function ChainGuard({ children }: { children: React.ReactNode }) {
const { chain, isConnected } = useAccount();
const { switchChain, isPending } = useSwitchChain();
if (isConnected && chain?.id !== ritualChain.id) {
return (
<button
onClick={() => switchChain({ chainId: ritualChain.id })}
disabled={isPending}
className="px-4 py-2 bg-amber-500/10 border border-amber-500 text-amber-400 rounded-lg text-sm
focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-amber-500/50
focus-visible:ring-offset-2 focus-visible:ring-offset-black"
>
{isPending ? "Switching..." : "Switch to Ritual Chain"}
</button>
);
}
return <>{children}</>;
}
Browser RPC Proxy (Critical Pitfall)
Frontend frameworks make JSON-RPC calls from the user's browser. If the Ritual RPC endpoint is not publicly accessible from the browser (internal IP, firewall-blocked), all contract reads silently fail — the UI shows empty data with no error.
Symptoms: useReadContract returns undefined. dApp works server-side but shows nothing in browser. Network tab shows failed RPC requests.
Fix: Proxy through a Next.js API route:
import { NextRequest, NextResponse } from "next/server";
const RPC_URL = process.env.RITUAL_RPC_URL ?? "https://rpc.ritualfoundation.org";
export async function POST(req: NextRequest) {
const body = await req.json();
const res = await fetch(RPC_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
return NextResponse.json(await res.json());
}
Then configure wagmi transport:
import { createConfig, http } from "wagmi";
import { ritualChain } from "./chain";
export const wagmiConfig = createConfig({
chains: [ritualChain],
connectors: [injected()],
transports: {
[ritualChain.id]: http("/api/rpc"),
},
});
Use the proxy when the RPC is not browser-accessible. The public https://rpc.ritualfoundation.org endpoint is browser-accessible.
2. Async Transaction State Machine
Ritual precompile calls pass through up to 9 states from submission to settlement. Some states map directly to on-chain events; others are UI-interpolated with no on-chain signal:
| State | On-chain signal | Source |
|---|
| SUBMITTING | — | Local (wallet interaction) |
| PENDING_COMMITMENT | — | Local (tx sent, awaiting inclusion) |
| COMMITTED | JobAdded event | AsyncJobTracker |
| EXECUTOR_PROCESSING | — | UI-interpolated (time since COMMITTED) |
| RESULT_READY | Phase1Settled event (long-running only) | AsyncJobTracker |
| PENDING_SETTLEMENT | — | UI-interpolated (long-running async only, awaiting callback) |
| SETTLED | ResultDelivered(success=true) (long-running) or JobRemoved(completed=true) + spcCalls in receipt (short-running) | AsyncJobTracker or receipt |
| FAILED | SettlementFailed, DeliveryFailed, ResultDelivered(success=false), or JobRemoved(completed=false) from cleanup | AsyncDelivery / AsyncJobTracker |
| EXPIRED | — | Derived (current block > commit block + TTL); confirmed by cleanup JobRemoved(completed=false) |
What Phase1Settled actually means (it's a footgun). This event does NOT mean the underlying job is done. It is emitted from AsyncJobTracker.markPhase1Settled only for long-running precompiles, after AsyncDelivery.settle has paid the executor + validators for Phase 1. At that point:
- Short-running (HTTP, LLM, ONNX, JQ, DKMS, …):
Phase1Settled is never emitted. The result is already in the receipt's spcCalls and JobRemoved(completed=true) fires instead.
- Long-running (Long HTTP, Sovereign Agent, Persistent Agent, Image / Audio / Video, ZK, FHE):
Phase1Settled means the executor has committed to starting the off-chain work and the Phase 2 deadline is now armed. The actual job result lands later via ResultDelivered + Delivered. For these jobs, the "Phase 1 result" is just the task ID, not the final payload.
So map Phase1Settled → RESULT_READY only for long-running async, and treat RESULT_READY as "executor accepted the job" rather than "result available".
State Diagram
User submits tx
│
▼
SUBMITTING ──────► FAILED (tx reverted / user rejected)
│
▼
PENDING_COMMITMENT ──► EXPIRED (no executor within TTL)
│
▼
COMMITTED ──────► FAILED (executor errored)
│
▼
EXECUTOR_PROCESSING
│
▼
RESULT_READY ────► FAILED (delivery failed)
│
▼
PENDING_SETTLEMENT
│
▼
SETTLED ◄──────── (final success state)
Full TypeScript Types
export type AsyncTxStatus =
| "SUBMITTING"
| "PENDING_COMMITMENT"
| "COMMITTED"
| "EXECUTOR_PROCESSING"
| "RESULT_READY"
| "PENDING_SETTLEMENT"
| "SETTLED"
| "FAILED"
| "EXPIRED";
export interface AsyncTxSubmitting { status: "SUBMITTING" }
export interface AsyncTxPendingCommitment {
status: "PENDING_COMMITMENT";
txHash: `0x${string}`;
submittedAt: number;
ttlBlocks: number;
}
export interface AsyncTxCommitted {
status: "COMMITTED";
txHash: `0x${string}`;
jobId: `0x${string}`;
executor: `0x${string}`;
committedBlock: number;
}
export interface AsyncTxExecutorProcessing {
status: "EXECUTOR_PROCESSING";
txHash: `0x${string}`;
jobId: `0x${string}`;
executor: `0x${string}`;
startBlock: number;
estimatedBlocks: number;
}
export interface AsyncTxResultReady {
status: "RESULT_READY";
txHash: `0x${string}`;
jobId: `0x${string}`;
settledBlock: number;
}
export interface AsyncTxPendingSettlement {
status: "PENDING_SETTLEMENT";
txHash: `0x${string}`;
jobId: `0x${string}`;
deliveryTxHash?: `0x${string}`;
}
export interface AsyncTxSettled {
status: "SETTLED";
txHash: `0x${string}`;
jobId: `0x${string}`;
result: unknown;
settlementTxHash: `0x${string}`;
settledBlock: number;
gasUsed: bigint;
}
export interface AsyncTxFailed {
status: "FAILED";
txHash?: `0x${string}`;
jobId?: `0x${string}`;
error: string;
errorCategory: ErrorCategory;
failedAt: AsyncTxStatus;
}
export interface AsyncTxExpired {
status: "EXPIRED";
txHash: `0x${string}`;
submittedAt: number;
expiredAt: number;
ttlBlocks: number;
}
export type AsyncTxState =
| AsyncTxSubmitting
| AsyncTxPendingCommitment
| AsyncTxCommitted
| AsyncTxExecutorProcessing
| AsyncTxResultReady
| AsyncTxPendingSettlement
| AsyncTxSettled
| AsyncTxFailed
| AsyncTxExpired;
export type ErrorCategory = "wallet" | "contract" | "async" | "network";
State Transition Logic
export function canTransition(from: AsyncTxStatus, to: AsyncTxStatus): boolean {
const valid: Record<AsyncTxStatus, AsyncTxStatus[]> = {
SUBMITTING: ["PENDING_COMMITMENT", "FAILED"],
PENDING_COMMITMENT: ["COMMITTED", "EXPIRED", "FAILED"],
COMMITTED: ["EXECUTOR_PROCESSING", "FAILED"],
EXECUTOR_PROCESSING: ["RESULT_READY", "FAILED"],
RESULT_READY: ["PENDING_SETTLEMENT", "SETTLED", "FAILED"],
PENDING_SETTLEMENT: ["SETTLED", "FAILED"],
SETTLED: [],
FAILED: [],
EXPIRED: [],
};
return valid[from]?.includes(to) ?? false;
}
export function isTerminalState(status: AsyncTxStatus): boolean {
return status === "SETTLED" || status === "FAILED" || status === "EXPIRED";
}
Transaction Store
Use Zustand with persist for localStorage persistence. The store shape tracks in-flight Ritual transactions:
import { create } from "zustand";
import { persist } from "zustand/middleware";
import type { AsyncTxState, AsyncTxStatus } from "@/types/asyncTx";
interface TrackedTransaction {
id: string;
precompileType: "http" | "llm" | "agent" | "longhttp" | "image" | "audio" | "video";
state: AsyncTxState;
createdAt: number;
updatedAt: number;
label?: string;
}
interface AsyncTxStore {
transactions: Record<string, TrackedTransaction>;
addTransaction: (id: string, precompileType: TrackedTransaction["precompileType"], label?: string) => void;
updateState: (id: string, newState: AsyncTxState) => void;
getTransaction: (id: string) => TrackedTransaction | undefined;
getActiveTransactions: () => TrackedTransaction[];
clearSettled: () => void;
}
export const useAsyncTxStore = create<AsyncTxStore>()(
persist(
(set, get) => ({
transactions: {},
addTransaction: (id, precompileType, label) =>
set((s) => ({
transactions: { ...s.transactions, [id]: { id, precompileType, state: { status: "SUBMITTING" }, createdAt: Date.now(), updatedAt: Date.now(), label } },
})),
updateState: (id, newState) =>
set((s) => {
const existing = s.transactions[id];
if (!existing) return s;
return { transactions: { ...s.transactions, [id]: { ...existing, state: newState, updatedAt: Date.now() } } };
}),
getTransaction: (id) => get().transactions[id],
getActiveTransactions: () => Object.values(get().transactions).filter((tx) => !isTerminalState(tx.state.status)),
clearSettled: () =>
set((s) => ({
transactions: Object.fromEntries(Object.entries(s.transactions).filter(([, tx]) => !isTerminalState(tx.state.status))),
})),
}),
{ name: "ritual-async-tx" },
),
);
Transactions survive page refresh. The persist middleware writes to localStorage keyed by "ritual-async-tx".
3. spcCalls Receipt Parsing
When a short-running async precompile (HTTP 0x0801, LLM 0x0802) settles, the result is in the transaction receipt's spcCalls field — a Ritual-specific extension not present on standard EVM receipts.
import { decodeAbiParameters } from "viem";
interface RitualReceipt {
spcCalls?: Array<{ input: `0x${string}`; output: `0x${string}` }>;
}
function extractSpcResult(receipt: unknown): `0x${string}` | null {
const spcCalls = (receipt as RitualReceipt).spcCalls;
if (!spcCalls || spcCalls.length === 0) return null;
return spcCalls[0].output;
}
function decodeHTTPResponse(output: `0x${string}`) {
const [statusCode, headerKeys, headerValues, body, errorMessage] =
decodeAbiParameters(
[{ type: "uint16" }, { type: "string[]" }, { type: "string[]" }, { type: "bytes" }, { type: "string" }],
output,
);
return {
statusCode,
headers: Object.fromEntries(headerKeys.map((k, i) => [k, headerValues[i]])),
body: new TextDecoder().decode(body as Uint8Array),
error: errorMessage || null,
};
}
4. Core Hooks
useRitualWrite — Bypass Broken eth_call Simulation
import { useSendTransaction } from "wagmi";
import { encodeFunctionData, type Abi } from "viem";
export function useRitualWrite() {
const { sendTransactionAsync } = useSendTransaction();
async function write({
address, abi, functionName, args = [], value, gas = 300_000n, nonce,
}: {
address: `0x${string}`;
abi: Abi;
functionName: string;
args?: unknown[];
value?: bigint;
gas?: bigint;
nonce?: number;
}) {
const data = encodeFunctionData({ abi, functionName, args });
return sendTransactionAsync({ to: address, data, value, gas, nonce });
}
return { write };
}
useAsyncJobEvents — Watch AsyncJobTracker
The AsyncJobTracker uses bytes32 job IDs (not uint256). The on-chain events are:
JobAdded — emitted when a job is committed by the chain (maps to COMMITTED state)Phase1Settled — emitted only for long-running async, when the executor's Phase 1 settlement TX has paid Phase 1 fees and armed the Phase 2 deadline (maps to RESULT_READY for long-running). Not emitted for short-running async — short-running jobs jump straight from JobAdded to JobRemoved(completed=true) via AsyncDelivery.Settled.ResultDelivered — emitted when the long-running callback actually delivers (maps to SETTLED if success=true, FAILED if success=false)AsyncDelivery.SettlementFailed / DeliveryFailed — payment-side failures (insufficient RitualWallet balance for Phase 1 fees or Phase 2 callback gas+value); job lingers until cleanup removes it as expiredJobRemoved — emitted when a job is cleaned up
Note: EXECUTOR_PROCESSING and PENDING_SETTLEMENT are UI-interpolated states — there is no on-chain event for them. Derive them from timing (blocks elapsed since JobAdded).
import { useWatchContractEvent, useAccount } from "wagmi";
import { useAsyncTxStore } from "@/stores/asyncTxStore";
const ASYNC_JOB_TRACKER = "0xC069FFCa0389f44eCA2C626e55491b0ab045AEF5" as const;
const asyncJobTrackerAbi = [
{
type: "event", name: "JobAdded",
inputs: [
{ name: "executor", type: "address", indexed: true },
{ name: "jobId", type: "bytes32", indexed: true },
{ name: "precompileAddress", type: "address", indexed: true },
{ name: "commitBlock", type: "uint256", indexed: false },
{ name: "precompileInput", type: "bytes", indexed: false },
{ name: "senderAddress", type: "address", indexed: false },
{ name: "previousBlockHash", type: "bytes32", indexed: false },
{ name: "previousBlockNumber", type: "uint256", indexed: false },
{ name: "previousBlockTimestamp", type: "uint256", indexed: false },
{ name: "ttl", type: "uint256", indexed: false },
{ name: "createdAt", type: "uint256", indexed: false },
],
},
{
type: "event", name: "Phase1Settled",
inputs: [
{ name: "jobId", type: "bytes32", indexed: true },
{ name: "executor", type: "address", indexed: true },
{ name: "settledBlock", type: "uint256", indexed: false },
],
},
{
type: "event", name: "ResultDelivered",
inputs: [
{ name: "jobId", type: "bytes32", indexed: true },
{ name: "target", type: "address", indexed: true },
{ name: "success", type: "bool", indexed: false },
],
},
{
type: "event", name: "JobRemoved",
inputs: [
{ name: "executor", type: "address", indexed: true },
{ name: "jobId", type: "bytes32", indexed: true },
{ name: "completed", type: "bool", indexed: true },
],
},
{
type: "function", name: "hasPendingJobForSender",
inputs: [{ name: "sender", type: "address" }],
outputs: [{ type: "bool" }],
stateMutability: "view",
},
] as const;
export function useAsyncJobEvents({ txId, enabled = true }: { txId: string; enabled?: boolean }) {
const { address } = useAccount();
const updateState = useAsyncTxStore((s) => s.updateState);
const getTransaction = useAsyncTxStore((s) => s.getTransaction);
useWatchContractEvent({
address: ASYNC_JOB_TRACKER,
abi: asyncJobTrackerAbi,
eventName: "JobAdded",
enabled: enabled && !!address,
onLogs: (logs) => {
for (const log of logs) {
if (log.args.senderAddress?.toLowerCase() !== address?.toLowerCase()) continue;
const tx = getTransaction(txId);
if (!tx || tx.state.status !== "PENDING_COMMITMENT") continue;
updateState(txId, {
status: "COMMITTED",
txHash: tx.state.txHash,
jobId: log.args.jobId!,
executor: log.args.executor as `0x${string}`,
committedBlock: Number(log.args.commitBlock),
});
}
},
});
useWatchContractEvent({
address: ASYNC_JOB_TRACKER,
abi: asyncJobTrackerAbi,
eventName: "Phase1Settled",
enabled: enabled && !!address,
onLogs: (logs) => {
for (const log of logs) {
const tx = getTransaction(txId);
if (!tx) continue;
if (tx.state.status === "COMMITTED" || tx.state.status === "EXECUTOR_PROCESSING") {
updateState(txId, {
status: "RESULT_READY",
txHash: tx.state.txHash,
jobId: log.args.jobId!,
settledBlock: Number(log.args.settledBlock),
});
}
}
},
});
useWatchContractEvent({
address: ASYNC_JOB_TRACKER,
abi: asyncJobTrackerAbi,
eventName: "ResultDelivered",
enabled: enabled && !!address,
onLogs: (logs) => {
for (const log of logs) {
const tx = getTransaction(txId);
if (!tx || tx.state.status !== "RESULT_READY") continue;
updateState(txId, {
status: log.args.success ? "SETTLED" : "FAILED",
txHash: tx.state.txHash,
jobId: log.args.jobId!,
deliverySuccess: log.args.success,
});
}
},
});
}
useSenderLock — Detect One-Async-Per-EOA Constraint
The chain rejects async submissions when the sender already has a pending job. Check before allowing submit:
import { useAccount, useReadContract } from "wagmi";
export function useSenderLock() {
const { address } = useAccount();
const { data: isLocked, refetch } = useReadContract({
address: ASYNC_JOB_TRACKER,
abi: asyncJobTrackerAbi,
functionName: "hasPendingJobForSender",
args: address ? [address] : undefined,
query: { enabled: !!address, refetchInterval: 5_000 },
});
return {
isLocked: isLocked ?? false,
refetch,
message: isLocked ? "You have a pending async job — wait for settlement before submitting another." : null,
};
}
useRitualWallet — Balance, Deposit, Withdraw
import { useAccount, useReadContract, useWaitForTransactionReceipt } from "wagmi";
import { parseEther, formatEther } from "viem";
import { useRitualWrite } from "./useRitualWrite";
import { useState, useCallback } from "react";
const RITUAL_WALLET = "0x532F0dF0896F353d8C3DD8cc134e8129DA2a3948" as const;
const ritualWalletAbi = [
{ type: "function", name: "balanceOf", inputs: [{ name: "user", type: "address" }], outputs: [{ type: "uint256" }], stateMutability: "view" },
{ type: "function", name: "lockUntil", inputs: [{ name: "user", type: "address" }], outputs: [{ type: "uint256" }], stateMutability: "view" },
{ type: "function", name: "deposit", inputs: [{ name: "lockDuration", type: "uint256" }], outputs: [], stateMutability: "payable" },
{ type: "function", name: "withdraw", inputs: [{ name: "amount", type: "uint256" }], outputs: [], stateMutability: "nonpayable" },
] as const;
export function useRitualWallet() {
const { address } = useAccount();
const { write } = useRitualWrite();
const { data: balance, refetch: refetchBalance } = useReadContract({
address: RITUAL_WALLET,
abi: ritualWalletAbi,
functionName: "balanceOf",
args: address ? [address] : undefined,
query: { enabled: !!address, refetchInterval: 12_000 },
});
const { data: lockUntilBlock } = useReadContract({
address: RITUAL_WALLET,
abi: ritualWalletAbi,
functionName: "lockUntil",
args: address ? [address] : undefined,
query: { enabled: !!address },
});
const [pendingTxHash, setPendingTxHash] = useState<`0x${string}` | undefined>();
const { isLoading: isConfirming } = useWaitForTransactionReceipt({ hash: pendingTxHash, query: { enabled: !!pendingTxHash } });
const deposit = useCallback(async (amountEther: string, lockDurationBlocks: bigint = 5000n) => {
const hash = await write({ address: RITUAL_WALLET, abi: ritualWalletAbi, functionName: "deposit", args: [lockDurationBlocks], value: parseEther(amountEther) });
setPendingTxHash(hash);
return hash;
}, [write]);
const withdraw = useCallback(async (amountEther: string) => {
const hash = await write({ address: RITUAL_WALLET, abi: ritualWalletAbi, functionName: "withdraw", args: [parseEther(amountEther)] });
setPendingTxHash(hash);
return hash;
}, [write]);
return { balance, balanceFormatted: balance ? formatEther(balance) : "0", lockUntilBlock, deposit, withdraw, isConfirming, refetchBalance };
}
useDepositGate — Block Submit Until Funded
import { useRitualWallet } from "./useRitualWallet";
import { useMemo } from "react";
export function useDepositGate(estimatedFeeWei: bigint) {
const { balance, deposit, isConfirming } = useRitualWallet();
const hasSufficientDeposit = useMemo(() => {
if (!balance) return false;
return balance >= estimatedFeeWei;
}, [balance, estimatedFeeWei]);
return {
hasSufficientDeposit,
shortfall: balance ? (estimatedFeeWei > balance ? estimatedFeeWei - balance : 0n) : estimatedFeeWei,
deposit,
isConfirming,
message: hasSufficientDeposit ? null : "Insufficient RitualWallet deposit. Deposit RITUAL before submitting.",
};
}
useBlockProgress — Block-Based Operation Tracking
import { useBlockNumber } from "wagmi";
import { useMemo } from "react";
export function useBlockProgress({ startBlock, estimatedBlocks, enabled = true }: { startBlock: number; estimatedBlocks: number; enabled?: boolean }) {
const { data: currentBlock } = useBlockNumber({ watch: enabled, query: { refetchInterval: 4_000 } });
return useMemo(() => {
if (!currentBlock) return { progress: 0, blocksElapsed: 0, blocksRemaining: estimatedBlocks, isComplete: false };
const elapsed = Math.max(0, Number(currentBlock) - startBlock);
const remaining = Math.max(0, estimatedBlocks - elapsed);
return { progress: Math.min(1, elapsed / estimatedBlocks), blocksElapsed: elapsed, blocksRemaining: remaining, isComplete: elapsed >= estimatedBlocks, currentBlock: Number(currentBlock) };
}, [currentBlock, startBlock, estimatedBlocks]);
}
5. Precompile Encoding / Decoding
Canonical encode/decode functions. Reference these from hooks — don't duplicate.
HTTP Call (0x0801)
13-field canonical encoding (includes DKMS fields). For non-DKMS flows, pass dkmsKeyIndex: 0n and dkmsKeyFormat: 0. See ritual-dapp-http skill for full HTTP precompile details.
import { encodeAbiParameters, decodeAbiParameters, type Hex } from "viem";
export function encodeHTTPCallRequest(params: {
executor: `0x${string}`;
url: string;
method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
headerKeys?: string[];
headerValues?: string[];
body?: string;
ttl?: bigint;
encryptedSecrets?: `0x${string}`[];
secretSignatures?: `0x${string}`[];
userPublicKey?: `0x${string}`;
dkmsKeyIndex?: bigint;
dkmsKeyFormat?: number;
piiEnabled?: boolean;
}): Hex {
const methodCode = { GET: 1, POST: 2, PUT: 3, DELETE: 4, PATCH: 5 }[params.method];
return encodeAbiParameters(
[
{ type: "address" }, { type: "bytes[]" }, { type: "uint256" },
{ type: "bytes[]" }, { type: "bytes" },
{ type: "string" }, { type: "uint8" },
{ type: "string[]" }, { type: "string[]" }, { type: "bytes" },
{ type: "uint256" }, { type: "uint8" },
{ type: "bool" },
],
[
params.executor,
params.encryptedSecrets ?? [],
params.ttl ?? 100n,
params.secretSignatures ?? [],
params.userPublicKey ?? "0x",
params.url,
methodCode,
params.headerKeys ?? [],
params.headerValues ?? [],
params.body ? (`0x${Buffer.from(params.body).toString("hex")}` as Hex) : "0x",
params.dkmsKeyIndex ?? 0n,
params.dkmsKeyFormat ?? 0,
params.piiEnabled ?? false,
],
);
}
export function decodeHTTPCallResponse(data: Hex) {
const [statusCode, headerKeys, headerValues, body, errorMessage] =
decodeAbiParameters(
[{ type: "uint16" }, { type: "string[]" }, { type: "string[]" }, { type: "bytes" }, { type: "string" }],
data,
);
const headers: Record<string, string> = {};
headerKeys.forEach((k, i) => { headers[k] = headerValues[i]; });
return {
statusCode, headers,
body: new TextDecoder().decode(body as Uint8Array),
error: errorMessage || null,
get jsonBody() { return JSON.parse(new TextDecoder().decode(body as Uint8Array)); },
};
}
Sovereign Agent (0x080C)
export function encodeAgentCallRequest(params: {
executor: `0x${string}`;
prompt: string;
tools?: string[];
maxIterations?: number;
maxToolCalls?: number;
maxTokens?: number;
temperatureScaled?: number;
ttl?: bigint;
deliveryTarget?: `0x${string}`;
deliverySelector?: `0x${string}`;
}): Hex {
return encodeAbiParameters(
[
{ type: "address" }, { type: "bytes[]" }, { type: "uint256" },
{ type: "bytes[]" }, { type: "bytes" },
{ type: "uint64" }, { type: "uint64" }, { type: "string" },
{ type: "address" }, { type: "bytes4" }, { type: "uint256" },
{ type: "uint256" }, { type: "uint256" }, { type: "uint256" },
{ type: "string" }, { type: "string[]" },
{ type: "uint16" }, { type: "uint16" }, { type: "uint32" },
{ type: "uint16" }, { type: "bool" },
],
[
params.executor, [], params.ttl ?? 200n, [], "0x",
5n, 1000n, "AGENT_TASK",
params.deliveryTarget ?? "0x0000000000000000000000000000000000000000",
params.deliverySelector ?? "0x00000000",
3_000_000n, 1_000_000_000n, 100_000_000n, 0n,
params.prompt, params.tools ?? [],
params.maxIterations ?? 10, params.maxToolCalls ?? 20,
params.maxTokens ?? 1024, params.temperatureScaled ?? 70, false,
],
);
}
export function decodeAgentPhase2(data: Hex) {
const [version, success, response, stoppedReason, iterations, toolCalls, errorMessage] =
decodeAbiParameters(
[{ type: "uint8" }, { type: "bool" }, { type: "string" }, { type: "string" }, { type: "uint16" }, { type: "uint16" }, { type: "string" }],
data,
);
return { version, success, response, stoppedReason, iterations, toolCalls, errorMessage };
}
6. Fee Estimation
Ritual charges executor fees from RitualWallet deposits. HTTP fees use fixed per-byte constants. LLM fees use a gas-based model with per-model parameters from the on-chain ModelPricingRegistry.
HTTP Fee Constants (verified from chain)
export const HTTP_FEE_CONSTANTS = {
BASE_FEE_WEI: 2_500_000_000_000n,
PER_INPUT_BYTE_WEI: 350_000_000n,
PER_OUTPUT_BYTE_WEI: 350_000_000n,
DEFAULT_LOCK_DURATION: 5000n,
} as const;
useHTTPFeeEstimate
import { useMemo } from "react";
import { HTTP_FEE_CONSTANTS } from "@/lib/fees";
export function useHTTPFeeEstimate(estimatedInputBytes = 256, estimatedOutputBytes = 4096) {
return useMemo(() => {
const baseFee = HTTP_FEE_CONSTANTS.BASE_FEE_WEI;
const inputFee = BigInt(estimatedInputBytes) * HTTP_FEE_CONSTANTS.PER_INPUT_BYTE_WEI;
const outputFee = BigInt(estimatedOutputBytes) * HTTP_FEE_CONSTANTS.PER_OUTPUT_BYTE_WEI;
const totalFee = baseFee + inputFee + outputFee;
return { baseFee, inputFee, outputFee, totalFee, lockDuration: HTTP_FEE_CONSTANTS.DEFAULT_LOCK_DURATION, depositRecommendation: totalFee * 2n };
}, [estimatedInputBytes, estimatedOutputBytes]);
}
LLM Fee Model
LLM fees are not fixed per-token constants. The actual fee is computed as total_gas × 1_000_000_000 (1 gwei), where total_gas depends on model-specific parameters (theta, params_b) from the ModelPricingRegistry. Query the registry to check if a model exists; for deposit sizing, use a conservative amount (0.1–1 RITUAL covers most single calls based on working e2e tests).
const MODEL_PRICING_REGISTRY = "0x7A85F48b971ceBb75491b61abe279728F4c4384f" as const;
const modelPricingAbi = [
{ type: "function", name: "modelExists", inputs: [{ name: "modelName", type: "string" }], outputs: [{ type: "bool" }], stateMutability: "view" },
] as const;
export function useModelCheck(model?: string) {
const { data: exists } = useReadContract({
address: MODEL_PRICING_REGISTRY,
abi: modelPricingAbi,
functionName: "modelExists",
args: model ? [model] : undefined,
query: { enabled: !!model },
});
return { modelRegistered: exists ?? null };
}
7. SSE Streaming Consumer for LLM
Connect to Ritual's streaming service for real-time token delivery:
import { useState, useCallback, useRef } from "react";
import { useWalletClient } from "wagmi";
interface StreamingState {
status: "idle" | "submitting" | "signing" | "streaming" | "done" | "error";
txHash?: `0x${string}`;
text: string;
tokens: number;
error?: string;
}
export function useStreamingLLM(streamingServiceUrl = "https://streaming.ritualfoundation.org") {
const [state, setState] = useState<StreamingState>({ status: "idle", text: "", tokens: 0 });
const abortControllerRef = useRef<AbortController | null>(null);
const { data: walletClient } = useWalletClient();
const stream = useCallback(async (txHash: `0x${string}`) => {
if (!walletClient) return;
setState((s) => ({ ...s, status: "signing", txHash }));
const timestamp = BigInt(Math.floor(Date.now() / 1000));
const signature = await walletClient.signTypedData({
domain: { name: "Ritual Streaming Service", version: "1", chainId: 1979 },
types: { StreamRequest: [{ name: "txHash", type: "bytes32" }, { name: "timestamp", type: "uint256" }] },
primaryType: "StreamRequest",
message: { txHash, timestamp },
});
setState((s) => ({ ...s, status: "streaming" }));
const controller = new AbortController();
abortControllerRef.current = controller;
const response = await fetch(`${streamingServiceUrl}/v1/stream/${txHash}`, {
headers: {
"Accept": "text/event-stream",
"Authorization": `Bearer ${signature}`,
"X-Timestamp": timestamp.toString(),
},
signal: controller.signal,
});
if (!response.ok) throw new Error(`Stream HTTP ${response.status}`);
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split("\n");
buffer = lines.pop()!;
for (const line of lines) {
if (!line.startsWith("data: ")) continue;
const payload = line.slice(6);
if (payload === "[DONE]") { setState((s) => ({ ...s, status: "done" })); return; }
const data = JSON.parse(payload);
if (data.type === "token" && data.content) {
setState((s) => ({ ...s, text: s.text + data.content, tokens: s.tokens + 1 }));
}
if (data.type === "error") { setState((s) => ({ ...s, status: "error", error: data.error })); return; }
}
}
setState((s) => ({ ...s, status: "done" }));
}, [walletClient, streamingServiceUrl]);
const stop = useCallback(() => { abortControllerRef.current?.abort(); setState((s) => ({ ...s, status: "done" })); }, []);
const reset = useCallback(() => { stop(); setState({ status: "idle", text: "", tokens: 0 }); }, [stop]);
return { state, stream, stop, reset };
}
8. Transaction Flow Patterns
Pattern 1: HTTP Call (short-running async — result in receipt)
import { useAccount, useWalletClient } from "wagmi";
import { useCallback, useId } from "react";
import { useAsyncTxStore } from "@/stores/asyncTxStore";
import { useAsyncJobEvents } from "@/hooks/useAsyncJobEvents";
import { encodeHTTPCallRequest } from "@/lib/encoding";
const HTTP_PRECOMPILE = "0x0000000000000000000000000000000000000801" as const;
export function useHTTPCall() {
const txId = useId();
const { data: walletClient } = useWalletClient();
const addTransaction = useAsyncTxStore((s) => s.addTransaction);
const updateState = useAsyncTxStore((s) => s.updateState);
const getTransaction = useAsyncTxStore((s) => s.getTransaction);
useAsyncJobEvents({ txId, enabled: !!getTransaction(txId) });
const submit = useCallback(async (options: {
url: string; method?: "GET" | "POST"; headers?: Record<string, string>;
body?: string; executor: `0x${string}`; ttl?: bigint; label?: string;
}) => {
addTransaction(txId, "http", options.label);
try {
const encoded = encodeHTTPCallRequest({
executor: options.executor,
url: options.url,
method: options.method ?? "GET",
headerKeys: Object.keys(options.headers ?? {}),
headerValues: Object.values(options.headers ?? {}),
body: options.body,
ttl: options.ttl,
});
const hash = await walletClient!.sendTransaction({ to: HTTP_PRECOMPILE, data: encoded, gas: 2_000_000n });
updateState(txId, { status: "PENDING_COMMITMENT", txHash: hash, submittedAt: Date.now(), ttlBlocks: Number(options.ttl ?? 100n) });
return hash;
} catch (err) {
updateState(txId, { status: "FAILED", error: err instanceof Error ? err.message : "Transaction failed", errorCategory: "wallet", failedAt: "SUBMITTING" });
throw err;
}
}, [txId, walletClient, addTransaction, updateState]);
return { txId, submit, state: getTransaction(txId)?.state ?? null };
}
Pattern 2: Sovereign Agent (long-running async — result via callback)
import { useSendTransaction } from "wagmi";
import { useCallback, useId } from "react";
import { useAsyncTxStore } from "@/stores/asyncTxStore";
import { useAsyncJobEvents } from "@/hooks/useAsyncJobEvents";
import { encodeAgentCallRequest } from "@/lib/encoding";
const SOVEREIGN_AGENT_PRECOMPILE = "0x000000000000000000000000000000000000080C" as const;
export function useAgentCall() {
const txId = useId();
const { sendTransactionAsync } = useSendTransaction();
const addTransaction = useAsyncTxStore((s) => s.addTransaction);
const updateState = useAsyncTxStore((s) => s.updateState);
const getTransaction = useAsyncTxStore((s) => s.getTransaction);
useAsyncJobEvents({ txId, enabled: !!getTransaction(txId) });
const submit = useCallback(async (options: {
executor: `0x${string}`; prompt: string; tools?: string[];
maxIterations?: number; ttl?: bigint;
deliveryTarget?: `0x${string}`; deliverySelector?: `0x${string}`; label?: string;
}) => {
addTransaction(txId, "agent", options.label);
try {
const encoded = encodeAgentCallRequest(options);
const hash = await sendTransactionAsync({ to: SOVEREIGN_AGENT_PRECOMPILE, data: encoded, gas: 3_000_000n });
updateState(txId, { status: "PENDING_COMMITMENT", txHash: hash, submittedAt: Date.now(), ttlBlocks: Number(options.ttl ?? 200n) });
return hash;
} catch (err) {
updateState(txId, { status: "FAILED", error: err instanceof Error ? err.message : "Sovereign Agent call failed", errorCategory: "contract", failedAt: "SUBMITTING" });
throw err;
}
}, [txId, sendTransactionAsync, addTransaction, updateState]);
return { txId, submit, state: getTransaction(txId)?.state ?? null };
}
Nonce Management for Multi-Transaction Flows
When a submit flow requires sequential transactions (deposit → register → submit), stale nonces cause "replacement transaction underpriced". Fetch the confirmed nonce at the start and increment:
import { usePublicClient } from "wagmi";
async function multiTxFlow(publicClient: ReturnType<typeof usePublicClient>, userAddress: `0x${string}`) {
let nonce = await publicClient!.getTransactionCount({ address: userAddress, blockTag: "pending" });
const hash1 = await sendTransactionAsync({ to: WALLET, data: depositData, nonce });
await publicClient!.waitForTransactionReceipt({ hash: hash1 });
nonce++;
const hash2 = await sendTransactionAsync({ to: CONTRACT, data: submitData, nonce });
}
If a user gets stuck with "replacement transaction underpriced", they need to "Clear activity data" in MetaMask (Settings → Advanced → Clear activity tab data) to reset MetaMask's nonce cache.
9. UI Components
These are Ritual-specific component patterns. The styling/layout is standard Tailwind — only the data contracts and Ritual-specific state mapping matter. See the ritual-dapp-design skill for full design system guidance.
AsyncTransactionStatus
Renders the 9-state lifecycle. Ritual-specific requirements:
- Map
AsyncTxState.status to a label/color/animation config
- Show
jobId (bytes32, display as truncated hex) when available
- For
EXECUTOR_PROCESSING: use useBlockProgress to show block-based progress (no on-chain signal — interpolate from blocks elapsed since JobAdded.commitBlock)
- For
FAILED: display error message and errorCategory
- Include a step indicator (7 non-terminal steps) showing progress through the pipeline
interface AsyncTransactionStatusProps {
state: AsyncTxState;
compact?: boolean;
}
const STATUS_CONFIG: Record<AsyncTxStatus, { label: string; icon: string; color: string }> = {
SUBMITTING: { label: "Submitting", icon: "↗", color: "blue" },
PENDING_COMMITMENT: { label: "Awaiting Executor", icon: "◎", color: "yellow" },
COMMITTED: { label: "Executor Committed", icon: "✓", color: "cyan" },
EXECUTOR_PROCESSING: { label: "Processing", icon: "⟳", color: "green" },
RESULT_READY: { label: "Result Ready", icon: "◆", color: "lime" },
PENDING_SETTLEMENT: { label: "Settling", icon: "⧖", color: "green" },
SETTLED: { label: "Settled", icon: "✔", color: "green" },
FAILED: { label: "Failed", icon: "✕", color: "red" },
EXPIRED: { label: "Expired", icon: "⏱", color: "gray" },
};
RitualWalletCard
Displays RitualWallet balance and deposit/withdraw controls. Ritual-specific requirements:
- Use
useRitualWallet() for balance, lockUntilBlock, deposit/withdraw actions
- Use
useSenderLock() to show lock indicator (amber dot + message when locked)
- Show balance in RITUAL with 4 decimal places (
formatEther)
- Show lock-until block number when locked
PrecompileSelector
Grid of available precompiles for user selection. Ritual-specific data:
const PRECOMPILES = [
{ id: "http", name: "HTTP Call", address: "0x0801", category: "data" },
{ id: "llm", name: "LLM", address: "0x0802", category: "inference" },
{ id: "longhttp", name: "Long HTTP", address: "0x0805", category: "data" },
{ id: "zk", name: "ZK Proof", address: "0x0806", category: "data" },
{ id: "sovereign", name: "Sovereign Agent", address: "0x080C", category: "agent" },
{ id: "image", name: "Image Gen", address: "0x0818", category: "multimodal" },
{ id: "audio", name: "Audio Gen", address: "0x0819", category: "multimodal" },
{ id: "video", name: "Video Gen", address: "0x081A", category: "multimodal" },
] as const;
FeeEstimateDisplay
Shows fee breakdown. Format wei to RITUAL: Number(wei) / 1e18, display with 4 decimal places. Show totalFee and lockDuration (in blocks).
10. Error Handling
Ritual-specific error codes to match against in error.message. Standard wallet errors (user rejected, insufficient funds) use normal wagmi/viem patterns.
| Code | Category | Match string | Recoverable | Ritual-specific guidance |
|---|
SENDER_LOCKED | async | "sender locked", "pending job" | Yes | Wait for current job to settle. Check hasPendingJobForSender. |
INSUFFICIENT_DEPOSIT | contract | "insufficient deposit", "wallet balance" | Yes | Deposit RITUAL into RitualWallet before submitting. |
NO_EXECUTOR | contract | "no executor", "executor not found" | Yes | No executor available. Retry shortly or pick a different executor. |
JOB_EXPIRED | async | "job expired", "ttl exceeded" | Yes | Increase TTL or retry during lower activity. |
DELIVERY_FAILED | async | "callback failed", "delivery failed" | No | Check callback function for reverts or gas limit. |
export type ErrorCategory = "wallet" | "contract" | "async" | "network";
11. Contract Addresses
export const RITUAL_ADDRESSES = {
PRECOMPILE: {
HTTP_CALL: "0x0000000000000000000000000000000000000801",
LLM: "0x0000000000000000000000000000000000000802",
LONG_RUNNING_HTTP:"0x0000000000000000000000000000000000000805",
ZK_LONG_RUNNING_ASYNC: "0x0000000000000000000000000000000000000806",
SOVEREIGN_AGENT: "0x000000000000000000000000000000000000080C",
IMAGE_CALL: "0x0000000000000000000000000000000000000818",
AUDIO_CALL: "0x0000000000000000000000000000000000000819",
VIDEO_CALL: "0x000000000000000000000000000000000000081A",
},
SYSTEM: {
WALLET: "0x532F0dF0896F353d8C3DD8cc134e8129DA2a3948",
ASYNC_JOB_TRACKER: "0xC069FFCa0389f44eCA2C626e55491b0ab045AEF5",
TEE_SERVICE_REGISTRY: "0x9644e8562cE0Fe12b4deeC4163c064A8862Bf47F",
SCHEDULER: "0x56e776BAE2DD60664b69Bd5F865F1180ffB7D58B",
SECRETS_ACCESS_CTRL: "0xf9BF1BC8A3e79B9EBeD0fa2Db70D0513fecE32FD",
MODEL_PRICING: "0x7A85F48b971ceBb75491b61abe279728F4c4384f",
},
} as const;
12. Cross-References to Other Skills
| Need | Skill | What it provides |
|---|
| HTTP precompile encoding details | ritual-dapp-http | Full 13-field ABI, method codes, secrets, PII mode |
| LLM precompile encoding details | ritual-dapp-llm | Message format, model selection, conversation history |
| Executor discovery & selection | ritual-dapp-precompiles | TEEServiceRegistry queries, capability checks |
| Long-running HTTP | ritual-dapp-longrunning | Poll/result URL encoding, phase 2 callback |
| Sovereign Agent | ritual-dapp-agents | Agent encoding, tool registration, iteration limits |
| Contract deployment patterns | ritual-dapp-contracts | System contract addresses, ABI references |
| Secrets & encryption | ritual-dapp-secrets | ECIES encryption, SecretsAccessControl |
| Storage & DA | ritual-dapp-da | StorageRef format, GCS/HF/Pinata credentials, output URI handling |
| Design system | ritual-dapp-design | Color palette, typography, component patterns |
| Wallet & deposit flow | ritual-dapp-wallet | RitualWallet details, lock mechanics |
Do not re-implement logic covered by these skills. Import the encoding/decoding functions they specify and use them in your hooks.
Quick Reference
| Task | Hook / Component | Notes |
|---|
| Connect wallet | Standard wagmi useConnect + ChainGuard | — |
| Bypass eth_call simulation | useRitualWrite() | Required for any async precompile call |
| Track async tx lifecycle | useAsyncJobEvents({ txId }) | Uses JobAdded, Phase1Settled, ResultDelivered events |
| Check sender lock | useSenderLock() | Calls hasPendingJobForSender on AsyncJobTracker |
| Check deposit sufficiency | useDepositGate(estimatedFee) | Compare RitualWallet balance to estimated fee |
| Wallet balance + deposit | useRitualWallet() | balanceOf, lockUntil, deposit, withdraw |
| Block progress | useBlockProgress({ startBlock, estimatedBlocks }) | UI-interpolated, no on-chain signal |
| HTTP fee estimate | useHTTPFeeEstimate(inputBytes, outputBytes) | Uses verified chain constants |
| LLM model check | useModelCheck(model) | Queries ModelPricingRegistry.modelExists |
| Parse spcCalls | extractSpcResult(receipt) + decodeHTTPResponse(output) | Short-running async precompiles only |
| Encode HTTP request | encodeHTTPCallRequest(params) | 13-field canonical format |
| Encode Sovereign Agent request | encodeAgentCallRequest(params) | See ritual-dapp-agents skill for field details |
| LLM streaming | useStreamingLLM() | SSE from streaming.ritualfoundation.org |
