maroo-viem-poc 0.1.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "maroo-viem-poc",
+  "version": "0.1.0",
+  "description": "PoC viem extension for the Maroo chain — namespaced precompile actions (pcl/okrw/eas/agent), PCL policy codec, runOnPcl wrapper, and typed policy-violation decoding. Verified against live marooTestnet.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "maroo",
+    "viem",
+    "precompile",
+    "pcl",
+    "cosmos-evm",
+    "poc"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "dependencies": {
+    "@maroo-chain/contracts": "0.0.6",
+    "abitype": "^1.0.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.44.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsdown": "^0.21.0",
+    "typescript": "^5.7.0",
+    "viem": "^2.44.0",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run test/unit",
+    "test:live": "vitest run test/live"
+  }
+}

package/src/actions/runOnPcl.ts

@@ -0,0 +1,117 @@
+import { iPclAbi } from '@maroo-chain/contracts/abi/precompiles/pcl/IPcl'
+import {
+  type Abi,
+  type Account,
+  type Address,
+  type Chain,
+  type Client,
+  type ContractFunctionArgs,
+  type ContractFunctionName,
+  type Hex,
+  type Transport,
+  type WriteContractReturnType,
+  encodeFunctionData,
+} from 'viem'
+import { writeContract } from 'viem/actions'
+import { getAction } from 'viem/utils'
+import { precompileAddresses } from '../constants.js'
+
+type RunOnPclBase = {
+  /** The contract — or plain account — to call *through* PCL. */
+  address: Address
+  /** Native value forwarded to `address`. Debited from the caller, not from `msg.value`. */
+  value?: bigint | undefined
+  gas?: bigint | undefined
+  /** Override the PCL precompile address. */
+  pclAddress?: Address | undefined
+}
+
+type RunOnPclContractCall<
+  abi extends Abi | readonly unknown[],
+  functionName extends ContractFunctionName<abi, 'nonpayable' | 'payable'>,
+> = RunOnPclBase & {
+  abi: abi
+  functionName: functionName
+  args?: ContractFunctionArgs<abi, 'nonpayable' | 'payable', functionName>
+  data?: undefined
+}
+
+/** A bare value transfer, or a call whose calldata you already encoded. */
+type RunOnPclRawCall = RunOnPclBase & {
+  abi?: undefined
+  functionName?: undefined
+  args?: undefined
+  data?: Hex | undefined
+}
+
+export type RunOnPclParameters<
+  abi extends Abi | readonly unknown[] = Abi,
+  functionName extends ContractFunctionName<abi, 'nonpayable' | 'payable'> = ContractFunctionName<
+    abi,
+    'nonpayable' | 'payable'
+  >,
+> = RunOnPclContractCall<abi, functionName> | RunOnPclRawCall
+
+export type RunOnPclReturnType = WriteContractReturnType
+
+/**
+ * Call a contract *through* the PCL precompile so that contract-scoped
+ * policies are enforced.
+ *
+ * A direct call to the same contract enforces **global policies only**. There
+ * is nothing in the target contract's ABI, nor in any revert, that signals
+ * this — the call simply succeeds with contract policies unapplied. Route
+ * through `runOnPcl` whenever the target has policies registered.
+ *
+ * For a contract call the parameter shape mirrors `writeContract`, so
+ * switching a call site is a one-word change. Omit `abi`/`functionName` to
+ * forward a bare native transfer, or pass pre-encoded `data`.
+ *
+ * @example
+ * ```ts
+ * const hash = await client.pcl.runOnPcl({
+ *   address: token,
+ *   abi: erc20Abi,
+ *   functionName: 'transfer',
+ *   args: [recipient, amount],
+ * })
+ *
+ * // Native transfer, policy-checked:
+ * const hash = await client.pcl.runOnPcl({ address: recipient, value: parseEther('1') })
+ * ```
+ */
+export async function runOnPcl<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  const abi extends Abi | readonly unknown[],
+  functionName extends ContractFunctionName<abi, 'nonpayable' | 'payable'>,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: RunOnPclParameters<abi, functionName>,
+): Promise<RunOnPclReturnType> {
+  const { address, value = 0n, gas, pclAddress } = parameters
+
+  const data: Hex = parameters.abi
+    ? (encodeFunctionData({
+        abi: parameters.abi,
+        functionName: parameters.functionName,
+        args: parameters.args,
+      } as never) as Hex)
+    : (parameters.data ?? '0x')
+
+  return getAction(
+    client,
+    writeContract,
+    'writeContract',
+  )({
+    address: pclAddress ?? precompileAddresses.pcl,
+    abi: iPclAbi,
+    functionName: 'runOnPcl',
+    args: [address, data, value],
+    // `value` rides on the argument, never on the outer tx. The precompile
+    // issues `evm.Call(caller, target, data, gas, value)`, which debits the
+    // original caller directly. Attaching `msg.value` here would strand funds
+    // at the precompile.
+    gas,
+  } as never)
+}

package/src/codec/policy.ts

@@ -0,0 +1,381 @@
+import type { AbiParametersToPrimitiveTypes } from 'abitype'
+import { type Hex, decodeAbiParameters, encodeAbiParameters } from 'viem'
+
+/**
+ * PCL policy codec.
+ *
+ * `PolicySet.policy` is an opaque `bytes` field whose layout is chosen by the
+ * sibling `templateId` string. That mapping exists nowhere in the ABI — the
+ * `_policies` dummy function only forces the structs into the artifact. This
+ * module is the mapping.
+ *
+ * Verified against `marooTestnet.globalPolicies()` at block 12447862.
+ */
+
+// ─── Template ids ────────────────────────────────────────────────────────────
+// Confirmed live: every id below returns a registered template from
+// `pcl.policyTemplate(id)` on marooTestnet. Note FOR_EACH_POLICY, not
+// FOREACH_POLICY — the underscore is load-bearing.
+
+export const policyTemplateIds = [
+  'EAS_POLICY',
+  'DENYLIST_POLICY',
+  'VOLUME_POLICY',
+  'OKRW_EAS_TRANSFER_LIMIT_POLICY',
+  'PERIODIC_VOLUME_POLICY',
+  'AGENT_OKRW_TRANSFER_LIMIT_POLICY',
+  'OKRW_EAS_PERIODIC_VOLUME_LIMIT_POLICY',
+  'LOGICAL_POLICY',
+  'FOR_EACH_POLICY',
+] as const
+
+export type PolicyTemplateId = (typeof policyTemplateIds)[number]
+
+// ─── Enums (IPcl.sol) ────────────────────────────────────────────────────────
+
+export const LogicalQuantifier = { Unspecified: 0, And: 1, Or: 2 } as const
+export const ForEachQuantifier = { Unspecified: 0, Any: 1, Every: 2 } as const
+export const ForEachSubject = { Unspecified: 0, AgentOwners: 1 } as const
+
+export type LogicalQuantifierName = keyof typeof LogicalQuantifier
+export type ForEachQuantifierName = keyof typeof ForEachQuantifier
+export type ForEachSubjectName = keyof typeof ForEachSubject
+
+const nameOf = <T extends Record<string, number>>(e: T, v: number): keyof T =>
+  (Object.keys(e) as (keyof T)[]).find((k) => e[k] === v) ?? ('Unspecified' as keyof T)
+
+// ─── ABI parameter shapes ────────────────────────────────────────────────────
+//
+// Plain `as const` literals — no helper. A helper that takes `(name: string,
+// type: string)` widens the literals before `as const` can pin them, which
+// erases the type `decodeAbiParameters` needs to infer a tuple. Written out,
+// abitype infers each payload's shape and the decode path below is cast-free.
+// (`parseAbiParameters` is not an option: it rejects the nested tuples that
+// LOGICAL_POLICY and FOR_EACH_POLICY require.)
+
+const POLICY_SET_COMPONENTS = [
+  { name: 'templateId', type: 'string' },
+  { name: 'policy', type: 'bytes' },
+  { name: 'selector', type: 'bytes' },
+] as const
+
+/**
+ * `templateId` → the ABI parameters of its `policy` bytes payload.
+ *
+ * Each entry is a one-element parameter list wrapping the payload tuple, so
+ * `decodeAbiParameters(codec, bytes)[0]` is the decoded struct.
+ */
+export const policyCodecs = {
+  EAS_POLICY: [
+    {
+      name: 'policy',
+      type: 'tuple',
+      components: [
+        { name: 'easContract', type: 'address' },
+        { name: 'indexContract', type: 'address' },
+        { name: 'schemaUid', type: 'bytes32' },
+      ],
+    },
+  ],
+  DENYLIST_POLICY: [
+    { name: 'policy', type: 'tuple', components: [{ name: 'addresses', type: 'address[]' }] },
+  ],
+  VOLUME_POLICY: [
+    {
+      name: 'policy',
+      type: 'tuple',
+      components: [
+        { name: 'tokens', type: 'string[]' },
+        {
+          name: 'limits',
+          type: 'tuple[]',
+          components: [
+            { name: 'minLimit', type: 'uint256' },
+            { name: 'maxLimit', type: 'uint256' },
+          ],
+        },
+      ],
+    },
+  ],
+  PERIODIC_VOLUME_POLICY: [
+    {
+      name: 'policy',
+      type: 'tuple',
+      components: [
+        { name: 'tokens', type: 'string[]' },
+        {
+          name: 'limits',
+          type: 'tuple[]',
+          components: [
+            { name: 'maxAmount', type: 'uint256' },
+            { name: 'resetPeriodSeconds', type: 'uint64' },
+          ],
+        },
+      ],
+    },
+  ],
+  OKRW_EAS_TRANSFER_LIMIT_POLICY: [
+    {
+      name: 'policy',
+      type: 'tuple',
+      components: [
+        { name: 'easContract', type: 'address' },
+        { name: 'indexContract', type: 'address' },
+        { name: 'schemaUid', type: 'bytes32' },
+        { name: 'transferLimitAmount', type: 'uint256' },
+      ],
+    },
+  ],
+  OKRW_EAS_PERIODIC_VOLUME_LIMIT_POLICY: [
+    {
+      name: 'policy',
+      type: 'tuple',
+      components: [
+        { name: 'easContract', type: 'address' },
+        { name: 'indexContract', type: 'address' },
+        { name: 'schemaUid', type: 'bytes32' },
+        { name: 'maxAmount', type: 'uint256' },
+        { name: 'resetPeriodSeconds', type: 'uint64' },
+      ],
+    },
+  ],
+  AGENT_OKRW_TRANSFER_LIMIT_POLICY: [
+    { name: 'policy', type: 'tuple', components: [{ name: 'reserved', type: 'uint256' }] },
+  ],
+  LOGICAL_POLICY: [
+    {
+      name: 'policy',
+      type: 'tuple',
+      components: [
+        { name: 'quantifier', type: 'uint8' },
+        { name: 'children', type: 'tuple[]', components: POLICY_SET_COMPONENTS },
+      ],
+    },
+  ],
+  FOR_EACH_POLICY: [
+    {
+      name: 'policy',
+      type: 'tuple',
+      components: [
+        { name: 'quantifier', type: 'uint8' },
+        { name: 'subject', type: 'uint8' },
+        { name: 'child', type: 'tuple', components: POLICY_SET_COMPONENTS },
+      ],
+    },
+  ],
+} as const
+
+/** The input struct expected by {@link encodePolicy} for a given template. */
+export type PolicyInput<id extends PolicyTemplateId> = AbiParametersToPrimitiveTypes<
+  (typeof policyCodecs)[id]
+>[0]
+
+// ─── Wire type ───────────────────────────────────────────────────────────────
+
+/** A `PolicySet` exactly as the precompile returns it. */
+export type RawPolicySet = {
+  templateId: string
+  policy: Hex
+  selector: Hex
+}
+
+// ─── Decoded tree ────────────────────────────────────────────────────────────
+
+export type DecodedPolicy =
+  | { templateId: 'EAS_POLICY'; selector: Hex; easContract: Hex; indexContract: Hex; schemaUid: Hex }
+  | { templateId: 'DENYLIST_POLICY'; selector: Hex; addresses: readonly Hex[] }
+  | {
+      templateId: 'VOLUME_POLICY'
+      selector: Hex
+      limits: readonly { token: string; minLimit: bigint; maxLimit: bigint }[]
+    }
+  | {
+      templateId: 'PERIODIC_VOLUME_POLICY'
+      selector: Hex
+      limits: readonly { token: string; maxAmount: bigint; resetPeriodSeconds: bigint }[]
+    }
+  | {
+      templateId: 'OKRW_EAS_TRANSFER_LIMIT_POLICY'
+      selector: Hex
+      easContract: Hex
+      indexContract: Hex
+      schemaUid: Hex
+      transferLimitAmount: bigint
+    }
+  | {
+      templateId: 'OKRW_EAS_PERIODIC_VOLUME_LIMIT_POLICY'
+      selector: Hex
+      easContract: Hex
+      indexContract: Hex
+      schemaUid: Hex
+      maxAmount: bigint
+      resetPeriodSeconds: bigint
+    }
+  /** The `reserved` field is ignored by the chain, so it is not surfaced. */
+  | { templateId: 'AGENT_OKRW_TRANSFER_LIMIT_POLICY'; selector: Hex }
+  | { templateId: 'LOGICAL_POLICY'; selector: Hex; quantifier: LogicalQuantifierName; children: DecodedPolicy[] }
+  | {
+      templateId: 'FOR_EACH_POLICY'
+      selector: Hex
+      quantifier: ForEachQuantifierName
+      subject: ForEachSubjectName
+      child: DecodedPolicy
+    }
+  /** Any template this SDK version does not model yet. Never throws. */
+  | { templateId: string; selector: Hex; raw: Hex; unknown: true }
+
+const MAX_DEPTH = 8
+
+const isKnown = (id: string): id is PolicyTemplateId =>
+  Object.prototype.hasOwnProperty.call(policyCodecs, id)
+
+/**
+ * Recursively decode a `PolicySet` returned by `globalPolicies()` or
+ * `contractPolicies()` into a readable tree.
+ *
+ * Unrecognised template ids decode to `{ unknown: true, raw }` rather than
+ * throwing, so a chain upgrade that adds a policy type degrades a dApp's
+ * policy inspector instead of breaking it.
+ */
+export function decodePolicySet(set: RawPolicySet, depth = 0): DecodedPolicy {
+  if (depth > MAX_DEPTH) throw new Error(`policy nesting exceeded depth ${MAX_DEPTH}`)
+
+  const { selector } = set
+  if (!isKnown(set.templateId))
+    return { templateId: set.templateId, selector, raw: set.policy, unknown: true }
+
+  // Each branch indexes its codec by literal key, so `decodeAbiParameters`
+  // infers the exact payload tuple — no casts.
+  switch (set.templateId) {
+    case 'EAS_POLICY': {
+      const [p] = decodeAbiParameters(policyCodecs.EAS_POLICY, set.policy)
+      return {
+        templateId: 'EAS_POLICY',
+        selector,
+        easContract: p.easContract,
+        indexContract: p.indexContract,
+        schemaUid: p.schemaUid,
+      }
+    }
+    case 'DENYLIST_POLICY': {
+      const [p] = decodeAbiParameters(policyCodecs.DENYLIST_POLICY, set.policy)
+      return { templateId: 'DENYLIST_POLICY', selector, addresses: p.addresses }
+    }
+    case 'VOLUME_POLICY': {
+      const [p] = decodeAbiParameters(policyCodecs.VOLUME_POLICY, set.policy)
+      // tokens[i] pairs with limits[i], but the ABI does not tie the array
+      // lengths — a mis-encoded policy must degrade to raw, not throw.
+      if (p.tokens.length !== p.limits.length)
+        return { templateId: set.templateId, selector, raw: set.policy, unknown: true }
+      return {
+        templateId: 'VOLUME_POLICY',
+        selector,
+        limits: p.tokens.map((token, i) => ({
+          token,
+          minLimit: p.limits[i].minLimit,
+          maxLimit: p.limits[i].maxLimit,
+        })),
+      }
+    }
+    case 'PERIODIC_VOLUME_POLICY': {
+      const [p] = decodeAbiParameters(policyCodecs.PERIODIC_VOLUME_POLICY, set.policy)
+      if (p.tokens.length !== p.limits.length)
+        return { templateId: set.templateId, selector, raw: set.policy, unknown: true }
+      return {
+        templateId: 'PERIODIC_VOLUME_POLICY',
+        selector,
+        limits: p.tokens.map((token, i) => ({
+          token,
+          maxAmount: p.limits[i].maxAmount,
+          resetPeriodSeconds: p.limits[i].resetPeriodSeconds,
+        })),
+      }
+    }
+    case 'OKRW_EAS_TRANSFER_LIMIT_POLICY': {
+      const [p] = decodeAbiParameters(policyCodecs.OKRW_EAS_TRANSFER_LIMIT_POLICY, set.policy)
+      return {
+        templateId: 'OKRW_EAS_TRANSFER_LIMIT_POLICY',
+        selector,
+        easContract: p.easContract,
+        indexContract: p.indexContract,
+        schemaUid: p.schemaUid,
+        transferLimitAmount: p.transferLimitAmount,
+      }
+    }
+    case 'OKRW_EAS_PERIODIC_VOLUME_LIMIT_POLICY': {
+      const [p] = decodeAbiParameters(policyCodecs.OKRW_EAS_PERIODIC_VOLUME_LIMIT_POLICY, set.policy)
+      return {
+        templateId: 'OKRW_EAS_PERIODIC_VOLUME_LIMIT_POLICY',
+        selector,
+        easContract: p.easContract,
+        indexContract: p.indexContract,
+        schemaUid: p.schemaUid,
+        maxAmount: p.maxAmount,
+        resetPeriodSeconds: p.resetPeriodSeconds,
+      }
+    }
+    case 'AGENT_OKRW_TRANSFER_LIMIT_POLICY': {
+      // Decode to validate the payload layout; `reserved` itself is ignored
+      // by the chain and not surfaced.
+      decodeAbiParameters(policyCodecs.AGENT_OKRW_TRANSFER_LIMIT_POLICY, set.policy)
+      return { templateId: 'AGENT_OKRW_TRANSFER_LIMIT_POLICY', selector }
+    }
+    case 'LOGICAL_POLICY': {
+      const [p] = decodeAbiParameters(policyCodecs.LOGICAL_POLICY, set.policy)
+      return {
+        templateId: 'LOGICAL_POLICY',
+        selector,
+        quantifier: nameOf(LogicalQuantifier, p.quantifier),
+        children: p.children.map((c) => decodePolicySet(c, depth + 1)),
+      }
+    }
+    case 'FOR_EACH_POLICY': {
+      const [p] = decodeAbiParameters(policyCodecs.FOR_EACH_POLICY, set.policy)
+      return {
+        templateId: 'FOR_EACH_POLICY',
+        selector,
+        quantifier: nameOf(ForEachQuantifier, p.quantifier),
+        subject: nameOf(ForEachSubject, p.subject),
+        child: decodePolicySet(p.child, depth + 1),
+      }
+    }
+    // Unreachable while the switch covers every id in `policyCodecs`; kept so
+    // a codec added without a decode branch degrades instead of crashing.
+    default:
+      return { templateId: set.templateId, selector, raw: set.policy, unknown: true }
+  }
+}
+
+/**
+ * ABI-encode a policy payload for its template.
+ *
+ * The `policy` argument is typed per `templateId` via {@link PolicyInput}, so
+ * the public signature is fully checked. The single internal cast is the
+ * unavoidable one: indexing `policyCodecs` by a generic `id` yields a union
+ * that `encodeAbiParameters` cannot unify positionally (viem does the same at
+ * this boundary).
+ *
+ * Admin-facing: only `policyAdmin` may set global policies, and only a
+ * contract's registered admin may change its contract policies.
+ */
+export function encodePolicy<id extends PolicyTemplateId>(templateId: id, policy: PolicyInput<id>): Hex {
+  const codec = policyCodecs[templateId]
+  return encodeAbiParameters(codec, [policy] as never)
+}
+
+/**
+ * Normalize a function selector for a `PolicySet`.
+ *
+ * The chain accepts either an empty value (wildcard, stored internally as
+ * `"__all__"`) or exactly 4 bytes, lowercased. Anything else is rejected with
+ * `InvalidSelector`.
+ */
+export function normalizeSelector(selector?: Hex | undefined): Hex {
+  if (!selector || selector === '0x') return '0x'
+  const body = selector.slice(2).toLowerCase()
+  // Length alone is not enough: a non-hex body would pass here and only be
+  // rejected chain-side with an opaque InvalidSelector after gas was spent.
+  if (!/^[0-9a-f]{8}$/.test(body))
+    throw new Error(`selector must be 4 bytes of hex (8 hex chars), got "${selector}"`)
+  return `0x${body}`
+}

package/src/constants.ts

@@ -0,0 +1,57 @@
+import { type Address, maxUint256 } from 'viem'
+
+/**
+ * Maroo static precompile addresses.
+ *
+ * Mirrors the `*_PRECOMPILED_ADDRESS` constants in
+ * `@maroo-chain/contracts/precompiles/{okrw,pcl,eas,agent}/I*.sol`.
+ *
+ * The contracts package does not export these from its TypeScript build
+ * (only the `.sol` sources carry them), so we redeclare them here.
+ * `test/addresses.test.ts` asserts these still match the installed package.
+ */
+export const precompileAddresses = {
+  okrw: '0x1000000000000000000000000000000000000001',
+  pcl: '0x1000000000000000000000000000000000000005',
+  /** Returns `eas` module params. Not the EAS contract itself — see {@link easContracts}. */
+  eas: '0x1000000000000000000000000000000000000009',
+  agent: '0x100000000000000000000000000000000000000A',
+  /** Clairveil shielded pool. Not yet deployed on marooTestnet. */
+  privacy: '0x100000000000000000000000000000000000000b',
+} as const satisfies Record<string, Address>
+
+/**
+ * EAS contracts, as reported by `eas.getParams()` on marooTestnet.
+ *
+ * These sit at precompile-shaped addresses but implement the standard
+ * Ethereum Attestation Service interfaces. `@maroo-chain/contracts@0.0.6`
+ * ships no ABI for them; use `@ethereum-attestation-service/eas-contracts`.
+ *
+ * Do not hardcode these in application code — read them from
+ * `client.eas.getParams()`, which is authoritative per network.
+ */
+export const easContracts = {
+  schemaRegistry: '0x1000000000000000000000000000000000000006',
+  eas: '0x1000000000000000000000000000000000000007',
+  indexer: '0x1000000000000000000000000000000000000008',
+} as const satisfies Record<string, Address>
+
+/**
+ * ABI entries that exist for chain-side codegen or proxy plumbing and must
+ * never be surfaced as client actions.
+ *
+ * - `_policies` is a `pure` no-op declared solely so the Solidity compiler
+ *   emits the policy structs into the ABI (see the comment at the bottom of
+ *   `IPcl.sol`). Calling it does nothing.
+ * - `preCall`/`postCall` are invoked by the PCL proxy hook with a `principal`
+ *   the caller cannot forge. Application code goes through {@link runOnPcl}.
+ */
+export const excludedFunctions = {
+  pcl: ['_policies', 'preCall', 'postCall'],
+} as const
+
+/** The selector wildcard. An empty `selector` matches every function. */
+export const SELECTOR_ALL = '0x' as const
+
+/** `VolumeUnitPolicy.maxLimit` sentinel meaning "no upper bound". */
+export const NO_MAX_LIMIT = maxUint256