@crediolabs/policy-synth 0.5.6 → 1.1.0

package/dist/run/schemas.js

@@ -134,9 +134,25 @@ export const InterpreterOptionsSchema = z.object({
     smartAccountAddress: z.string(),
     installNonce: z.number().int().positive().optional(),
 });
-export const SynthesizePolicyInputSchema = z.object({
+export const SynthesizePolicyInputSchema = z
+    .object({
     source: z.literal('recording'),
-    recordedTx: RecordedTransactionSchema,
+    // Two ways to name the recording, because an MCP client has no variable to
+    // pass by reference. `recordedTx` is the full RecordedTransaction, which a
+    // programmatic caller can hand straight over from `record_transaction`. An
+    // agent cannot: it sees that output as text and has to retype it, and the
+    // payload is thousands of characters and a dozen levels deep, with exact
+    // i128 strings that do not survive the round trip. `transactionHash` lets the
+    // agent carry a 64-character handle instead and have the server re-record.
+    //
+    // Re-recording rather than caching keeps the server stateless (see
+    // build-install-policy.ts). Recording is deterministic for a settled
+    // transaction, so the second read returns the same thing as the first.
+    recordedTx: RecordedTransactionSchema.optional(),
+    transactionHash: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/, 'transaction hash must be 64 lowercase hex characters')
+        .optional(),
     network: NetworkSchema,
     userResponses: ComposeUserResponsesSchema.optional(),
     confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
@@ -150,6 +166,9 @@ export const SynthesizePolicyInputSchema = z.object({
     // (encodedPredicate, predicateHash, etc.) are never altered by enabling
     // explain.
     explain: z.boolean().optional(),
+})
+    .refine((v) => v.recordedTx !== undefined || v.transactionHash !== undefined, {
+    message: 'supply either `recordedTx` (the full recording) or `transactionHash` (and the server will record it)',
 });
 // ===== PredicateNode / PredicateLeaf =====
 //
@@ -242,10 +261,38 @@ export const PredicateNodeSchema = z.lazy(() => z.union([
 // take the same input. A null predicate used to mean "OZ built-in policies
 // only"; that backend is gone, so every policy carries a predicate and there is
 // nothing to simulate without one.
-export const SimulatePolicyInputSchema = z.object({
-    predicate: PredicateNodeSchema,
-    permitTx: RecordedTransactionSchema,
+export const SimulatePolicyInputSchema = z
+    .object({
+    // Same two ways in as `synthesize_policy`, for the same reason. The tree
+    // is only returned under `explain`, so a caller who did not ask for it has
+    // nothing to pass here and skips the check entirely - which is the one
+    // step that must not be skippable by accident. `transactionHash` re-records and
+    // re-synthesizes, so the predicate checked is the predicate that was built.
+    predicate: PredicateNodeSchema.optional(),
+    /** The canonical encoding `declare_policy` and `synthesize_policy` both
+     *  return. A DECLARED policy has no recording behind it, so re-synthesizing
+     *  from a hash would check a different predicate than the one declared -
+     *  and the tree is the shape callers mistype. One opaque string is the
+     *  handle that path was missing. */
+    encodedPredicate: z.string().optional(),
+    permitTx: RecordedTransactionSchema.optional(),
+    transactionHash: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/, 'transaction hash must be 64 lowercase hex characters')
+        .optional(),
+    network: NetworkSchema.optional(),
+    /** Needed only with `transactionHash`: lowering a recording to an interpreter
+     *  predicate is scoped to the account it will be installed on, and the
+     *  self-call gate is defined against it. */
+    smartAccount: z.string().optional(),
+    userResponses: ComposeUserResponsesSchema.optional(),
     validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+})
+    // Two halves, each satisfiable on its own terms: something to check, and a
+    // call to check it against. `transactionHash` alone answers both.
+    .refine((v) => v.transactionHash !== undefined ||
+    ((v.predicate !== undefined || v.encodedPredicate !== undefined) && v.permitTx !== undefined), {
+    message: 'supply `transactionHash` (and the server will record and synthesize), or a predicate (`predicate` tree or `encodedPredicate` string) together with `permitTx` or `transactionHash`',
 });
 export const VerifyPolicyInputSchema = SimulatePolicyInputSchema;
 // ===== install_policy / revoke_policy / get_interpreter_info =====
@@ -310,12 +357,25 @@ const ContextRuleDraftSchema = z
         }),
     ]))
         .max(MAX_SIGNERS_PER_RULE),
+    /** Policies on one rule compose as ALL-OF, so an interpreter predicate and
+     *  an OpenZeppelin built-in can sit together and both must permit. That
+     *  pairing is what expresses a rolling total: the predicate bounds each
+     *  call, the built-in bounds the sum across calls. */
     policies: z
-        .array(z.object({
-        kind: z.literal('interpreter'),
-        interpreterAddress: z.string(),
-        predicateBlobBase64: z.string().min(1),
-    }))
+        .array(z.discriminatedUnion('kind', [
+        z.object({
+            kind: z.literal('interpreter'),
+            interpreterAddress: z.string(),
+            predicateBlobBase64: z.string().min(1),
+        }),
+        z.object({
+            kind: z.literal('spending_limit'),
+            policyAddress: z.string(),
+            /** LEDGERS, not seconds. */
+            periodLedgers: z.number().int().positive().max(U32_MAX),
+            spendingLimit: z.string().regex(/^[0-9]+$/),
+        }),
+    ]))
         .max(MAX_POLICIES_PER_RULE),
 })
     .passthrough()
@@ -364,6 +424,10 @@ export const RPC_URL_BY_NETWORK = {
     testnet: TESTNET_RPC_URL,
     mainnet: MAINNET_RPC_URL,
 };
+/** The upstream tag the deployed policy instances were built from. Exported so
+ *  `scripts/upstream-drift-check.ts` can compare it against the latest upstream
+ *  release; a tag recorded only in prose cannot be checked by anything. */
+export const PINNED_OZ_STELLAR_CONTRACTS_TAG = 'v0.7.2';
 /** Instance addresses per network. Exported so consumers import the pin
  *  instead of copying a literal - a copied address is how a testnet id ends up
  *  being queried against mainnet, which returns `Error(Storage, MissingValue)`
@@ -484,10 +548,70 @@ export const InstallPolicyInputSchema = z
      *  A caller that targets mainnet MUST set this to `mainnet` (the
      *  pin and RPC pin do not move by themselves). */
     network: NetworkSchema.optional(),
-    /** The proposed rule draft. Mirrors the core `ContextRuleDraft` shape. */
-    rule: ContextRuleDraftSchema,
-    /** Per-rule install nonce; 1 for a fresh install. */
-    installNonce: z.number().int().positive(),
+    /** The proposed rule draft. Mirrors the core `ContextRuleDraft` shape.
+     *
+     *  Optional because of `fromHash` below. An agent cannot reliably retype the
+     *  `contextRule` that `synthesize_policy` returned - it is nested, and the
+     *  observed failures were exactly that: `validUntilLedger` sent as a string,
+     *  `signers` as "", `policies` as an object instead of an array. Supplying
+     *  `fromHash` instead lets the server rebuild the same rule it just
+     *  produced, rather than asking the caller to transcribe it. */
+    rule: ContextRuleDraftSchema.optional(),
+    /** Build the rule here instead of receiving it: record this transaction,
+     *  synthesize against `smartAccount`, and install the result. The
+     *  agent-friendly counterpart to `rule`, and the same handle
+     *  `synthesize_policy` accepts. */
+    fromHash: z
+        .object({
+        transactionHash: z
+            .string()
+            .regex(/^[0-9a-f]{64}$/, 'transaction hash must be 64 lowercase hex characters'),
+        /** The keys this rule governs. Synthesis cannot choose them: it reads a
+         *  transaction, and which keys a rule binds is the caller's security
+         *  decision, not an inference from one recording. Naming a key here
+         *  attaches it as a delegated signer. A rule with no signer is refused
+         *  on chain, so this is required in practice; the `rule` form remains
+         *  the way to attach an external (verifier + key bytes) signer. */
+        signers: z
+            .array(z.string().refine(isStellarAddress, 'must be a Stellar address (G... or C...)'))
+            .max(MAX_SIGNERS_PER_RULE)
+            .optional(),
+        userResponses: ComposeUserResponsesSchema.optional(),
+    })
+        .optional(),
+    /** Install a predicate the caller ALREADY holds - the base64 string
+     *  `declare_policy` returns.
+     *
+     *  Without this there is no route from `declare_policy` to here:
+     *  `fromHash` re-synthesizes from a recording and would discard the
+     *  declared predicate, and `rule` means hand-building a draft that the
+     *  tool boundary types as `unknown`, so the caller is guessing. An agent
+     *  asked to do that invented a requirement to deploy a signer contract,
+     *  which is not a thing - a delegated signer is a plain account address.
+     *
+     *  The context rule type is taken FROM the predicate: if it pins a
+     *  contract, the rule is scoped to that contract. One source of truth, so
+     *  the rule's scope cannot drift from what the predicate actually checks. */
+    fromPredicate: z
+        .object({
+        encodedPredicate: z.string().min(1),
+        /** The keys this rule governs, as plain Stellar account addresses. */
+        signers: z
+            .array(z.string().refine(isStellarAddress, 'must be a Stellar address (G... or C...)'))
+            .min(1)
+            .max(MAX_SIGNERS_PER_RULE),
+        name: z.string().min(1).optional(),
+        validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+    })
+        .optional(),
+    /** Per-rule install nonce. Defaults to 1, which is the only correct value
+     *  here: this tool builds `add_context_rule`, the account assigns a NEW
+     *  rule id, and the interpreter has no stored nonce for a rule that does
+     *  not exist yet. Required, it was undiscoverable - an agent has no way to
+     *  read it, and asking cost a round trip on a value the server already
+     *  knows. Supply it only to re-install over an existing rule, where the
+     *  interpreter wants `stored_nonce + 1`. */
+    installNonce: z.number().int().positive().optional(),
     /** Optional RPC URL override. Defaults to the pinned RPC for the
      *  selected `network` (testnet by default, mainnet when
      *  `network: 'mainnet'`); the override is refused unless
@@ -499,6 +623,38 @@ export const InstallPolicyInputSchema = z
      *  network because the caller's auth-digest binds to whatever the
      *  RPC returned. */
     allowUnpinnedRpcUrl: z.boolean().optional(),
+    /** Attach an OpenZeppelin `spending_limit` beside the predicate, giving the
+     *  rule a ROLLING TOTAL as well as a per-call bound. Both must permit,
+     *  because policies on one rule compose as all-of.
+     *
+     *  This is the only way to express "N per day": the interpreter is handed
+     *  one call and keeps no state, so a predicate cannot add up spending
+     *  across calls. Composes with all three ways of naming the rule.
+     *
+     *  The primitive meters the third argument of a call named exactly
+     *  `transfer` and requires a `call_contract` rule scope, so the rule must
+     *  be pinned to the token whose transfers it meters. */
+    spendingLimit: z
+        .object({
+        /** Rolling total in the token's smallest unit. */
+        amount: z
+            .string()
+            .regex(/^[0-9]+$/, 'amount must be a base-10 integer in the smallest unit'),
+        /** Window length in LEDGERS. Stellar closes one in roughly five
+         *  seconds, so a period in seconds is an approximation of this. */
+        periodLedgers: z.number().int().positive().max(U32_MAX),
+    })
+        .optional(),
+    /** Opt-in to installing a rule that bounds no amount, when the recording
+     *  behind `fromHash` showed a spend.
+     *
+     *  Default-deny, because the failure is silent and reads as success: such
+     *  a rule installs cleanly, verifies cleanly - a missing constraint
+     *  generates no deny case to fail - and caps nothing. That combination
+     *  reached the chain once already. A rule with no spend to bound is
+     *  unaffected; only the case the synthesizer explicitly flagged is
+     *  refused. */
+    allowUnboundedAmount: z.boolean().optional(),
     /** Opt-in to pointing the rule's interpreter policy at any address
      *  other than the pinned interpreter for the selected network.
      *  Default-deny: a caller that controls the interpreter can permit
@@ -507,6 +663,9 @@ export const InstallPolicyInputSchema = z
     allowUnpinnedInterpreter: z.boolean().optional(),
     /** Base fee in stroops; defaults to BASE_FEE (100). */
     baseFee: z.number().int().positive().optional(),
+})
+    .refine((v) => v.rule !== undefined || v.fromHash !== undefined || v.fromPredicate !== undefined, {
+    message: 'name the rule one of three ways: `fromHash` (server records, synthesizes and installs), `fromPredicate` (a predicate you already hold, plus the keys it governs), or `rule` (the full ContextRuleDraft, for programmatic callers)',
 })
     .refine((v) => Boolean(v.smartAccount) && Boolean(v.sourceAccount), {
     message: 'smartAccount and sourceAccount are required',

package/dist/synth/lower.d.ts

@@ -19,5 +19,9 @@ export interface IntentFacts {
     allowedPaths?: Record<string, string[][]>;
 }
 /** Lower a recorded transaction to the canonical IntentFacts. Pure (no
- *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts. */
-export declare function lower(tx: RecordedTransaction): IntentFacts;
+ *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts.
+ *
+ *  `governedAccount` is the smart account the policy will be installed on, when
+ *  one is known. It spends from itself while a wallet submits the transaction,
+ *  so it counts as a spender alongside the source account. */
+export declare function lower(tx: RecordedTransaction, governedAccount?: string): IntentFacts;

package/dist/synth/lower.js

@@ -9,12 +9,19 @@
 // invocations hit the same contract, and the per-contract hop-path lists for
 // router calls (SoroSwap `path`).
 /** Lower a recorded transaction to the canonical IntentFacts. Pure (no
- *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts. */
-export function lower(tx) {
+ *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts.
+ *
+ *  `governedAccount` is the smart account the policy will be installed on, when
+ *  one is known. It spends from itself while a wallet submits the transaction,
+ *  so it counts as a spender alongside the source account. */
+export function lower(tx, governedAccount) {
     const invocations = tx.invocations;
     const callTargets = uniqueOrdered(invocations.map((i) => i.contract));
     const functionsByContract = groupFunctionsByContract(invocations);
-    const spendByToken = aggregateOutgoingSpend(tx.tokenMovements, tx.sourceAccount);
+    const spenders = governedAccount !== undefined && governedAccount !== tx.sourceAccount
+        ? [tx.sourceAccount, governedAccount]
+        : [tx.sourceAccount];
+    const spendByToken = aggregateOutgoingSpend(tx.tokenMovements, spenders);
     const allowedPaths = extractPathsByContract(invocations);
     const sharedRouter = inferSharedRouter(invocations);
     const facts = {
@@ -53,13 +60,19 @@ function groupFunctionsByContract(invocations) {
     }
     return out;
 }
-/** Sum outgoing TokenMovement amounts per token, where `from === source`.
- *  BigInt throughout; never lossy. Movements whose `from` does not match the
- *  recorded source account are NOT counted (incoming yield, refund, etc.). */
-function aggregateOutgoingSpend(movements, sourceAccount) {
+/** Sum outgoing TokenMovement amounts per token, across every spender.
+ *  BigInt throughout; never lossy. Movements whose `from` is none of the
+ *  spenders are NOT counted (incoming yield, refund, etc.).
+ *
+ *  A smart account spends from ITSELF while a wallet submits the transaction,
+ *  so matching the source account alone missed the entire treasury case: the
+ *  flow read as incoming-only, no amount bound was required, and a rule that
+ *  capped nothing installed with every check green. The account a policy
+ *  governs is a spender in its own right. */
+function aggregateOutgoingSpend(movements, spenders) {
     const totals = new Map();
     for (const m of movements) {
-        if (m.from !== sourceAccount)
+        if (!spenders.includes(m.from))
             continue;
         const current = totals.get(m.token) ?? 0n;
         totals.set(m.token, current + BigInt(m.amount));

package/dist/synth/synthesize-from-recording.js

@@ -122,7 +122,7 @@ function synthesizeFromRecordingInner(tx, opts) {
             },
         };
     }
-    const facts = lower(tx);
+    const facts = lower(tx, opts.interpreter?.smartAccountAddress);
     const scopeRes = decideScope(facts, {
         network: opts.network,
         ...(opts.userResponses?.validUntilLedger !== undefined

package/dist/types.d.ts

@@ -114,11 +114,28 @@ export type SignerDraft = {
     verifier: string;
     keyBytes: string;
 };
-/** Reference to one policy attached to a context rule. */
+/** Reference to one policy attached to a context rule.
+ *
+ *  Policies on one rule compose as ALL-OF, so a rule may carry our interpreter
+ *  AND an OpenZeppelin built-in, and both must permit. That is what expresses a
+ *  rolling total: the interpreter bounds each call, the built-in bounds the sum
+ *  across calls - state the interpreter deliberately does not keep. */
 export type PolicyRef = {
     kind: 'interpreter';
     interpreterAddress: string;
     predicateBlobBase64: string;
+} | {
+    /** OpenZeppelin's `spending_limit`: a rolling total over a window of
+     *  ledgers. It meters the third argument of a call named exactly
+     *  `transfer` and refuses any rule scope other than `CallContract`. */
+    kind: 'spending_limit';
+    policyAddress: string;
+    /** Window length in LEDGERS, not seconds. Stellar closes a ledger in
+     *  roughly five seconds, so a period given in seconds is an
+     *  approximation of this number and should be reported as one. */
+    periodLedgers: number;
+    /** i128 as a base-10 string, in the token's smallest unit. */
+    spendingLimit: string;
 };
 /** Grammar version baked into the interpreter wasm, mirroring `SELF_VERSION` in
  *  `contracts/policy-interpreter/src/version.rs`. Every value this package puts on

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

@@ -52,6 +52,7 @@ exports.ADD_CONTEXT_RULE_SYMBOL = exports.DEFAULT_GRAMMAR_VERSION = void 0;
 exports.buildAddContextRuleArgs = buildAddContextRuleArgs;
 const node_crypto_1 = require("node:crypto");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const encode_ts_1 = require("../predicate/encode.js");
 const types_ts_1 = require("../types.js");
 exports.DEFAULT_GRAMMAR_VERSION = types_ts_1.GRAMMAR_VERSION;
 /** The verb `add_context_rule` takes on the wire. */
@@ -125,27 +126,58 @@ function encodeSigner(s) {
 function encodePoliciesMap(args) {
     const entries = [];
     for (const ref of args.policies) {
-        // Refuse anything that is not an interpreter policy rather than skipping
-        // it. This loop used to `if (kind === 'interpreter')` and drop everything
-        // else in silence, so a caller attaching an OZ `spending_limit` beside the
-        // interpreter got a rule WITHOUT the cap and no indication of it - the
-        // policy the user asked for was simply absent from the install they signed.
-        // `PolicyRef` has one shape today, so TypeScript narrows this branch to
-        // `never`; the guard is for callers reaching the built JS untyped, and for
-        // the next kind added to `PolicyRef` without a case here. Failing loudly is
-        // the only safe direction: a dropped policy is a missing restriction.
-        if (ref.kind !== 'interpreter') {
-            const kind = JSON.stringify(ref.kind ?? null);
-            throw limitError('INSTALL_BUILD_FAILED', `policy kind ${kind} is not supported; this builder attaches interpreter policies only. Attach an OpenZeppelin built-in through the account layer instead - dropping it here would install a rule missing the restriction you asked for.`);
+        // Each policy carries its OWN params. This loop once applied one set of
+        // install params to every entry, which is why nothing but the interpreter
+        // could be expressed; before that it dropped other kinds in silence, so a
+        // caller attaching a cap received a rule without it and no indication.
+        // Both directions were wrong. An unknown kind still fails loudly below - a
+        // dropped policy is a missing restriction.
+        switch (ref.kind) {
+            case 'interpreter':
+                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
+                    key: stellar_sdk_1.Address.fromString(ref.interpreterAddress).toScVal(),
+                    val: encodePolicyInstallParams(args),
+                }));
+                break;
+            case 'spending_limit':
+                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
+                    key: stellar_sdk_1.Address.fromString(ref.policyAddress).toScVal(),
+                    val: encodeSpendingLimitParams(ref),
+                }));
+                break;
+            default: {
+                const kind = JSON.stringify(ref.kind ?? null);
+                throw limitError('INSTALL_BUILD_FAILED', `policy kind ${kind} is not supported; dropping it here would install a rule missing the restriction you asked for`);
+            }
         }
-        entries.push(new stellar_sdk_1.xdr.ScMapEntry({
-            key: stellar_sdk_1.Address.fromString(ref.interpreterAddress).toScVal(),
-            val: encodePolicyInstallParams(args),
-        }));
     }
     entries.sort(sortByScValSymbolString);
     return stellar_sdk_1.xdr.ScVal.scvMap(entries);
 }
+/** OpenZeppelin `spending_limit`'s install params: `{ period_ledgers: u32,
+ *  spending_limit: i128 }`, emitted in symbol-string order. Validated here
+ *  rather than left to the chain, because a rolling cap that fails at submit
+ *  has already cost the caller a signature. */
+function encodeSpendingLimitParams(ref) {
+    if (!Number.isInteger(ref.periodLedgers) || ref.periodLedgers <= 0) {
+        throw limitError('INSTALL_BUILD_FAILED', `spending_limit periodLedgers must be a positive integer - it counts LEDGERS, not seconds; got: ${ref.periodLedgers}`);
+    }
+    if (!/^[0-9]+$/.test(ref.spendingLimit) || BigInt(ref.spendingLimit) <= 0n) {
+        throw limitError('INSTALL_BUILD_FAILED', `spending_limit must be a positive integer in the token's smallest unit; got: ${ref.spendingLimit}`);
+    }
+    const entries = [
+        new stellar_sdk_1.xdr.ScMapEntry({
+            key: stellar_sdk_1.xdr.ScVal.scvSymbol('period_ledgers'),
+            val: stellar_sdk_1.xdr.ScVal.scvU32(ref.periodLedgers),
+        }),
+        new stellar_sdk_1.xdr.ScMapEntry({
+            key: stellar_sdk_1.xdr.ScVal.scvSymbol('spending_limit'),
+            val: (0, encode_ts_1.scvI128FromDecimal)(ref.spendingLimit),
+        }),
+    ];
+    entries.sort((a, b) => sortBySymbolString(a.key(), b.key()));
+    return stellar_sdk_1.xdr.ScVal.scvMap(entries);
+}
 function encodePolicyInstallParams(args) {
     const predicate = Buffer.from(args.encodedPredicate, 'base64');
     const computedHash = (0, node_crypto_1.createHash)('sha256').update(predicate).digest('hex');

package/dist-cjs/install/build-install-policy.d.ts

@@ -93,6 +93,13 @@ export interface InstallCallDescribes {
         installNonce: number;
         predicateHash: string;
         predicateSha256OfEmbeddedBytes: string;
+    } | {
+        /** An OpenZeppelin built-in bounding the SUM across calls, which the
+         *  predicate cannot: the interpreter sees one call and keeps no state. */
+        kind: 'spending_limit';
+        address: string;
+        periodLedgers: number;
+        spendingLimit: string;
     }>;
     /** The install nonce, decoded from the interpreter policy's
      *  `install_nonce` field. Echoed at the top level for reviewer convenience;
@@ -172,3 +179,17 @@ export interface BuildRevokePolicyResult {
     authValidUntilLedger: number;
     rootInvocationXdr: string;
 }
+/** 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. */
+export declare function simulationReason(sim: {
+    error?: string;
+}): string;

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");
@@ -136,6 +137,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 +181,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 +203,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 +377,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;