@crediolabs/policy-synth 0.1.9 → 0.1.11

package/dist/adapters/interpreter/adapter.js

@@ -47,7 +47,10 @@ export const ORACLE_DEFAULTS = {
 const CAPABILITIES = {
     supportsSpendWindow: true,
     supportsThreshold: false, // thresholds are the OZ adapter's job
-    supportsTimeExpiry: true, // via valid_until ledger expiry
+    // False for the predicate-leaf path: the interpreter refuses a `valid_until`
+    // leaf at install. Expiry is still available, but as the context rule's
+    // validUntilLedger, which the smart account enforces - not as a predicate.
+    supportsTimeExpiry: false,
     supportsOraclePrice: true,
     supportsInvocationCount: true,
     supportsGeneralPredicate: true,
@@ -216,26 +219,61 @@ function lowerRule(rule, config) {
 function unsupportedConstruct(cond) {
     switch (cond.op) {
         case 'in':
-            return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
-                ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
-                : null;
+            // The oracle position rule is a hard error and must be raised before a
+            // construct can be written off as uncovered - otherwise a subtree that
+            // is BOTH misplaced-oracle and unsourceable would be silently dropped
+            // instead of rejected.
+            assertNoOracleDescendants(cond);
+            return (unsourceableSelector(cond.selector) ??
+                (cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+                    ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
+                    : null));
         case 'eq_seq':
-            return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
-                ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
-                : null;
+            return (unsourceableSelector(cond.selector) ??
+                (cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+                    ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
+                    : null));
         case 'compare': {
             const s = cond.compare.selector;
             if (s.kind === 'calldata')
                 return 'EVM calldata comparison (predicate DSL)';
             if (s.kind === 'value')
                 return 'tx.value comparison (predicate DSL)';
-            return null;
+            // The on-chain interpreter sees ONE authorized call - there is no
+            // `Context.sub_invocations` in v1 - so it cannot observe the
+            // transaction's token movements. `amount` has no value to read, and
+            // `window_spent` accumulates BY that amount, so its counter would never
+            // move. Deriving either from the call payload would quietly swap "value
+            // actually moved" for "value the caller declared" - a weaker guarantee
+            // than the review card would be claiming.
+            //
+            // Rolling spend caps belong to the OZ `spending_limit` primitive, which
+            // is already audited and which the OZ adapter emits. A per-call cap is
+            // expressible here as `arg_field`; bounding it with `invocation_count`
+            // gives an enforceable ceiling per window.
+            return unsourceableSelector(s);
         }
+        // Recurse: a nested `and`/`or`/`not` must not smuggle a selector past the
+        // pre-scan, which only sees top-level constraints.
         case 'and':
+            return cond.children.map(unsupportedConstruct).find((u) => u !== null) ?? null;
         case 'or':
+            assertNoOracleDescendants(cond);
+            return cond.children.map(unsupportedConstruct).find((u) => u !== null) ?? null;
         case 'not':
-            return null;
+            assertNoOracleDescendants(cond);
+            return unsupportedConstruct(cond.child);
+    }
+}
+/** Selectors whose value the on-chain interpreter has no way to obtain. */
+function unsourceableSelector(s) {
+    if (s.kind === 'amount') {
+        return `per-call amount comparison on ${s.token} - the interpreter cannot observe token movements; express a per-call cap with arg_field, or a rolling cap with the OZ spending_limit primitive`;
+    }
+    if (s.kind === 'window_spent') {
+        return `rolling spend cap on ${s.token} over ${s.windowSeconds}s - not enforceable by the interpreter; use the OZ spending_limit primitive, or bound per-call value with arg_field plus invocation_count`;
     }
+    return null;
 }
 /** Lower one IR condition to a PredicateNode. Enforces the oracle position
  *  rule (oracle_price leaves must sit directly under the top-level `and`) and
@@ -311,10 +349,13 @@ function lowerSelector(s) {
             return { kind: 'call_arg_len', index: s.argIndex };
         case 'arg_field':
             return { kind: 'call_arg_field', index: s.argIndex, element: s.element, field: s.field };
+        // `amount` / `window_spent` are filtered out by `unsupportedConstruct`
+        // before lowering - the interpreter cannot source either on chain. Reaching
+        // here means the pre-scan was bypassed, so fail loudly rather than emit a
+        // leaf the contract will refuse.
         case 'amount':
-            return { kind: 'amount', token: s.token };
         case 'window_spent':
-            return { kind: 'window_spent', token: s.token, windowSeconds: s.windowSeconds };
+            throw new Error(`interpreter adapter cannot lower \`${s.kind}\`: it should have been reported as uncovered`);
         case 'invocation_count':
             return { kind: 'invocation_count_in_window', windowSecs: s.windowSeconds };
         case 'now':
@@ -341,6 +382,16 @@ function lowerSelector(s) {
  *    - invocation_count -> u32 (counts are small non-negative integers)
  *    - now / valid_until -> u64 (unix timestamps in seconds) */
 function literalFromIRCompare(c) {
+    // An oracle comparand is not a bare literal: the interpreter refuses one,
+    // because assuming it shares the normalised 9-dp basis is what made a raw
+    // 14-dp threshold permit everything it was written to deny.
+    if (c.selector.kind === 'oracle_price') {
+        if (c.valueDecimals === undefined) {
+            throw toolError('ORACLE_THRESHOLD_BASIS_REQUIRED', 'An oracle price bound must declare the decimal basis of its threshold ' +
+                '(oracle prices normalise to 9 decimals).');
+        }
+        return { kind: 'oracle_threshold', value: c.value, decimals: c.valueDecimals };
+    }
     const scalarType = selectorScalarType(c.selector);
     return literalFromScalar(c.value, scalarType);
 }

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = 'RECORDING_FAILED' | 'RECORDING_VALIDATION_FAILED' | 'SCOPE_UNRESOLVED' | 'SYNTHESIS_ERROR' | 'MALFORMED_PREDICATE' | 'SIMULATION_ERROR' | 'VERIFICATION_FAILED' | 'DENY_CASE_FAILURE' | 'PERMIT_CASE_FAILED' | 'SUMMARY_DRIFT' | 'INSTALL_BUILD_FAILED' | 'INSTALL_CONFIRM_MISSING' | 'INSTALL_CONFIRM_EXPIRED' | 'REVOKE_BUILD_FAILED' | 'REVOKE_CONFIRM_MISSING' | 'USER_REJECTED_SIGN' | 'WALLET_TIMEOUT' | 'WALLET_UNAVAILABLE' | 'PREDICATE_TOO_LARGE' | 'PREDICATE_TOO_DEEP' | 'TOO_MANY_LEAVES' | 'IN_OPERAND_LIMIT' | 'PREDICATE_ORACLE_OVER_LIMIT' | 'POLICY_CAP_EXCEEDED' | 'WASM_TOO_LARGE' | 'MASTER_AUTH_REQUIRED' | 'NONCE_REPLAY' | 'VERSION_MISMATCH' | 'ARITHMETIC_OVERFLOW' | 'AMOUNT_OVERFLOW' | 'RULE_SIGNERS_CHANGED' | 'SCOPE_SELF_CALL' | 'ORACLE_STALE' | 'ORACLE_MISSING' | 'ORACLE_DEVIATION_EXCEEDED' | 'ORACLE_MALFORMED_HISTORY' | 'ORACLE_FINGERPRINT_DRIFT' | 'ORACLE_PAUSED' | 'ORACLE_LEAF_INVALID_POSITION' | 'ORACLE_PARAMS_OUT_OF_RANGE' | 'ORACLE_DECIMALS_MISMATCH' | 'COMPILE_OK' | 'COMPILE_GATE_FAILED';
+export type ErrorCode = 'RECORDING_FAILED' | 'RECORDING_VALIDATION_FAILED' | 'SCOPE_UNRESOLVED' | 'SYNTHESIS_ERROR' | 'MALFORMED_PREDICATE' | 'SIMULATION_ERROR' | 'VERIFICATION_FAILED' | 'DENY_CASE_FAILURE' | 'PERMIT_CASE_FAILED' | 'SUMMARY_DRIFT' | 'INSTALL_BUILD_FAILED' | 'INSTALL_CONFIRM_MISSING' | 'INSTALL_CONFIRM_EXPIRED' | 'REVOKE_BUILD_FAILED' | 'REVOKE_CONFIRM_MISSING' | 'USER_REJECTED_SIGN' | 'WALLET_TIMEOUT' | 'WALLET_UNAVAILABLE' | 'PREDICATE_TOO_LARGE' | 'PREDICATE_TOO_DEEP' | 'TOO_MANY_LEAVES' | 'IN_OPERAND_LIMIT' | 'PREDICATE_ORACLE_OVER_LIMIT' | 'POLICY_CAP_EXCEEDED' | 'WASM_TOO_LARGE' | 'MASTER_AUTH_REQUIRED' | 'NONCE_REPLAY' | 'VERSION_MISMATCH' | 'ARITHMETIC_OVERFLOW' | 'AMOUNT_OVERFLOW' | 'RULE_SIGNERS_CHANGED' | 'SCOPE_SELF_CALL' | 'ARG_MISMATCH' | 'CONTRACT_SCOPE' | 'UNSUPPORTED_NODE' | 'STATEFUL_BOUND' | 'NOT_IN_ALLOWLIST' | 'FREQUENCY' | 'SLIPPAGE_FLOOR' | 'ORACLE_STALE' | 'ORACLE_MISSING' | 'ORACLE_NO_CONFIRMATION' | 'ORACLE_DEVIATION_EXCEEDED' | 'ORACLE_MALFORMED_HISTORY' | 'ORACLE_FINGERPRINT_DRIFT' | 'ORACLE_PAUSED' | 'ORACLE_LEAF_INVALID_POSITION' | 'ORACLE_PARAMS_OUT_OF_RANGE' | 'ORACLE_DECIMALS_MISMATCH' | 'ORACLE_THRESHOLD_DECIMALS_OUT_OF_RANGE' | 'ORACLE_THRESHOLD_BASIS_REQUIRED' | 'COMPILE_OK' | 'COMPILE_GATE_FAILED';
 export interface ToolError {
     code: ErrorCode;
     message: string;

package/dist/install/build-add-context-rule.d.ts

@@ -0,0 +1,48 @@
+import { xdr } from '@stellar/stellar-sdk';
+import { type ContextRuleDraft, 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 declare const DEFAULT_GRAMMAR_VERSION: 1;
+/** The verb `add_context_rule` takes on the wire. */
+export declare const ADD_CONTEXT_RULE_SYMBOL: "add_context_rule";
+/** 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 declare function buildAddContextRuleArgs(draft: ContextRuleDraft, args: BuildAddContextRuleArgs): AddContextRuleArgs;

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

@@ -0,0 +1,304 @@
+// 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 { OZ_LIMITS, } from "../types.js";
+export const DEFAULT_GRAMMAR_VERSION = 1;
+/** The verb `add_context_rule` takes on the wire. */
+export const 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. */
+export function buildAddContextRuleArgs(draft, args) {
+    // ---- 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];
+}
+// ---- 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 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) {
+    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) {
+    const entries = [];
+    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) {
+    const entries = [];
+    const push = (name, val) => entries.push(new xdr.ScMapEntry({ key: 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', 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;
+            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) {
+    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) {
+    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 = [];
+    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) {
+    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, 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/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

package/dist/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;