@crediolabs/policy-synth 0.1.9 → 0.1.11

package/src/install/build-add-context-rule.ts

@@ -0,0 +1,429 @@
+// src/install/build-add-context-rule.ts - pure builder for the OZ
+// `add_context_rule` invocation arguments.
+//
+// Hand-rolled instead of reusing the scripts' helpers because the product
+// path (Phase 06 install_policy) needs a single callable that takes a typed
+// `ContextRuleDraft` + predicate bytes and returns the `ScVal` argument list
+// the host will pass to `add_context_rule`. The script-level helpers stay
+// out of `src/` to avoid dragging the ts-node SDK into the library surface.
+//
+// The OZ trait signature is pinned in
+// `stellar-contracts::smart_account::SmartAccount::add_context_rule`:
+//
+//     fn add_context_rule(
+//         e: &Env,
+//         context_type: ContextRuleType,
+//         name: String,
+//         valid_until: Option<u32>,
+//         signers: Vec<Signer>,
+//         policies: Map<Address, Val>,
+//     ) -> ContextRule
+//
+// The default body calls `e.current_contract_address().require_auth()`, so
+// installation goes through the account's `__check_auth` -> `do_check_auth`.
+// That requires the DEPLOYER to have shipped an admin rule with NO
+// restrictive policy, otherwise the policy would refuse the very call that
+// installs it. The caller is responsible for that contract; this builder
+// just emits the args.
+//
+// Two hard limits the contract enforces (verified against
+// `storage::validate_signers_and_policies` at /tmp/ozsc):
+//   - signers.len() <= MAX_SIGNERS (15)
+//   - policies.len() <= MAX_POLICIES (5)
+//   - signers and policies must not both be empty
+// The same limits are mirrored in `OZ_LIMITS` (see src/types.ts) and
+// checked here fail-closed before any encoding work - the user gets a
+// typed error with the specific cap, not a runtime trap.
+//
+// Policypayloads are `Map<Address, Val>`. The host orders map entries by the
+// symbol STRING of the key, NOT by the key's XDR bytes (a length prefix
+// would otherwise put `amount` before `address` and produce a map the
+// contract reads differently - a previous session lost hours to this). Our
+// only key is an `Address`, so we build a single-entry map and the ordering
+// question is moot, but the comment is here so the next map-bearing code
+// in this file does not regress.
+//
+// Pure: no network, no signing. The caller hands the returned ScVal[] to
+// `Operation.invokeHostFunction` AFTER wiring the auth entries, otherwise
+// the account refuses with `Error(Auth, InvalidAction)`.
+
+import { createHash } from 'node:crypto'
+import { Address, xdr } from '@stellar/stellar-sdk'
+import type { ToolError } from '../errors.ts'
+import {
+  type ContextRuleDraft,
+  OZ_LIMITS,
+  type OZPrimitiveConfig,
+  type PolicyRef,
+  type SignerDraft,
+} from '../types.ts'
+
+/** Inputs for `buildAddContextRuleArgs`. The fields are the ones the contract
+ *  validates at install; everything else is downstream. */
+export interface BuildAddContextRuleArgs {
+  /** The auth-context rule signers to attach - `Vec<Signer>` wire form.
+   *  These are the SIGNERS the new rule authorises, not the deployer's
+   *  admin session. The deployer signs the install call via the admin rule
+   *  already on the account, which is separate from this list. */
+  signers: SignerDraft[]
+  /** The policy(ies) to attach to the new rule. Only `interpreter` refs
+   *  reach the wire today; `oz_builtin` is reserved for Phase 06 follow-ups. */
+  policies: PolicyRef[]
+  /** Per-policy install nonce; 1 for a fresh install. */
+  installNonce: number
+  /** Already-encoded (base64) canonical ScVal of the predicate. The builder
+   *  decodes it to bytes for the `predicate` field and re-hashes to confirm
+   *  the caller-supplied `predicateHash` matches. */
+  encodedPredicate: string
+  /** Hex sha256 of the canonical predicate XDR bytes. */
+  predicateHash: string
+  /** Per-policy oracle overrides. Absent on any key uses the wasm default. */
+  oracleParams?: {
+    maxStalenessSeconds?: number
+    maxDeviationBps?: number
+    /** Bound between the primary and secondary feeds. Tighten-only against
+     *  the wasm default, like the other two. */
+    maxCrossFeedDeviationBps?: number
+  }
+  /** Hard pin to the interpreter's wasm grammar. Refusing here fails closed
+   *  before the chain does; the contract will refuse a mismatch again. */
+  grammarVersion?: number
+}
+
+export const DEFAULT_GRAMMAR_VERSION = 1 as const
+
+/** The verb `add_context_rule` takes on the wire. */
+export const ADD_CONTEXT_RULE_SYMBOL = 'add_context_rule' as const
+
+/** Tuple of `ScVal` arguments to pass to `Operation.invokeHostFunction` for
+ *  `add_context_rule`. Order matches the OZ trait signature. */
+export type AddContextRuleArgs = readonly [
+  contextType: xdr.ScVal,
+  name: xdr.ScVal,
+  validUntil: xdr.ScVal,
+  signers: xdr.ScVal,
+  policies: xdr.ScVal,
+]
+
+/** Build the `add_context_rule` invocation args. Throws a `ToolError`-shaped
+ *  error on limit breaches or malformed input. */
+export function buildAddContextRuleArgs(
+  draft: ContextRuleDraft,
+  args: BuildAddContextRuleArgs
+): AddContextRuleArgs {
+  // ---- 1. Cap checks (fail-closed before any encoding) ----
+  if (args.signers.length > OZ_LIMITS.maxSignersPerRule) {
+    throw limitError(
+      'INSTALL_BUILD_FAILED',
+      `signers ${args.signers.length} exceed MAX_SIGNERS_PER_RULE ${OZ_LIMITS.maxSignersPerRule}`
+    )
+  }
+  if (args.policies.length > OZ_LIMITS.maxPoliciesPerRule) {
+    throw limitError(
+      'INSTALL_BUILD_FAILED',
+      `policies ${args.policies.length} exceed MAX_POLICIES_PER_RULE ${OZ_LIMITS.maxPoliciesPerRule}`
+    )
+  }
+  if (args.signers.length === 0 && args.policies.length === 0) {
+    throw limitError(
+      'INSTALL_BUILD_FAILED',
+      'a rule with no signers and no policies is refused at install (NoSignersAndPolicies)'
+    )
+  }
+  // OZ's spending_limit caps spend on the CONTEXT CONTRACT - it takes no
+  // token argument - so it refuses a Default rule on chain with a bare
+  // #3227. Say which rule shape it needs here, before the encoding, rather
+  // than letting the user read a numeric trap.
+  if (
+    args.policies.some((p) => p.kind === 'oz_builtin' && p.primitive.primitive === 'spending_limit')
+  ) {
+    if (draft.contextRuleType.kind !== 'call_contract') {
+      throw limitError(
+        'INSTALL_BUILD_FAILED',
+        `spending_limit caps spend on the rule's context contract, so the rule must be call_contract-scoped to that token - a "${draft.contextRuleType.kind}" rule is refused on chain (#3227)`
+      )
+    }
+  }
+
+  // ---- 2. context_type encoding ----
+  const contextType = encodeContextRuleType(draft.contextRuleType)
+
+  // ---- 3. name (string) + valid_until (Option<u32>) ----
+  const name = xdr.ScVal.scvString(draft.name)
+  const validUntil =
+    draft.validUntilLedger === null ? xdr.ScVal.scvVoid() : xdr.ScVal.scvU32(draft.validUntilLedger)
+
+  // ---- 4. signers ----
+  const signersVec = xdr.ScVal.scvVec(args.signers.map(encodeSigner))
+
+  // ---- 5. policies Map<Address, Val> ----
+  const policies = encodePoliciesMap(args)
+
+  return [contextType, name, validUntil, signersVec, policies] as const
+}
+
+// ---- helpers ----
+
+/** Field order of the `PolicyInstallParams` struct. The contract's
+ *  `#[contracttype]` derives a Map<Symbol, Val> encoding, so the host
+ *  sorts by symbol STRING (NOT by XDR bytes). This explicit list is the
+ *  single source of truth for the field order. */
+const POLICY_INSTALL_PARAM_FIELDS = [
+  'grammar_version',
+  'install_nonce',
+  'predicate',
+  'predicate_hash',
+  'oracle_max_staleness_seconds',
+  'oracle_max_deviation_bps',
+  // Cross-feed divergence bound. A field added to the contract's
+  // `PolicyInstallParams` changes the ABI: the host unpacks the map by field
+  // count, so omitting one fails the entire install with
+  // `Error(Object, UnexpectedSize)` and no indication of which field is
+  // missing. The Rust tests build that struct in Rust and never cross this
+  // boundary, so only a real install against a deployed contract catches it.
+  'oracle_max_xfeed_dev_bps',
+] as const
+
+function encodeContextRuleType(
+  rule:
+    | { kind: 'default' }
+    | { kind: 'call_contract'; contract: string }
+    | { kind: 'create_contract'; wasmHash: string }
+): xdr.ScVal {
+  switch (rule.kind) {
+    case 'default':
+      return xdr.ScVal.scvVec([xdr.ScVal.scvSymbol('Default')])
+    case 'call_contract':
+      return xdr.ScVal.scvVec([
+        xdr.ScVal.scvSymbol('CallContract'),
+        Address.fromString(rule.contract).toScVal(),
+      ])
+    case 'create_contract':
+      return xdr.ScVal.scvVec([
+        xdr.ScVal.scvSymbol('CreateContract'),
+        xdr.ScVal.scvBytes(Buffer.from(rule.wasmHash, 'hex')),
+      ])
+  }
+}
+
+function encodeSigner(s: SignerDraft): xdr.ScVal {
+  switch (s.kind) {
+    case 'delegated':
+      return xdr.ScVal.scvVec([
+        xdr.ScVal.scvSymbol('Delegated'),
+        Address.fromString(s.address).toScVal(),
+      ])
+    case 'external':
+      return xdr.ScVal.scvVec([
+        xdr.ScVal.scvSymbol('External'),
+        Address.fromString(s.verifier).toScVal(),
+        xdr.ScVal.scvBytes(Buffer.from(s.keyBytes, 'hex')),
+      ])
+  }
+}
+
+function encodePoliciesMap(args: BuildAddContextRuleArgs): xdr.ScVal {
+  const entries: xdr.ScMapEntry[] = []
+  for (const ref of args.policies) {
+    if (ref.kind === 'interpreter') {
+      const val = encodePolicyInstallParams(args)
+      entries.push(
+        new xdr.ScMapEntry({
+          key: Address.fromString(ref.interpreterAddress).toScVal(),
+          val,
+        })
+      )
+    }
+    if (ref.kind === 'oz_builtin') {
+      entries.push(
+        new xdr.ScMapEntry({
+          key: Address.fromString(ref.instanceAddress).toScVal(),
+          val: encodeOzPrimitiveParams(ref.primitive),
+        })
+      )
+    }
+  }
+  entries.sort(sortByScValSymbolString)
+  return xdr.ScVal.scvMap(entries)
+}
+
+/** Encode the install params for one OZ built-in policy.
+ *
+ *  Field names and types are read from the deployed contracts' own spec:
+ *    SpendingLimitAccountParams   { period_ledgers: u32, spending_limit: i128 }
+ *    SimpleThresholdAccountParams { threshold: u32 }
+ *    WeightedThresholdAccountParams { signer_weights: map, threshold: u32 }
+ *  Entries are symbol-string ordered for the same reason the interpreter's
+ *  are: the host orders by symbol, not by XDR bytes.
+ */
+function encodeOzPrimitiveParams(primitive: OZPrimitiveConfig): xdr.ScVal {
+  const entries: xdr.ScMapEntry[] = []
+  const push = (name: string, val: xdr.ScVal) =>
+    entries.push(new xdr.ScMapEntry({ key: xdr.ScVal.scvSymbol(name), val }))
+  const p = primitive.params as Record<string, unknown>
+  switch (primitive.primitive) {
+    case 'spending_limit': {
+      const limit = p.spending_limit
+      const period = p.period_ledgers
+      if (typeof limit !== 'string' || typeof period !== 'number') {
+        throw limitError(
+          'INSTALL_BUILD_FAILED',
+          'spending_limit needs { spending_limit: string; period_ledgers: number }'
+        )
+      }
+      push('period_ledgers', xdr.ScVal.scvU32(period))
+      push('spending_limit', encodeI128(limit))
+      break
+    }
+    case 'simple_threshold': {
+      const threshold = p.threshold
+      if (typeof threshold !== 'number') {
+        throw limitError('INSTALL_BUILD_FAILED', 'simple_threshold needs { threshold: number }')
+      }
+      push('threshold', xdr.ScVal.scvU32(threshold))
+      break
+    }
+    case 'weighted_threshold': {
+      const threshold = p.threshold
+      const weights = p.weights as Record<string, number> | undefined
+      if (typeof threshold !== 'number' || !weights) {
+        throw limitError(
+          'INSTALL_BUILD_FAILED',
+          'weighted_threshold needs { threshold: number; weights: Record<address, number> }'
+        )
+      }
+      const weightEntries = Object.entries(weights)
+        .map(
+          ([addr, w]) =>
+            new xdr.ScMapEntry({
+              key: Address.fromString(addr).toScVal(),
+              val: xdr.ScVal.scvU32(w),
+            })
+        )
+        .sort((a, b) => (a.key().toXDR('base64') < b.key().toXDR('base64') ? -1 : 1))
+      push('signer_weights', xdr.ScVal.scvMap(weightEntries))
+      push('threshold', xdr.ScVal.scvU32(threshold))
+      break
+    }
+  }
+  entries.sort((a, b) => sortBySymbolString(a.key(), b.key()))
+  return xdr.ScVal.scvMap(entries)
+}
+
+function encodeI128(value: string): xdr.ScVal {
+  const v = BigInt(value)
+  return xdr.ScVal.scvI128(
+    new xdr.Int128Parts({
+      hi: new xdr.Int64(BigInt.asIntN(64, v >> 64n)),
+      lo: new xdr.Uint64(BigInt.asUintN(64, v)),
+    })
+  )
+}
+
+function encodePolicyInstallParams(args: BuildAddContextRuleArgs): xdr.ScVal {
+  const predicate = Buffer.from(args.encodedPredicate, 'base64')
+  const computedHash = createHash('sha256').update(predicate).digest('hex')
+  if (computedHash !== args.predicateHash) {
+    throw limitError(
+      'INSTALL_BUILD_FAILED',
+      `predicateHash ${args.predicateHash.slice(0, 16)}... does not match sha256(encodedPredicate) ${computedHash.slice(0, 16)}...`
+    )
+  }
+  const entries: xdr.ScMapEntry[] = []
+  for (const k of POLICY_INSTALL_PARAM_FIELDS) {
+    const key = xdr.ScVal.scvSymbol(k)
+    switch (k) {
+      case 'grammar_version':
+        entries.push(
+          new xdr.ScMapEntry({
+            key,
+            val: xdr.ScVal.scvU32(args.grammarVersion ?? DEFAULT_GRAMMAR_VERSION),
+          })
+        )
+        break
+      case 'install_nonce':
+        entries.push(new xdr.ScMapEntry({ key, val: xdr.ScVal.scvU32(args.installNonce) }))
+        break
+      case 'predicate':
+        entries.push(new xdr.ScMapEntry({ key, val: xdr.ScVal.scvBytes(predicate) }))
+        break
+      case 'predicate_hash':
+        entries.push(
+          new xdr.ScMapEntry({
+            key,
+            val: xdr.ScVal.scvBytes(Buffer.from(args.predicateHash, 'hex')),
+          })
+        )
+        break
+      case 'oracle_max_staleness_seconds':
+        entries.push(
+          new xdr.ScMapEntry({
+            key,
+            val: encodeOptionU32(args.oracleParams?.maxStalenessSeconds),
+          })
+        )
+        break
+      case 'oracle_max_deviation_bps':
+        entries.push(
+          new xdr.ScMapEntry({
+            key,
+            val: encodeOptionU32(args.oracleParams?.maxDeviationBps),
+          })
+        )
+        break
+      case 'oracle_max_xfeed_dev_bps':
+        entries.push(
+          new xdr.ScMapEntry({
+            key,
+            val: encodeOptionU32(args.oracleParams?.maxCrossFeedDeviationBps),
+          })
+        )
+        break
+    }
+  }
+  // The host orders map entries by the SYMBOL STRING, not by XDR bytes. A
+  // length prefix in the XDR encoding would otherwise put `amount` before
+  // `address` and produce a struct the contract reads differently. Emit the
+  // entries in symbol-string order so the wire form matches the host's view.
+  entries.sort((a, b) => sortBySymbolString(a.key(), b.key()))
+  return xdr.ScVal.scvMap(entries)
+}
+
+function encodeOptionU32(v: number | undefined): xdr.ScVal {
+  if (v === undefined) return xdr.ScVal.scvVoid()
+  if (!Number.isFinite(v) || v < 0 || v > 0xffffffff) {
+    throw limitError('INSTALL_BUILD_FAILED', `oracle params value ${v} is outside u32 range`)
+  }
+  return xdr.ScVal.scvU32(v)
+}
+
+/** Sort host-map keys by their symbol-string form. The host orders map
+ *  entries by the SYMBOL STRING, not by the key's XDR bytes (a length
+ *  prefix in the encoding would otherwise put `amount` before `address`).
+ *  For non-symbol keys we fall back to length-prefixed XDR bytes; the
+ *  caller's only Address keys today are length-stable so this is moot, but
+ *  the helper stands ready for the multi-policy variant. */
+function sortByScValSymbolString(a: xdr.ScMapEntry, b: xdr.ScMapEntry): number {
+  return sortBySymbolString(a.key(), b.key())
+}
+
+function sortBySymbolString(a: xdr.ScVal, b: xdr.ScVal): number {
+  const aSym = a.switch().name === 'scvSymbol' ? a.sym().toString() : null
+  const bSym = b.switch().name === 'scvSymbol' ? b.sym().toString() : null
+  if (aSym !== null && bSym !== null) {
+    return aSym < bSym ? -1 : aSym > bSym ? 1 : 0
+  }
+  return Buffer.compare(a.toXDR(), b.toXDR())
+}
+
+function limitError(code: ToolError['code'], message: string): ToolError {
+  const err = new Error(message) as Error & {
+    code: ToolError['code']
+    severity: string
+    retryable: boolean
+  }
+  err.code = code
+  err.severity = 'error'
+  err.retryable = false
+  throw err
+}

package/src/ir/types.ts

@@ -65,6 +65,10 @@ export interface IRCompare {
   selector: IRSelector
   operator: IRCompOp
   value: string
+  /** Decimal basis of `value`, for selectors whose comparand is not on a basis
+   *  the contract can infer. Set for `oracle_price`, where prices normalise to
+   *  9 dp and an undeclared basis fails OPEN. */
+  valueDecimals?: number
 }
 
 /** Condition tree. NEAR-V2 guard/constraint are flat And/Or; the IR allows

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)
+}