@crediolabs/policy-synth 1.0.0 → 1.1.1

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

@@ -48,6 +48,7 @@
 // the account refuses with `Error(Auth, InvalidAction)`.
 import { createHash } from 'node:crypto';
 import { Address, xdr } from '@stellar/stellar-sdk';
+import { scvI128FromDecimal } from "../predicate/encode.js";
 import { GRAMMAR_VERSION, OZ_LIMITS, } from "../types.js";
 export const DEFAULT_GRAMMAR_VERSION = GRAMMAR_VERSION;
 /** The verb `add_context_rule` takes on the wire. */
@@ -121,27 +122,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 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.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) {
+    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) {
     const predicate = Buffer.from(args.encodedPredicate, 'base64');
     const computedHash = createHash('sha256').update(predicate).digest('hex');

package/dist/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;

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

@@ -62,6 +62,14 @@ export function rpcClientFromServer(server, networkPassphrase) {
         },
     };
 }
+/** `unsignedXdr` plus the length and digest that prove it arrived whole. */
+function xdrIntegrity(unsignedXdr) {
+    return {
+        unsignedXdr,
+        unsignedXdrLength: unsignedXdr.length,
+        unsignedXdrSha256: createHash('sha256').update(unsignedXdr, 'utf8').digest('hex'),
+    };
+}
 /** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
  *  The output XDR is signed by the wallet, not by us. */
 export async function buildInstallPolicyXdr(args) {
@@ -90,7 +98,7 @@ export async function buildInstallPolicyXdr(args) {
     //    The human approval binds to the exact bytes the wallet will sign.
     const describes = decodeInstallCallDescribes(finalTx, args.installNonce);
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'add_context_rule' },
@@ -119,7 +127,7 @@ export async function buildRevokePolicyXdr(args) {
     // consumer supplies only the ordinary envelope signature.
     const { finalTx, original, validUntilLedger } = await buildAuthorisedSmartAccountTx(args, 'remove_context_rule', [xdr.ScVal.scvU32(args.ruleId)], 'revoke_policy');
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
@@ -131,6 +139,21 @@ export 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. */
+export 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.
  *
@@ -160,8 +183,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' &&
         Address.fromScAddress(entry.credentials().address().address()).toString() ===
@@ -180,7 +205,7 @@ async function buildAuthorisedSmartAccountTx(args, functionName, callArgs, error
     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(),
@@ -354,6 +379,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/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/predicate/encode.js

@@ -231,7 +231,11 @@ 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. */
-function scvI128FromDecimal(decimal) {
+/** 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) {
     const v = BigInt(decimal);
     const hi = v >> 64n;
     const lo = v & UINT64_MAX;

package/dist/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;