@crediolabs/policy-synth 0.1.10 → 0.1.12

package/src/predicate/decode.ts

@@ -0,0 +1,242 @@
+// src/predicate/decode.ts - the inverse of `encode.ts`.
+//
+// Turns the canonical wire encoding back into a `PredicateNode`, so a policy
+// already installed on chain can be read and explained. The interpreter has no
+// getter for the document, but its persistent storage IS readable over RPC, so
+// the bytes are available to any caller that can reconstruct the storage key -
+// this module takes it from there.
+//
+// Mirrors `decode_leaf` / `decode_node` in
+// `packages/policy-interpreter/src/dsl.rs`. Two rules carry most of the
+// weight, and both come from the Rust decoder verbatim:
+//
+//   1. A `Vec` whose FIRST element is a Symbol is a selector tuple. A `Vec`
+//      whose first element is anything else is a `literal_vec`, decoded
+//      element-wise with order preserved (the order IS the semantic for exact
+//      sequence equality).
+//   2. An unknown symbol at a selector position is MALFORMED, never a
+//      literal_vec fallback. Guessing there would let an unsupported selector
+//      decode as data and read as permitted.
+//
+// The round-trip `decode(encode(node)) === node` is pinned in decode.test.ts
+// for every leaf and node shape; that test is what keeps this file honest as
+// the grammar grows.
+
+import { Address, scValToBigInt, xdr } from '@stellar/stellar-sdk'
+import type { ToolError } from '../errors.ts'
+import type { PredicateLeaf, PredicateNode } from '../types.ts'
+
+/** Same shape the encoder raises, so both directions surface one error type.
+ *  Returns `never` - it always throws; callers `throw malformed(...)` purely
+ *  so the control flow reads at the call site. */
+function malformed(detail: string): never {
+  const err = new Error(`cannot decode predicate: ${detail}`) as Error & {
+    code: ToolError['code']
+    severity: string
+    retryable: boolean
+  }
+  err.code = 'MALFORMED_PREDICATE'
+  err.severity = 'error'
+  err.retryable = false
+  throw err
+}
+
+/** The symbol at a leaf's selector position, or null when the value is not a
+ *  symbol-headed vec (i.e. it is a literal or a literal vector). */
+function selectorSymbol(items: xdr.ScVal[]): string | null {
+  const head = items[0]
+  if (!head) return null
+  return head.switch() === xdr.ScValType.scvSymbol() ? head.sym().toString() : null
+}
+
+function expectVec(v: xdr.ScVal, what: string): xdr.ScVal[] {
+  if (v.switch() !== xdr.ScValType.scvVec()) throw malformed(`${what} is not a vec`)
+  return v.vec() ?? []
+}
+
+function expectU32(v: xdr.ScVal | undefined, what: string): number {
+  if (!v || v.switch() !== xdr.ScValType.scvU32()) throw malformed(`${what} is not a u32`)
+  return v.u32()
+}
+
+function expectSymbol(v: xdr.ScVal | undefined, what: string): string {
+  if (!v || v.switch() !== xdr.ScValType.scvSymbol()) throw malformed(`${what} is not a symbol`)
+  return v.sym().toString()
+}
+
+function expectAddress(v: xdr.ScVal | undefined, what: string): string {
+  if (!v || v.switch() !== xdr.ScValType.scvAddress()) throw malformed(`${what} is not an address`)
+  return Address.fromScAddress(v.address()).toString()
+}
+
+function expectU64(v: xdr.ScVal | undefined, what: string): string {
+  if (!v || v.switch() !== xdr.ScValType.scvU64()) throw malformed(`${what} is not a u64`)
+  return v.u64().toString()
+}
+
+function expectI128(v: xdr.ScVal | undefined, what: string): string {
+  if (!v || v.switch() !== xdr.ScValType.scvI128()) throw malformed(`${what} is not an i128`)
+  return scValToBigInt(v).toString()
+}
+
+/** Arity check with the same intent as the Rust `check_arity`: a selector with
+ *  the wrong element count is malformed, not silently truncated. */
+function arity(items: xdr.ScVal[], n: number, selector: string): void {
+  if (items.length !== n) {
+    throw malformed(`${selector} expects ${n} elements, got ${items.length}`)
+  }
+}
+
+function decodeSelectorLeaf(items: xdr.ScVal[], sym: string): PredicateLeaf {
+  switch (sym) {
+    case 'call_contract':
+      arity(items, 1, sym)
+      return { kind: 'call_contract' }
+    case 'call_fn':
+      arity(items, 1, sym)
+      return { kind: 'call_fn' }
+    case 'call_arg':
+      arity(items, 2, sym)
+      return { kind: 'call_arg', index: expectU32(items[1], 'call_arg index') }
+    case 'call_arg_len':
+      arity(items, 2, sym)
+      return { kind: 'call_arg_len', index: expectU32(items[1], 'call_arg_len index') }
+    case 'call_arg_field':
+      arity(items, 4, sym)
+      return {
+        kind: 'call_arg_field',
+        index: expectU32(items[1], 'call_arg_field index'),
+        element: expectU32(items[2], 'call_arg_field element'),
+        field: expectSymbol(items[3], 'call_arg_field field'),
+      }
+    case 'call_arg_scaled':
+      arity(items, 4, sym)
+      return {
+        kind: 'call_arg_scaled',
+        index: expectU32(items[1], 'call_arg_scaled index'),
+        num: expectI128(items[2], 'call_arg_scaled num'),
+        den: expectI128(items[3], 'call_arg_scaled den'),
+      }
+    case 'amount':
+      arity(items, 2, sym)
+      return { kind: 'amount', token: expectAddress(items[1], 'amount token') }
+    case 'window_spent':
+      arity(items, 3, sym)
+      return {
+        kind: 'window_spent',
+        token: expectAddress(items[1], 'window_spent token'),
+        windowSeconds: Number(expectU64(items[2], 'window_spent windowSeconds')),
+      }
+    case 'now':
+      arity(items, 1, sym)
+      return { kind: 'now' }
+    case 'valid_until':
+      // The encoder refuses to emit this and the interpreter refuses it at
+      // install, so it cannot appear in a document that installed. Decoding it
+      // anyway would present a rule the chain would never have accepted.
+      throw malformed('valid_until is not a usable predicate leaf')
+    case 'invocation_count':
+      arity(items, 2, sym)
+      return {
+        kind: 'invocation_count_in_window',
+        windowSecs: Number(expectU64(items[1], 'invocation_count windowSecs')),
+      }
+    case 'oracle_price':
+      arity(items, 2, sym)
+      return { kind: 'oracle_price', asset: expectAddress(items[1], 'oracle_price asset') }
+    case 'oracle_threshold':
+      arity(items, 3, sym)
+      return {
+        kind: 'oracle_threshold',
+        value: expectI128(items[1], 'oracle_threshold value'),
+        decimals: expectU32(items[2], 'oracle_threshold decimals'),
+      }
+    default:
+      // Deliberately NOT a literal_vec fallback - see the header note.
+      throw malformed(`unknown selector symbol '${sym}'`)
+  }
+}
+
+/** One leaf. Order of the bare-literal checks mirrors `decode_leaf` in dsl.rs. */
+export function decodeLeaf(v: xdr.ScVal): PredicateLeaf {
+  if (v.switch() === xdr.ScValType.scvVec()) {
+    const items = v.vec() ?? []
+    if (items.length === 0) throw malformed('empty vec is neither a selector nor a literal vector')
+    const sym = selectorSymbol(items)
+    if (sym !== null) return decodeSelectorLeaf(items, sym)
+    return { kind: 'literal_vec', elements: items.map(decodeLeaf) }
+  }
+  switch (v.switch()) {
+    case xdr.ScValType.scvAddress():
+      return { kind: 'literal_address', value: Address.fromScAddress(v.address()).toString() }
+    case xdr.ScValType.scvSymbol():
+      return { kind: 'literal_symbol', value: v.sym().toString() }
+    case xdr.ScValType.scvU32():
+      return { kind: 'literal_u32', value: v.u32() }
+    case xdr.ScValType.scvU64():
+      return { kind: 'literal_u64', value: v.u64().toString() }
+    case xdr.ScValType.scvI128():
+      return { kind: 'literal_i128', value: scValToBigInt(v).toString() }
+    case xdr.ScValType.scvBytes():
+      return { kind: 'literal_bytes', value: Buffer.from(v.bytes()).toString('hex') }
+    default:
+      throw malformed(`unsupported leaf value type ${v.switch().name}`)
+  }
+}
+
+/** One node. `not` wraps a NODE; the comparison ops wrap two LEAVES. */
+export function decodeNode(v: xdr.ScVal): PredicateNode {
+  const items = expectVec(v, 'node')
+  const op = selectorSymbol(items)
+  if (op === null) throw malformed('node does not start with an operator symbol')
+  switch (op) {
+    case 'and':
+    case 'or': {
+      arity(items, 2, op)
+      const children = expectVec(items[1] as xdr.ScVal, `${op} children`).map(decodeNode)
+      if (children.length === 0) throw malformed(`${op} has no children`)
+      return { op, children }
+    }
+    case 'not':
+      arity(items, 2, op)
+      return { op: 'not', child: decodeNode(items[1] as xdr.ScVal) }
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      arity(items, 3, op)
+      return {
+        op,
+        left: decodeLeaf(items[1] as xdr.ScVal),
+        right: decodeLeaf(items[2] as xdr.ScVal),
+      }
+    case 'in': {
+      arity(items, 3, op)
+      return {
+        op: 'in',
+        needle: decodeLeaf(items[1] as xdr.ScVal),
+        haystack: expectVec(items[2] as xdr.ScVal, 'in haystack').map(decodeLeaf),
+      }
+    }
+    default:
+      throw malformed(`unknown node operator '${op}'`)
+  }
+}
+
+/** Decode a predicate from the wire bytes the interpreter stores.
+ *
+ *  Accepts the base64 the encoder emits (`encodePredicate().encodedPredicate`)
+ *  or the raw XDR bytes read straight out of `StoredDoc.predicate_bytes`. */
+export function decodePredicate(encoded: string | Uint8Array): PredicateNode {
+  let scv: xdr.ScVal
+  try {
+    scv =
+      typeof encoded === 'string'
+        ? xdr.ScVal.fromXDR(Buffer.from(encoded, 'base64'))
+        : xdr.ScVal.fromXDR(Buffer.from(encoded))
+  } catch (e) {
+    throw malformed(`not valid ScVal XDR (${e instanceof Error ? e.message : String(e)})`)
+  }
+  return decodeNode(scv)
+}

package/src/predicate/encode.ts

@@ -18,6 +18,19 @@
 //
 // Caps from `PREDICATE_CAPS` are enforced BEFORE returning; a cap breach throws
 // a `ToolError` with the matching error code and `severity: 'error'`.
+//
+// The encoder is also the gate for the structures the contract refuses: an
+// empty `and`/`or` child list and an empty `in` haystack (MALFORMED_PREDICATE
+// at decode, dsl.rs), an `oracle_price` under a `not`/`or`, and an oracle bound
+// with no non-oracle constraint beside it (validate_oracle_placement at
+// install).
+//
+// One gap remains, deliberately: the `amount` / `window_spent` leaf branches
+// below are dead ABI - the contract's grammar no longer has those selector
+// symbols, so a predicate carrying one is MALFORMED at decode. The interpreter
+// adapter reports them as uncovered before lowering, so the product path
+// cannot emit one; removing the branches (and the leaf kinds) is a separate
+// change.
 
 import { createHash } from 'node:crypto'
 import { Address, xdr } from '@stellar/stellar-sdk'
@@ -68,6 +81,12 @@ export function encodePredicate(node: PredicateNode): EncodedPredicate {
       `oracle reads ${oracleReads} exceed MAX_ORACLE_READS ${PREDICATE_CAPS.MAX_ORACLE_READS}`
     )
   }
+  if (stats.oracleAssets.size > 0 && stats.nonOracleSelectorLeaves === 0) {
+    throw capError(
+      'MALFORMED_PREDICATE',
+      'predicate constrains nothing but an oracle price: the contract refuses it at install (dsl.rs MissingNonOracleEnvelope). Pin the call itself (contract / method / argument) alongside the price bound.'
+    )
+  }
 
   // --- pass 2: build + canonicalise the ScVal ---
   const root = encodeNode(node)
@@ -89,35 +108,63 @@ interface PredicateStats {
   inCounts: Array<{ count: number }>
   /** Unique assets referenced by `oracle_price` leaves - each costs 2 reads. */
   oracleAssets: Set<string>
+  /** Selector leaves that are NOT `oracle_price`. The contract refuses a
+   *  predicate whose only constraint is an oracle read (dsl.rs
+   *  `validate_oracle_placement` -> MissingNonOracleEnvelope): a price bound
+   *  alone pins nothing about the call itself. Literals are operands, not
+   *  constraints, so they do not count. */
+  nonOracleSelectorLeaves: number
 }
 
 function computeStats(node: PredicateNode): PredicateStats {
   const inCounts: Array<{ count: number }> = []
   const oracleAssets = new Set<string>()
-  const { depth, leaves } = walk(node, inCounts, oracleAssets)
-  return { depth, leaves, inCounts, oracleAssets }
+  const counters = { nonOracleSelectorLeaves: 0 }
+  const { depth, leaves } = walk(node, inCounts, oracleAssets, counters, false)
+  return {
+    depth,
+    leaves,
+    inCounts,
+    oracleAssets,
+    nonOracleSelectorLeaves: counters.nonOracleSelectorLeaves,
+  }
 }
 
 function walk(
   node: PredicateNode,
   inCounts: Array<{ count: number }>,
-  oracleAssets: Set<string>
+  oracleAssets: Set<string>,
+  counters: { nonOracleSelectorLeaves: number },
+  /** True once the walk is under a `not` or an `or`, where an oracle read
+   *  becomes a condition the caller can satisfy by taking the other branch. */
+  negatedOrDisjunctive: boolean
 ): { depth: number; leaves: number } {
   switch (node.op) {
     case 'and':
     case 'or': {
-      if (node.children.length === 0) return { depth: 1, leaves: 0 }
+      if (node.children.length === 0) {
+        throw capError(
+          'MALFORMED_PREDICATE',
+          `\`${node.op}\` with no children: the contract refuses it at decode (MALFORMED_PREDICATE), so it can never be installed`
+        )
+      }
       let maxChildDepth = 0
       let totalLeaves = 0
       for (const c of node.children) {
-        const child = walk(c, inCounts, oracleAssets)
+        const child = walk(
+          c,
+          inCounts,
+          oracleAssets,
+          counters,
+          negatedOrDisjunctive || node.op === 'or'
+        )
         if (child.depth > maxChildDepth) maxChildDepth = child.depth
         totalLeaves += child.leaves
       }
       return { depth: maxChildDepth + 1, leaves: totalLeaves }
     }
     case 'not': {
-      const child = walk(node.child, inCounts, oracleAssets)
+      const child = walk(node.child, inCounts, oracleAssets, counters, true)
       return { depth: child.depth + 1, leaves: child.leaves }
     }
     case 'eq':
@@ -125,16 +172,22 @@ function walk(
     case 'lte':
     case 'gt':
     case 'gte': {
-      collectOracle(node.left, oracleAssets)
-      collectOracle(node.right, oracleAssets)
+      collectOracle(node.left, oracleAssets, counters, negatedOrDisjunctive)
+      collectOracle(node.right, oracleAssets, counters, negatedOrDisjunctive)
       return { depth: 1, leaves: leafCount(node.left) + leafCount(node.right) }
     }
     case 'in': {
+      if (node.haystack.length === 0) {
+        throw capError(
+          'MALFORMED_PREDICATE',
+          '`in` with an empty haystack: the contract refuses it at decode (MALFORMED_PREDICATE), so it can never be installed'
+        )
+      }
       inCounts.push({ count: node.haystack.length })
-      collectOracle(node.needle, oracleAssets)
+      collectOracle(node.needle, oracleAssets, counters, negatedOrDisjunctive)
       let haystackLeaves = 0
       for (const h of node.haystack) {
-        collectOracle(h, oracleAssets)
+        collectOracle(h, oracleAssets, counters, negatedOrDisjunctive)
         haystackLeaves += leafCount(h)
       }
       return {
@@ -157,14 +210,31 @@ function leafCount(leaf: PredicateLeaf): number {
   return 1
 }
 
-function collectOracle(leaf: PredicateLeaf, oracleAssets: Set<string>): void {
+function collectOracle(
+  leaf: PredicateLeaf,
+  oracleAssets: Set<string>,
+  counters: { nonOracleSelectorLeaves: number },
+  negatedOrDisjunctive: boolean
+): void {
   // literal_vec is the only nested leaf; recurse so an oracle_price buried in a
   // vector literal (which the lowering would forbid, but the cap-walker must
   // still see) is counted toward the oracle-read budget.
   if (leaf.kind === 'oracle_price') {
+    if (negatedOrDisjunctive) {
+      throw capError(
+        'ORACLE_LEAF_INVALID_POSITION',
+        `oracle_price(${leaf.asset}) sits under a \`not\`/\`or\`: the contract refuses that position at install (dsl.rs validate_oracle_placement). An oracle bound must be a conjunct the call has to satisfy.`
+      )
+    }
     oracleAssets.add(leaf.asset)
   } else if (leaf.kind === 'literal_vec') {
-    for (const el of leaf.elements) collectOracle(el, oracleAssets)
+    for (const el of leaf.elements) collectOracle(el, oracleAssets, counters, negatedOrDisjunctive)
+  } else if (!leaf.kind.startsWith('literal_') && leaf.kind !== 'oracle_threshold') {
+    // A threshold is the oracle compare's operand, not an independent
+    // constraint. Counting it would let an oracle-only predicate satisfy the
+    // non-oracle envelope with its own bound (mirrors collect_oracle_leaf in
+    // dsl.rs, where it sits with the literals).
+    counters.nonOracleSelectorLeaves += 1
   }
 }
 
@@ -216,6 +286,17 @@ function encodeLeaf(leaf: PredicateLeaf): xdr.ScVal {
         xdr.ScVal.scvU32(leaf.element),
         xdr.ScVal.scvSymbol(leaf.field),
       ])
+    case 'call_arg_scaled':
+      // Wire shape `vec[symbol, u32, i128, i128]` mirrors the Rust decoder's
+      // expectation in dsl.rs SEL_CALL_ARG_SCALED. `scvI128FromDecimal` is
+      // the same range-checked helper used by `literal_i128`; an out-of-range
+      // num/den is refused at encode time (rather than at install on chain).
+      return xdr.ScVal.scvVec([
+        symbol('call_arg_scaled'),
+        xdr.ScVal.scvU32(leaf.index),
+        scvI128FromDecimal(leaf.num),
+        scvI128FromDecimal(leaf.den),
+      ])
     case 'amount':
       return xdr.ScVal.scvVec([symbol('amount'), scvAddressFromStrkey(leaf.token)])
     case 'window_spent':
@@ -227,11 +308,27 @@ function encodeLeaf(leaf: PredicateLeaf): xdr.ScVal {
     case 'now':
       return xdr.ScVal.scvVec([symbol('now')])
     case 'valid_until':
-      return xdr.ScVal.scvVec([symbol('valid_until')])
+      // The interpreter refuses this leaf at install: it never sources
+      // valid_until_ledger, so a policy built on it would deny forever.
+      // Expiry belongs to the smart account, through the context rule's
+      // validUntilLedger. Refuse at synthesis so the author finds out here
+      // rather than from an install that always fails.
+      throw new Error(
+        'valid_until is not a usable predicate leaf: the interpreter never sources it and ' +
+          'refuses it at install. Put expiry on the context rule (validUntilLedger) instead.'
+      )
     case 'invocation_count_in_window':
       return xdr.ScVal.scvVec([symbol('invocation_count'), scvU64FromValue(leaf.windowSecs)])
     case 'oracle_price':
       return xdr.ScVal.scvVec([symbol('oracle_price'), scvAddressFromStrkey(leaf.asset)])
+    case 'oracle_threshold':
+      // Arity 3, matching SEL_ORACLE_THRESHOLD in dsl.rs. The declared basis
+      // travels with the value so the contract never has to assume one.
+      return xdr.ScVal.scvVec([
+        symbol('oracle_threshold'),
+        scvI128FromDecimal(leaf.value),
+        xdr.ScVal.scvU32(leaf.decimals),
+      ])
     case 'literal_address':
       return scvAddressFromStrkey(leaf.value)
     case 'literal_i128':

package/src/predicate/from-json.ts

@@ -0,0 +1,124 @@
+// src/predicate/from-json.ts - parse untrusted JSON into a `PredicateNode`.
+//
+// The counterpart to `encodePredicate`: that turns a typed node into the
+// canonical wire bytes, this turns arbitrary parsed JSON into a typed node,
+// or throws. Anything accepting a hand-written policy needs both, so both
+// belong in this package rather than in whichever app happened to grow the
+// paste box first.
+//
+// Deliberately shape-only. Structural caps (depth, node count, argument
+// count) stay in the encoder, which is the gate the contract's decoder
+// mirrors; duplicating them here would give two places to drift.
+
+import type { PredicateLeaf, PredicateNode } from '../types.ts'
+
+/** Parse a JSON object back into a `PredicateNode`. Throws on shape
+ *  mismatches. The encoder's structural caps are the real gate. */
+export function jsonToAst(value: unknown): PredicateNode {
+  if (value === null || typeof value !== 'object') throw new Error('predicate must be an object')
+  const v = value as {
+    op?: unknown
+    children?: unknown
+    child?: unknown
+    left?: unknown
+    right?: unknown
+    needle?: unknown
+    haystack?: unknown
+  }
+  switch (v.op) {
+    case 'and':
+    case 'or':
+      return { op: v.op, children: arrayOf(v.children, jsonToAst) }
+    case 'not':
+      return { op: 'not', child: jsonToAst(v.child) }
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      return { op: v.op, left: jsonToLeaf(v.left), right: jsonToLeaf(v.right) }
+    case 'in':
+      return { op: 'in', needle: jsonToLeaf(v.needle), haystack: arrayOf(v.haystack, jsonToLeaf) }
+    default:
+      throw new Error(`unknown predicate op: ${String(v.op)}`)
+  }
+}
+
+function arrayOf<T>(v: unknown, f: (x: unknown) => T): T[] {
+  if (!Array.isArray(v)) throw new Error('expected array')
+  return v.map(f)
+}
+
+function jsonToLeaf(value: unknown): PredicateLeaf {
+  if (value === null || typeof value !== 'object') throw new Error('leaf must be an object')
+  const v = value as { kind?: unknown; [k: string]: unknown }
+  switch (v.kind) {
+    case 'call_contract':
+    case 'call_fn':
+    case 'now':
+    case 'valid_until':
+      return { kind: v.kind }
+    case 'call_arg':
+      return { kind: 'call_arg', index: numberField(v, 'index') }
+    case 'call_arg_len':
+      return { kind: 'call_arg_len', index: numberField(v, 'index') }
+    // num/den are strings, not numbers: they are i128 on chain, and a JSON
+    // number would silently lose precision past 2^53 before the encoder
+    // ever saw the value.
+    case 'call_arg_scaled':
+      return {
+        kind: 'call_arg_scaled',
+        index: numberField(v, 'index'),
+        num: stringField(v, 'num'),
+        den: stringField(v, 'den'),
+      }
+    case 'call_arg_field':
+      return {
+        kind: 'call_arg_field',
+        index: numberField(v, 'index'),
+        element: numberField(v, 'element'),
+        field: stringField(v, 'field'),
+      }
+    case 'amount':
+      return { kind: 'amount', token: stringField(v, 'token') }
+    case 'window_spent':
+      return {
+        kind: 'window_spent',
+        token: stringField(v, 'token'),
+        windowSeconds: numberField(v, 'windowSeconds'),
+      }
+    case 'invocation_count_in_window':
+      return { kind: 'invocation_count_in_window', windowSecs: numberField(v, 'windowSecs') }
+    case 'oracle_price':
+      return { kind: 'oracle_price', asset: stringField(v, 'asset') }
+    case 'literal_address':
+      return { kind: 'literal_address', value: stringField(v, 'value') }
+    case 'literal_i128':
+      return { kind: 'literal_i128', value: stringField(v, 'value') }
+    case 'literal_symbol':
+      return { kind: 'literal_symbol', value: stringField(v, 'value') }
+    case 'literal_u32':
+      return { kind: 'literal_u32', value: numberField(v, 'value') }
+    case 'literal_u64':
+      return { kind: 'literal_u64', value: stringField(v, 'value') }
+    case 'literal_bytes':
+      return { kind: 'literal_bytes', value: stringField(v, 'value') }
+    case 'literal_vec':
+      return { kind: 'literal_vec', elements: arrayOf(v.elements, jsonToLeaf) }
+    default:
+      throw new Error(`unknown leaf kind: ${String(v.kind)}`)
+  }
+}
+
+function numberField(v: { [k: string]: unknown }, key: string): number {
+  const x = v[key]
+  if (typeof x !== 'number' || !Number.isInteger(x))
+    throw new Error(`field ${key} must be an integer`)
+  return x
+}
+
+function stringField(v: { [k: string]: unknown }, key: string): string {
+  const x = v[key]
+  if (typeof x !== 'string') throw new Error(`field ${key} must be a string`)
+  return x
+}

package/src/predicate/index.ts

@@ -1,3 +1,7 @@
-// src/predicate/index.ts - re-export the canonical predicate encoder.
+// src/predicate/index.ts - re-export the canonical predicate encoder and the
+// untrusted-JSON parser that feeds it. A consumer accepting a hand-written
+// policy needs both halves.
 
+export { decodeLeaf, decodeNode, decodePredicate } from './decode.ts'
 export { type EncodedPredicate, encodePredicate } from './encode.ts'
+export { jsonToAst } from './from-json.ts'

package/src/registry/identify.ts

@@ -16,6 +16,13 @@
 //   3. SoroSwap: recognised by ADDRESS only - the router is a single pinned
 //      contract. FIX 4: the method must ALSO be present in the protocol's
 //      ABI; an unknown method on a pinned router -> null (fail-closed).
+//   4. OZ smart-account: recognised by INTERFACE - the user-facing context
+//      rule entrypoints (`batch_add_signer` / `batch_remove_signer` /
+//      `add_context_rule` / `remove_context_rule`) have a fixed (fn, args)
+//      shape across every OZ multisig deployment. Pinned per-deployment
+//      addresses are impossible (every user deploys their own smart
+//      account), so interface recognition is the only viable path - same
+//      reasoning SEP-41 uses for any token address.
 //
 // Method lookup uses `Object.hasOwn` rather than `in` so prototype-chain
 // names like `constructor`, `toString`, `hasOwnProperty` do NOT register as
@@ -25,7 +32,7 @@
 import type { ScVal } from '../types.ts'
 import { addressToProtocol } from './known-addresses.ts'
 import type { AbiArg, ProtocolId } from './protocols.ts'
-import { BLEND_ABI, SEP41_ABI, SOROSWAP_ABI } from './protocols.ts'
+import { BLEND_ABI, OZ_ACCOUNT_ABI, SEP41_ABI, SOROSWAP_ABI } from './protocols.ts'
 
 export interface IdentifiedProtocol {
   protocol: ProtocolId
@@ -62,7 +69,20 @@ export function identifyProtocol(
     return null
   }
 
-  // 3) Pinned-address recognition (Blend factory + SoroSwap router/factory).
+  // 3) OpenZeppelin smart-account by interface. The four context-rule
+  //    entrypoints have a fixed (fn, args) shape across every OZ
+  //    multisig deployment. `__check_auth` is private (host-invoked)
+  //    and is intentionally NOT in this ABI - the recogniser only
+  //    claims OZ for the public surface.
+  if (Object.hasOwn(OZ_ACCOUNT_ABI, method)) {
+    const sig = OZ_ACCOUNT_ABI[method]
+    if (sig && argsMatchAbi(sig.args, args)) {
+      return { protocol: 'oz_account', fn: method }
+    }
+    return null
+  }
+
+  // 4) Pinned-address recognition (Blend factory + SoroSwap router/factory).
   //    FIX 4: the method must also be in the protocol's ABI; an unknown
   //    method on a pinned address -> null.
   if (network) {