@crediolabs/policy-synth 0.1.11 → 0.1.13

package/dist/install/build-install-policy.js

@@ -0,0 +1,427 @@
+// src/install/build-install-policy.ts - builds the unsigned Soroban
+// transaction XDR for `account.add_context_rule(...)` and
+// `account.remove_context_rule(...)`.
+//
+// The MCP server is stateless and holds no key material (server.ts:10-12),
+// so this module NEVER signs. The caller (the wallet / CLI / SDK consumer)
+// wraps the returned XDR in a transaction envelope and signs that envelope
+// with their wallet; the wallet signature IS the user-confirmation step.
+//
+// We deliberately depart from the spec in plans/phase-04 which calls for a
+// two-call `install_policy`/`confirm_install` pair backed by a host-signed
+// short-TTL `action_id`. That contract requires (a) a stateful store and
+// (b) key material the server does not have, so we ship the simpler ONE-CALL
+// shape. The wallet signature covers the change.
+//
+// `buildInstallPolicyXdr` returns CALL 1 ONLY. Call 2 (interpreter.install)
+// needs the rule id the account assigns in call 1, so it cannot be pre-built
+// and is documented in the response envelope under `followUp`.
+import { createHash } from 'node:crypto';
+import { Address, BASE_FEE, Contract, Keypair, Operation, rpc, scValToBigInt, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
+import { buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION } from "./build-add-context-rule.js";
+/** Convert a real rpc.Server into the InstallRpcClient surface. The
+ *  `getContractVersion` lookup uses `simulateTransaction` against
+ *  `contract.call('grammar_version')` and decodes the returned u32.
+ *
+ *  The passphrase is a REQUIRED argument rather than something read off the
+ *  server: `rpc.Server` does not carry one, so reaching for
+ *  `server.networkPassphrase` yielded a non-string and every version probe
+ *  died with "Invalid passphrase provided to Transaction". The caller knows
+ *  which network it dialled; make it say so. */
+export function rpcClientFromServer(server, networkPassphrase) {
+    return {
+        getAccount: (address) => server.getAccount(address),
+        simulateTransaction: (tx) => server.simulateTransaction(tx),
+        getLatestLedger: () => server.getLatestLedger(),
+        async getContractVersion(address) {
+            // The source account is constructed locally rather than fetched. This is
+            // a read-only simulation, so the sequence number is never checked, and a
+            // random key does NOT exist on chain - asking the network for it returns
+            // 404 and the version probe fails for a reason that has nothing to do
+            // with the contract being probed.
+            const account = new Account(Keypair.random().publicKey(), '0');
+            const tx = new TransactionBuilder(account, {
+                fee: BASE_FEE,
+                networkPassphrase,
+            })
+                .addOperation(new Contract(address).call('grammar_version'))
+                .setTimeout(30)
+                .build();
+            const sim = await server.simulateTransaction(tx);
+            if (rpc.Api.isSimulationError(sim)) {
+                throw new Error(`getContractVersion: simulateTransaction failed: ${sim.error}`);
+            }
+            if (!sim.result?.retval) {
+                throw new Error('getContractVersion: grammar_version() returned no value');
+            }
+            const native = scValToBigInt(sim.result.retval);
+            if (typeof native !== 'bigint') {
+                throw new Error('getContractVersion: grammar_version() did not return an integer');
+            }
+            return Number(native);
+        },
+    };
+}
+const FOLLOWUP_HINT = 'after this tx confirms, read the rule id via account.get_context_rules_count()-1 (or get the receipt events), then call runInstallPolicy a second time with the interpreter as the target and the rule id in context_rule_ids - OR hand-build the install() call directly with the OZ auth pattern.';
+/** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
+ *  The output XDR is signed by the wallet, not by us. */
+export async function buildInstallPolicyXdr(args) {
+    // 1. Pure arg encoding first - fail closed on any limit / shape problem
+    //    BEFORE we burn a network round-trip on a malformed call.
+    const callArgs = buildAddContextRuleArgs({
+        contextRuleType: args.rule.contextRuleType,
+        name: args.rule.name,
+        validUntilLedger: args.rule.validUntilLedger,
+        signers: args.rule.signers,
+        policies: args.rule.policies.map(adaptPolicyRef),
+    }, {
+        signers: args.rule.signers,
+        policies: args.rule.policies.map(adaptPolicyRef),
+        installNonce: args.installNonce,
+        encodedPredicate: args.encodedPredicate,
+        predicateHash: args.predicateHash,
+        ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
+        ...(args.grammarVersion !== undefined ? { grammarVersion: args.grammarVersion } : {}),
+    });
+    // 2. Network pass: source account sequence + latest ledger.
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const latest = await args.rpc.getLatestLedger();
+    const validUntilLedger = latest.sequence + (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_LEDGERS);
+    // 3. Build the unsigned transaction envelope with the bare host call.
+    const op = Operation.invokeHostFunction({
+        func: xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+            contractAddress: new Address(args.smartAccount).toScAddress(),
+            functionName: 'add_context_rule',
+            args: [...callArgs],
+        })),
+        auth: [],
+    });
+    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
+    const tx = buildUnsignedTx({
+        sourceAccount: args.sourceAccount,
+        sequence: source.sequenceNumber(),
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+        op,
+    });
+    // 4. Simulation pass. Returns the auth nonce + rootInvocation the wallet
+    //    signature binds to. We do NOT add the AuthPayload here - the wallet
+    //    injects auth entries using its own __check_auth flow.
+    const recorded = await args.rpc.simulateTransaction(tx);
+    if (rpc.Api.isSimulationError(recorded)) {
+        // Short, stable reason. The full `simulateTransaction` error (which
+        // carries host + URL detail) stays in the SDK's own logs - never
+        // reflected back into a user-facing message where it would
+        // reconnoitre the RPC.
+        throw new Error('install_policy: simulateTransaction failed');
+    }
+    const original = (recorded.result?.auth ?? []).find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
+        Address.fromScAddress(entry.credentials().address().address()).toString() ===
+            args.smartAccount);
+    if (!original) {
+        throw new Error(`install_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
+    }
+    // 5. Decode the structured description FROM the unsigned XDR. The human
+    //    approval binds to the bytes the wallet will sign; deriving this from
+    //    the input args would re-describe the caller's intent rather than the
+    //    transaction. Re-parse the envelope we just built so the description
+    //    reflects what the wallet actually signs, not what we thought it would.
+    const describes = decodeInstallCallDescribes(tx, op, args.installNonce);
+    return {
+        unsignedXdr: tx.toEnvelope().toXDR().toString('base64'),
+        smartAccount: args.smartAccount,
+        sourceAccount: args.sourceAccount,
+        call: { contract: args.smartAccount, fn: 'add_context_rule' },
+        followUp: {
+            contract: 'interpreter',
+            fn: 'install',
+            requiresRuleIdFromCallOne: true,
+            hint: FOLLOWUP_HINT,
+        },
+        describes,
+        authNonce: original.credentials().address().nonce().toString(),
+        authValidUntilLedger: validUntilLedger,
+        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+    };
+}
+/** Build an unsigned XDR for `account.remove_context_rule(ruleId)`. The
+ *  smart account itself handles uninstalling each attached policy (calling
+ *  `interpreter.uninstall` for the interpreter policy); this builder only
+ *  emits the account-side removal call.
+ *
+ *  Who may authorise it is the ACCOUNT's decision, and the account's source is
+ *  not in this repo. The interpreter's own `uninstall` is master-gated, but
+ *  that is a different entry point from this one, so do not restate it as the
+ *  rule for this call. What is proven on testnet is that the account's
+ *  deployer can revoke. This builder does not pre-check the signer: it would
+ *  be guessing at a contract it cannot read, and the chain is the authority. */
+export async function buildRevokePolicyXdr(args) {
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const latest = await args.rpc.getLatestLedger();
+    const validUntilLedger = latest.sequence + (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_LEDGERS);
+    const op = Operation.invokeHostFunction({
+        func: xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+            contractAddress: new Address(args.smartAccount).toScAddress(),
+            functionName: 'remove_context_rule',
+            args: [xdr.ScVal.scvU32(args.ruleId)],
+        })),
+        auth: [],
+    });
+    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
+    const tx = buildUnsignedTx({
+        sourceAccount: args.sourceAccount,
+        sequence: source.sequenceNumber(),
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+        op,
+    });
+    const recorded = await args.rpc.simulateTransaction(tx);
+    if (rpc.Api.isSimulationError(recorded)) {
+        // Short, stable reason. The full `simulateTransaction` error (which
+        // carries host + URL detail) stays in the SDK's own logs - never
+        // reflected back into a user-facing message where it would
+        // reconnoitre the RPC.
+        throw new Error('revoke_policy: simulateTransaction failed');
+    }
+    const original = (recorded.result?.auth ?? []).find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
+        Address.fromScAddress(entry.credentials().address().address()).toString() ===
+            args.smartAccount);
+    if (!original) {
+        throw new Error(`revoke_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
+    }
+    return {
+        unsignedXdr: tx.toEnvelope().toXDR().toString('base64'),
+        smartAccount: args.smartAccount,
+        sourceAccount: args.sourceAccount,
+        call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
+        authNonce: original.credentials().address().nonce().toString(),
+        authValidUntilLedger: validUntilLedger,
+        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+    };
+}
+/** ~25 minutes at 5s/ledger. */
+const DEFAULT_AUTH_VALID_LEDGERS = 300;
+// ---- internals ----
+/** Adapter: turn the install-policy wire `PolicyRef` shape into the core
+ *  `PolicyRef` shape `buildAddContextRuleArgs` expects. Keeps the wire
+ *  schema hand-rolled + flat (the strict union would need a recursive
+ *  schema) while delegating to the proven encoder for the actual bytes. */
+function adaptPolicyRef(p) {
+    if (p.kind === 'interpreter') {
+        return {
+            kind: 'interpreter',
+            interpreterAddress: p.interpreterAddress,
+            predicateBlobBase64: p.predicateBlobBase64,
+        };
+    }
+    return {
+        kind: 'oz_builtin',
+        instanceAddress: p.instanceAddress,
+        primitive: p.primitive,
+    };
+}
+/** Build an unsigned Soroban transaction envelope. The `sequence` is
+ *  whatever `getAccount().sequenceNumber()` returned (a string of digits
+ *  the SDK accepts). No signing. The returned Transaction is what
+ *  `simulateTransaction` accepts. */
+function buildUnsignedTx(args) {
+    const account = new Account(args.sourceAccount, args.sequence);
+    const tx = new TransactionBuilder(account, {
+        fee: args.fee,
+        networkPassphrase: args.networkPassphrase,
+    })
+        .addOperation(args.op)
+        .setTimeout(0)
+        .build();
+    // `TransactionBuilder.build()` returns a Transaction whose envelope
+    // has empty signatures. The wallet re-reads the unsigned XDR, appends
+    // its signature, and broadcasts. We do NOT sign here.
+    return tx;
+}
+/** Decode the install call's structured fields directly out of the
+ *  built (transaction, operation) pair. The bytes are the source of
+ *  truth: a human reviewing the install wants to see what the wallet
+ *  will actually sign, not what we think it will. The decode is
+ *  deliberately strict - any shape we did not build ourselves throws
+ *  a ToolError, since that would mean the XDR was tampered with (or
+ *  the encoder changed and this descriptor lags).
+ *
+ *  `expectedInstallNonce` is a fallback for the rare case where the
+ *  install has no interpreter policy (no `install_nonce` to read); the
+ *  caller already knows it. */
+function decodeInstallCallDescribes(tx, op, expectedInstallNonce) {
+    const hostFn = op.body().invokeHostFunctionOp()?.hostFunction();
+    if (!hostFn || hostFn.switch().name !== 'hostFunctionTypeInvokeContract') {
+        throw new Error('install_policy: built op is not an invokeHostFunction(invokeContract(...)) call');
+    }
+    const invokeArgs = hostFn.invokeContract();
+    if (!invokeArgs) {
+        throw new Error('install_policy: built op has no InvokeContractArgs payload');
+    }
+    const targetContract = Address.fromScAddress(invokeArgs.contractAddress()).toString();
+    const fnName = invokeArgs.functionName().toString();
+    if (fnName !== 'add_context_rule') {
+        throw new Error(`install_policy: built op fn name is "${fnName}", expected "add_context_rule"`);
+    }
+    const scvArgs = invokeArgs.args();
+    if (scvArgs.length !== 5) {
+        throw new Error(`install_policy: built op has ${scvArgs.length} args, expected 5 (context_type, name, valid_until, signers, policies)`);
+    }
+    const contextType = scvArgs[0];
+    const nameScv = scvArgs[1];
+    const validUntilScv = scvArgs[2];
+    const signersScv = scvArgs[3];
+    const policiesScv = scvArgs[4];
+    // The length check above pins these as defined; the local references
+    // satisfy noUncheckedIndexedAccess on the accessors below.
+    if (!nameScv || !validUntilScv || !signersScv || !policiesScv || !contextType) {
+        throw new Error('install_policy: built op args include an undefined slot despite length check');
+    }
+    // name
+    if (nameScv.switch().name !== 'scvString') {
+        throw new Error('install_policy: args[1] (name) is not an ScVal::String');
+    }
+    const ruleName = nameScv.str().toString();
+    // valid_until (Option<u32> -> void when absent)
+    let validUntilLedger;
+    if (validUntilScv.switch().name === 'scvVoid') {
+        validUntilLedger = null;
+    }
+    else if (validUntilScv.switch().name === 'scvU32') {
+        validUntilLedger = validUntilScv.u32();
+    }
+    else {
+        throw new Error('install_policy: args[2] (valid_until) is neither void nor u32');
+    }
+    // signers (Vec<Vec<Symbol, Address[, Bytes]>>)
+    if (signersScv.switch().name !== 'scvVec') {
+        throw new Error('install_policy: args[3] (signers) is not an ScVal::Vec');
+    }
+    const signers = [];
+    for (const signerScv of signersScv.vec() ?? []) {
+        if (signerScv.switch().name !== 'scvVec') {
+            throw new Error('install_policy: a signer entry is not an ScVal::Vec');
+        }
+        const tuple = signerScv.vec() ?? [];
+        const tag = tuple[0]?.sym().toString();
+        const inner = tuple[1];
+        if (tag === 'Delegated') {
+            if (!inner || inner.switch().name !== 'scvAddress') {
+                throw new Error('install_policy: a Delegated signer is missing its Address');
+            }
+            signers.push({
+                kind: 'delegated',
+                address: Address.fromScAddress(inner.address()).toString(),
+            });
+            continue;
+        }
+        if (tag === 'External') {
+            if (!inner || inner.switch().name !== 'scvAddress') {
+                throw new Error('install_policy: an External signer is missing its verifier Address');
+            }
+            signers.push({
+                kind: 'external',
+                verifier: Address.fromScAddress(inner.address()).toString(),
+            });
+            continue;
+        }
+        throw new Error(`install_policy: signer tag "${tag ?? '<missing>'}" is not Delegated|External`);
+    }
+    // policies (Map<Address, Val>). Re-derive an interpreter-vs-OZ primitive
+    // classification by inspecting the value's map keys (PolicyInstallParams
+    // starts with `grammar_version`/`install_nonce`/`predicate`; OZ primitive
+    // params start with `spending_limit`/`threshold`/`period_ledgers`).
+    if (policiesScv.switch().name !== 'scvMap') {
+        throw new Error('install_policy: args[4] (policies) is not an ScVal::Map');
+    }
+    const policies = [];
+    let observedInstallNonce = null;
+    for (const entry of policiesScv.map() ?? []) {
+        const key = entry.key();
+        if (key.switch().name !== 'scvAddress') {
+            throw new Error('install_policy: a policies map entry has a non-Address key');
+        }
+        const address = Address.fromScAddress(key.address()).toString();
+        const val = entry.val();
+        if (val.switch().name !== 'scvMap') {
+            throw new Error(`install_policy: policies[${address}] value is not an ScVal::Map (got ${val.switch().name})`);
+        }
+        const fields = new Map();
+        for (const inner of val.map() ?? []) {
+            const fk = inner.key();
+            if (fk.switch().name !== 'scvSymbol') {
+                throw new Error(`install_policy: policies[${address}] field key is not an ScVal::Symbol`);
+            }
+            fields.set(fk.sym().toString(), inner.val());
+        }
+        // Interpreter policy fields carry grammar_version/install_nonce/predicate.
+        // OZ primitives carry spending_limit/period_ledgers/threshold/signers.
+        if (fields.has('predicate') || fields.has('grammar_version') || fields.has('install_nonce')) {
+            const installNonceScv = fields.get('install_nonce');
+            if (!installNonceScv || installNonceScv.switch().name !== 'scvU32') {
+                throw new Error(`install_policy: interpreter policy ${address} is missing a u32 install_nonce`);
+            }
+            const installNonce = installNonceScv.u32();
+            const predicateScv = fields.get('predicate');
+            if (!predicateScv || predicateScv.switch().name !== 'scvBytes') {
+                throw new Error(`install_policy: interpreter policy ${address} is missing its bytes predicate`);
+            }
+            const predicateBytes = Buffer.from(predicateScv.bytes());
+            const predicateSha256OfEmbeddedBytes = createHash('sha256')
+                .update(predicateBytes)
+                .digest('hex');
+            const predicateHashScv = fields.get('predicate_hash');
+            const predicateHash = predicateHashScv && predicateHashScv.switch().name === 'scvBytes'
+                ? Buffer.from(predicateHashScv.bytes()).toString('hex')
+                : '';
+            policies.push({
+                kind: 'interpreter',
+                address,
+                installNonce,
+                predicateHash,
+                predicateSha256OfEmbeddedBytes,
+            });
+            observedInstallNonce = installNonce;
+            continue;
+        }
+        // OZ built-in primitive. Distinguish by the parameter shape we
+        // emitted; matching one of the three primitives exactly pins the
+        // kind we built.
+        if (fields.has('spending_limit') && fields.has('period_ledgers')) {
+            policies.push({ kind: 'oz_builtin', address, primitive: 'spending_limit' });
+            continue;
+        }
+        if (fields.has('threshold') && fields.has('signer_weights')) {
+            policies.push({ kind: 'oz_builtin', address, primitive: 'weighted_threshold' });
+            continue;
+        }
+        if (fields.has('threshold')) {
+            policies.push({ kind: 'oz_builtin', address, primitive: 'simple_threshold' });
+            continue;
+        }
+        throw new Error(`install_policy: policies[${address}] value has an unknown field set; the encoder may have drifted`);
+    }
+    // `observedInstallNonce` is the nonce baked into whichever interpreter
+    // policy is present; when none, fall back to the caller-supplied value.
+    const installNonce = observedInstallNonce ?? expectedInstallNonce;
+    // Touch `tx` so the linter does not flag it as unused - the parameter
+    // documents that the caller built this Transaction; we re-parse the
+    // operation off it as a sanity check.
+    void tx;
+    return {
+        targetContract,
+        fnName: 'add_context_rule',
+        ruleName,
+        validUntilLedger,
+        signers,
+        policies,
+        installNonce,
+    };
+}
+/** Re-export so the run-layer does not need to import from
+ *  build-add-context-rule.ts (keeps the install/ -> install/ dependency
+ *  direction intact). */
+export { Contract, DEFAULT_GRAMMAR_VERSION };
+// Local re-import to avoid pulling the class from the SDK module path
+// at the top of the file (avoids the unused-import lint).
+import { Account } from '@stellar/stellar-sdk';

package/dist/install/get-interpreter-info.d.ts

@@ -0,0 +1,29 @@
+import type { Network } from '../types.ts';
+export interface InterpreterInfo {
+    /** Pinned interpreter contract address. */
+    pinnedAddress: string;
+    /** Pinned grammar version (matches SELF_VERSION in version.rs). */
+    pinnedGrammarVersion: number;
+    /** Pinned wasm sha256 (hex). */
+    pinnedWasmHash: string;
+    /** Network this pin applies to (the address + hash are network-scoped). */
+    network: Network;
+    /** Present only when the caller supplied a live `deployedGrammarVersion`. */
+    deployedGrammarVersion?: number;
+    /** True when `deployedGrammarVersion` matches `pinnedGrammarVersion`.
+     *  Absent when no live verification was performed. */
+    liveMatchesPin?: boolean;
+}
+/** Build the interpreter-info response. When `deployedGrammarVersion` is
+ *  supplied (after a live RPC `grammar_version()` call by the run layer),
+ *  compares it to the pin and sets `liveMatchesPin`. When absent, returns
+ *  the pin alone. */
+export declare function getInterpreterInfo(args: {
+    pinnedAddress: string;
+    pinnedGrammarVersion: number;
+    pinnedWasmHash: string;
+    network: Network;
+    /** When supplied, the u32 returned by the live contract's
+     *  `grammar_version()` RPC call. */
+    deployedGrammarVersion?: number;
+}): InterpreterInfo;

package/dist/install/get-interpreter-info.js

@@ -0,0 +1,41 @@
+// src/install/get-interpreter-info.ts - read-only fingerprint lookup for
+// the interpreter contract.
+//
+// Returns the pinned deployment fingerprint + (optionally) compares a
+// caller-supplied live `grammar_version` against the pin. No fabricated
+// audit field; a real deployed-contract check is worth more than a fake
+// reference.
+//
+// Per design decision 5: phase-04's "audit #44" is aspirational and has no
+// source-of-truth in the repo. Returning a fabricated audit id would be a
+// lie on a security surface. The honest outputs are:
+//   - the pinned address (DEPLOYMENTS.md)
+//   - the pinned grammar version (SELF_VERSION in version.rs)
+//   - the pinned wasm sha256 (DEPLOYMENTS.md)
+//   - an OPTIONAL `deployedGrammarVersion` returned by a live `grammar_version()`
+//     RPC call, with a `liveMatchesPin` boolean the caller can dispatch on. A
+//     mismatch means the deployed wasm is NOT the pinned artifact - the caller
+//     should refuse to install until they redeploy.
+//
+// The RPC plumbing lives in the run layer (`run/index.ts`); this module
+// stays pure so it is testable without a network.
+/** Build the interpreter-info response. When `deployedGrammarVersion` is
+ *  supplied (after a live RPC `grammar_version()` call by the run layer),
+ *  compares it to the pin and sets `liveMatchesPin`. When absent, returns
+ *  the pin alone. */
+export function getInterpreterInfo(args) {
+    const info = {
+        pinnedAddress: args.pinnedAddress,
+        pinnedGrammarVersion: args.pinnedGrammarVersion,
+        pinnedWasmHash: args.pinnedWasmHash,
+        network: args.network,
+    };
+    if (typeof args.deployedGrammarVersion === 'number') {
+        return {
+            ...info,
+            deployedGrammarVersion: args.deployedGrammarVersion,
+            liveMatchesPin: args.deployedGrammarVersion === args.pinnedGrammarVersion,
+        };
+    }
+    return info;
+}

package/dist/ir/types.d.ts

@@ -85,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/predicate/index.d.ts

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

package/dist/predicate/index.js

@@ -1,6 +1,6 @@
 // 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.
-export { encodePredicate } from "./encode.js";
 export { decodeLeaf, decodeNode, decodePredicate } from "./decode.js";
+export { encodePredicate } from "./encode.js";
 export { jsonToAst } from "./from-json.js";

package/dist/review-card/builder.js

@@ -192,6 +192,38 @@ function renderComparison(node) {
         const allowed = node.op === 'lt' ? right.value : right.value + 1;
         return `At most ${allowed} calls per ${left.windowSecs} seconds`;
     }
+    // OP(call_arg[i], <scalar literal>) -> arg[i] OP <value>
+    //
+    // The per-call cap. It has to be here because the `amount` template below
+    // is unreachable for an interpreter policy: `amount` is deliberately not in
+    // the contract's grammar (dsl.rs - the interpreter sees one authorized
+    // call, not the transaction's token movements), so a predicate using it is
+    // refused at install. A bound on the call's own amount ARGUMENT is how a
+    // cap is actually written, and it was rendering nothing at all - the card
+    // silently understated the policy.
+    //
+    // Placed after the literal_vec case above so an exact-sequence `eq` still
+    // reads as a path rather than as a comparison.
+    if (left.kind === 'call_arg') {
+        const head = `arg[${left.index}]`;
+        const sep = node.op === 'eq' ? '=' : comparisonOpText(node.op);
+        if (right.kind === 'literal_i128')
+            return `${head} ${sep} ${right.value}`;
+        if (right.kind === 'literal_u64')
+            return `${head} ${sep} ${right.value}`;
+        if (right.kind === 'literal_u32')
+            return `${head} ${sep} ${right.value}`;
+        if (right.kind === 'literal_address')
+            return `${head} ${sep} ${right.value}`;
+        if (right.kind === 'literal_symbol')
+            return `${head} ${sep} ${right.value}`;
+        if (right.kind === 'literal_bytes')
+            return `${head} ${sep} ${right.value}`;
+        // call_arg_scaled is the slippage floor and reads as itself.
+        if (right.kind === 'call_arg_scaled') {
+            return `${head} >= arg[${right.index}] * ${right.num}/${right.den}`;
+        }
+    }
     // amount <= v -> Amount <= v
     if (left.kind === 'amount' && right.kind === 'literal_i128') {
         return `Amount <= ${right.value}`;

package/dist/review-card/cross-check.js

@@ -112,6 +112,26 @@ function pushComparison(left, right, op, out) {
         out.push(`At most ${allowed} calls per ${left.windowSecs} seconds`);
         return;
     }
+    // Mirrors the builder's per-call cap line. Both sides must render the same
+    // string: cross-check compares the summary against the predicate, so a
+    // shape only ONE of them renders would read as a dropped constraint.
+    if (left.kind === 'call_arg') {
+        const head = `arg[${left.index}]`;
+        const sep = op === 'eq' ? '=' : comparisonOpText(op);
+        if (right.kind === 'literal_i128' ||
+            right.kind === 'literal_u64' ||
+            right.kind === 'literal_u32' ||
+            right.kind === 'literal_address' ||
+            right.kind === 'literal_symbol' ||
+            right.kind === 'literal_bytes') {
+            out.push(`${head} ${sep} ${right.value}`);
+            return;
+        }
+        if (right.kind === 'call_arg_scaled') {
+            out.push(`${head} >= arg[${right.index}] * ${right.num}/${right.den}`);
+            return;
+        }
+    }
     if (left.kind === 'amount' && right.kind === 'literal_i128') {
         out.push(`Amount <= ${right.value}`);
         return;