@crediolabs/policy-synth 1.0.0 → 1.1.1

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

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.rpcClientFromServer = rpcClientFromServer;
 exports.buildInstallPolicyXdr = buildInstallPolicyXdr;
 exports.buildRevokePolicyXdr = buildRevokePolicyXdr;
+exports.simulationReason = simulationReason;
 const node_crypto_1 = require("node:crypto");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const build_add_context_rule_ts_1 = require("./build-add-context-rule.js");
@@ -67,6 +68,14 @@ function rpcClientFromServer(server, networkPassphrase) {
         },
     };
 }
+/** `unsignedXdr` plus the length and digest that prove it arrived whole. */
+function xdrIntegrity(unsignedXdr) {
+    return {
+        unsignedXdr,
+        unsignedXdrLength: unsignedXdr.length,
+        unsignedXdrSha256: (0, node_crypto_1.createHash)('sha256').update(unsignedXdr, 'utf8').digest('hex'),
+    };
+}
 /** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
  *  The output XDR is signed by the wallet, not by us. */
 async function buildInstallPolicyXdr(args) {
@@ -95,7 +104,7 @@ async function buildInstallPolicyXdr(args) {
     //    The human approval binds to the exact bytes the wallet will sign.
     const describes = decodeInstallCallDescribes(finalTx, args.installNonce);
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'add_context_rule' },
@@ -124,7 +133,7 @@ async function buildRevokePolicyXdr(args) {
     // consumer supplies only the ordinary envelope signature.
     const { finalTx, original, validUntilLedger } = await buildAuthorisedSmartAccountTx(args, 'remove_context_rule', [stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId)], 'revoke_policy');
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
@@ -136,6 +145,21 @@ async function buildRevokePolicyXdr(args) {
 /** ~25 minutes at 5s/ledger. */
 const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300;
 // ---- internals ----
+/** The actionable half of a failed simulation, with the transport half left out.
+ *
+ *  `sim.error` names both why the chain refused the call and which host was
+ *  asked, and the second half must not reach a caller. So we return only
+ *  Soroban's own `Error(Type, #Code)` forms: those are contract state, and they
+ *  are what tells an operator whether the source account lacks authority, a
+ *  nonce is stale, or a predicate refused. Without them "simulateTransaction
+ *  failed" names nothing a caller can act on.
+ *
+ *  Returns "" when the error carries no such form, so the caller keeps its short
+ *  stable message rather than gaining an empty parenthesis. */
+function simulationReason(sim) {
+    const codes = [...new Set((sim.error ?? '').match(/Error\([^)]*\)/g) ?? [])];
+    return codes.length > 0 ? ` (${codes.join(', ')})` : '';
+}
 /** Record a bare call to the smart account, attach the deploy-time admin rule's
  *  auth entries, and re-simulate to assemble the footprint.
  *
@@ -165,8 +189,10 @@ async function buildAuthorisedSmartAccountTx(args, functionName, callArgs, error
         // 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(`${errorPrefix}: simulateTransaction failed`);
+        // reconnoitre the RPC. `simulationReason` re-adds only the chain's own
+        // error codes, which say why the call was refused without saying where
+        // the RPC lives.
+        throw new Error(`${errorPrefix}: simulateTransaction failed${simulationReason(recorded)}`);
     }
     const original = (recorded.result?.auth ?? []).find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
         stellar_sdk_1.Address.fromScAddress(entry.credentials().address().address()).toString() ===
@@ -185,7 +211,7 @@ async function buildAuthorisedSmartAccountTx(args, functionName, callArgs, error
     const txWithAuth = buildTx(makeOperation(authEntries));
     const enforcing = await args.rpc.simulateTransaction(txWithAuth);
     if (stellar_sdk_1.rpc.Api.isSimulationError(enforcing)) {
-        throw new Error(`${errorPrefix}: auth simulateTransaction failed`);
+        throw new Error(`${errorPrefix}: auth simulateTransaction failed${simulationReason(enforcing)}`);
     }
     return {
         finalTx: stellar_sdk_1.rpc.assembleTransaction(txWithAuth, enforcing).build(),
@@ -359,6 +385,27 @@ function decodeInstallCallDescribes(tx, expectedInstallNonce) {
             observedInstallNonce = installNonce;
             continue;
         }
+        // OpenZeppelin `spending_limit`: { period_ledgers: u32, spending_limit: i128 }.
+        if (fields.has('period_ledgers') || fields.has('spending_limit')) {
+            const periodScv = fields.get('period_ledgers');
+            if (periodScv?.switch().name !== 'scvU32') {
+                throw new Error(`install_policy: spending_limit policy ${address} is missing a u32 period_ledgers`);
+            }
+            const limitScv = fields.get('spending_limit');
+            if (limitScv?.switch().name !== 'scvI128') {
+                throw new Error(`install_policy: spending_limit policy ${address} is missing an i128 spending_limit`);
+            }
+            const parts = limitScv.i128();
+            const spendingLimit = ((BigInt(parts.hi().toString()) << 64n) +
+                BigInt(parts.lo().toString())).toString();
+            policies.push({
+                kind: 'spending_limit',
+                address,
+                periodLedgers: periodScv.u32(),
+                spendingLimit,
+            });
+            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

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

@@ -1,3 +1,4 @@
+import { xdr } from '@stellar/stellar-sdk';
 import { type PredicateNode } from '../types.ts';
 export interface EncodedPredicate {
     /** base64 of the canonical ScVal XDR of the predicate root. */
@@ -8,3 +9,14 @@ export interface EncodedPredicate {
 /** Encode a `PredicateNode` to the canonical ScVal wire format and hash it.
  *  Pure function: same input -> byte-identical output every run. */
 export declare function encodePredicate(node: PredicateNode): EncodedPredicate;
+/** Build `ScVal::I128(Int128Parts{hi, lo})` from a signed decimal string.
+ *  `Int128Parts` encodes the value as `(hi << 64) + lo` with `hi` a SIGNED
+ *  64-bit int and `lo` an UNSIGNED 64-bit int (this is NOT signed-magnitude).
+ *  The inverse split is `hi = v >> 64n` (arithmetic right shift) and
+ *  `lo = v & 0xFFFF...`. The SDK's `Int64` constructor takes a signed
+ *  bigint/string/number. */
+/** Canonical i128 encoding of a base-10 decimal string, with the Int64 range
+ *  guard on the high word. Exported so the install builder encodes an
+ *  OpenZeppelin amount the same way a predicate literal is encoded - a second
+ *  implementation is how a value above 2^64 silently loses its high word. */
+export declare function scvI128FromDecimal(decimal: string): xdr.ScVal;

package/dist-cjs/predicate/encode.js

@@ -20,6 +20,7 @@
 //
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.encodePredicate = encodePredicate;
+exports.scvI128FromDecimal = scvI128FromDecimal;
 const node_crypto_1 = require("node:crypto");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const types_ts_1 = require("../types.js");
@@ -234,6 +235,10 @@ function scvAddressFromStrkey(strkey) {
  *  The inverse split is `hi = v >> 64n` (arithmetic right shift) and
  *  `lo = v & 0xFFFF...`. The SDK's `Int64` constructor takes a signed
  *  bigint/string/number. */
+/** Canonical i128 encoding of a base-10 decimal string, with the Int64 range
+ *  guard on the high word. Exported so the install builder encodes an
+ *  OpenZeppelin amount the same way a predicate literal is encoded - a second
+ *  implementation is how a value above 2^64 silently loses its high word. */
 function scvI128FromDecimal(decimal) {
     const v = BigInt(decimal);
     const hi = v >> 64n;

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

@@ -2,7 +2,7 @@ import { type ErrorCode, type PredicateNode, type ProposedPolicy, type RecordedT
 import { type AuthorityOverlap } from '../install/authority-overlap.ts';
 import { type BuildInstallPolicyResult, type BuildRevokePolicyResult } from '../install/build-install-policy.ts';
 import { getInterpreterInfo } from '../install/get-interpreter-info.ts';
-import { type RecordTransactionInput, type SimulatePolicyInput, type SynthesizePolicyInput, type VerifyPolicyInput } from './schemas.ts';
+import { type InstallPolicyInput, type RecordTransactionInput, type SimulatePolicyInput, type SynthesizePolicyInput, type VerifyPolicyInput } from './schemas.ts';
 export type { DeclarePolicyInput, GetInterpreterInfoInput, InstallPolicyInput, OzBuiltinPolicy, RecordTransactionInput, RevokePolicyInput, SimulatePolicyInput, SynthesizePolicyInput, VerifyPolicyInput, } from './schemas.ts';
 export { ComposeUserResponsesSchema, DeclarePolicyInputSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MAINNET_RPC_URL, NetworkSchema, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_MAINNET_ADDRESS, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256, PINNED_OZ_POLICY_ADDRESS_BY_NETWORK, PINNED_OZ_POLICY_WASM_SHA256, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, } from './schemas.ts';
 export type RunRecordTransactionInput = RecordTransactionInput;
@@ -51,13 +51,22 @@ export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<Bui
  *  policy payload, so the interpreter pin is not re-checked here.
  *  Pin selection follows `input.network` (defaults to `testnet`). */
 export declare function runRevokePolicy(raw: unknown): Promise<ToolResponse<BuildRevokePolicyResult>>;
+/** Scope a rule to whatever contract its predicate pins.
+ *
+ *  Taking this from the predicate rather than from a separate argument means
+ *  the rule's scope cannot drift from what the predicate actually checks. A
+ *  predicate that pins no contract yields the default (account-wide) type,
+ *  which is what an unpinned predicate means. Only the top level is walked:
+ *  a contract pin nested under an `or` does not scope the rule, because the
+ *  other branch would not be covered by it. */
+export declare function contextTypeForPredicate(predicate: PredicateNode): NonNullable<InstallPolicyInput['rule']>['contextRuleType'];
 /** `simulate_policy` body - evaluate a predicate against one recorded call.
  *
  *  The evaluator is a second implementation of the on-chain semantics, and the
  *  conformance harness asserts it agrees with the Rust interpreter case for
  *  case. A verdict here is therefore a claim about what the contract would do,
  *  not a guess. */
-export declare function runSimulatePolicy(raw: unknown): ToolResponse<{
+export declare function runSimulatePolicy(raw: unknown): Promise<ToolResponse<{
     permitted: boolean;
     reason: string | null;
     call: {
@@ -65,7 +74,7 @@ export declare function runSimulatePolicy(raw: unknown): ToolResponse<{
         fn: string;
         argCount: number;
     };
-}>;
+}>>;
 /** `declare_policy` body - the DECLARATIVE front-end.
  *
  *  `synthesize_policy` infers a predicate from a transaction that happened;
@@ -92,7 +101,7 @@ export declare function runDeclarePolicy(raw: unknown): ToolResponse<{
  *  very transaction it was synthesised from. A deny case that permits means it
  *  is too LOOSE: some mutation of that transaction still gets through. `ok` is
  *  true only when neither holds. */
-export declare function runVerifyPolicy(raw: unknown): ToolResponse<{
+export declare function runVerifyPolicy(raw: unknown): Promise<ToolResponse<{
     ok: boolean;
     permit: {
         permitted: boolean;
@@ -104,6 +113,6 @@ export declare function runVerifyPolicy(raw: unknown): ToolResponse<{
         reason: string | null;
     }>;
     dimensionsCovered: number;
-}>;
+}>>;
 export declare function runGetInterpreterInfo(raw: unknown): Promise<ToolResponse<ReturnType<typeof getInterpreterInfo>>>;
 export declare function caughtError(toolName: RunToolName, code: ErrorCode, e: unknown): ToolError;

package/dist-cjs/run/index.js

@@ -23,6 +23,7 @@ exports.runRecordTransaction = runRecordTransaction;
 exports.runSynthesizePolicy = runSynthesizePolicy;
 exports.runInstallPolicy = runInstallPolicy;
 exports.runRevokePolicy = runRevokePolicy;
+exports.contextTypeForPredicate = contextTypeForPredicate;
 exports.runSimulatePolicy = runSimulatePolicy;
 exports.runDeclarePolicy = runDeclarePolicy;
 exports.runVerifyPolicy = runVerifyPolicy;
@@ -30,6 +31,7 @@ exports.runGetInterpreterInfo = runGetInterpreterInfo;
 exports.caughtError = caughtError;
 const node_crypto_1 = require("node:crypto");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const adapter_ts_1 = require("../adapters/interpreter/adapter.js");
 const index_ts_1 = require("../index.js");
 const authority_overlap_ts_1 = require("../install/authority-overlap.js");
 const build_install_policy_ts_1 = require("../install/build-install-policy.js");
@@ -130,7 +132,24 @@ async function runSynthesizePolicy(raw) {
     }
     const input = parsed.data;
     try {
-        const recorded = input.recordedTx;
+        // `hash` is the agent-friendly alternative to `recordedTx`: re-record here
+        // rather than make the caller retype a recording it cannot copy faithfully.
+        // A recording failure is returned as-is, so the caller sees why the hash was
+        // refused instead of a synthesis error about a payload it never sent.
+        let recorded;
+        if (input.recordedTx === undefined) {
+            const rerecorded = await runRecordTransaction({
+                hash: input.transactionHash,
+                network: input.network,
+            });
+            if (!rerecorded.ok) {
+                return { ok: false, error: rerecorded.error };
+            }
+            recorded = rerecorded.data;
+        }
+        else {
+            recorded = input.recordedTx;
+        }
         return await (0, index_ts_1.synthesizeFromRecording)(recorded, {
             network: input.network,
             ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
@@ -152,10 +171,143 @@ async function runInstallPolicy(raw) {
     }
     const input = parsed.data;
     const network = input.network ?? 'testnet';
+    // `fromHash` builds the rule here rather than accepting a transcribed copy.
+    // The pinning gates below then run against the rule we just synthesized, so
+    // this path is gated identically to a caller-supplied one - it is a shortcut
+    // for the caller, never for the checks.
+    let rule = input.rule;
+    if (rule === undefined && input.fromPredicate !== undefined) {
+        const fp = input.fromPredicate;
+        let scope;
+        try {
+            scope = contextTypeForPredicate((0, decode_ts_1.decodePredicate)(fp.encodedPredicate));
+        }
+        catch (e) {
+            return toolFailure('install_policy', e);
+        }
+        rule = {
+            contextRuleType: scope,
+            name: fp.name ?? 'policy',
+            validUntilLedger: fp.validUntilLedger ?? null,
+            signers: fp.signers.map((address) => ({ kind: 'delegated', address })),
+            policies: [
+                {
+                    kind: 'interpreter',
+                    interpreterAddress: schemas_ts_1.PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network],
+                    predicateBlobBase64: fp.encodedPredicate,
+                },
+            ],
+        };
+    }
+    if (rule === undefined) {
+        // Typed rather than inline: every tool body takes `unknown`, so a
+        // misspelled key here would compile and fail only at runtime, as a
+        // validation error blamed on the caller. Naming the type restores the
+        // check on this hop.
+        const synthArgs = {
+            source: 'recording',
+            network,
+            transactionHash: input.fromHash?.transactionHash,
+            interpreter: { smartAccountAddress: input.smartAccount },
+            ...(input.fromHash?.userResponses !== undefined
+                ? { userResponses: input.fromHash.userResponses }
+                : {}),
+        };
+        const synthesized = await runSynthesizePolicy(synthArgs);
+        if (!synthesized.ok) {
+            return { ok: false, error: synthesized.error };
+        }
+        // The synthesizer saw a spend it could not bound. Installing anyway yields
+        // a rule that reads as a cap and enforces nothing, and nothing downstream
+        // catches it: it installs cleanly and verifies cleanly, because a missing
+        // constraint generates no deny case that could fail. That combination
+        // reached the chain once. Refuse rather than emit a warning to skim past.
+        const unbounded = synthesized.data.ambiguities.some((a) => a.code === 'AMOUNT_BOUND_MISSING');
+        if (unbounded && input.allowUnboundedAmount !== true) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: 'install_policy: the recorded call spends an amount this policy does not bound, so the rule would constrain everything about the call except how much it moves; set `fromHash.userResponses.limitAmount` to the per-call cap, or `allowUnboundedAmount: true` to install an unbounded rule deliberately',
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        // Synthesis leaves the signer set empty - it reads a transaction, and which
+        // keys a rule binds is a security decision no single recording answers.
+        // The caller names them here.
+        rule = {
+            ...synthesized.data.contextRule,
+            signers: (input.fromHash?.signers ?? []).map((address) => ({
+                kind: 'delegated',
+                address,
+            })),
+        };
+    }
+    // A rule that governs no key is refused on chain, and the refusal arrives as
+    // a bare contract error code with nothing to act on. Say what is missing
+    // instead, while the caller still has the recording in hand.
+    if (rule.signers.length === 0) {
+        return {
+            ok: false,
+            error: {
+                code: 'INSTALL_BUILD_FAILED',
+                message: 'install_policy: the rule names no signer, so it would govern no key; name the keys it applies to',
+                severity: 'error',
+                retryable: false,
+                remediation: { toolCall: { name: 'install_policy', args: {} } },
+            },
+        };
+    }
     // ---- Pinning gates (default-deny) ----
     const expectedInterpreter = schemas_ts_1.PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network];
     const expectedRpc = schemas_ts_1.RPC_URL_BY_NETWORK[network];
-    const pinningError = enforceInterpreterPin(input.rule.policies, input.allowUnpinnedInterpreter, expectedInterpreter);
+    // Synthesis stamps every interpreter policy with the placeholder marker: it
+    // is handed a recording, not a network, so it emits a marker rather than
+    // inventing a deploy address. Install DOES know the network, and resolves
+    // the pin just above, so it fills the marker in here - otherwise the
+    // synthesize -> install path is unreachable, because the marker is not a
+    // strkey and fails the pin on every call. Only the exact marker is replaced;
+    // a caller-supplied address is still checked against the pin unchanged, so
+    // this widens nothing.
+    rule = {
+        ...rule,
+        policies: rule.policies.map((p) => p.kind === 'interpreter' && p.interpreterAddress === adapter_ts_1.PLACEHOLDER_INTERPRETER_ADDRESS
+            ? { ...p, interpreterAddress: expectedInterpreter }
+            : p),
+    };
+    // A rolling total, when asked for. The predicate bounds each call; this
+    // bounds the sum across calls, which is state the interpreter does not keep.
+    // Both sit on the one rule and compose as all-of.
+    if (input.spendingLimit !== undefined) {
+        if (rule.contextRuleType.kind !== 'call_contract') {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: `install_policy: a spending limit meters transfers of one token, so the rule must be scoped to that token's contract; this rule's scope is "${rule.contextRuleType.kind}"`,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        rule = {
+            ...rule,
+            policies: [
+                ...rule.policies,
+                {
+                    kind: 'spending_limit',
+                    policyAddress: schemas_ts_1.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
+                    periodLedgers: input.spendingLimit.periodLedgers,
+                    spendingLimit: input.spendingLimit.amount,
+                },
+            ],
+        };
+    }
+    const pinningError = enforceInterpreterPin(rule.policies, input.allowUnpinnedInterpreter, expectedInterpreter);
     if (pinningError) {
         return { ok: false, error: pinningError };
     }
@@ -171,7 +323,7 @@ async function runInstallPolicy(raw) {
         return toolFailure('install_policy', e);
     }
     try {
-        const interpreterPolicy = input.rule.policies.find((p) => p.kind === 'interpreter');
+        const interpreterPolicy = rule.policies.find((p) => p.kind === 'interpreter');
         const encodedPredicate = interpreterPolicy?.predicateBlobBase64 ?? '';
         const predicateHash = (0, node_crypto_1.createHash)('sha256')
             .update(Buffer.from(encodedPredicate, 'base64'))
@@ -180,8 +332,10 @@ async function runInstallPolicy(raw) {
             smartAccount: input.smartAccount,
             sourceAccount: input.sourceAccount,
             networkPassphrase: schemas_ts_1.NETWORK_PASSPHRASES[network],
-            rule: input.rule,
-            installNonce: input.installNonce,
+            rule,
+            // A fresh rule has no stored nonce, so 1 is the value the interpreter
+            // expects unless the caller is deliberately re-installing.
+            installNonce: input.installNonce ?? 1,
             encodedPredicate,
             predicateHash,
             rpc: rpcClient,
@@ -206,8 +360,8 @@ async function runInstallPolicy(raw) {
                     // no existing rule this install replaces. A sentinel no real id
                     // can equal keeps every observed rule in scope.
                     ruleId: -1,
-                    contextType: input.rule.contextRuleType,
-                    signers: input.rule.signers,
+                    contextType: rule.contextRuleType,
+                    signers: rule.signers,
                     predicate: (0, decode_ts_1.decodePredicate)(encodedPredicate),
                 },
                 existing: observed,
@@ -301,23 +455,116 @@ function noInvocationError(toolName) {
         retryable: false,
     };
 }
+/** Scope a rule to whatever contract its predicate pins.
+ *
+ *  Taking this from the predicate rather than from a separate argument means
+ *  the rule's scope cannot drift from what the predicate actually checks. A
+ *  predicate that pins no contract yields the default (account-wide) type,
+ *  which is what an unpinned predicate means. Only the top level is walked:
+ *  a contract pin nested under an `or` does not scope the rule, because the
+ *  other branch would not be covered by it. */
+function contextTypeForPredicate(predicate) {
+    const conjuncts = predicate.op === 'and' ? predicate.children : [predicate];
+    for (const node of conjuncts) {
+        if (node.op !== 'eq')
+            continue;
+        if (node.left?.kind !== 'call_contract')
+            continue;
+        if (node.right?.kind !== 'literal_address')
+            continue;
+        return { kind: 'call_contract', contract: node.right.value };
+    }
+    return { kind: 'default' };
+}
+/** Resolve what `simulate_policy` and `verify_policy` evaluate.
+ *
+ *  Both want a predicate TREE plus the recording it came from, and neither is
+ *  something a caller holds by default: the tree is only returned by
+ *  `synthesize_policy` under `explain`, so a caller who did not ask for it has
+ *  nothing to pass and skips the check. Skipping is the worst outcome here -
+ *  these two ARE the check - so a transaction hash is accepted instead and the
+ *  server rebuilds both from it. Recording is deterministic for a settled
+ *  transaction, so this evaluates the same predicate the synthesiser produced. */
+async function resolveCheckInputs(input, tool) {
+    const network = input.network ?? 'testnet';
+    // The call to check against: whichever the caller supplied, recording only
+    // when they gave a hash instead.
+    let permitTx;
+    if (input.permitTx !== undefined) {
+        permitTx = input.permitTx;
+    }
+    else {
+        const recordArgs = { hash: input.transactionHash, network };
+        const recorded = await runRecordTransaction(recordArgs);
+        if (!recorded.ok)
+            return { ok: false, error: recorded.error };
+        permitTx = recorded.data;
+    }
+    // The thing to check. A caller-supplied predicate wins over re-synthesis,
+    // in either form: a DECLARED policy has no recording behind it, so
+    // re-deriving one from the transaction would check a different predicate
+    // than the one the caller is asking about.
+    if (input.predicate !== undefined) {
+        return { ok: true, data: { predicate: input.predicate, permitTx } };
+    }
+    if (input.encodedPredicate !== undefined) {
+        try {
+            return { ok: true, data: { predicate: (0, decode_ts_1.decodePredicate)(input.encodedPredicate), permitTx } };
+        }
+        catch (e) {
+            return toolFailure(tool, e);
+        }
+    }
+    const synthArgs = {
+        source: 'recording',
+        network,
+        // The schema's inferred type is `passthrough`, so it carries an index
+        // signature the core type does not; the shapes agree field for field.
+        recordedTx: permitTx,
+        explain: true,
+        ...(input.smartAccount !== undefined
+            ? { interpreter: { smartAccountAddress: input.smartAccount } }
+            : {}),
+        ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
+    };
+    const synthesized = await runSynthesizePolicy(synthArgs);
+    if (!synthesized.ok)
+        return { ok: false, error: synthesized.error };
+    const tree = synthesized.explain?.predicateTree;
+    if (!tree) {
+        return {
+            ok: false,
+            error: {
+                code: TOOL_ERROR_CODE[tool],
+                message: `${tool}: synthesis produced no predicate to check for that transaction`,
+                severity: 'error',
+                retryable: false,
+                remediation: { toolCall: { name: tool, args: {} } },
+            },
+        };
+    }
+    return { ok: true, data: { predicate: tree, permitTx } };
+}
 /** `simulate_policy` body - evaluate a predicate against one recorded call.
  *
  *  The evaluator is a second implementation of the on-chain semantics, and the
  *  conformance harness asserts it agrees with the Rust interpreter case for
  *  case. A verdict here is therefore a claim about what the contract would do,
  *  not a guess. */
-function runSimulatePolicy(raw) {
+async function runSimulatePolicy(raw) {
     const parsed = schemas_ts_1.SimulatePolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
         return { ok: false, error: validationError('simulate_policy', parsed.error.issues) };
     }
     const input = parsed.data;
-    const ctx = evalContextFromRecording(input.permitTx);
+    const resolved = await resolveCheckInputs(input, 'simulate_policy');
+    if (!resolved.ok)
+        return { ok: false, error: resolved.error };
+    const ctx = evalContextFromRecording(resolved.data.permitTx);
     if (!ctx)
         return { ok: false, error: noInvocationError('simulate_policy') };
     try {
-        const res = (0, index_ts_2.evaluate)(input.predicate, ctx);
+        const res = (0, index_ts_2.evaluate)(resolved.data.predicate, ctx);
         return {
             ok: true,
             data: {
@@ -391,17 +638,20 @@ function runDeclarePolicy(raw) {
  *  very transaction it was synthesised from. A deny case that permits means it
  *  is too LOOSE: some mutation of that transaction still gets through. `ok` is
  *  true only when neither holds. */
-function runVerifyPolicy(raw) {
+async function runVerifyPolicy(raw) {
     const parsed = schemas_ts_1.VerifyPolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
         return { ok: false, error: validationError('verify_policy', parsed.error.issues) };
     }
     const input = parsed.data;
-    const ctx = evalContextFromRecording(input.permitTx);
+    const resolved = await resolveCheckInputs(input, 'verify_policy');
+    if (!resolved.ok)
+        return { ok: false, error: resolved.error };
+    const ctx = evalContextFromRecording(resolved.data.permitTx);
     if (!ctx)
         return { ok: false, error: noInvocationError('verify_policy') };
     try {
-        const predicate = input.predicate;
+        const predicate = resolved.data.predicate;
         const cases = (0, index_ts_2.generateCases)(predicate, ctx);
         const permitRes = (0, index_ts_2.evaluate)(predicate, cases.permit);
         const denies = cases.denies.map((d) => {