@crediolabs/policy-synth 1.0.0 → 1.1.1

package/src/run/schemas.ts

@@ -15,6 +15,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.
 
+import { StrKey } from '@stellar/stellar-sdk'
 import { z } from 'zod'
 import { isStellarAddress } from '../synth/address.ts'
 
@@ -153,23 +154,43 @@ export const InterpreterOptionsSchema = z.object({
   installNonce: z.number().int().positive().optional(),
 })
 
-export const SynthesizePolicyInputSchema = z.object({
-  source: z.literal('recording'),
-  recordedTx: RecordedTransactionSchema,
-  network: NetworkSchema,
-  userResponses: ComposeUserResponsesSchema.optional(),
-  confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
-  interpreter: InterpreterOptionsSchema.optional(),
-  // --explain opt-in. When true, the orchestrator attaches the
-  // in-memory PredicateNode + the corresponding SimulationResult
-  // (real one from the self-verify pipeline when the interpreter is
-  // engaged, minimal honest value otherwise) to the success envelope.
-  // Absent or false -> the success envelope is unchanged (byte-identical
-  // to today). The flag is ADDITIVE: the existing ProposedPolicy fields
-  // (encodedPredicate, predicateHash, etc.) are never altered by enabling
-  // explain.
-  explain: z.boolean().optional(),
-})
+export const SynthesizePolicyInputSchema = z
+  .object({
+    source: z.literal('recording'),
+    // 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(),
+    interpreter: InterpreterOptionsSchema.optional(),
+    // --explain opt-in. When true, the orchestrator attaches the
+    // in-memory PredicateNode + the corresponding SimulationResult
+    // (real one from the self-verify pipeline when the interpreter is
+    // engaged, minimal honest value otherwise) to the success envelope.
+    // Absent or false -> the success envelope is unchanged (byte-identical
+    // to today). The flag is ADDITIVE: the existing ProposedPolicy fields
+    // (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)',
+  })
 
 export type SynthesizePolicyInput = z.infer<typeof SynthesizePolicyInputSchema>
 
@@ -271,11 +292,44 @@ export const PredicateNodeSchema: z.ZodType<unknown> = z.lazy(() =>
 // 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,
-  validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
-})
+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 type SimulatePolicyInput = z.infer<typeof SimulatePolicyInputSchema>
 
 export const VerifyPolicyInputSchema = SimulatePolicyInputSchema
@@ -350,13 +404,26 @@ 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),
-        })
+        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),
   })
@@ -429,6 +496,11 @@ export const RPC_URL_BY_NETWORK: Record<Network, string> = {
  *  Provenance detail in `docs/audit/README.md` finding 7. */
 export type OzBuiltinPolicy = 'spending_limit' | 'simple_threshold' | 'weighted_threshold'
 
+/** 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)`
@@ -479,6 +551,29 @@ export const NETWORK_PASSPHRASES: Record<Network, string> = {
 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: string) =>
+  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: string) =>
+  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
@@ -542,14 +637,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
@@ -558,10 +649,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
@@ -573,6 +724,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
@@ -582,6 +765,13 @@ export const InstallPolicyInputSchema = z
     /** 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',
   })
@@ -590,16 +780,12 @@ export type InstallPolicyInput = z.infer<typeof InstallPolicyInputSchema>
 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/src/synth/lower.ts

@@ -32,12 +32,20 @@ export interface IntentFacts {
 }
 
 /** Lower a recorded transaction to the canonical IntentFacts. Pure (no
- *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts. */
-export 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 function lower(tx: RecordedTransaction, governedAccount?: string): IntentFacts {
   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)
 
@@ -76,16 +84,22 @@ function groupFunctionsByContract(invocations: ContractInvocation[]): Record<str
   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.). */
+/** 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: TokenMovement[],
-  sourceAccount: string
+  spenders: readonly string[]
 ): Record<string, string> {
   const totals = new Map<string, bigint>()
   for (const m of movements) {
-    if (m.from !== sourceAccount) continue
+    if (!spenders.includes(m.from)) continue
     const current = totals.get(m.token) ?? 0n
     totals.set(m.token, current + BigInt(m.amount))
   }

package/src/synth/synthesize-from-recording.ts

@@ -207,7 +207,7 @@ function synthesizeFromRecordingInner(
     }
   }
 
-  const facts = lower(tx)
+  const facts = lower(tx, opts.interpreter?.smartAccountAddress)
 
   const scopeRes = decideScope(facts, {
     network: opts.network,

package/src/types.ts

@@ -94,12 +94,31 @@ export type SignerDraft =
   | { kind: 'delegated'; address: string }
   | { kind: 'external'; verifier: string; keyBytes: string }
 
-/** Reference to one policy attached to a context rule. */
-export type PolicyRef = {
-  kind: 'interpreter'
-  interpreterAddress: string
-  predicateBlobBase64: string
-}
+/** 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