@crediolabs/policy-synth 0.1.10 → 0.1.12

package/dist-cjs/install/build-add-context-rule.js

@@ -0,0 +1,308 @@
+"use strict";
+// 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)`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADD_CONTEXT_RULE_SYMBOL = exports.DEFAULT_GRAMMAR_VERSION = void 0;
+exports.buildAddContextRuleArgs = buildAddContextRuleArgs;
+const node_crypto_1 = require("node:crypto");
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const types_ts_1 = require("../types.js");
+exports.DEFAULT_GRAMMAR_VERSION = 1;
+/** The verb `add_context_rule` takes on the wire. */
+exports.ADD_CONTEXT_RULE_SYMBOL = 'add_context_rule';
+/** Build the `add_context_rule` invocation args. Throws a `ToolError`-shaped
+ *  error on limit breaches or malformed input. */
+function buildAddContextRuleArgs(draft, args) {
+    // ---- 1. Cap checks (fail-closed before any encoding) ----
+    if (args.signers.length > types_ts_1.OZ_LIMITS.maxSignersPerRule) {
+        throw limitError('INSTALL_BUILD_FAILED', `signers ${args.signers.length} exceed MAX_SIGNERS_PER_RULE ${types_ts_1.OZ_LIMITS.maxSignersPerRule}`);
+    }
+    if (args.policies.length > types_ts_1.OZ_LIMITS.maxPoliciesPerRule) {
+        throw limitError('INSTALL_BUILD_FAILED', `policies ${args.policies.length} exceed MAX_POLICIES_PER_RULE ${types_ts_1.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 = stellar_sdk_1.xdr.ScVal.scvString(draft.name);
+    const validUntil = draft.validUntilLedger === null ? stellar_sdk_1.xdr.ScVal.scvVoid() : stellar_sdk_1.xdr.ScVal.scvU32(draft.validUntilLedger);
+    // ---- 4. signers ----
+    const signersVec = stellar_sdk_1.xdr.ScVal.scvVec(args.signers.map(encodeSigner));
+    // ---- 5. policies Map<Address, Val> ----
+    const policies = encodePoliciesMap(args);
+    return [contextType, name, validUntil, signersVec, policies];
+}
+// ---- 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',
+];
+function encodeContextRuleType(rule) {
+    switch (rule.kind) {
+        case 'default':
+            return stellar_sdk_1.xdr.ScVal.scvVec([stellar_sdk_1.xdr.ScVal.scvSymbol('Default')]);
+        case 'call_contract':
+            return stellar_sdk_1.xdr.ScVal.scvVec([
+                stellar_sdk_1.xdr.ScVal.scvSymbol('CallContract'),
+                stellar_sdk_1.Address.fromString(rule.contract).toScVal(),
+            ]);
+        case 'create_contract':
+            return stellar_sdk_1.xdr.ScVal.scvVec([
+                stellar_sdk_1.xdr.ScVal.scvSymbol('CreateContract'),
+                stellar_sdk_1.xdr.ScVal.scvBytes(Buffer.from(rule.wasmHash, 'hex')),
+            ]);
+    }
+}
+function encodeSigner(s) {
+    switch (s.kind) {
+        case 'delegated':
+            return stellar_sdk_1.xdr.ScVal.scvVec([
+                stellar_sdk_1.xdr.ScVal.scvSymbol('Delegated'),
+                stellar_sdk_1.Address.fromString(s.address).toScVal(),
+            ]);
+        case 'external':
+            return stellar_sdk_1.xdr.ScVal.scvVec([
+                stellar_sdk_1.xdr.ScVal.scvSymbol('External'),
+                stellar_sdk_1.Address.fromString(s.verifier).toScVal(),
+                stellar_sdk_1.xdr.ScVal.scvBytes(Buffer.from(s.keyBytes, 'hex')),
+            ]);
+    }
+}
+function encodePoliciesMap(args) {
+    const entries = [];
+    for (const ref of args.policies) {
+        if (ref.kind === 'interpreter') {
+            const val = encodePolicyInstallParams(args);
+            entries.push(new stellar_sdk_1.xdr.ScMapEntry({
+                key: stellar_sdk_1.Address.fromString(ref.interpreterAddress).toScVal(),
+                val,
+            }));
+        }
+        if (ref.kind === 'oz_builtin') {
+            entries.push(new stellar_sdk_1.xdr.ScMapEntry({
+                key: stellar_sdk_1.Address.fromString(ref.instanceAddress).toScVal(),
+                val: encodeOzPrimitiveParams(ref.primitive),
+            }));
+        }
+    }
+    entries.sort(sortByScValSymbolString);
+    return stellar_sdk_1.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) {
+    const entries = [];
+    const push = (name, val) => entries.push(new stellar_sdk_1.xdr.ScMapEntry({ key: stellar_sdk_1.xdr.ScVal.scvSymbol(name), val }));
+    const p = primitive.params;
+    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', stellar_sdk_1.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', stellar_sdk_1.xdr.ScVal.scvU32(threshold));
+            break;
+        }
+        case 'weighted_threshold': {
+            const threshold = p.threshold;
+            const weights = p.weights;
+            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 stellar_sdk_1.xdr.ScMapEntry({
+                key: stellar_sdk_1.Address.fromString(addr).toScVal(),
+                val: stellar_sdk_1.xdr.ScVal.scvU32(w),
+            }))
+                .sort((a, b) => (a.key().toXDR('base64') < b.key().toXDR('base64') ? -1 : 1));
+            push('signer_weights', stellar_sdk_1.xdr.ScVal.scvMap(weightEntries));
+            push('threshold', stellar_sdk_1.xdr.ScVal.scvU32(threshold));
+            break;
+        }
+    }
+    entries.sort((a, b) => sortBySymbolString(a.key(), b.key()));
+    return stellar_sdk_1.xdr.ScVal.scvMap(entries);
+}
+function encodeI128(value) {
+    const v = BigInt(value);
+    return stellar_sdk_1.xdr.ScVal.scvI128(new stellar_sdk_1.xdr.Int128Parts({
+        hi: new stellar_sdk_1.xdr.Int64(BigInt.asIntN(64, v >> 64n)),
+        lo: new stellar_sdk_1.xdr.Uint64(BigInt.asUintN(64, v)),
+    }));
+}
+function encodePolicyInstallParams(args) {
+    const predicate = Buffer.from(args.encodedPredicate, 'base64');
+    const computedHash = (0, node_crypto_1.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 = [];
+    for (const k of POLICY_INSTALL_PARAM_FIELDS) {
+        const key = stellar_sdk_1.xdr.ScVal.scvSymbol(k);
+        switch (k) {
+            case 'grammar_version':
+                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
+                    key,
+                    val: stellar_sdk_1.xdr.ScVal.scvU32(args.grammarVersion ?? exports.DEFAULT_GRAMMAR_VERSION),
+                }));
+                break;
+            case 'install_nonce':
+                entries.push(new stellar_sdk_1.xdr.ScMapEntry({ key, val: stellar_sdk_1.xdr.ScVal.scvU32(args.installNonce) }));
+                break;
+            case 'predicate':
+                entries.push(new stellar_sdk_1.xdr.ScMapEntry({ key, val: stellar_sdk_1.xdr.ScVal.scvBytes(predicate) }));
+                break;
+            case 'predicate_hash':
+                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
+                    key,
+                    val: stellar_sdk_1.xdr.ScVal.scvBytes(Buffer.from(args.predicateHash, 'hex')),
+                }));
+                break;
+            case 'oracle_max_staleness_seconds':
+                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
+                    key,
+                    val: encodeOptionU32(args.oracleParams?.maxStalenessSeconds),
+                }));
+                break;
+            case 'oracle_max_deviation_bps':
+                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
+                    key,
+                    val: encodeOptionU32(args.oracleParams?.maxDeviationBps),
+                }));
+                break;
+            case 'oracle_max_xfeed_dev_bps':
+                entries.push(new stellar_sdk_1.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 stellar_sdk_1.xdr.ScVal.scvMap(entries);
+}
+function encodeOptionU32(v) {
+    if (v === undefined)
+        return stellar_sdk_1.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 stellar_sdk_1.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, b) {
+    return sortBySymbolString(a.key(), b.key());
+}
+function sortBySymbolString(a, b) {
+    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, message) {
+    const err = new Error(message);
+    err.code = code;
+    err.severity = 'error';
+    err.retryable = false;
+    throw err;
+}

package/dist-cjs/ir/types.d.ts

@@ -53,6 +53,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
  *  nesting + `not` + `in` + `eq_seq` so the same IR can later lower to the OZ
@@ -81,6 +85,25 @@ export type IRCondition = {
     op: 'eq_seq';
     selector: IRSelector;
     values: string[];
+}
+/** A swap's output floor, expressed against its own input: the output arg
+ *  must be at least `inArgIndex * num / den`.
+ *
+ *  It is its own construct because `compare` bounds a selector against a
+ *  CONSTANT, and a slippage floor has no constant to bound against - the
+ *  acceptable output depends on the input of the same call. Encoding the
+ *  recorded output as a constant would pin a policy to one trade size.
+ *
+ *  `num/den` is the caller's minimum acceptable output per unit of input.
+ *  It is never derived from the recording: the recorded rate is a price at
+ *  one moment, and freezing it as policy would deny normal trades later.
+ *  Adapters that cannot express it (the OZ built-ins) flag it `uncovered`. */
+ | {
+    op: 'slippage_floor';
+    outArgIndex: number;
+    inArgIndex: number;
+    num: string;
+    den: string;
 };
 export interface IRPolicyRule {
     /** NEAR-V2 roles whitelist (empty = any; owner exempt). */

package/dist-cjs/predicate/decode.d.ts

@@ -0,0 +1,11 @@
+import { xdr } from '@stellar/stellar-sdk';
+import type { PredicateLeaf, PredicateNode } from '../types.ts';
+/** One leaf. Order of the bare-literal checks mirrors `decode_leaf` in dsl.rs. */
+export declare function decodeLeaf(v: xdr.ScVal): PredicateLeaf;
+/** One node. `not` wraps a NODE; the comparison ops wrap two LEAVES. */
+export declare function decodeNode(v: xdr.ScVal): PredicateNode;
+/** 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 declare function decodePredicate(encoded: string | Uint8Array): PredicateNode;

package/dist-cjs/predicate/decode.js

@@ -0,0 +1,239 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeLeaf = decodeLeaf;
+exports.decodeNode = decodeNode;
+exports.decodePredicate = decodePredicate;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+/** 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) {
+    const err = new Error(`cannot decode predicate: ${detail}`);
+    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) {
+    const head = items[0];
+    if (!head)
+        return null;
+    return head.switch() === stellar_sdk_1.xdr.ScValType.scvSymbol() ? head.sym().toString() : null;
+}
+function expectVec(v, what) {
+    if (v.switch() !== stellar_sdk_1.xdr.ScValType.scvVec())
+        throw malformed(`${what} is not a vec`);
+    return v.vec() ?? [];
+}
+function expectU32(v, what) {
+    if (!v || v.switch() !== stellar_sdk_1.xdr.ScValType.scvU32())
+        throw malformed(`${what} is not a u32`);
+    return v.u32();
+}
+function expectSymbol(v, what) {
+    if (!v || v.switch() !== stellar_sdk_1.xdr.ScValType.scvSymbol())
+        throw malformed(`${what} is not a symbol`);
+    return v.sym().toString();
+}
+function expectAddress(v, what) {
+    if (!v || v.switch() !== stellar_sdk_1.xdr.ScValType.scvAddress())
+        throw malformed(`${what} is not an address`);
+    return stellar_sdk_1.Address.fromScAddress(v.address()).toString();
+}
+function expectU64(v, what) {
+    if (!v || v.switch() !== stellar_sdk_1.xdr.ScValType.scvU64())
+        throw malformed(`${what} is not a u64`);
+    return v.u64().toString();
+}
+function expectI128(v, what) {
+    if (!v || v.switch() !== stellar_sdk_1.xdr.ScValType.scvI128())
+        throw malformed(`${what} is not an i128`);
+    return (0, stellar_sdk_1.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, n, selector) {
+    if (items.length !== n) {
+        throw malformed(`${selector} expects ${n} elements, got ${items.length}`);
+    }
+}
+function decodeSelectorLeaf(items, sym) {
+    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. */
+function decodeLeaf(v) {
+    if (v.switch() === stellar_sdk_1.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 stellar_sdk_1.xdr.ScValType.scvAddress():
+            return { kind: 'literal_address', value: stellar_sdk_1.Address.fromScAddress(v.address()).toString() };
+        case stellar_sdk_1.xdr.ScValType.scvSymbol():
+            return { kind: 'literal_symbol', value: v.sym().toString() };
+        case stellar_sdk_1.xdr.ScValType.scvU32():
+            return { kind: 'literal_u32', value: v.u32() };
+        case stellar_sdk_1.xdr.ScValType.scvU64():
+            return { kind: 'literal_u64', value: v.u64().toString() };
+        case stellar_sdk_1.xdr.ScValType.scvI128():
+            return { kind: 'literal_i128', value: (0, stellar_sdk_1.scValToBigInt)(v).toString() };
+        case stellar_sdk_1.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. */
+function decodeNode(v) {
+    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], `${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]) };
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+            arity(items, 3, op);
+            return {
+                op,
+                left: decodeLeaf(items[1]),
+                right: decodeLeaf(items[2]),
+            };
+        case 'in': {
+            arity(items, 3, op);
+            return {
+                op: 'in',
+                needle: decodeLeaf(items[1]),
+                haystack: expectVec(items[2], '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`. */
+function decodePredicate(encoded) {
+    let scv;
+    try {
+        scv =
+            typeof encoded === 'string'
+                ? stellar_sdk_1.xdr.ScVal.fromXDR(Buffer.from(encoded, 'base64'))
+                : stellar_sdk_1.xdr.ScVal.fromXDR(Buffer.from(encoded));
+    }
+    catch (e) {
+        throw malformed(`not valid ScVal XDR (${e instanceof Error ? e.message : String(e)})`);
+    }
+    return decodeNode(scv);
+}