@crediolabs/policy-synth 0.3.1 → 0.5.0

package/src/errors.ts

@@ -43,6 +43,11 @@ export type ErrorCode =
   | 'UNSUPPORTED_NODE'
   | 'STATEFUL_BOUND'
   | 'NOT_IN_ALLOWLIST'
+  /** A comparison against a `call_arg_scaled` operand failed (contract 107). */
+  | 'SLIPPAGE_FLOOR'
+  /** A `call_arg_scaled` ratio is zero or non-positive. Refused at install
+   *  (contract 214) and mirrored at encode. */
+  | 'INVALID_SCALED_RATIO'
   // --- escape-hatch compile gate ---
   | 'COMPILE_OK'
   | 'COMPILE_GATE_FAILED'

package/src/install/authority-overlap.ts

@@ -0,0 +1,323 @@
+// src/install/authority-overlap.ts - cross-rule authority analysis.
+//
+// An OZ smart account selects a context rule by CALLER DECLARATION and enforces
+// only the policies of the rule that was named. A signer belonging to several
+// rules therefore picks which one applies, so for any given call their
+// authority is the MAXIMUM over the matching rules, never the intersection.
+//
+// The consequence is the one that catches people: installing a second, tighter
+// rule restricts nothing. A key that also sits on an unpoliced rule is not
+// constrained at all - it names that rule and the predicate never runs. This
+// module detects that at install time, before the caller acts on a policy that
+// looks binding and is not.
+//
+// Not theoretical. Proven on chain 2026-08-22: the same key, the same account
+// and the same forbidden call was denied `#100` naming the policed rule and
+// PERMITTED naming an unpoliced one. It happened in this project's own end-to-
+// end harness, written by the author of the grammar, and was caught by review
+// rather than by tooling - which is why the tooling now exists.
+//
+// Adapted to grammar 3 from the version published in `@crediolabs/policy-synth`
+// 0.2.0, which came from the `octogate` repository and was lost when the npm
+// lineage moved here. `or` and `not` are gone from the grammar, so the cases
+// handling them are gone too; oracle bounds are gone from the stored document.
+//
+// Pure: no network. The caller supplies the account's rules.
+
+import type { PredicateLeaf, PredicateNode, SignerDraft } from '../types.ts'
+
+/** Wildcard component of a `Selector`: the predicate does not pin this half. */
+export const ANY = '*'
+
+/** A (contract, function) pair a predicate may permit. `ANY` in either half
+ *  means unconstrained, so `{contract: ANY, fn: ANY}` is "any call at all". */
+export interface Selector {
+  contract: string
+  fn: string
+}
+
+export type ContextType =
+  | { kind: 'default' }
+  | { kind: 'call_contract'; contract: string }
+  | { kind: 'create_contract'; wasmHash: string }
+
+/** How much can be said about a neighbouring rule.
+ *  - `interpreter`: policed by our interpreter and the predicate was readable,
+ *    so its authority is known exactly.
+ *  - `foreign`: policed by some other contract. The address is visible, the
+ *    semantics are not, so it needs review by hand.
+ *  - `unpoliced`: no policy at all. Whatever its context type allows, its
+ *    signers may do without constraint. */
+export type RuleClass = 'interpreter' | 'foreign' | 'unpoliced'
+
+export interface ObservedRule {
+  id: number
+  contextType: ContextType
+  signers: SignerDraft[]
+  /** Policy contract addresses attached to the rule, in OZ's order. */
+  policyAddresses: string[]
+  /** Decoded predicate. Present only when the rule is policed by OUR
+   *  interpreter and the stored document was readable. */
+  predicate?: PredicateNode
+}
+
+export interface IntendedInstall {
+  /** Rule the predicate is being installed onto. A re-install onto the same
+   *  id REPLACES its predicate rather than adding a second source of
+   *  authority, so that id is skipped. */
+  ruleId: number
+  contextType: ContextType
+  signers: SignerDraft[]
+  predicate: PredicateNode
+}
+
+export type OverlapSeverity =
+  /** A neighbouring rule imposes no constraint at all on the shared calls. */
+  | 'bypass'
+  /** A neighbouring policy exists but what it permits cannot be read. */
+  | 'unknown'
+  /** Both rules are ours. The new rule will not restrict the shared calls,
+   *  because the signer names whichever is more permissive. */
+  | 'not-restricting'
+
+export interface AuthorityOverlap {
+  ruleId: number
+  ruleClass: RuleClass
+  severity: OverlapSeverity
+  /** Signers present in BOTH rules. An overlap is only reachable by a signer
+   *  who can name both, so a rule sharing no signer is not a collision. */
+  sharedSigners: SignerDraft[]
+  /** The selectors both rules can serve. Non-empty by construction. */
+  sharedSelectors: Selector[]
+  advice: string
+}
+
+// ---- signer identity ----
+
+/** Canonical key for signer equality. Mirrors OZ's `Signer` enum: a delegated
+ *  signer is its address, an external signer is the verifier plus the key
+ *  bytes, since one verifier may hold many keys. */
+export function signerKey(s: SignerDraft): string {
+  return s.kind === 'delegated' ? `delegated:${s.address}` : `external:${s.verifier}:${s.keyBytes}`
+}
+
+function sharedSigners(a: SignerDraft[], b: SignerDraft[]): SignerDraft[] {
+  const bKeys = new Set(b.map(signerKey))
+  return a.filter((s) => bKeys.has(signerKey(s)))
+}
+
+// ---- selector extraction ----
+
+const WILDCARD: Selector = { contract: ANY, fn: ANY }
+
+function selectorKey(s: Selector): string {
+  return `${s.contract} ${s.fn}`
+}
+
+function dedupe(sels: Selector[]): Selector[] {
+  const seen = new Map<string, Selector>()
+  for (const s of sels) seen.set(selectorKey(s), s)
+  return [...seen.values()]
+}
+
+/** Intersect one pair. `ANY` absorbs, equal literals survive, and two
+ *  different literals cannot both hold for a single call. */
+function intersectOne(a: Selector, b: Selector): Selector | null {
+  const contract =
+    a.contract === ANY
+      ? b.contract
+      : b.contract === ANY
+        ? a.contract
+        : a.contract === b.contract
+          ? a.contract
+          : null
+  if (contract === null) return null
+  const fn = a.fn === ANY ? b.fn : b.fn === ANY ? a.fn : a.fn === b.fn ? a.fn : null
+  if (fn === null) return null
+  return { contract, fn }
+}
+
+/** Intersection of two selector SETS: every compatible pairing survives. */
+export function intersectSelectors(a: Selector[], b: Selector[]): Selector[] {
+  const out: Selector[] = []
+  for (const x of a) {
+    for (const y of b) {
+      const hit = intersectOne(x, y)
+      if (hit) out.push(hit)
+    }
+  }
+  return dedupe(out)
+}
+
+function literalAddress(leaf: PredicateLeaf): string | null {
+  return leaf.kind === 'literal_address' ? leaf.value : null
+}
+
+function literalSymbol(leaf: PredicateLeaf): string | null {
+  return leaf.kind === 'literal_symbol' ? leaf.value : null
+}
+
+/** Selector pinned by a single `eq`, whichever side the literal sits on. */
+function selectorFromEq(left: PredicateLeaf, right: PredicateLeaf): Selector | null {
+  if (left.kind === 'call_contract') {
+    const addr = literalAddress(right)
+    return addr === null ? null : { contract: addr, fn: ANY }
+  }
+  if (right.kind === 'call_contract') {
+    const addr = literalAddress(left)
+    return addr === null ? null : { contract: addr, fn: ANY }
+  }
+  if (left.kind === 'call_fn') {
+    const sym = literalSymbol(right)
+    return sym === null ? null : { contract: ANY, fn: sym }
+  }
+  if (right.kind === 'call_fn') {
+    const sym = literalSymbol(left)
+    return sym === null ? null : { contract: ANY, fn: sym }
+  }
+  return null
+}
+
+/**
+ * The set of `(contract, fn)` selectors a predicate may permit.
+ *
+ * A deliberate OVER-approximation: every call the predicate actually permits is
+ * covered by some returned selector, and unrecognised structure widens to the
+ * wildcard rather than narrowing. That direction is what makes the emptiness
+ * test sound. A call carries exactly one `(contract, fn)`, so if two
+ * predicates' over-approximations do not intersect, no single call can be
+ * routed to either and the rules provably cannot collide.
+ *
+ * Narrowing instead would be the fail-OPEN direction: it would let this report
+ * "no overlap" for rules that do collide.
+ */
+export function permittedSelectors(node: PredicateNode): Selector[] {
+  switch (node.op) {
+    case 'and': {
+      // Every conjunct must hold at once, so the permitted set is the
+      // intersection. Intersecting over-approximations stays one.
+      let acc: Selector[] = [WILDCARD]
+      for (const child of node.children) acc = intersectSelectors(acc, permittedSelectors(child))
+      return acc
+    }
+    case 'or': {
+      // Any branch may hold, so the permitted set is the UNION. A union of
+      // over-approximations is still an over-approximation, so this keeps the
+      // fail-safe direction while staying tighter than the wildcard the
+      // default branch would give. Precision matters here: `or` is how a
+      // policy says "pair A or pair B", and widening that to the wildcard
+      // would report an overlap against every rule on the account.
+      const acc: Selector[] = []
+      for (const child of node.children) acc.push(...permittedSelectors(child))
+      return dedupe(acc)
+    }
+    case 'eq': {
+      const sel = selectorFromEq(node.left, node.right)
+      return sel === null ? [WILDCARD] : [sel]
+    }
+    case 'in': {
+      // Set membership over the selector halves: `call_fn in {a, b}` permits
+      // both. A haystack element that is not the matching literal kind makes
+      // the node uninformative rather than narrower.
+      if (node.needle.kind === 'call_contract') {
+        const addrs = node.haystack.map(literalAddress)
+        if (addrs.some((a) => a === null)) return [WILDCARD]
+        return dedupe((addrs as string[]).map((a) => ({ contract: a, fn: ANY })))
+      }
+      if (node.needle.kind === 'call_fn') {
+        const syms = node.haystack.map(literalSymbol)
+        if (syms.some((s) => s === null)) return [WILDCARD]
+        return dedupe((syms as string[]).map((s) => ({ contract: ANY, fn: s })))
+      }
+      return [WILDCARD]
+    }
+    default:
+      // `lte` binds an amount, never the selector.
+      return [WILDCARD]
+  }
+}
+
+/** Selectors a context type admits, before the predicate narrows them. */
+export function selectorsForContextType(ct: ContextType): Selector[] {
+  switch (ct.kind) {
+    case 'default':
+      return [WILDCARD]
+    case 'call_contract':
+      return [{ contract: ct.contract, fn: ANY }]
+    case 'create_contract':
+      // A contract-creation context is a different `Context` shape. The
+      // interpreter refuses anything that is not `Context::Contract`, and a
+      // creation rule can never serve a call, so it shares no selector.
+      return []
+  }
+}
+
+/** What a rule can actually authorise: its context type narrowed by its
+ *  predicate. An unpoliced or unreadable rule contributes no narrowing. */
+export function effectiveSelectors(rule: ObservedRule): Selector[] {
+  const fromType = selectorsForContextType(rule.contextType)
+  if (!rule.predicate) return fromType
+  return intersectSelectors(fromType, permittedSelectors(rule.predicate))
+}
+
+function classifyRule(rule: ObservedRule): RuleClass {
+  if (rule.policyAddresses.length === 0) return 'unpoliced'
+  return rule.predicate ? 'interpreter' : 'foreign'
+}
+
+function adviceFor(cls: RuleClass, ruleId: number): string {
+  switch (cls) {
+    case 'unpoliced':
+      return `rule ${ruleId} has no policy attached, so a shared signer may make these calls with no constraint at all - the predicate you are installing will never run for them. Remove the shared signer from rule ${ruleId}, or attach a policy to it.`
+    case 'foreign':
+      return `rule ${ruleId} is policed by a contract this tool cannot decode, so its authority over these calls is unknown. Review it by hand before relying on the new rule.`
+    case 'interpreter':
+      return `a shared signer may name rule ${ruleId} instead, so the new rule will not restrict these calls. To TIGHTEN, edit rule ${ruleId} itself rather than adding a second rule. To ADD a separate capability, keep both and expect neither to constrain the other.`
+  }
+}
+
+/**
+ * Every existing rule a signer of the intended install could name instead.
+ *
+ * A rule collides when it shares at least one signer AND at least one selector.
+ * Both are needed for the signer to have a choice: same signer but disjoint
+ * calls means no call can be rerouted, and same calls but no shared signer
+ * means nobody can reroute them.
+ */
+export function findAuthorityOverlaps(args: {
+  intended: IntendedInstall
+  existing: ObservedRule[]
+}): AuthorityOverlap[] {
+  const intendedSelectors = intersectSelectors(
+    selectorsForContextType(args.intended.contextType),
+    permittedSelectors(args.intended.predicate)
+  )
+  const out: AuthorityOverlap[] = []
+
+  for (const rule of args.existing) {
+    if (rule.id === args.intended.ruleId) continue
+
+    const shared = sharedSigners(args.intended.signers, rule.signers)
+    if (shared.length === 0) continue
+
+    const sharedSelectors = intersectSelectors(intendedSelectors, effectiveSelectors(rule))
+    if (sharedSelectors.length === 0) continue
+
+    const ruleClass = classifyRule(rule)
+    out.push({
+      ruleId: rule.id,
+      ruleClass,
+      severity:
+        ruleClass === 'unpoliced'
+          ? 'bypass'
+          : ruleClass === 'foreign'
+            ? 'unknown'
+            : 'not-restricting',
+      sharedSigners: shared,
+      sharedSelectors,
+      advice: adviceFor(ruleClass, rule.id),
+    })
+  }
+
+  return out
+}

package/src/install/index.ts

@@ -12,6 +12,26 @@
 // Exported here rather than from the package root to keep the root surface
 // about synthesis, and because these are transaction-building primitives whose
 // callers should know they are reaching for them.
+
+// Cross-rule authority analysis. Exported because the check has to happen
+// wherever an install is BUILT, and a client that assembles its own
+// `add_context_rule` call never reaches `runInstallPolicy`.
+export {
+  ANY,
+  type AuthorityOverlap,
+  type ContextType,
+  effectiveSelectors,
+  findAuthorityOverlaps,
+  type IntendedInstall,
+  intersectSelectors,
+  type ObservedRule,
+  type OverlapSeverity,
+  permittedSelectors,
+  type RuleClass,
+  type Selector,
+  selectorsForContextType,
+  signerKey,
+} from './authority-overlap.ts'
 export {
   ADD_CONTEXT_RULE_SYMBOL,
   type AddContextRuleArgs,

package/src/install/read-account-rules.ts

@@ -0,0 +1,313 @@
+//! Reading an OpenZeppelin smart account's context rules back off chain.
+//!
+//! `authority-overlap.ts` needs to know what a signer can already do before a
+//! new policy is installed. That means every rule on the account: its context
+//! type, its signers, its attached policies, and - for rules our interpreter
+//! polices - the predicate itself.
+//!
+//! Without this, the overlap scan can only report on rules the CALLER supplied,
+//! which means it answers "what did you tell me about" rather than "what is on
+//! the account". Those are different questions, and only the second one is
+//! worth anything to someone deciding whether to sign.
+//!
+//! The predicate is NOT reachable through a contract call. The interpreter
+//! publishes only `grammar_version`, `install`, `enforce`, `uninstall` and
+//! `rotate_master_signer_set`, so the stored document is read as a ledger entry
+//! instead. That keeps this a purely client-side capability: adding a getter
+//! would change a deployed contract's ABI and force a redeploy plus re-audit to
+//! obtain data the ledger already exposes.
+//!
+//! The decoders are pure so they can be tested without a network; the caller
+//! supplies raw `ScVal`s.
+
+import {
+  Account,
+  Address,
+  BASE_FEE,
+  Contract,
+  Keypair,
+  rpc,
+  TransactionBuilder,
+  xdr,
+} from '@stellar/stellar-sdk'
+import { decodePredicate } from '../predicate/decode.ts'
+import type { SignerDraft } from '../types.ts'
+import type { ContextType, ObservedRule } from './authority-overlap.ts'
+
+/** `storage.rs` - the third element of the persistent doc key tuple. */
+export const K_DOC = 1
+
+/** Persistent-storage key for a rule's stored document:
+ *  `(account, rule_id, K_DOC)`. */
+export function docKeyScVal(smartAccount: string, ruleId: number): xdr.ScVal {
+  return xdr.ScVal.scvVec([
+    new Address(smartAccount).toScVal(),
+    xdr.ScVal.scvU32(ruleId),
+    xdr.ScVal.scvU32(K_DOC),
+  ])
+}
+
+/** Ledger key for the interpreter's persistent entry holding that document. */
+export function docLedgerKey(
+  interpreter: string,
+  smartAccount: string,
+  ruleId: number
+): xdr.LedgerKey {
+  return xdr.LedgerKey.contractData(
+    new xdr.LedgerKeyContractData({
+      contract: new Address(interpreter).toScAddress(),
+      key: docKeyScVal(smartAccount, ruleId),
+      durability: xdr.ContractDataDurability.persistent(),
+    })
+  )
+}
+
+// ---- ScVal helpers -----
+
+/** Field of a `#[contracttype]` struct, which the host encodes as a map keyed
+ *  by field-name symbol. Returns undefined when the field is absent so a
+ *  caller can distinguish "not there" from "there and empty". */
+function mapField(v: xdr.ScVal, name: string): xdr.ScVal | undefined {
+  if (v.switch() !== xdr.ScValType.scvMap()) return undefined
+  for (const entry of v.map() ?? []) {
+    const key = entry.key()
+    if (key.switch() === xdr.ScValType.scvSymbol() && key.sym().toString() === name) {
+      return entry.val()
+    }
+  }
+  return undefined
+}
+
+function u32Of(v: xdr.ScVal | undefined): number | undefined {
+  return v?.switch() === xdr.ScValType.scvU32() ? v.u32() : undefined
+}
+
+function addressOf(v: xdr.ScVal | undefined): string | undefined {
+  if (!v || v.switch() !== xdr.ScValType.scvAddress()) return undefined
+  return Address.fromScAddress(v.address()).toString()
+}
+
+/** An enum variant of a `#[contracttype]` enum: `ScVal::Vec([Symbol, ...args])`. */
+function enumVariant(v: xdr.ScVal | undefined): { tag: string; args: xdr.ScVal[] } | undefined {
+  if (!v || v.switch() !== xdr.ScValType.scvVec()) return undefined
+  const items = v.vec() ?? []
+  const head = items[0]
+  if (!head || head.switch() !== xdr.ScValType.scvSymbol()) return undefined
+  return { tag: head.sym().toString(), args: items.slice(1) }
+}
+
+// ---- decoders -----
+
+/** OZ `ContextRuleType`. An unrecognised tag is reported as `default`, which
+ *  is the widest reading and therefore the safe one: it makes the rule look
+ *  like it could serve any call, so overlap is over-reported, never missed. */
+export function decodeContextType(v: xdr.ScVal | undefined): ContextType {
+  const variant = enumVariant(v)
+  if (!variant) return { kind: 'default' }
+  if (variant.tag === 'CallContract') {
+    const addr = addressOf(variant.args[0])
+    return addr ? { kind: 'call_contract', contract: addr } : { kind: 'default' }
+  }
+  if (variant.tag === 'CreateContract') {
+    const arg = variant.args[0]
+    const hash = arg?.switch() === xdr.ScValType.scvBytes() ? arg.bytes().toString('hex') : ''
+    return { kind: 'create_contract', wasmHash: hash }
+  }
+  return { kind: 'default' }
+}
+
+/** OZ `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
+export function decodeSigner(v: xdr.ScVal): SignerDraft | undefined {
+  const variant = enumVariant(v)
+  if (!variant) return undefined
+  if (variant.tag === 'Delegated') {
+    const addr = addressOf(variant.args[0])
+    return addr ? { kind: 'delegated', address: addr } : undefined
+  }
+  if (variant.tag === 'External') {
+    const verifier = addressOf(variant.args[0])
+    const keyArg = variant.args[1]
+    const keyBytes =
+      keyArg?.switch() === xdr.ScValType.scvBytes() ? keyArg.bytes().toString('hex') : ''
+    return verifier ? { kind: 'external', verifier, keyBytes } : undefined
+  }
+  return undefined
+}
+
+/** A full OZ `ContextRule` as returned by `get_context_rule(id)`.
+ *  `predicate` is filled in separately from the ledger entry. */
+export function decodeContextRule(v: xdr.ScVal): ObservedRule | undefined {
+  const id = u32Of(mapField(v, 'id'))
+  if (id === undefined) return undefined
+
+  const signersVal = mapField(v, 'signers')
+  const signers: SignerDraft[] = []
+  if (signersVal?.switch() === xdr.ScValType.scvVec()) {
+    for (const s of signersVal.vec() ?? []) {
+      const decoded = decodeSigner(s)
+      if (decoded) signers.push(decoded)
+    }
+  }
+
+  const policiesVal = mapField(v, 'policies')
+  const policyAddresses: string[] = []
+  if (policiesVal?.switch() === xdr.ScValType.scvVec()) {
+    for (const p of policiesVal.vec() ?? []) {
+      const addr = addressOf(p)
+      if (addr) policyAddresses.push(addr)
+    }
+  }
+
+  return {
+    id,
+    contextType: decodeContextType(mapField(v, 'context_type')),
+    signers,
+    policyAddresses,
+  }
+}
+
+/** The interpreter's `StoredDoc { predicate_bytes }`. */
+export function decodeStoredPredicateBytes(v: xdr.ScVal): Buffer | undefined {
+  const field = mapField(v, 'predicate_bytes')
+  if (!field || field.switch() !== xdr.ScValType.scvBytes()) return undefined
+  return field.bytes()
+}
+
+// ---- collection -----
+
+/** The three reads the scan needs. Kept as an interface so the collection
+ *  below is testable without a network. */
+export interface AccountRuleReader {
+  /** OZ `get_context_rules_count()`. */
+  getContextRuleCount(smartAccount: string): Promise<number>
+  /** OZ `get_context_rule(id)`. Undefined when the id is absent. */
+  getContextRule(smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>
+  /** The interpreter's persistent `StoredDoc` entry, read as a ledger entry.
+   *  Undefined when no document is stored for that rule. */
+  getStoredDoc(
+    interpreter: string,
+    smartAccount: string,
+    ruleId: number
+  ): Promise<xdr.ScVal | undefined>
+}
+
+/** How far the id scan will probe before giving up. OZ imposes no per-account
+ *  rule cap, so there is no exact bound to derive; this one is far above any
+ *  realistic account and keeps a malformed `Count` from spinning forever. */
+export const MAX_RULE_ID_SCAN = 512
+
+export interface CollectedRules {
+  rules: ObservedRule[]
+  /** Rule ids whose stored predicate could not be read even though the
+   *  interpreter is attached. Such a rule is reported without a predicate,
+   *  which classifies it as opaque rather than as safely narrow. */
+  unreadablePredicateRuleIds: number[]
+  /** True when the scan stopped before accounting for every live rule. The
+   *  result is then a SUBSET of the account's rules, so an empty overlap list
+   *  proves nothing and the caller must not present it as safety. */
+  incomplete: boolean
+}
+
+/**
+ * Every context rule on the account, with predicates filled in for the rules
+ * our interpreter polices.
+ *
+ * Rule ids are NOT contiguous. OZ assigns them from a monotonic `NextId` and
+ * decrements `Count` on removal without ever reusing an id, so after any
+ * removal `Count < NextId` and the live ids have gaps. Iterating `0..Count-1`
+ * would silently skip live rules at higher ids, and a skipped rule is a missed
+ * overlap - the one error that reports safety which does not exist. Instead the
+ * scan walks ids upward until it has accounted for `Count` live rules.
+ *
+ * A rule whose predicate cannot be read is deliberately left without one. That
+ * demotes it to the `foreign` class, so the scan reports it as opaque instead
+ * of assuming it is narrow.
+ */
+export async function collectObservedRules(args: {
+  reader: AccountRuleReader
+  smartAccount: string
+  interpreterAddress: string
+  maxRuleIdScan?: number
+}): Promise<CollectedRules> {
+  const count = await args.reader.getContextRuleCount(args.smartAccount)
+  const limit = args.maxRuleIdScan ?? MAX_RULE_ID_SCAN
+  const rules: ObservedRule[] = []
+  const unreadablePredicateRuleIds: number[] = []
+
+  let id = 0
+  while (rules.length < count && id < limit) {
+    const raw = await args.reader.getContextRule(args.smartAccount, id)
+    id++
+    if (!raw) continue
+    const rule = decodeContextRule(raw)
+    if (!rule) continue
+
+    if (rule.policyAddresses.includes(args.interpreterAddress)) {
+      const doc = await args.reader.getStoredDoc(
+        args.interpreterAddress,
+        args.smartAccount,
+        rule.id
+      )
+      const bytes = doc ? decodeStoredPredicateBytes(doc) : undefined
+      if (bytes) {
+        try {
+          rule.predicate = decodePredicate(bytes)
+        } catch {
+          unreadablePredicateRuleIds.push(rule.id)
+        }
+      } else {
+        unreadablePredicateRuleIds.push(rule.id)
+      }
+    }
+    rules.push(rule)
+  }
+
+  return { rules, unreadablePredicateRuleIds, incomplete: rules.length < count }
+}
+
+/**
+ * An `AccountRuleReader` over a live RPC server.
+ *
+ * The two OZ getters are read-only simulations: the source account is
+ * constructed locally because a simulation never checks its sequence number,
+ * and asking the network for a random key would 404.
+ *
+ * The stored document is fetched as a ledger entry rather than a contract
+ * call, because the interpreter publishes no getter for it.
+ */
+export function accountRuleReaderFromServer(
+  server: rpc.Server,
+  networkPassphrase: string
+): AccountRuleReader {
+  async function simulateCall(
+    contract: string,
+    method: string,
+    ...args: xdr.ScVal[]
+  ): Promise<xdr.ScVal | undefined> {
+    const account = new Account(Keypair.random().publicKey(), '0')
+    const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase })
+      .addOperation(new Contract(contract).call(method, ...args))
+      .setTimeout(30)
+      .build()
+    const sim = await server.simulateTransaction(tx)
+    if (rpc.Api.isSimulationError(sim)) return undefined
+    return sim.result?.retval
+  }
+
+  return {
+    async getContextRuleCount(smartAccount) {
+      const val = await simulateCall(smartAccount, 'get_context_rules_count')
+      return u32Of(val) ?? 0
+    },
+    async getContextRule(smartAccount, ruleId) {
+      return simulateCall(smartAccount, 'get_context_rule', xdr.ScVal.scvU32(ruleId))
+    },
+    async getStoredDoc(interpreter, smartAccount, ruleId) {
+      const key = docLedgerKey(interpreter, smartAccount, ruleId)
+      const res = await server.getLedgerEntries(key)
+      const entry = res.entries?.[0]?.val
+      if (!entry || entry.switch() !== xdr.LedgerEntryType.contractData()) return undefined
+      return entry.contractData().val()
+    },
+  }
+}