maroo-viem-poc 0.1.0

package/src/core/precompileActions.ts

@@ -0,0 +1,215 @@
+import type { ExtractAbiFunction, ExtractAbiFunctionNames } from 'abitype'
+import type {
+  Abi,
+  Account,
+  Address,
+  Chain,
+  Client,
+  ContractFunctionArgs,
+  ContractFunctionName,
+  ReadContractReturnType,
+  Transport,
+  WriteContractReturnType,
+} from 'viem'
+import { readContract, writeContract } from 'viem/actions'
+import { getAction } from 'viem/utils'
+
+type ReadName<abi extends Abi> = ContractFunctionName<abi, 'pure' | 'view'>
+type WriteName<abi extends Abi> = ContractFunctionName<abi, 'nonpayable' | 'payable'>
+
+/** Per-call escape hatch: precompile addresses are chain params, not universal. */
+export type PrecompileCallOptions = {
+  /** Override the precompile address for this call. */
+  address?: Address | undefined
+}
+
+type ReadArgs<abi extends Abi, name extends ReadName<abi>> = ContractFunctionArgs<
+  abi,
+  'pure' | 'view',
+  name
+>
+type WriteArgs<abi extends Abi, name extends WriteName<abi>> = ContractFunctionArgs<
+  abi,
+  'nonpayable' | 'payable',
+  name
+>
+
+/**
+ * The parameters tuple for a generated action: `args` (and the whole object)
+ * is optional only when the function takes no inputs. This preserves viem's
+ * own required-args typing — omitting mandatory args must fail at compile
+ * time, not as an AbiEncodingLengthMismatchError at runtime.
+ */
+type ParametersFor<args, extra> = readonly [] extends args
+  ? [parameters?: ({ args?: args } & extra) | undefined]
+  : [parameters: { args: args } & extra]
+
+/**
+ * A read call as a plain descriptor, not an executed promise. Its shape is
+ * exactly what `multicall`, `simulateContract`, and `estimateContractGas`
+ * accept, so batching precompile reads (e.g. one PeriodicVolume per user)
+ * costs one round-trip instead of N.
+ */
+export type PrecompileReadCall<abi extends Abi, name extends ReadName<abi>> = {
+  address: Address
+  abi: abi
+  functionName: name
+  args: ReadArgs<abi, name>
+}
+
+export type PrecompileReadActions<abi extends Abi> = {
+  [name in ReadName<abi>]: ((
+    ...parameters: ParametersFor<ReadArgs<abi, name>, PrecompileCallOptions>
+  ) => Promise<ReadContractReturnType<abi, name>>) & {
+    /** Build a multicall/simulate descriptor for this read instead of executing it. */
+    call: (
+      ...parameters: ParametersFor<ReadArgs<abi, name>, PrecompileCallOptions>
+    ) => PrecompileReadCall<abi, name>
+  }
+}
+
+/**
+ * `value` is only accepted for `payable` functions. On this chain no
+ * precompile write is payable — `runOnPcl` carries its forwarded value as an
+ * argument, and the precompile neither forwards nor refunds `msg.value`, so
+ * attaching it to the outer tx strands funds at the precompile address.
+ * Typing it `never` (and stripping it at runtime) closes that path.
+ *
+ * Payability is derived from `ExtractAbiFunction` rather than viem's
+ * `ContractFunctionName<abi, 'payable'>`: the latter widens to `string` when
+ * an ABI has NO payable functions, which would make every name "payable" —
+ * the exact opposite of the guard. With overloads, `value` is allowed when
+ * any overload is payable.
+ */
+type WriteExtra<abi extends Abi, name> = PrecompileCallOptions & {
+  gas?: bigint | undefined
+} & ([name] extends [ExtractAbiFunctionNames<abi>]
+    ? 'payable' extends ExtractAbiFunction<abi, name>['stateMutability']
+      ? { value?: bigint | undefined }
+      : { value?: never }
+    : { value?: bigint | undefined })
+
+export type PrecompileWriteActions<abi extends Abi> = {
+  [name in WriteName<abi>]: (
+    ...parameters: ParametersFor<WriteArgs<abi, name>, WriteExtra<abi, name>>
+  ) => Promise<WriteContractReturnType>
+}
+
+/**
+ * The public shape of every decorator this factory produces.
+ *
+ * Declared as an explicit named alias — and used as the annotated return type
+ * of {@link precompileActions} — so TypeScript's declaration emit references
+ * it by name instead of structurally re-expanding the inferred type at each
+ * `export const xActions = precompileActions(...)` site. Without this the
+ * emitted `.d.ts` grows superlinearly with the number of decorators.
+ */
+export type PrecompileActions<
+  abi extends Abi,
+  mode extends 'read' | 'write' | 'all' = 'all',
+> = mode extends 'read'
+  ? PrecompileReadActions<abi>
+  : mode extends 'write'
+    ? PrecompileWriteActions<abi>
+    : PrecompileReadActions<abi> & PrecompileWriteActions<abi>
+
+export type PrecompileActionsFactory<abi extends Abi, mode extends 'read' | 'write' | 'all'> = (
+  config?: PrecompileCallOptions,
+) => <transport extends Transport, chain extends Chain | undefined, account extends Account | undefined>(
+  client: Client<transport, chain, account>,
+) => PrecompileActions<abi, mode>
+
+const isRead = (m: string) => m === 'view' || m === 'pure'
+
+/**
+ * Build a typed action map from an `as const` ABI by walking it at runtime.
+ *
+ * Replaces per-precompile codegen: every function in `abi` becomes one method,
+ * dispatched to `readContract` or `writeContract` by its state mutability.
+ *
+ * Overloads that agree on mutability share one dispatcher (viem resolves the
+ * overload from `args`). Overloads that mix read and write mutability throw at
+ * factory construction — a single dispatcher would silently misroute one side.
+ *
+ * @param abi - The precompile interface, as an `as const` ABI.
+ * @param defaultAddress - Where the precompile lives on a stock Maroo chain.
+ * @param options.mode - Emit only reads, only writes, or both.
+ * @param options.exclude - Function names to omit (codegen dummies, proxy hooks).
+ */
+export function precompileActions<
+  const abi extends Abi,
+  mode extends 'read' | 'write' | 'all' = 'all',
+>(
+  abi: abi,
+  defaultAddress: Address,
+  options: { mode?: mode; exclude?: readonly string[] } = {},
+): PrecompileActionsFactory<abi, mode> {
+  const { mode = 'all' as mode, exclude = [] } = options
+  const excluded = new Set<string>(exclude)
+
+  // Fail fast on mixed-mutability overloads, before any client exists.
+  const classification = new Map<string, boolean>()
+  const payableNames = new Set<string>()
+  for (const item of abi) {
+    if (item.type !== 'function' || excluded.has(item.name)) continue
+    const read = isRead(item.stateMutability)
+    const prev = classification.get(item.name)
+    if (prev !== undefined && prev !== read)
+      throw new Error(
+        `precompileActions: "${item.name}" has overloads with mixed read/write mutability; ` +
+          'add it to options.exclude and wrap it by hand',
+      )
+    classification.set(item.name, read)
+    if (item.stateMutability === 'payable') payableNames.add(item.name)
+  }
+
+  return (config = {}) =>
+    (client) => {
+      const actions: Record<string, unknown> = {}
+
+      for (const item of abi) {
+        if (item.type !== 'function') continue
+        if (excluded.has(item.name)) continue
+        if (actions[item.name]) continue // same-mutability overload: one dispatcher
+
+        const read = isRead(item.stateMutability)
+        if (mode === 'read' && !read) continue
+        if (mode === 'write' && read) continue
+
+        const functionName = item.name
+        // Any same-name overload being payable admits `value` (matches WriteExtra).
+        const payable = payableNames.has(functionName)
+
+        const resolveCall = (parameters: Record<string, unknown>) => {
+          // `value` is deliberately dropped here; only payable writes re-add it.
+          const { address, args, value: _value, ...rest } = parameters
+          return {
+            ...rest,
+            abi,
+            functionName,
+            args: (args as readonly unknown[] | undefined) ?? [],
+            address: (address as Address) ?? config.address ?? defaultAddress,
+          }
+        }
+
+        const fn = (parameters: Record<string, unknown> = {}) => {
+          const call = resolveCall(parameters)
+          if (read) return getAction(client, readContract, 'readContract')(call as never)
+          const value = payable ? (parameters.value as bigint | undefined) : undefined
+          return getAction(
+            client,
+            writeContract,
+            'writeContract',
+          )({ ...call, ...(value !== undefined ? { value } : {}) } as never)
+        }
+        // Reads also expose `.call` — a descriptor for multicall/simulate.
+        if (read)
+          (fn as { call?: unknown }).call = (parameters: Record<string, unknown> = {}) =>
+            resolveCall(parameters)
+
+        actions[functionName] = fn
+      }
+
+      return actions as PrecompileActions<abi, mode>
+    }
+}

package/src/decorators/maroo.ts

@@ -0,0 +1,114 @@
+import type { Abi, Account, Chain, Client, ContractFunctionName, Transport } from 'viem'
+import { type RunOnPclParameters, type RunOnPclReturnType, runOnPcl } from '../actions/runOnPcl.js'
+import {
+  type AgentReadActions,
+  type EasReadActions,
+  type OkrwReadActions,
+  type OkrwWriteActions,
+  type PclReadActions,
+  type PclWriteActions,
+  agentReadActions,
+  easReadActions,
+  okrwReadActions,
+  okrwWriteActions,
+  pclReadActions,
+  pclWriteActions,
+} from './precompiles.js'
+
+/**
+ * Namespaces are not stylistic here. All four precompiles expose a method
+ * named `getParams`, so a flat merge is impossible without renaming.
+ */
+
+// ─── public ──────────────────────────────────────────────────────────────────
+
+export type MarooPublicActions = {
+  pcl: PclReadActions
+  okrw: OkrwReadActions
+  eas: EasReadActions
+  agent: AgentReadActions
+}
+
+/**
+ * Read actions for every Maroo precompile.
+ *
+ * @example
+ * ```ts
+ * const client = createPublicClient({ chain: marooTestnet, transport: http() })
+ *   .extend(marooPublicActions())
+ *
+ * const { policyAdmin, entrypoints } = await client.pcl.getParams()
+ * const { policies } = await client.pcl.globalPolicies()
+ * const [ids, page] = await client.agent.getAgentIds({ args: [wallet, pageRequest] })
+ * ```
+ */
+export function marooPublicActions() {
+  return <transport extends Transport, chain extends Chain | undefined, account extends Account | undefined>(
+    client: Client<transport, chain, account>,
+  ): MarooPublicActions => ({
+    pcl: pclReadActions()(client),
+    okrw: okrwReadActions()(client),
+    eas: easReadActions()(client),
+    agent: agentReadActions()(client),
+  })
+}
+
+// ─── wallet ──────────────────────────────────────────────────────────────────
+
+/**
+ * Write actions, grouped by who may actually call them.
+ *
+ * Everything under `pcl` and `okrw` is reachable, but most of it reverts for
+ * ordinary accounts:
+ *
+ * - `pcl.runOnPcl`, `pcl.deployPclProxy`, `pcl.registerContractPolicies`
+ *   — callable by anyone.
+ * - `pcl.changeContractPolicies`, `pcl.removeContractPolicies`
+ *   — only that contract's admin, fixed at registration time.
+ * - `pcl.setGlobalPolicies`, `pcl.removeGlobalPolicies`,
+ *   `pcl.registerPolicyTemplate`, `pcl.removePolicyTemplate`
+ *   — only `PclParams.policyAdmin`, a chain parameter.
+ * - `okrw.mint` — only `OkrwParams.minter`, a chain parameter.
+ */
+export type MarooWalletActions<
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+> = {
+  pcl: PclWriteActions & {
+    /**
+     * Call a contract through PCL so its contract-scoped policies apply.
+     * A direct call enforces global policies only, silently.
+     */
+    runOnPcl: <
+      const abi extends Abi | readonly unknown[],
+      functionName extends ContractFunctionName<abi, 'nonpayable' | 'payable'>,
+    >(
+      parameters: RunOnPclParameters<abi, functionName>,
+    ) => Promise<RunOnPclReturnType>
+  }
+  okrw: OkrwWriteActions
+}
+
+/**
+ * @example
+ * ```ts
+ * const client = createWalletClient({ chain: marooTestnet, account, transport: http() })
+ *   .extend(marooWalletActions())
+ *
+ * const hash = await client.pcl.runOnPcl({
+ *   address: token, abi: erc20Abi, functionName: 'transfer', args: [to, amount],
+ * })
+ * ```
+ */
+export function marooWalletActions() {
+  return <transport extends Transport, chain extends Chain | undefined, account extends Account | undefined>(
+    client: Client<transport, chain, account>,
+  ): MarooWalletActions<chain, account> =>
+    ({
+      pcl: {
+        ...pclWriteActions()(client),
+        runOnPcl: (parameters: never) => runOnPcl(client, parameters),
+      },
+      okrw: okrwWriteActions()(client),
+    }) as MarooWalletActions<chain, account>
+}

package/src/decorators/precompiles.ts

@@ -0,0 +1,44 @@
+import { iAgentAbi } from '@maroo-chain/contracts/abi/precompiles/agent/IAgent'
+import { iEasAbi } from '@maroo-chain/contracts/abi/precompiles/eas/IEas'
+import { iOkrwAbi } from '@maroo-chain/contracts/abi/precompiles/okrw/IOkrw'
+import { iPclAbi } from '@maroo-chain/contracts/abi/precompiles/pcl/IPcl'
+import { type PrecompileActions, precompileActions } from '../core/precompileActions.js'
+import { excludedFunctions, precompileAddresses } from '../constants.js'
+
+/**
+ * Per-precompile decorators, generated from the shipped ABIs.
+ *
+ * `eas` and `agent` are view-only; `okrw` exposes exactly one write (`mint`,
+ * restricted to `OkrwParams.minter`). None of them need hand-written actions.
+ *
+ * Each type alias below is named and exported deliberately — see the note on
+ * {@link PrecompileActions}.
+ */
+
+// ─── read ────────────────────────────────────────────────────────────────────
+
+export type PclReadActions = PrecompileActions<typeof iPclAbi, 'read'>
+export const pclReadActions = precompileActions(iPclAbi, precompileAddresses.pcl, {
+  mode: 'read',
+  exclude: excludedFunctions.pcl,
+})
+
+export type OkrwReadActions = PrecompileActions<typeof iOkrwAbi, 'read'>
+export const okrwReadActions = precompileActions(iOkrwAbi, precompileAddresses.okrw, { mode: 'read' })
+
+export type EasReadActions = PrecompileActions<typeof iEasAbi, 'read'>
+export const easReadActions = precompileActions(iEasAbi, precompileAddresses.eas, { mode: 'read' })
+
+export type AgentReadActions = PrecompileActions<typeof iAgentAbi, 'read'>
+export const agentReadActions = precompileActions(iAgentAbi, precompileAddresses.agent, { mode: 'read' })
+
+// ─── write ───────────────────────────────────────────────────────────────────
+
+export type PclWriteActions = PrecompileActions<typeof iPclAbi, 'write'>
+export const pclWriteActions = precompileActions(iPclAbi, precompileAddresses.pcl, {
+  mode: 'write',
+  exclude: excludedFunctions.pcl,
+})
+
+export type OkrwWriteActions = PrecompileActions<typeof iOkrwAbi, 'write'>
+export const okrwWriteActions = precompileActions(iOkrwAbi, precompileAddresses.okrw, { mode: 'write' })

package/src/errors/pcl.ts

@@ -0,0 +1,137 @@
+import { iPclAbi } from '@maroo-chain/contracts/abi/precompiles/pcl/IPcl'
+import { BaseError, ContractFunctionRevertedError, type Hex, decodeErrorResult } from 'viem'
+
+/**
+ * A PCL policy rejection, decoded into something a dApp can act on.
+ *
+ * viem already decodes the custom error name and args from the revert data
+ * once it has the ABI. What it cannot do is tell you which of the 40 errors
+ * mean "a policy rejected this user" as opposed to "you passed bad input" or
+ * "you are not the admin" — nor turn `resetAt` into a `Date`.
+ */
+export type PclViolation =
+  | { kind: 'denylist'; sender: Hex }
+  | { kind: 'volume-below-min'; minLimit: bigint; value: bigint }
+  | { kind: 'volume-above-max'; maxLimit: bigint; value: bigint }
+  | { kind: 'periodic-volume'; maxLimit: bigint; value: bigint; resetAt: Date }
+  | { kind: 'non-eas-limit'; maxLimit: bigint; value: bigint }
+  | { kind: 'agent-transfer-limit'; maxLimit: bigint; value: bigint }
+  | {
+      kind: 'attestation'
+      reason: 'required' | 'none-received' | 'lookup-failed' | 'revoked' | 'expired'
+      sender: Hex
+    }
+  /** `AnyOfRejected` — every branch of a LOGICAL(Or) failed. Each child revert, decoded. */
+  | { kind: 'any-of-rejected'; children: (PclViolation | { kind: 'unknown'; name: string })[] }
+  | { kind: 'unauthorized' }
+  | { kind: 'unknown'; name: string; args: readonly unknown[] }
+
+/**
+ * The errors PCL actually declares. Used to refuse errors we do not own —
+ * `decodeErrorResult` also recognises the built-in `Error(string)` / `Panic`
+ * signatures, and those must decode to `null`, not to a policy verdict.
+ */
+const PCL_ERROR_NAMES: ReadonlySet<string> = new Set(
+  iPclAbi.flatMap((item) => (item.type === 'error' ? [item.name] : [])),
+)
+
+/**
+ * `AnyOfRejected` nests (a LOGICAL(Or) branch can itself be a LOGICAL(Or)),
+ * and revert bytes are attacker-controlled via `eth_call` — cap the recursion
+ * like the policy codec caps its tree depth. Past the cap, children surface
+ * as `undecodable` instead of overflowing the stack inside an error handler.
+ */
+const MAX_ERROR_DEPTH = 8
+
+type AttestationReason = Extract<PclViolation, { kind: 'attestation' }>['reason']
+
+const ATTESTATION: Record<string, AttestationReason> = {
+  EasAttestationRequired: 'required',
+  EasNoAttestationReceived: 'none-received',
+  EasAttestationLookupFailed: 'lookup-failed',
+  EasAttestationRevoked: 'revoked',
+  EasAttestationExpired: 'expired',
+}
+
+function toViolation(name: string, args: readonly unknown[], depth: number): PclViolation {
+  const a = args as never[]
+  switch (name) {
+    case 'InDenylist':
+      return { kind: 'denylist', sender: a[0] }
+    case 'VolumeBelowMinLimit':
+      return { kind: 'volume-below-min', minLimit: a[0], value: a[1] }
+    case 'VolumeAboveMaxLimit':
+      return { kind: 'volume-above-max', maxLimit: a[0], value: a[1] }
+    case 'ExceededPeriodicVolume':
+      return {
+        kind: 'periodic-volume',
+        maxLimit: a[0],
+        value: a[1],
+        resetAt: new Date(Number(a[2] as bigint) * 1000),
+      }
+    case 'ReachedLimitOfNonEAS':
+      return { kind: 'non-eas-limit', maxLimit: a[0], value: a[1] }
+    case 'ExceededAgentTransferLimit':
+      return { kind: 'agent-transfer-limit', maxLimit: a[0], value: a[1] }
+    case 'Unauthorized':
+      return { kind: 'unauthorized' }
+    case 'AnyOfRejected':
+      return {
+        kind: 'any-of-rejected',
+        children: ((a[0] as Hex[]) ?? []).map(
+          (child) => decode(child, depth + 1) ?? { kind: 'unknown', name: 'undecodable' },
+        ),
+      }
+    default:
+      if (name in ATTESTATION) return { kind: 'attestation', reason: ATTESTATION[name], sender: a[0] }
+      return { kind: 'unknown', name, args }
+  }
+}
+
+function decode(source: Hex | unknown, depth: number): PclViolation | null {
+  if (depth > MAX_ERROR_DEPTH) return null
+
+  let data: Hex | undefined
+
+  if (typeof source === 'string' && source.startsWith('0x')) {
+    data = source as Hex
+  } else if (source instanceof BaseError) {
+    const revert = source.walk((e) => e instanceof ContractFunctionRevertedError)
+    // Always decode from the raw revert bytes, never from viem's pre-decoded
+    // errorName: viem decoded against the *call's* ABI, and other precompiles
+    // declare errors sharing a PCL error's name with a different signature
+    // (okrw: InvalidAddress(address), agent: InvalidAddress(string,uint256,string),
+    // pcl: InvalidAddress(string)). Only the 4-byte selector — which
+    // decodeErrorResult matches below — tells them apart.
+    if (revert instanceof ContractFunctionRevertedError) data = revert.raw
+  }
+
+  if (!data || data === '0x') return null
+  try {
+    const { errorName, args } = decodeErrorResult({ abi: iPclAbi, data })
+    if (!PCL_ERROR_NAMES.has(errorName)) return null
+    return toViolation(errorName, args ?? [], depth)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Decode PCL revert data — or a thrown viem error wrapping it — into a
+ * {@link PclViolation}. Returns `null` if the revert is not a PCL error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.pcl.runOnPcl({ ... })
+ * } catch (err) {
+ *   const v = decodePclError(err)
+ *   if (v?.kind === 'periodic-volume')
+ *     throw new Error(`24h limit hit. Resets ${v.resetAt.toISOString()}`)
+ *   throw err
+ * }
+ * ```
+ */
+export function decodePclError(source: Hex | unknown): PclViolation | null {
+  return decode(source, 0)
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+// biome-ignore lint/performance/noBarrelFile: entrypoint module
+
+export { precompileAddresses, easContracts, SELECTOR_ALL, NO_MAX_LIMIT } from './constants.js'
+
+export {
+  type PrecompileActions,
+  type PrecompileCallOptions,
+  type PrecompileReadActions,
+  type PrecompileReadCall,
+  type PrecompileWriteActions,
+  precompileActions,
+} from './core/precompileActions.js'
+
+export {
+  type MarooPublicActions,
+  type MarooWalletActions,
+  marooPublicActions,
+  marooWalletActions,
+} from './decorators/maroo.js'
+
+export {
+  type AgentReadActions,
+  type EasReadActions,
+  type OkrwReadActions,
+  type OkrwWriteActions,
+  type PclReadActions,
+  type PclWriteActions,
+  agentReadActions,
+  easReadActions,
+  okrwReadActions,
+  okrwWriteActions,
+  pclReadActions,
+  pclWriteActions,
+} from './decorators/precompiles.js'
+
+export { type RunOnPclParameters, type RunOnPclReturnType, runOnPcl } from './actions/runOnPcl.js'
+
+export {
+  type DecodedPolicy,
+  type PolicyInput,
+  type PolicyTemplateId,
+  type RawPolicySet,
+  ForEachQuantifier,
+  ForEachSubject,
+  LogicalQuantifier,
+  decodePolicySet,
+  encodePolicy,
+  normalizeSelector,
+  policyCodecs,
+  policyTemplateIds,
+} from './codec/policy.js'
+
+export { type PclViolation, decodePclError } from './errors/pcl.js'
+
+// `marooTestnet` is deliberately NOT re-exported here: it ships in viem only
+// from 2.55+, and re-exporting it would crash this whole package at import
+// time for consumers on older viem within our ^2.44.0 peer range. Import it
+// from 'viem/chains' directly.