@crediolabs/policy-synth 0.1.10 → 0.1.11

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

package/dist-cjs/predicate/encode.js

@@ -19,6 +19,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.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.encodePredicate = encodePredicate;
 const node_crypto_1 = require("node:crypto");
@@ -48,6 +61,9 @@ function encodePredicate(node) {
     if (oracleReads > types_ts_1.PREDICATE_CAPS.MAX_ORACLE_READS) {
         throw capError('PREDICATE_ORACLE_OVER_LIMIT', `oracle reads ${oracleReads} exceed MAX_ORACLE_READS ${types_ts_1.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);
     const rawBytes = root.toXDR();
@@ -61,19 +77,30 @@ function encodePredicate(node) {
 function computeStats(node) {
     const inCounts = [];
     const oracleAssets = new Set();
-    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, inCounts, oracleAssets) {
+function walk(node, inCounts, oracleAssets, counters, 
+/** 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) {
     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;
@@ -81,7 +108,7 @@ function walk(node, inCounts, oracleAssets) {
             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':
@@ -89,16 +116,19 @@ function walk(node, inCounts, oracleAssets) {
         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 {
@@ -120,16 +150,26 @@ function leafCount(leaf) {
     }
     return 1;
 }
-function collectOracle(leaf, oracleAssets) {
+function collectOracle(leaf, oracleAssets, counters, negatedOrDisjunctive) {
     // 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);
+            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;
     }
 }
 function encodeNode(node) {
@@ -179,6 +219,17 @@ function encodeLeaf(leaf) {
                 stellar_sdk_1.xdr.ScVal.scvU32(leaf.element),
                 stellar_sdk_1.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 stellar_sdk_1.xdr.ScVal.scvVec([
+                symbol('call_arg_scaled'),
+                stellar_sdk_1.xdr.ScVal.scvU32(leaf.index),
+                scvI128FromDecimal(leaf.num),
+                scvI128FromDecimal(leaf.den),
+            ]);
         case 'amount':
             return stellar_sdk_1.xdr.ScVal.scvVec([symbol('amount'), scvAddressFromStrkey(leaf.token)]);
         case 'window_spent':
@@ -190,11 +241,25 @@ function encodeLeaf(leaf) {
         case 'now':
             return stellar_sdk_1.xdr.ScVal.scvVec([symbol('now')]);
         case 'valid_until':
-            return stellar_sdk_1.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 stellar_sdk_1.xdr.ScVal.scvVec([symbol('invocation_count'), scvU64FromValue(leaf.windowSecs)]);
         case 'oracle_price':
             return stellar_sdk_1.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 stellar_sdk_1.xdr.ScVal.scvVec([
+                symbol('oracle_threshold'),
+                scvI128FromDecimal(leaf.value),
+                stellar_sdk_1.xdr.ScVal.scvU32(leaf.decimals),
+            ]);
         case 'literal_address':
             return scvAddressFromStrkey(leaf.value);
         case 'literal_i128':

package/dist-cjs/predicate/from-json.d.ts

@@ -0,0 +1,4 @@
+import type { 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 declare function jsonToAst(value: unknown): PredicateNode;

package/dist-cjs/predicate/from-json.js

@@ -0,0 +1,116 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonToAst = jsonToAst;
+/** Parse a JSON object back into a `PredicateNode`. Throws on shape
+ *  mismatches. The encoder's structural caps are the real gate. */
+function jsonToAst(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('predicate must be an object');
+    const v = value;
+    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(v, f) {
+    if (!Array.isArray(v))
+        throw new Error('expected array');
+    return v.map(f);
+}
+function jsonToLeaf(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('leaf must be an object');
+    const v = value;
+    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, key) {
+    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, key) {
+    const x = v[key];
+    if (typeof x !== 'string')
+        throw new Error(`field ${key} must be a string`);
+    return x;
+}

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

@@ -1 +1,3 @@
 export { type EncodedPredicate, encodePredicate } from './encode.ts';
+export { decodeLeaf, decodeNode, decodePredicate } from './decode.ts';
+export { jsonToAst } from './from-json.ts';

package/dist-cjs/predicate/index.js

@@ -1,6 +1,14 @@
 "use strict";
-// 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.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.encodePredicate = void 0;
+exports.jsonToAst = exports.decodePredicate = exports.decodeNode = exports.decodeLeaf = exports.encodePredicate = void 0;
 var encode_ts_1 = require("./encode.js");
 Object.defineProperty(exports, "encodePredicate", { enumerable: true, get: function () { return encode_ts_1.encodePredicate; } });
+var decode_ts_1 = require("./decode.js");
+Object.defineProperty(exports, "decodeLeaf", { enumerable: true, get: function () { return decode_ts_1.decodeLeaf; } });
+Object.defineProperty(exports, "decodeNode", { enumerable: true, get: function () { return decode_ts_1.decodeNode; } });
+Object.defineProperty(exports, "decodePredicate", { enumerable: true, get: function () { return decode_ts_1.decodePredicate; } });
+var from_json_ts_1 = require("./from-json.js");
+Object.defineProperty(exports, "jsonToAst", { enumerable: true, get: function () { return from_json_ts_1.jsonToAst; } });

package/dist-cjs/registry/identify.js

@@ -17,6 +17,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
@@ -49,7 +56,19 @@ function identifyProtocol(contract, method, args, network) {
         }
         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(protocols_ts_1.OZ_ACCOUNT_ABI, method)) {
+        const sig = protocols_ts_1.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) {

package/dist-cjs/registry/protocols.d.ts

@@ -1,5 +1,5 @@
 import type { ScVal } from '../types.ts';
-export type ProtocolId = 'sep41' | 'blend' | 'soroswap';
+export type ProtocolId = 'sep41' | 'blend' | 'soroswap' | 'oz_account';
 /** ScVal subset type vocabulary the ABI uses. Mirrors `ScVal['type']` minus
  *  `other` (which by definition cannot be matched against an ABI arg). */
 export type AbiArgType = Exclude<ScVal['type'], 'other'>;
@@ -34,5 +34,54 @@ export declare const BLEND_ABI: ProtocolAbi;
  *  `vec<address>` - we record it as the outer `vec` subset and leave the
  *  per-element shape to the downstream reviewer. */
 export declare const SOROSWAP_ABI: ProtocolAbi;
+/** OpenZeppelin smart-account ABI subset.
+ *
+ *  Why this lives in the recogniser: every user's smart account has a
+ *  different C-address, so a per-deployment pin would never cover them.
+ *  What is the same across every OpenZeppelin multisig account is the
+ *  small set of public context-rule entrypoints. A recording that
+ *  invokes `batch_add_signer(u32, vec<signer>)` on an arbitrary contract
+ *  is overwhelmingly likely to be calling the user's own OpenZeppelin
+ *  smart account (the canonical reason this product exists); we
+ *  recognise that pattern by interface, the same way SEP-41 is
+ *  recognised by interface.
+ *
+ *  SECURITY PROPERTY (load-bearing):
+ *   - Recognition claims the call TARGETS a particular protocol. We
+ *     only claim `oz_account` when the (fn, args) shape uniquely matches
+ *     one of the three entrypoints below AND the call looks like a real
+ *     context-rule operation. The match is exact: off-by-one arg count,
+ *     off-by-one arg type, or a method name close-but-wrong returns null
+ *     (fail-closed). A contract that incidentally happens to expose a
+ *     single matching fn is not sufficient - the recorder requires ALL
+ *     invocations to individually match, so a hostile contract with
+ *     exactly one matching fn would still contribute to the unknown
+ *     bucket for any other calls.
+ *   - We do NOT claim `oz_account` for unknown calls, for arg-shape
+ *     mismatches, or for calls where the recorder could not pin down
+ *     the (fn, args) shape. The freshness gate then runs at the same
+ *     1.0 threshold - lowering the gate for unknown protocols remains
+ *     a separate, opt-in production override (see RecordInput below).
+ *
+ *  ABI source: packages/policy-interpreter/tests/fixtures/multisig_account_example.wasm,
+ *  pinned from the OpenZeppelin Reloaded `multisig_account_example`
+ *  contract (commit ef82b65, fetched 2026-07-28).
+ *
+ *  SCOPE NOTE: this ABI only covers the three entrypoints whose args
+ *  map cleanly onto the normalised `AbiArgType` vocabulary (u32, vec,
+ *  ...). `add_context_rule` - the install path - takes `(Symbol,
+ *  String, Option<u32>, Vec<SignerKey>, Map<Address, Val>)`. The
+ *  `String`, `Option<u32>` (`scvVoid`), and `Map<...>` arg types are
+ *  not in the AbiArgType set today (the recogniser's `argsMatchAbi`
+ *  helper rejects `other` deliberately so a close-but-wrong call does
+ *  not slip through). Excluding `add_context_rule` is the right
+ *  trade-off for now - it never blocks OZ smart-account recognition,
+ *  because the install tx always follows a recognised
+ *  `batch_add_signer` (the demo's first-pass tx), so the
+ *  contract still ends up in `knownContracts`. Updating the Arg type
+ *  vocabulary to cover these shapes is a separate concern (and would
+ *  also lift the SEP-41 / Blend recognition in the same change).
+ */
+export declare const OZ_ACCOUNT_ABI: ProtocolAbi;
 export declare const PROTOCOL_ABIS: Record<ProtocolId, ProtocolAbi>;
 export declare function getAbi(protocol: ProtocolId): ProtocolAbi;