@crediolabs/policy-synth 0.5.4 → 0.5.6

package/dist/run/index.js

@@ -323,6 +323,19 @@ export function runDeclarePolicy(raw) {
             ...(d.contract !== undefined ? { contract: d.contract } : {}),
             ...(d.maxAmount !== undefined ? { maxAmount: d.maxAmount } : {}),
             ...(d.amountArgIndex !== undefined ? { amountArgIndex: d.amountArgIndex } : {}),
+            ...(d.amountPath !== undefined
+                ? {
+                    // Rebuilt like the rest: `exactOptionalPropertyTypes` treats the
+                    // schema's `number | undefined` and the declaration's absent-or-T
+                    // as different types, and the nested optional needs the same
+                    // treatment as the top-level ones.
+                    amountPath: {
+                        argIndex: d.amountPath.argIndex,
+                        field: d.amountPath.field,
+                        ...(d.amountPath.elements !== undefined ? { elements: d.amountPath.elements } : {}),
+                    },
+                }
+                : {}),
             ...(d.recipients !== undefined ? { recipients: d.recipients } : {}),
             ...(d.recipientArgIndex !== undefined ? { recipientArgIndex: d.recipientArgIndex } : {}),
             ...(d.allowZeroCap !== undefined ? { allowZeroCap: d.allowZeroCap } : {}),

package/dist/run/schemas.d.ts

@@ -1657,6 +1657,26 @@ export declare const DeclarePolicyInputSchema: z.ZodObject<{
      *  Number.MAX_SAFE_INTEGER, so a number here would silently round. */
     maxAmount: z.ZodOptional<z.ZodString>;
     amountArgIndex: z.ZodOptional<z.ZodNumber>;
+    /** Nested amount location, for a call whose amount is a field inside a
+     *  struct argument rather than an argument of its own. Every coordinate is
+     *  REQUIRED - `declarePredicate` defaults none of them, because a nested
+     *  path guessed wrong caps something the caller never named. */
+    amountPath: z.ZodOptional<z.ZodObject<{
+        argIndex: z.ZodNumber;
+        field: z.ZodString;
+        /** How many entries the vec may carry. EVERY one is capped; see
+         *  `declarePredicate`, which refuses a single-element bound because it
+         *  would leave the rest of the vec unconstrained. */
+        elements: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        argIndex: number;
+        elements?: number | undefined;
+    }, {
+        field: string;
+        argIndex: number;
+        elements?: number | undefined;
+    }>>;
     recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     recipientArgIndex: z.ZodOptional<z.ZodNumber>;
     allowZeroCap: z.ZodOptional<z.ZodBoolean>;
@@ -1684,6 +1704,11 @@ export declare const DeclarePolicyInputSchema: z.ZodObject<{
     contract?: string | undefined;
     maxAmount?: string | undefined;
     amountArgIndex?: number | undefined;
+    amountPath?: {
+        field: string;
+        argIndex: number;
+        elements?: number | undefined;
+    } | undefined;
     recipients?: string[] | undefined;
     recipientArgIndex?: number | undefined;
     allowZeroCap?: boolean | undefined;
@@ -1698,6 +1723,11 @@ export declare const DeclarePolicyInputSchema: z.ZodObject<{
     contract?: string | undefined;
     maxAmount?: string | undefined;
     amountArgIndex?: number | undefined;
+    amountPath?: {
+        field: string;
+        argIndex: number;
+        elements?: number | undefined;
+    } | undefined;
     recipients?: string[] | undefined;
     recipientArgIndex?: number | undefined;
     allowZeroCap?: boolean | undefined;

package/dist/run/schemas.js

@@ -428,6 +428,20 @@ export const DeclarePolicyInputSchema = z
         .regex(/^[0-9]+$/, 'maxAmount must be an unsigned integer in the smallest unit')
         .optional(),
     amountArgIndex: z.number().int().nonnegative().max(U32_MAX).optional(),
+    /** Nested amount location, for a call whose amount is a field inside a
+     *  struct argument rather than an argument of its own. Every coordinate is
+     *  REQUIRED - `declarePredicate` defaults none of them, because a nested
+     *  path guessed wrong caps something the caller never named. */
+    amountPath: z
+        .object({
+        argIndex: z.number().int().nonnegative().max(U32_MAX),
+        field: z.string().min(1),
+        /** How many entries the vec may carry. EVERY one is capped; see
+         *  `declarePredicate`, which refuses a single-element bound because it
+         *  would leave the rest of the vec unconstrained. */
+        elements: z.number().int().min(1).max(U32_MAX).optional(),
+    })
+        .optional(),
     recipients: z.array(z.string()).min(1, 'recipients must not be empty').optional(),
     recipientArgIndex: z.number().int().nonnegative().max(U32_MAX).optional(),
     allowZeroCap: z.boolean().optional(),

package/dist/synth/declare.d.ts

@@ -10,6 +10,31 @@ export interface PolicyDeclaration {
     maxAmount?: string;
     /** Which argument carries the amount. Defaults to the SEP-41 position. */
     amountArgIndex?: number;
+    /** Where the amount sits when it is NESTED inside a struct argument rather
+     *  than being an argument of its own - Blend's `submit` is the motivating
+     *  case: its amount is `requests[i].amount`, so no positional index names it
+     *  and `amountArgIndex` has nothing to point at.
+     *
+     *  Mutually exclusive with `amountArgIndex`.
+     *
+     *  THIS NAMES A COUNT, NOT AN INDEX, and that is deliberate. `call_arg_field`
+     *  binds ONE element of the vec and says nothing about the others, so a
+     *  declaration that pointed at a single element would leave every other
+     *  element unbounded - a caller puts the real spend in one of those and the
+     *  cap is decorative. There is no safe way to bound "the amount" in a vec
+     *  without bounding EVERY entry, so `elements` states how many entries the
+     *  call may carry and all of them are capped.
+     *
+     *  THE CAP IS PER ENTRY. With `elements: 3` and `maxAmount` 100, one call may
+     *  carry three requests of 100 and move 300 in total. Declare the per-entry
+     *  figure you mean, not the total you have in mind. */
+    amountPath?: {
+        argIndex: number;
+        field: string;
+        /** How many entries the vec may carry. Defaults to 1 - a single-request
+         *  call, which is the shape a per-call cap is usually written for. */
+        elements?: number;
+    };
     /** Recipient allowlist. */
     recipients?: string[];
     /** Which argument carries the recipient. Defaults to the SEP-41 position. */
@@ -38,6 +63,6 @@ export interface DeclaredPredicate {
      *  was defaulted rather than supplied. */
     warnings: string[];
 }
-/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+/** Lower a declared constraint to a grammar-4 predicate. Pure and total:
  *  the same declaration always produces the same predicate. */
 export declare function declarePredicate(d: PolicyDeclaration): DeclaredPredicate;

package/dist/synth/declare.js

@@ -19,6 +19,9 @@
 //   fn            -> eq(call_fn, literal_symbol)
 //   contract      -> eq(call_contract, literal_address)
 //   maxAmount     -> lte(call_arg(i), literal_i128)
+//   maxAmount + amountPath
+//                 -> lte(call_arg_field(i, e, field), literal_i128) for EVERY
+//                    e in 0..elements-1, AND eq(call_arg_len(i), literal_u32(elements))
 //   recipients    -> in(call_arg(j), [literal_address, ...])
 //   minOutputRatio-> gte(call_arg(out), call_arg_scaled(in, num, den))
 import { isStellarAddress } from "./address.js";
@@ -29,7 +32,13 @@ import { isStellarAddress } from "./address.js";
  *  user did not mean and fails silently. */
 const SEP41_RECIPIENT_ARG = 1;
 const SEP41_AMOUNT_ARG = 2;
-/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+/** `MAX_LEAVES` in the on-chain interpreter (policy-interpreter/src/dsl.rs). */
+const INTERPRETER_MAX_LEAVES = 200;
+/** Entries a nested amount bound may cover. Each costs one comparison (two
+ *  leaves), so this sits well inside the interpreter's budget while being far
+ *  more than any real call carries - a Blend `submit` is a handful. */
+const MAX_BOUNDED_ELEMENTS = 16;
+/** Lower a declared constraint to a grammar-4 predicate. Pure and total:
  *  the same declaration always produces the same predicate. */
 export function declarePredicate(d) {
     if (!d.fn || d.fn.trim() === '') {
@@ -68,6 +77,12 @@ export function declarePredicate(d) {
             haystack: d.recipients.map((value) => ({ kind: 'literal_address', value })),
         });
     }
+    if (d.amountPath !== undefined && d.amountArgIndex !== undefined) {
+        throw declareError('SYNTHESIS_ERROR', 'amountArgIndex and amountPath both name where the amount lives, and they disagree by construction: one is a positional argument, the other a field inside one. Pass exactly one.');
+    }
+    if (d.amountPath !== undefined && d.maxAmount === undefined) {
+        throw declareError('SYNTHESIS_ERROR', 'amountPath says WHERE the amount is but not what bounds it. Pass maxAmount, or omit amountPath.');
+    }
     if (d.maxAmount !== undefined) {
         if (!/^[0-9]+$/.test(d.maxAmount)) {
             throw declareError('SYNTHESIS_ERROR', `maxAmount must be an unsigned integer in the token's smallest unit, got "${d.maxAmount}" (25 XLM = "250000000")`);
@@ -75,15 +90,56 @@ export function declarePredicate(d) {
         if (d.maxAmount === '0' && d.allowZeroCap !== true) {
             throw declareError('SYNTHESIS_ERROR', 'maxAmount "0" denies every call: no amount satisfies the bound. Set allowZeroCap to declare that deliberately.');
         }
-        const idx = d.amountArgIndex ?? SEP41_AMOUNT_ARG;
-        if (d.amountArgIndex === undefined) {
-            warnings.push(`amount cap bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the amount elsewhere this caps the wrong argument - pass amountArgIndex.`);
+        if (d.amountPath !== undefined) {
+            const { argIndex, field } = d.amountPath;
+            const elements = d.amountPath.elements ?? 1;
+            if (!Number.isInteger(argIndex) || argIndex < 0) {
+                throw declareError('SYNTHESIS_ERROR', `amountPath.argIndex must be a non-negative integer, got ${String(argIndex)}`);
+            }
+            if (!Number.isInteger(elements) || elements < 1) {
+                throw declareError('SYNTHESIS_ERROR', `amountPath.elements is how many entries the vec may carry, so it must be at least 1, got ${String(elements)}`);
+            }
+            if (elements > MAX_BOUNDED_ELEMENTS) {
+                throw declareError('SYNTHESIS_ERROR', `amountPath.elements is ${elements}; each entry costs a comparison and the interpreter caps a predicate at ${INTERPRETER_MAX_LEAVES} leaves. ${MAX_BOUNDED_ELEMENTS} is already far past any real call.`);
+            }
+            if (typeof field !== 'string' || field.trim() === '') {
+                throw declareError('SYNTHESIS_ERROR', 'amountPath.field must name the map key holding the amount');
+            }
+            // EVERY entry, not one. Bounding a single element leaves the rest of the
+            // vec unconstrained and the caller simply puts the spend in an unbounded
+            // one - the cap then reads as enforced while permitting any amount.
+            for (let element = 0; element < elements; element += 1) {
+                children.push({
+                    op: 'lte',
+                    left: { kind: 'call_arg_field', index: argIndex, element, field },
+                    right: { kind: 'literal_i128', value: d.maxAmount },
+                });
+            }
+            // And the count, or the caller appends an entry past the ones bounded
+            // above and spends through it. The two leaves are only safe together:
+            // the bounds cover entries 0..elements-1, this makes those the only
+            // entries there are. The recording front-end pairs them for the same
+            // reason.
+            children.push({
+                op: 'eq',
+                left: { kind: 'call_arg_len', index: argIndex },
+                right: { kind: 'literal_u32', value: elements },
+            });
+            warnings.push(elements === 1
+                ? `amount cap bound to call_arg_field(${argIndex}, 0, "${field}"), and argument ${argIndex} is pinned to exactly 1 entry. A call carrying more than one entry is DENIED - if this method is normally called with several, pass amountPath.elements.`
+                : `amount cap bound to every entry of argument ${argIndex} ("${field}"), which is pinned to exactly ${elements} entries. The cap is PER ENTRY: a single call may carry ${elements} of them and move up to ${elements} x ${d.maxAmount} in total. A call carrying a different number of entries is DENIED.`);
+        }
+        else {
+            const idx = d.amountArgIndex ?? SEP41_AMOUNT_ARG;
+            if (d.amountArgIndex === undefined) {
+                warnings.push(`amount cap bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the amount elsewhere this caps the wrong argument - pass amountArgIndex.`);
+            }
+            children.push({
+                op: 'lte',
+                left: { kind: 'call_arg', index: idx },
+                right: { kind: 'literal_i128', value: d.maxAmount },
+            });
         }
-        children.push({
-            op: 'lte',
-            left: { kind: 'call_arg', index: idx },
-            right: { kind: 'literal_i128', value: d.maxAmount },
-        });
     }
     if (d.minOutputRatio !== undefined) {
         const { num, den, inputArgIndex, outputArgIndex } = d.minOutputRatio;

package/dist-cjs/run/index.js

@@ -358,6 +358,19 @@ function runDeclarePolicy(raw) {
             ...(d.contract !== undefined ? { contract: d.contract } : {}),
             ...(d.maxAmount !== undefined ? { maxAmount: d.maxAmount } : {}),
             ...(d.amountArgIndex !== undefined ? { amountArgIndex: d.amountArgIndex } : {}),
+            ...(d.amountPath !== undefined
+                ? {
+                    // Rebuilt like the rest: `exactOptionalPropertyTypes` treats the
+                    // schema's `number | undefined` and the declaration's absent-or-T
+                    // as different types, and the nested optional needs the same
+                    // treatment as the top-level ones.
+                    amountPath: {
+                        argIndex: d.amountPath.argIndex,
+                        field: d.amountPath.field,
+                        ...(d.amountPath.elements !== undefined ? { elements: d.amountPath.elements } : {}),
+                    },
+                }
+                : {}),
             ...(d.recipients !== undefined ? { recipients: d.recipients } : {}),
             ...(d.recipientArgIndex !== undefined ? { recipientArgIndex: d.recipientArgIndex } : {}),
             ...(d.allowZeroCap !== undefined ? { allowZeroCap: d.allowZeroCap } : {}),

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

@@ -1657,6 +1657,26 @@ export declare const DeclarePolicyInputSchema: z.ZodObject<{
      *  Number.MAX_SAFE_INTEGER, so a number here would silently round. */
     maxAmount: z.ZodOptional<z.ZodString>;
     amountArgIndex: z.ZodOptional<z.ZodNumber>;
+    /** Nested amount location, for a call whose amount is a field inside a
+     *  struct argument rather than an argument of its own. Every coordinate is
+     *  REQUIRED - `declarePredicate` defaults none of them, because a nested
+     *  path guessed wrong caps something the caller never named. */
+    amountPath: z.ZodOptional<z.ZodObject<{
+        argIndex: z.ZodNumber;
+        field: z.ZodString;
+        /** How many entries the vec may carry. EVERY one is capped; see
+         *  `declarePredicate`, which refuses a single-element bound because it
+         *  would leave the rest of the vec unconstrained. */
+        elements: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        argIndex: number;
+        elements?: number | undefined;
+    }, {
+        field: string;
+        argIndex: number;
+        elements?: number | undefined;
+    }>>;
     recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     recipientArgIndex: z.ZodOptional<z.ZodNumber>;
     allowZeroCap: z.ZodOptional<z.ZodBoolean>;
@@ -1684,6 +1704,11 @@ export declare const DeclarePolicyInputSchema: z.ZodObject<{
     contract?: string | undefined;
     maxAmount?: string | undefined;
     amountArgIndex?: number | undefined;
+    amountPath?: {
+        field: string;
+        argIndex: number;
+        elements?: number | undefined;
+    } | undefined;
     recipients?: string[] | undefined;
     recipientArgIndex?: number | undefined;
     allowZeroCap?: boolean | undefined;
@@ -1698,6 +1723,11 @@ export declare const DeclarePolicyInputSchema: z.ZodObject<{
     contract?: string | undefined;
     maxAmount?: string | undefined;
     amountArgIndex?: number | undefined;
+    amountPath?: {
+        field: string;
+        argIndex: number;
+        elements?: number | undefined;
+    } | undefined;
     recipients?: string[] | undefined;
     recipientArgIndex?: number | undefined;
     allowZeroCap?: boolean | undefined;

package/dist-cjs/run/schemas.js

@@ -431,6 +431,20 @@ exports.DeclarePolicyInputSchema = zod_1.z
         .regex(/^[0-9]+$/, 'maxAmount must be an unsigned integer in the smallest unit')
         .optional(),
     amountArgIndex: zod_1.z.number().int().nonnegative().max(U32_MAX).optional(),
+    /** Nested amount location, for a call whose amount is a field inside a
+     *  struct argument rather than an argument of its own. Every coordinate is
+     *  REQUIRED - `declarePredicate` defaults none of them, because a nested
+     *  path guessed wrong caps something the caller never named. */
+    amountPath: zod_1.z
+        .object({
+        argIndex: zod_1.z.number().int().nonnegative().max(U32_MAX),
+        field: zod_1.z.string().min(1),
+        /** How many entries the vec may carry. EVERY one is capped; see
+         *  `declarePredicate`, which refuses a single-element bound because it
+         *  would leave the rest of the vec unconstrained. */
+        elements: zod_1.z.number().int().min(1).max(U32_MAX).optional(),
+    })
+        .optional(),
     recipients: zod_1.z.array(zod_1.z.string()).min(1, 'recipients must not be empty').optional(),
     recipientArgIndex: zod_1.z.number().int().nonnegative().max(U32_MAX).optional(),
     allowZeroCap: zod_1.z.boolean().optional(),

package/dist-cjs/synth/declare.d.ts

@@ -10,6 +10,31 @@ export interface PolicyDeclaration {
     maxAmount?: string;
     /** Which argument carries the amount. Defaults to the SEP-41 position. */
     amountArgIndex?: number;
+    /** Where the amount sits when it is NESTED inside a struct argument rather
+     *  than being an argument of its own - Blend's `submit` is the motivating
+     *  case: its amount is `requests[i].amount`, so no positional index names it
+     *  and `amountArgIndex` has nothing to point at.
+     *
+     *  Mutually exclusive with `amountArgIndex`.
+     *
+     *  THIS NAMES A COUNT, NOT AN INDEX, and that is deliberate. `call_arg_field`
+     *  binds ONE element of the vec and says nothing about the others, so a
+     *  declaration that pointed at a single element would leave every other
+     *  element unbounded - a caller puts the real spend in one of those and the
+     *  cap is decorative. There is no safe way to bound "the amount" in a vec
+     *  without bounding EVERY entry, so `elements` states how many entries the
+     *  call may carry and all of them are capped.
+     *
+     *  THE CAP IS PER ENTRY. With `elements: 3` and `maxAmount` 100, one call may
+     *  carry three requests of 100 and move 300 in total. Declare the per-entry
+     *  figure you mean, not the total you have in mind. */
+    amountPath?: {
+        argIndex: number;
+        field: string;
+        /** How many entries the vec may carry. Defaults to 1 - a single-request
+         *  call, which is the shape a per-call cap is usually written for. */
+        elements?: number;
+    };
     /** Recipient allowlist. */
     recipients?: string[];
     /** Which argument carries the recipient. Defaults to the SEP-41 position. */
@@ -38,6 +63,6 @@ export interface DeclaredPredicate {
      *  was defaulted rather than supplied. */
     warnings: string[];
 }
-/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+/** Lower a declared constraint to a grammar-4 predicate. Pure and total:
  *  the same declaration always produces the same predicate. */
 export declare function declarePredicate(d: PolicyDeclaration): DeclaredPredicate;

package/dist-cjs/synth/declare.js

@@ -20,6 +20,9 @@
 //   fn            -> eq(call_fn, literal_symbol)
 //   contract      -> eq(call_contract, literal_address)
 //   maxAmount     -> lte(call_arg(i), literal_i128)
+//   maxAmount + amountPath
+//                 -> lte(call_arg_field(i, e, field), literal_i128) for EVERY
+//                    e in 0..elements-1, AND eq(call_arg_len(i), literal_u32(elements))
 //   recipients    -> in(call_arg(j), [literal_address, ...])
 //   minOutputRatio-> gte(call_arg(out), call_arg_scaled(in, num, den))
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -32,7 +35,13 @@ const address_ts_1 = require("./address.js");
  *  user did not mean and fails silently. */
 const SEP41_RECIPIENT_ARG = 1;
 const SEP41_AMOUNT_ARG = 2;
-/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+/** `MAX_LEAVES` in the on-chain interpreter (policy-interpreter/src/dsl.rs). */
+const INTERPRETER_MAX_LEAVES = 200;
+/** Entries a nested amount bound may cover. Each costs one comparison (two
+ *  leaves), so this sits well inside the interpreter's budget while being far
+ *  more than any real call carries - a Blend `submit` is a handful. */
+const MAX_BOUNDED_ELEMENTS = 16;
+/** Lower a declared constraint to a grammar-4 predicate. Pure and total:
  *  the same declaration always produces the same predicate. */
 function declarePredicate(d) {
     if (!d.fn || d.fn.trim() === '') {
@@ -71,6 +80,12 @@ function declarePredicate(d) {
             haystack: d.recipients.map((value) => ({ kind: 'literal_address', value })),
         });
     }
+    if (d.amountPath !== undefined && d.amountArgIndex !== undefined) {
+        throw declareError('SYNTHESIS_ERROR', 'amountArgIndex and amountPath both name where the amount lives, and they disagree by construction: one is a positional argument, the other a field inside one. Pass exactly one.');
+    }
+    if (d.amountPath !== undefined && d.maxAmount === undefined) {
+        throw declareError('SYNTHESIS_ERROR', 'amountPath says WHERE the amount is but not what bounds it. Pass maxAmount, or omit amountPath.');
+    }
     if (d.maxAmount !== undefined) {
         if (!/^[0-9]+$/.test(d.maxAmount)) {
             throw declareError('SYNTHESIS_ERROR', `maxAmount must be an unsigned integer in the token's smallest unit, got "${d.maxAmount}" (25 XLM = "250000000")`);
@@ -78,15 +93,56 @@ function declarePredicate(d) {
         if (d.maxAmount === '0' && d.allowZeroCap !== true) {
             throw declareError('SYNTHESIS_ERROR', 'maxAmount "0" denies every call: no amount satisfies the bound. Set allowZeroCap to declare that deliberately.');
         }
-        const idx = d.amountArgIndex ?? SEP41_AMOUNT_ARG;
-        if (d.amountArgIndex === undefined) {
-            warnings.push(`amount cap bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the amount elsewhere this caps the wrong argument - pass amountArgIndex.`);
+        if (d.amountPath !== undefined) {
+            const { argIndex, field } = d.amountPath;
+            const elements = d.amountPath.elements ?? 1;
+            if (!Number.isInteger(argIndex) || argIndex < 0) {
+                throw declareError('SYNTHESIS_ERROR', `amountPath.argIndex must be a non-negative integer, got ${String(argIndex)}`);
+            }
+            if (!Number.isInteger(elements) || elements < 1) {
+                throw declareError('SYNTHESIS_ERROR', `amountPath.elements is how many entries the vec may carry, so it must be at least 1, got ${String(elements)}`);
+            }
+            if (elements > MAX_BOUNDED_ELEMENTS) {
+                throw declareError('SYNTHESIS_ERROR', `amountPath.elements is ${elements}; each entry costs a comparison and the interpreter caps a predicate at ${INTERPRETER_MAX_LEAVES} leaves. ${MAX_BOUNDED_ELEMENTS} is already far past any real call.`);
+            }
+            if (typeof field !== 'string' || field.trim() === '') {
+                throw declareError('SYNTHESIS_ERROR', 'amountPath.field must name the map key holding the amount');
+            }
+            // EVERY entry, not one. Bounding a single element leaves the rest of the
+            // vec unconstrained and the caller simply puts the spend in an unbounded
+            // one - the cap then reads as enforced while permitting any amount.
+            for (let element = 0; element < elements; element += 1) {
+                children.push({
+                    op: 'lte',
+                    left: { kind: 'call_arg_field', index: argIndex, element, field },
+                    right: { kind: 'literal_i128', value: d.maxAmount },
+                });
+            }
+            // And the count, or the caller appends an entry past the ones bounded
+            // above and spends through it. The two leaves are only safe together:
+            // the bounds cover entries 0..elements-1, this makes those the only
+            // entries there are. The recording front-end pairs them for the same
+            // reason.
+            children.push({
+                op: 'eq',
+                left: { kind: 'call_arg_len', index: argIndex },
+                right: { kind: 'literal_u32', value: elements },
+            });
+            warnings.push(elements === 1
+                ? `amount cap bound to call_arg_field(${argIndex}, 0, "${field}"), and argument ${argIndex} is pinned to exactly 1 entry. A call carrying more than one entry is DENIED - if this method is normally called with several, pass amountPath.elements.`
+                : `amount cap bound to every entry of argument ${argIndex} ("${field}"), which is pinned to exactly ${elements} entries. The cap is PER ENTRY: a single call may carry ${elements} of them and move up to ${elements} x ${d.maxAmount} in total. A call carrying a different number of entries is DENIED.`);
+        }
+        else {
+            const idx = d.amountArgIndex ?? SEP41_AMOUNT_ARG;
+            if (d.amountArgIndex === undefined) {
+                warnings.push(`amount cap bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the amount elsewhere this caps the wrong argument - pass amountArgIndex.`);
+            }
+            children.push({
+                op: 'lte',
+                left: { kind: 'call_arg', index: idx },
+                right: { kind: 'literal_i128', value: d.maxAmount },
+            });
         }
-        children.push({
-            op: 'lte',
-            left: { kind: 'call_arg', index: idx },
-            right: { kind: 'literal_i128', value: d.maxAmount },
-        });
     }
     if (d.minOutputRatio !== undefined) {
         const { num, den, inputArgIndex, outputArgIndex } = d.minOutputRatio;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "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/run/index.ts

@@ -459,6 +459,19 @@ export function runDeclarePolicy(raw: unknown): ToolResponse<{
       ...(d.contract !== undefined ? { contract: d.contract } : {}),
       ...(d.maxAmount !== undefined ? { maxAmount: d.maxAmount } : {}),
       ...(d.amountArgIndex !== undefined ? { amountArgIndex: d.amountArgIndex } : {}),
+      ...(d.amountPath !== undefined
+        ? {
+            // Rebuilt like the rest: `exactOptionalPropertyTypes` treats the
+            // schema's `number | undefined` and the declaration's absent-or-T
+            // as different types, and the nested optional needs the same
+            // treatment as the top-level ones.
+            amountPath: {
+              argIndex: d.amountPath.argIndex,
+              field: d.amountPath.field,
+              ...(d.amountPath.elements !== undefined ? { elements: d.amountPath.elements } : {}),
+            },
+          }
+        : {}),
       ...(d.recipients !== undefined ? { recipients: d.recipients } : {}),
       ...(d.recipientArgIndex !== undefined ? { recipientArgIndex: d.recipientArgIndex } : {}),
       ...(d.allowZeroCap !== undefined ? { allowZeroCap: d.allowZeroCap } : {}),

package/src/run/schemas.ts

@@ -500,6 +500,20 @@ export const DeclarePolicyInputSchema = z
       .regex(/^[0-9]+$/, 'maxAmount must be an unsigned integer in the smallest unit')
       .optional(),
     amountArgIndex: z.number().int().nonnegative().max(U32_MAX).optional(),
+    /** Nested amount location, for a call whose amount is a field inside a
+     *  struct argument rather than an argument of its own. Every coordinate is
+     *  REQUIRED - `declarePredicate` defaults none of them, because a nested
+     *  path guessed wrong caps something the caller never named. */
+    amountPath: z
+      .object({
+        argIndex: z.number().int().nonnegative().max(U32_MAX),
+        field: z.string().min(1),
+        /** How many entries the vec may carry. EVERY one is capped; see
+         *  `declarePredicate`, which refuses a single-element bound because it
+         *  would leave the rest of the vec unconstrained. */
+        elements: z.number().int().min(1).max(U32_MAX).optional(),
+      })
+      .optional(),
     recipients: z.array(z.string()).min(1, 'recipients must not be empty').optional(),
     recipientArgIndex: z.number().int().nonnegative().max(U32_MAX).optional(),
     allowZeroCap: z.boolean().optional(),

package/src/synth/declare.ts

@@ -19,6 +19,9 @@
 //   fn            -> eq(call_fn, literal_symbol)
 //   contract      -> eq(call_contract, literal_address)
 //   maxAmount     -> lte(call_arg(i), literal_i128)
+//   maxAmount + amountPath
+//                 -> lte(call_arg_field(i, e, field), literal_i128) for EVERY
+//                    e in 0..elements-1, AND eq(call_arg_len(i), literal_u32(elements))
 //   recipients    -> in(call_arg(j), [literal_address, ...])
 //   minOutputRatio-> gte(call_arg(out), call_arg_scaled(in, num, den))
 
@@ -34,6 +37,13 @@ import { isStellarAddress } from './address.ts'
 const SEP41_RECIPIENT_ARG = 1
 const SEP41_AMOUNT_ARG = 2
 
+/** `MAX_LEAVES` in the on-chain interpreter (policy-interpreter/src/dsl.rs). */
+const INTERPRETER_MAX_LEAVES = 200
+/** Entries a nested amount bound may cover. Each costs one comparison (two
+ *  leaves), so this sits well inside the interpreter's budget while being far
+ *  more than any real call carries - a Blend `submit` is a handful. */
+const MAX_BOUNDED_ELEMENTS = 16
+
 export interface PolicyDeclaration {
   /** Method to pin. Required: a predicate with no selector leaf constrains
    *  nothing and the contract refuses it at install. */
@@ -45,6 +55,31 @@ export interface PolicyDeclaration {
   maxAmount?: string
   /** Which argument carries the amount. Defaults to the SEP-41 position. */
   amountArgIndex?: number
+  /** Where the amount sits when it is NESTED inside a struct argument rather
+   *  than being an argument of its own - Blend's `submit` is the motivating
+   *  case: its amount is `requests[i].amount`, so no positional index names it
+   *  and `amountArgIndex` has nothing to point at.
+   *
+   *  Mutually exclusive with `amountArgIndex`.
+   *
+   *  THIS NAMES A COUNT, NOT AN INDEX, and that is deliberate. `call_arg_field`
+   *  binds ONE element of the vec and says nothing about the others, so a
+   *  declaration that pointed at a single element would leave every other
+   *  element unbounded - a caller puts the real spend in one of those and the
+   *  cap is decorative. There is no safe way to bound "the amount" in a vec
+   *  without bounding EVERY entry, so `elements` states how many entries the
+   *  call may carry and all of them are capped.
+   *
+   *  THE CAP IS PER ENTRY. With `elements: 3` and `maxAmount` 100, one call may
+   *  carry three requests of 100 and move 300 in total. Declare the per-entry
+   *  figure you mean, not the total you have in mind. */
+  amountPath?: {
+    argIndex: number
+    field: string
+    /** How many entries the vec may carry. Defaults to 1 - a single-request
+     *  call, which is the shape a per-call cap is usually written for. */
+    elements?: number
+  }
   /** Recipient allowlist. */
   recipients?: string[]
   /** Which argument carries the recipient. Defaults to the SEP-41 position. */
@@ -70,7 +105,7 @@ export interface DeclaredPredicate {
   warnings: string[]
 }
 
-/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+/** Lower a declared constraint to a grammar-4 predicate. Pure and total:
  *  the same declaration always produces the same predicate. */
 export function declarePredicate(d: PolicyDeclaration): DeclaredPredicate {
   if (!d.fn || d.fn.trim() === '') {
@@ -120,6 +155,19 @@ export function declarePredicate(d: PolicyDeclaration): DeclaredPredicate {
     })
   }
 
+  if (d.amountPath !== undefined && d.amountArgIndex !== undefined) {
+    throw declareError(
+      'SYNTHESIS_ERROR',
+      'amountArgIndex and amountPath both name where the amount lives, and they disagree by construction: one is a positional argument, the other a field inside one. Pass exactly one.'
+    )
+  }
+  if (d.amountPath !== undefined && d.maxAmount === undefined) {
+    throw declareError(
+      'SYNTHESIS_ERROR',
+      'amountPath says WHERE the amount is but not what bounds it. Pass maxAmount, or omit amountPath.'
+    )
+  }
+
   if (d.maxAmount !== undefined) {
     if (!/^[0-9]+$/.test(d.maxAmount)) {
       throw declareError(
@@ -133,17 +181,71 @@ export function declarePredicate(d: PolicyDeclaration): DeclaredPredicate {
         'maxAmount "0" denies every call: no amount satisfies the bound. Set allowZeroCap to declare that deliberately.'
       )
     }
-    const idx = d.amountArgIndex ?? SEP41_AMOUNT_ARG
-    if (d.amountArgIndex === undefined) {
+    if (d.amountPath !== undefined) {
+      const { argIndex, field } = d.amountPath
+      const elements = d.amountPath.elements ?? 1
+      if (!Number.isInteger(argIndex) || argIndex < 0) {
+        throw declareError(
+          'SYNTHESIS_ERROR',
+          `amountPath.argIndex must be a non-negative integer, got ${String(argIndex)}`
+        )
+      }
+      if (!Number.isInteger(elements) || elements < 1) {
+        throw declareError(
+          'SYNTHESIS_ERROR',
+          `amountPath.elements is how many entries the vec may carry, so it must be at least 1, got ${String(elements)}`
+        )
+      }
+      if (elements > MAX_BOUNDED_ELEMENTS) {
+        throw declareError(
+          'SYNTHESIS_ERROR',
+          `amountPath.elements is ${elements}; each entry costs a comparison and the interpreter caps a predicate at ${INTERPRETER_MAX_LEAVES} leaves. ${MAX_BOUNDED_ELEMENTS} is already far past any real call.`
+        )
+      }
+      if (typeof field !== 'string' || field.trim() === '') {
+        throw declareError(
+          'SYNTHESIS_ERROR',
+          'amountPath.field must name the map key holding the amount'
+        )
+      }
+      // EVERY entry, not one. Bounding a single element leaves the rest of the
+      // vec unconstrained and the caller simply puts the spend in an unbounded
+      // one - the cap then reads as enforced while permitting any amount.
+      for (let element = 0; element < elements; element += 1) {
+        children.push({
+          op: 'lte',
+          left: { kind: 'call_arg_field', index: argIndex, element, field },
+          right: { kind: 'literal_i128', value: d.maxAmount },
+        })
+      }
+      // And the count, or the caller appends an entry past the ones bounded
+      // above and spends through it. The two leaves are only safe together:
+      // the bounds cover entries 0..elements-1, this makes those the only
+      // entries there are. The recording front-end pairs them for the same
+      // reason.
+      children.push({
+        op: 'eq',
+        left: { kind: 'call_arg_len', index: argIndex },
+        right: { kind: 'literal_u32', value: elements },
+      })
       warnings.push(
-        `amount cap bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the amount elsewhere this caps the wrong argument - pass amountArgIndex.`
+        elements === 1
+          ? `amount cap bound to call_arg_field(${argIndex}, 0, "${field}"), and argument ${argIndex} is pinned to exactly 1 entry. A call carrying more than one entry is DENIED - if this method is normally called with several, pass amountPath.elements.`
+          : `amount cap bound to every entry of argument ${argIndex} ("${field}"), which is pinned to exactly ${elements} entries. The cap is PER ENTRY: a single call may carry ${elements} of them and move up to ${elements} x ${d.maxAmount} in total. A call carrying a different number of entries is DENIED.`
       )
+    } else {
+      const idx = d.amountArgIndex ?? SEP41_AMOUNT_ARG
+      if (d.amountArgIndex === undefined) {
+        warnings.push(
+          `amount cap bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the amount elsewhere this caps the wrong argument - pass amountArgIndex.`
+        )
+      }
+      children.push({
+        op: 'lte',
+        left: { kind: 'call_arg', index: idx },
+        right: { kind: 'literal_i128', value: d.maxAmount },
+      })
     }
-    children.push({
-      op: 'lte',
-      left: { kind: 'call_arg', index: idx },
-      right: { kind: 'literal_i128', value: d.maxAmount },
-    })
   }
 
   if (d.minOutputRatio !== undefined) {