@crediolabs/policy-synth 1.0.0 → 1.1.0

package/dist-cjs/run/schemas.js

@@ -16,7 +16,7 @@
 // imports them here so its tool-shape bindings stay in step; the CLI imports
 // them here so it can build the same args envelope the MCP transport builds.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolErrorSchema = exports.GetInterpreterInfoInputSchema = exports.RevokePolicyInputSchema = exports.InstallPolicyInputSchema = exports.DeclarePolicyInputSchema = exports.NETWORK_PASSPHRASES = exports.PINNED_OZ_POLICY_WASM_SHA256 = exports.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK = exports.RPC_URL_BY_NETWORK = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.MAINNET_RPC_URL = exports.TESTNET_RPC_URL = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.ObservedRuleSchema = exports.VerifyPolicyInputSchema = exports.SimulatePolicyInputSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.SynthesizePolicyInputSchema = exports.InterpreterOptionsSchema = exports.RecordTransactionInputSchema = exports.ComposeUserResponsesSchema = exports.RecordedTransactionSchema = exports.ParseConfidenceSchema = exports.OnChainEventSchema = exports.TokenMovementSchema = exports.ContractInvocationSchema = exports.ScValSchema = exports.NetworkSchema = void 0;
+exports.ToolErrorSchema = exports.GetInterpreterInfoInputSchema = exports.RevokePolicyInputSchema = exports.InstallPolicyInputSchema = exports.DeclarePolicyInputSchema = exports.NETWORK_PASSPHRASES = exports.PINNED_OZ_POLICY_WASM_SHA256 = exports.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK = exports.PINNED_OZ_STELLAR_CONTRACTS_TAG = exports.RPC_URL_BY_NETWORK = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.MAINNET_RPC_URL = exports.TESTNET_RPC_URL = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.ObservedRuleSchema = exports.VerifyPolicyInputSchema = exports.SimulatePolicyInputSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.SynthesizePolicyInputSchema = exports.InterpreterOptionsSchema = exports.RecordTransactionInputSchema = exports.ComposeUserResponsesSchema = exports.RecordedTransactionSchema = exports.ParseConfidenceSchema = exports.OnChainEventSchema = exports.TokenMovementSchema = exports.ContractInvocationSchema = exports.ScValSchema = exports.NetworkSchema = void 0;
 const zod_1 = require("zod");
 const address_ts_1 = require("../synth/address.js");
 /** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
@@ -137,9 +137,25 @@ exports.InterpreterOptionsSchema = zod_1.z.object({
     smartAccountAddress: zod_1.z.string(),
     installNonce: zod_1.z.number().int().positive().optional(),
 });
-exports.SynthesizePolicyInputSchema = zod_1.z.object({
+exports.SynthesizePolicyInputSchema = zod_1.z
+    .object({
     source: zod_1.z.literal('recording'),
-    recordedTx: exports.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: exports.RecordedTransactionSchema.optional(),
+    transactionHash: zod_1.z
+        .string()
+        .regex(/^[0-9a-f]{64}$/, 'transaction hash must be 64 lowercase hex characters')
+        .optional(),
     network: exports.NetworkSchema,
     userResponses: exports.ComposeUserResponsesSchema.optional(),
     confidenceOverride: zod_1.z.object({ threshold: zod_1.z.number().min(0).max(1) }).optional(),
@@ -153,6 +169,9 @@ exports.SynthesizePolicyInputSchema = zod_1.z.object({
     // (encodedPredicate, predicateHash, etc.) are never altered by enabling
     // explain.
     explain: zod_1.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 =====
 //
@@ -245,10 +264,38 @@ exports.PredicateNodeSchema = zod_1.z.lazy(() => zod_1.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.
-exports.SimulatePolicyInputSchema = zod_1.z.object({
-    predicate: exports.PredicateNodeSchema,
-    permitTx: exports.RecordedTransactionSchema,
+exports.SimulatePolicyInputSchema = zod_1.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: exports.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: zod_1.z.string().optional(),
+    permitTx: exports.RecordedTransactionSchema.optional(),
+    transactionHash: zod_1.z
+        .string()
+        .regex(/^[0-9a-f]{64}$/, 'transaction hash must be 64 lowercase hex characters')
+        .optional(),
+    network: exports.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: zod_1.z.string().optional(),
+    userResponses: exports.ComposeUserResponsesSchema.optional(),
     validUntilLedger: zod_1.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`',
 });
 exports.VerifyPolicyInputSchema = exports.SimulatePolicyInputSchema;
 // ===== install_policy / revoke_policy / get_interpreter_info =====
@@ -313,12 +360,25 @@ const ContextRuleDraftSchema = zod_1.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: zod_1.z
-        .array(zod_1.z.object({
-        kind: zod_1.z.literal('interpreter'),
-        interpreterAddress: zod_1.z.string(),
-        predicateBlobBase64: zod_1.z.string().min(1),
-    }))
+        .array(zod_1.z.discriminatedUnion('kind', [
+        zod_1.z.object({
+            kind: zod_1.z.literal('interpreter'),
+            interpreterAddress: zod_1.z.string(),
+            predicateBlobBase64: zod_1.z.string().min(1),
+        }),
+        zod_1.z.object({
+            kind: zod_1.z.literal('spending_limit'),
+            policyAddress: zod_1.z.string(),
+            /** LEDGERS, not seconds. */
+            periodLedgers: zod_1.z.number().int().positive().max(U32_MAX),
+            spendingLimit: zod_1.z.string().regex(/^[0-9]+$/),
+        }),
+    ]))
         .max(MAX_POLICIES_PER_RULE),
 })
     .passthrough()
@@ -367,6 +427,10 @@ exports.RPC_URL_BY_NETWORK = {
     testnet: exports.TESTNET_RPC_URL,
     mainnet: exports.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. */
+exports.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)`
@@ -487,10 +551,70 @@ exports.InstallPolicyInputSchema = zod_1.z
      *  A caller that targets mainnet MUST set this to `mainnet` (the
      *  pin and RPC pin do not move by themselves). */
     network: exports.NetworkSchema.optional(),
-    /** The proposed rule draft. Mirrors the core `ContextRuleDraft` shape. */
-    rule: ContextRuleDraftSchema,
-    /** Per-rule install nonce; 1 for a fresh install. */
-    installNonce: zod_1.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: zod_1.z
+        .object({
+        transactionHash: zod_1.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: zod_1.z
+            .array(zod_1.z.string().refine(address_ts_1.isStellarAddress, 'must be a Stellar address (G... or C...)'))
+            .max(MAX_SIGNERS_PER_RULE)
+            .optional(),
+        userResponses: exports.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: zod_1.z
+        .object({
+        encodedPredicate: zod_1.z.string().min(1),
+        /** The keys this rule governs, as plain Stellar account addresses. */
+        signers: zod_1.z
+            .array(zod_1.z.string().refine(address_ts_1.isStellarAddress, 'must be a Stellar address (G... or C...)'))
+            .min(1)
+            .max(MAX_SIGNERS_PER_RULE),
+        name: zod_1.z.string().min(1).optional(),
+        validUntilLedger: zod_1.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: zod_1.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
@@ -502,6 +626,38 @@ exports.InstallPolicyInputSchema = zod_1.z
      *  network because the caller's auth-digest binds to whatever the
      *  RPC returned. */
     allowUnpinnedRpcUrl: zod_1.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: zod_1.z
+        .object({
+        /** Rolling total in the token's smallest unit. */
+        amount: zod_1.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: zod_1.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: zod_1.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
@@ -510,6 +666,9 @@ exports.InstallPolicyInputSchema = zod_1.z
     allowUnpinnedInterpreter: zod_1.z.boolean().optional(),
     /** Base fee in stroops; defaults to BASE_FEE (100). */
     baseFee: zod_1.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-cjs/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-cjs/synth/lower.js

@@ -12,12 +12,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.lower = lower;
 /** Lower a recorded transaction to the canonical IntentFacts. Pure (no
- *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts. */
-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. */
+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 = {
@@ -56,13 +63,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-cjs/synth/synthesize-from-recording.js

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

package/dist-cjs/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "MIT",
   "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
   "type": "module",

package/src/install/build-add-context-rule.ts

@@ -50,6 +50,7 @@
 import { createHash } from 'node:crypto'
 import { Address, xdr } from '@stellar/stellar-sdk'
 import type { ToolError } from '../errors.ts'
+import { scvI128FromDecimal } from '../predicate/encode.ts'
 import {
   type ContextRuleDraft,
   GRAMMAR_VERSION,
@@ -194,33 +195,76 @@ function encodeSigner(s: SignerDraft): xdr.ScVal {
 function encodePoliciesMap(args: BuildAddContextRuleArgs): xdr.ScVal {
   const entries: xdr.ScMapEntry[] = []
   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 as { kind?: unknown }).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 xdr.ScMapEntry({
+            key: Address.fromString(ref.interpreterAddress).toScVal(),
+            val: encodePolicyInstallParams(args),
+          })
+        )
+        break
+      case 'spending_limit':
+        entries.push(
+          new xdr.ScMapEntry({
+            key: Address.fromString(ref.policyAddress).toScVal(),
+            val: encodeSpendingLimitParams(ref),
+          })
+        )
+        break
+      default: {
+        const kind = JSON.stringify((ref as { kind?: unknown }).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 xdr.ScMapEntry({
-        key: Address.fromString(ref.interpreterAddress).toScVal(),
-        val: encodePolicyInstallParams(args),
-      })
-    )
   }
   entries.sort(sortByScValSymbolString)
   return 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: {
+  periodLedgers: number
+  spendingLimit: string
+}): xdr.ScVal {
+  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 xdr.ScMapEntry({
+      key: xdr.ScVal.scvSymbol('period_ledgers'),
+      val: xdr.ScVal.scvU32(ref.periodLedgers),
+    }),
+    new xdr.ScMapEntry({
+      key: xdr.ScVal.scvSymbol('spending_limit'),
+      val: scvI128FromDecimal(ref.spendingLimit),
+    }),
+  ]
+  entries.sort((a, b) => sortBySymbolString(a.key(), b.key()))
+  return xdr.ScVal.scvMap(entries)
+}
+
 function encodePolicyInstallParams(args: BuildAddContextRuleArgs): xdr.ScVal {
   const predicate = Buffer.from(args.encodedPredicate, 'base64')
   const computedHash = createHash('sha256').update(predicate).digest('hex')

package/src/install/build-install-policy.ts

@@ -159,13 +159,23 @@ export interface InstallCallDescribes {
    *  sha256 of the predicate blob actually embedded in the XDR - so a
    *  mismatch between the wire bytes and the review card is detectable
    *  by reading `describes`. */
-  policies: Array<{
-    kind: 'interpreter'
-    address: string
-    installNonce: number
-    predicateHash: string
-    predicateSha256OfEmbeddedBytes: string
-  }>
+  policies: Array<
+    | {
+        kind: 'interpreter'
+        address: string
+        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;
    *  the per-policy entry is the source of truth. */
@@ -317,6 +327,22 @@ 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. */
+export function simulationReason(sim: { error?: string }): string {
+  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.
  *
@@ -367,8 +393,10 @@ async function buildAuthorisedSmartAccountTx(
     // 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) =>
@@ -406,7 +434,7 @@ async function buildAuthorisedSmartAccountTx(
   const txWithAuth = buildTx(makeOperation(authEntries))
   const enforcing = await args.rpc.simulateTransaction(txWithAuth)
   if (rpc.Api.isSimulationError(enforcing)) {
-    throw new Error(`${errorPrefix}: auth simulateTransaction failed`)
+    throw new Error(`${errorPrefix}: auth simulateTransaction failed${simulationReason(enforcing)}`)
   }
   return {
     finalTx: rpc.assembleTransaction(txWithAuth, enforcing).build(),
@@ -609,6 +637,33 @@ function decodeInstallCallDescribes(
       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`
     )

package/src/predicate/encode.ts

@@ -285,7 +285,11 @@ function scvAddressFromStrkey(strkey: string): xdr.ScVal {
  *  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. */
-function scvI128FromDecimal(decimal: string): xdr.ScVal {
+/** 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 function scvI128FromDecimal(decimal: string): xdr.ScVal {
   const v = BigInt(decimal)
   const hi = v >> 64n
   const lo = v & UINT64_MAX