@crediolabs/policy-synth 1.0.0 → 1.1.1

package/dist/run/schemas.js

@@ -14,6 +14,7 @@
 // This module is the SINGLE source of truth for these shapes. The MCP package
 // 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.
+import { StrKey } from '@stellar/stellar-sdk';
 import { z } from 'zod';
 import { isStellarAddress } from "../synth/address.js";
 /** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
@@ -134,9 +135,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 +167,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 +262,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 +358,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 +425,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)`
@@ -407,6 +472,20 @@ export const NETWORK_PASSPHRASES = {
 // `sourceAccount` is the signing wallet (G...).
 const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/;
 const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/;
+// The regexes above check SHAPE only. A wrong-but-well-formed address - the
+// classic case being one an agent reproduced from memory - passes them and then
+// fails the SDK's StrKey decoder deep inside the build, where the throw is
+// caught by the tool envelope and reported as a bare "invalid checksum" naming
+// no field. A caller holding several addresses then cannot tell which one is
+// wrong. Validating the checksum HERE keeps the field name attached.
+const contractAddress = (field) => z
+    .string()
+    .regex(STELLAR_CONTRACT_ADDRESS, `${field} must be a Stellar contract address (C...)`)
+    .refine(StrKey.isValidContract, `${field} is not a valid contract address: the checksum does not match, so this address does not exist`);
+const accountAddress = (field) => z
+    .string()
+    .regex(STELLAR_ACCOUNT_ADDRESS, `${field} must be a Stellar account address (G...)`)
+    .refine(StrKey.isValidEd25519PublicKey, `${field} is not a valid account address: the checksum does not match, so this address does not exist`);
 // ===== declare_policy =====
 //
 // The declarative front-end: the constraint stated outright, with no
@@ -468,14 +547,10 @@ export const InstallPolicyInputSchema = z
      *  result says so rather than reporting "no overlaps found". */
     existingRules: z.array(ObservedRuleSchema).optional(),
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -484,10 +559,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 +634,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 +674,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',
@@ -514,16 +684,12 @@ export const InstallPolicyInputSchema = z
 export const RevokePolicyInputSchema = z
     .object({
     /** The smart account contract address (C...). */
-    smartAccount: z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: NetworkSchema.optional(),

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;
@@ -105,6 +112,21 @@ export interface InstallCallDescribes {
 export interface BuildInstallPolicyResult {
     /** Unsigned Soroban transaction envelope, base64 XDR. */
     unsignedXdr: string;
+    /** Length and SHA-256 of `unsignedXdr`, so a caller that has to move it can
+     *  prove it arrived whole.
+     *
+     *  This envelope runs to several thousand characters, and the only route
+     *  from a tool result onto disk is the caller re-emitting it. A truncated
+     *  copy is not obviously wrong - it fails later as
+     *  "failed to decode XDR: xdr value invalid", which reads like a malformed
+     *  transaction rather than a transport problem. Observed in practice: one of
+     *  two envelopes written in the same session lost its tail and its base64
+     *  length went from a multiple of four to `len % 4 == 3`.
+     *
+     *  Check both before signing. They are cheap, and they turn a silent,
+     *  fatal truncation into a retry. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     /** Smart account contract address (echo). */
     smartAccount: string;
     /** Source account (echo) - the address that must sign. */
@@ -161,6 +183,11 @@ export declare function buildRevokePolicyXdr(args: {
 }): Promise<BuildRevokePolicyResult>;
 export interface BuildRevokePolicyResult {
     unsignedXdr: string;
+    /** Same integrity pair as the install result, for the same reason: a revoke
+     *  envelope also has to reach a signer intact, and a truncated copy fails as
+     *  a malformed transaction rather than as a transport error. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     smartAccount: string;
     sourceAccount: string;
     call: {
@@ -172,3 +199,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;