@crediolabs/policy-synth 0.1.10 → 0.1.11

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

@@ -60,6 +60,10 @@ export interface OraclePriceBound {
   asset: string
   operator: IRCompOp
   value: string
+  /** Decimal basis `value` is written on. REQUIRED: oracle prices normalise to
+   *  9 dp, and a threshold silently assumed to share that basis is what let a
+   *  raw 14-dp bound permit everything. The author states it; we convert. */
+  decimals: number
 }
 
 /** Caller-supplied answers to the ambiguity prompts. Every numeric bound the
@@ -184,10 +188,19 @@ export function composeFromRecording(
             value: limit,
           },
         }
-        if (!interpreterEnabled || token === scopeContract) {
-          ozConstraints.push(spendCond)
-        } else {
-          interpreterConstraints.push(spendCond)
+        // A rolling spend cap always goes to OZ, whose `spending_limit` is the
+        // audited implementation. The interpreter is NOT a fallback for the
+        // token != scopeContract case: on chain it sees one authorized call,
+        // not the transaction's token movements, so it has no per-call amount
+        // to accumulate and the counter would never move. OZ reports the case
+        // it cannot cover (it pins the limit to the context contract), which
+        // is the honest outcome - the old fallback produced an interpreter
+        // predicate that silently never bound.
+        ozConstraints.push(spendCond)
+        if (interpreterEnabled && token !== scopeContract) {
+          warnings.push(
+            `rolling spend cap on ${token} cannot be enforced on chain: OZ spending_limit pins the limit to the context contract, and the interpreter cannot observe token movements. Bound the per-call value with an argument cap plus an invocation-count limit instead.`
+          )
         }
       }
     }
@@ -213,7 +226,10 @@ export function composeFromRecording(
         op: 'compare',
         compare: {
           selector: { kind: 'invocation_count', windowSeconds },
-          operator: 'lte',
+          // `lt`, not `lte`: the leaf reports the calls ALREADY made in the
+          // window, so `< N` is what permits N of them. With `lte` a limit
+          // of N let an N+1th call through.
+          operator: 'lt',
           value: String(invocationLimit),
         },
       }
@@ -245,6 +261,7 @@ export function composeFromRecording(
           selector: { kind: 'oracle_price', asset: b.asset },
           operator: b.operator,
           value: b.value,
+          valueDecimals: b.decimals,
         },
       }
       if (interpreterEnabled) {
@@ -405,7 +422,17 @@ function appendProtocolSpecificConstraints(
       })
       for (let i = 0; i < elements.length; i++) {
         const element = elements[i]
-        if (!element || element.type !== 'map') continue
+        // An element we cannot bind leaves that request's action, asset and
+        // amount free while the length pin makes the policy LOOK total. The
+        // length pin still stays (it is a real restriction, and dropping it
+        // would only widen the policy) - what must not happen is dropping the
+        // element quietly.
+        if (element?.type !== 'map') {
+          warnings.push(
+            `Blend submit requests element ${i} is not a Request map (recorded as ${element?.type ?? 'nothing'}): its request_type, address and amount are NOT pinned, so any action on any asset for any amount is permitted in that position`
+          )
+          continue
+        }
         const fields = element.value
         const fieldValue = (
           name: string,
@@ -421,7 +448,19 @@ function appendProtocolSpecificConstraints(
         const address = fieldValue('address', 'address')
         const amount = fieldValue('amount', 'i128')
         const requestType = fieldValue('request_type', 'u32')
-        if (address === null || amount === null || requestType === null) continue
+        if (address === null || amount === null || requestType === null) {
+          const missing = [
+            requestType === null ? 'request_type (u32)' : null,
+            address === null ? 'address' : null,
+            amount === null ? 'amount (i128)' : null,
+          ].filter((f): f is string => f !== null)
+          // Partial pins are deliberately NOT emitted (see the note above): a
+          // half-pinned request reads as a bound one on the review card.
+          warnings.push(
+            `Blend submit requests element ${i} could not be bound: ${missing.join(', ')} missing or of an unexpected type. That request's request_type, address and amount are NOT pinned, so any action on any asset for any amount is permitted in that position`
+          )
+          continue
+        }
         interpreterConstraints.push({
           op: 'compare',
           compare: {

package/src/synth/deny-cases.ts

@@ -566,7 +566,9 @@ function cloneContext(ctx: EvalContext): EvalContext {
   return cloned
 }
 
-function cloneScVal(value: ScVal, depth = 0): ScVal {
+/** Deep-copy an ScVal so a mutation cannot alias the recorded call.
+ *  Exported so the permit-context builder shares this one implementation. */
+export function cloneScVal(value: ScVal, depth = 0): ScVal {
   // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
   // payload cannot RangeError the JS stack during deny-case mutation. Over-depth
   // throws a ToolError-shaped error that the `synthesizeFromRecording` envelope

package/src/synth/evaluate.ts

@@ -32,6 +32,13 @@
 import type { PredicateLeaf, PredicateNode, ScVal } from '../types.ts'
 import { literalNumericBigInt } from './predicate-literals.ts'
 
+/** Oracle prices normalise to this many decimals; mirrors NORMALISED_DECIMALS
+ *  in oracle.rs. A threshold on any other basis must say so. */
+const NORMALISED_DECIMALS = 9
+/** Mirrors MAX_ORACLE_THRESHOLD_DECIMALS in dsl.rs. */
+const MAX_ORACLE_THRESHOLD_DECIMALS = 18
+
+
 export interface EvalContext {
   /** Contract the interpreter is asked to enforce against. */
   contract: string
@@ -206,6 +213,13 @@ function evalCompare(
 
   // --- step 4b: call_arg comparison (eq / exact-vec, or an ordered numeric bound) ---
   if (left.kind === 'call_arg') {
+    // The swap's canonical form is `call_arg[out] >= call_arg_scaled(in, num, den)`.
+    // Dispatched here so the floor's dedicated reason codes (ARITHMETIC_OVERFLOW
+    // -> SLIPPAGE_FLOOR) reach the user; routing the scaled RHS through the
+    // generic `evalArgOrderedCompare` would mask overflow as ARG_MISMATCH.
+    if (right.kind === 'call_arg_scaled') {
+      return evalScaledArgCompare(op, left, right, ctx)
+    }
     const actual = ctx.args[left.index]
     // An ordered comparison (lt/lte/gt/gte) reads the arg as an integer and
     // compares it to a numeric literal via BigInt (e.g. a SoroSwap input-amount
@@ -216,6 +230,12 @@ function evalCompare(
     return evalArgEq(op, actual, right, ctx)
   }
 
+  // --- step 4b': scaled leaf on the LEFT (`call_arg_scaled(in, num, den) <= call_arg[out]`).
+  // Symmetric form so a policy that phrases the floor either way works.
+  if (left.kind === 'call_arg_scaled') {
+    return evalScaledArgCompare(op, right, left, ctx)
+  }
+
   // --- step 4c: call_arg_len: the length of a vec-typed argument as a u32.
   // Fails closed on a non-vec arg, an absent arg, or a non-u32 literal.
   if (left.kind === 'call_arg_len') {
@@ -337,6 +357,100 @@ function evalArgEq(
   return { permit: false, reason: 'ARG_MISMATCH' }
 }
 
+/** Step 4b': slippage-floor comparison. Mirrors the Rust `eval_scaled_arg_compare`
+ *  path: the scaled leaf is `args[index] * num / den` (truncating toward
+ *  zero). On `checked_mul` / `checked_div` failure (overflow or
+ *  divide-by-zero) the comparison denies with `ARITHMETIC_OVERFLOW`. A
+ *  failed comparison denies with `SLIPPAGE_FLOOR` (the dedicated reason)
+ *  rather than the generic `ARG_MISMATCH`.
+ *
+ *  `left` is whichever side of the compare is NOT the scaled leaf. A
+ *  scaled-on-scaled compare denies `ARG_MISMATCH` (pipelining two scaled
+ *  leaves has no definable semantics). The other operand must be a
+ *  numeric shape (`call_arg` carrying a number, or a numeric literal);
+ *  anything else is `ARG_MISMATCH`. */
+function evalScaledArgCompare(
+  op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte',
+  left: PredicateLeaf,
+  right: PredicateLeaf,
+  ctx: EvalContext
+): EvalResult {
+  // Identify which side is scaled, and pull the other side as a number.
+  let scaled: { index: number; num: string; den: string }
+  let other: PredicateLeaf
+  let scaledOnRight: boolean
+  if (left.kind === 'call_arg_scaled') {
+    scaled = left
+    other = right
+    scaledOnRight = false
+  } else if (right.kind === 'call_arg_scaled') {
+    scaled = right
+    other = left
+    scaledOnRight = true
+  } else {
+    // Neither side is scaled - this is a programming error in the
+    // dispatcher; the contract returns ARG_MISMATCH to fail closed.
+    return { permit: false, reason: 'ARG_MISMATCH' }
+  }
+  // Source `args[index]` -> BigInt. An out-of-bounds index or a
+  // non-numeric arg fails closed as ARG_MISMATCH (not SLIPPAGE_FLOOR) -
+  // a violated floor is the wrong code when the operand itself could
+  // not be read.
+  if (scaled.index >= ctx.args.length) {
+    return { permit: false, reason: 'ARG_MISMATCH' }
+  }
+  const input = argNumericBigInt(ctx.args[scaled.index])
+  if (input === null) return { permit: false, reason: 'ARG_MISMATCH' }
+  let num: bigint
+  let den: bigint
+  try {
+    num = BigInt(scaled.num)
+    den = BigInt(scaled.den)
+  } catch {
+    return { permit: false, reason: 'ARG_MISMATCH' }
+  }
+  // Install refuses `den == 0` and `num <= 0` / `den <= 0`. The runtime
+  // check is a defensive belt-and-braces - a future validator
+  // regression cannot panic the frame on a divide-by-zero.
+  if (den === 0n) return { permit: false, reason: 'ARITHMETIC_OVERFLOW' }
+  const product = input * num
+  // BigInt overflow is silent in JS (it does not throw on multiplication).
+  // We can detect over-range by dividing and checking the result against
+  // i128 bounds, but the more practical check is whether the result
+  // divides cleanly. We rely on BigInt's arbitrary precision and then
+  // surface ARITHMETIC_OVERFLOW if the result is outside i128.
+  let scaledValue: bigint
+  try {
+    // BigInt division truncates toward zero (matches Rust `i128::checked_div`).
+    scaledValue = product / den
+  } catch {
+    return { permit: false, reason: 'ARITHMETIC_OVERFLOW' }
+  }
+  // i128 range check: if the scaled value is outside i128, the contract
+  // would have wrapped on i128 arithmetic; surface the same deny.
+  const I128_MAX = (1n << 127n) - 1n
+  const I128_MIN = -(1n << 127n)
+  if (scaledValue > I128_MAX || scaledValue < I128_MIN) {
+    return { permit: false, reason: 'ARITHMETIC_OVERFLOW' }
+  }
+  // Resolving the operand when the scaled side is on the right: the
+  // operand is `left`; the scaled value is the RHS. The AST order is
+  // `left <op> scaled`, so the comparator applies to `other <op> scaled`.
+  // When the scaled side is on the left, the order is `scaled <op> other`,
+  // i.e. `scaled <op> other_val`.
+  let otherVal: bigint | null
+  if (other.kind === 'call_arg') {
+    otherVal = argNumericBigInt(ctx.args[other.index])
+  } else {
+    otherVal = literalNumericBigInt(other)
+  }
+  if (otherVal === null) return { permit: false, reason: 'ARG_MISMATCH' }
+  const pass = scaledOnRight
+    ? bigintCmp(op, otherVal.toString(), scaledValue.toString())
+    : bigintCmp(op, scaledValue.toString(), otherVal.toString())
+  return pass ? { permit: true } : { permit: false, reason: 'SLIPPAGE_FLOOR' }
+}
+
 /** Ordered numeric comparison (lt/lte/gt/gte) on a `call_arg`. The interpreter
  *  reads the arg as an integer (i128 / u64 / u32 on the recorder's ScVal
  *  surface) and compares it to a numeric literal via BigInt. A non-numeric arg
@@ -430,6 +544,7 @@ function resolveLeaf(leaf: PredicateLeaf, ctx: EvalContext): ScVal | undefined {
     case 'invocation_count_in_window':
     case 'now':
     case 'valid_until':
+    case 'call_arg_scaled':
       return undefined // selector leaves with no ScVal projection
     case 'literal_address':
       return { type: 'address', value: leaf.value }
@@ -507,9 +622,22 @@ function evalOracleCompare(
     if (!mapped) throw new OracleError('ORACLE_STALE')
     throw new OracleError(mapped)
   }
-  const literal = right.kind === 'literal_i128' ? right.value : null
-  if (literal === null) throw new OracleError('ORACLE_DECIMALS_MISMATCH')
-  return bigintCmp(op, entry.price, literal)
+  // Mirrors eval_oracle_compare in dsl.rs. The threshold MUST declare its
+  // decimal basis: prices are on the normalised 9-dp basis, and assuming a
+  // bare literal shares it is what let a raw 14-dp threshold permit
+  // everything. A bare literal is refused rather than assumed.
+  if (right.kind !== 'oracle_threshold') throw new OracleError('ORACLE_DECIMALS_MISMATCH')
+  if (right.decimals > MAX_ORACLE_THRESHOLD_DECIMALS) {
+    throw new OracleError('ORACLE_THRESHOLD_DECIMALS_OUT_OF_RANGE')
+  }
+  // Scale BOTH sides up to the wider basis rather than dividing the threshold
+  // down: dividing truncates, and a truncated bound moves the permit boundary.
+  const decimals = BigInt(right.decimals)
+  const normalised = BigInt(NORMALISED_DECIMALS)
+  const common = decimals > normalised ? decimals : normalised
+  const priceScaled = BigInt(entry.price) * 10n ** (common - normalised)
+  const literalScaled = BigInt(right.value) * 10n ** (common - decimals)
+  return bigintCmp(op, String(priceScaled), String(literalScaled))
     ? { permit: true }
     : { permit: false, reason: 'FN_MISMATCH' }
 }

package/src/synth/permit-context.ts

@@ -0,0 +1,137 @@
+// src/synth/permit-context.ts - build the EvalContext that represents the
+// recorded call being replayed.
+//
+// Extracted from the over-permissiveness harness so the same construction
+// feeds both the in-process battery and the on-chain replay
+// (scripts/verify-mutations-testnet.ts). Two callers building this
+// separately would be two chances to disagree about what "the recorded
+// call" means, which is the one thing both must share.
+
+import type { PredicateLeaf, PredicateNode, RecordedTransaction } from '../types.ts'
+import { cloneScVal } from './deny-cases.ts'
+import type { EvalContext } from './evaluate.ts'
+import { literalNumericBigInt } from './predicate-literals.ts'
+
+export interface PermitContextResponses {
+  windowSeconds: number
+  invocationLimit?: number
+  limitAmount?: string
+  validUntilLedger: number
+  oraclePriceBound?: Array<{ asset: string; operator: string; value: string; decimals: number }>
+}
+
+export function buildPermitContext(
+  tx: RecordedTransaction,
+  responses: PermitContextResponses,
+  predicate: PredicateNode
+): EvalContext {
+  const amountByToken: Record<string, string> = {}
+  const totals = new Map<string, bigint>()
+  for (const m of tx.tokenMovements) {
+    const current = totals.get(m.token) ?? 0n
+    totals.set(m.token, current + BigInt(m.amount))
+  }
+  for (const [token, total] of totals) {
+    amountByToken[token] = total.toString()
+  }
+
+  const topLevel = tx.invocations[0]
+  const scopeContract = topLevel?.contract ?? ''
+
+  const oraclePriceByAsset: EvalContext['oraclePriceByAsset'] = {}
+  visitOracleLeaves(predicate, (asset, op, bound) => {
+    let price: bigint
+    switch (op) {
+      case 'lt':
+        price = bound - 1n
+        break
+      case 'gt':
+        price = bound + 1n
+        break
+      default:
+        price = bound
+    }
+    if (price < 0n) price = 0n
+    oraclePriceByAsset[asset] = { price: price.toString(), timestampSeconds: tx.fetchedAt }
+  })
+
+  const ctx: EvalContext = {
+    contract: scopeContract,
+    fn: topLevel?.fn ?? '',
+    args: (topLevel?.args ?? []).map(cloneScVal),
+    atLedger: tx.ledgerSequence,
+    nowSeconds: tx.fetchedAt,
+    amountByToken,
+    windowSpentByToken: {},
+    invocationCountByWindow: {},
+    oraclePriceByAsset,
+  }
+  if (responses.validUntilLedger !== undefined) {
+    ctx.validUntilLedger = responses.validUntilLedger
+  }
+  return ctx
+}
+
+function visitOracleLeaves(
+  node: PredicateNode,
+  visit: (asset: string, op: string, bound: bigint) => void
+): void {
+  switch (node.op) {
+    case 'and':
+    case 'or':
+      for (const child of node.children) visitOracleLeaves(child, visit)
+      return
+    case 'not':
+      visitOracleLeaves(node.child, visit)
+      return
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte': {
+      const leftIsOracle = node.left.kind === 'oracle_price'
+      const rightIsOracle = node.right.kind === 'oracle_price'
+      let asset: string | undefined
+      let literal: bigint | undefined
+      if (leftIsOracle) {
+        asset = node.left.kind === 'oracle_price' ? node.left.asset : undefined
+        literal = oracleThresholdNormalised(node.right)
+      } else if (rightIsOracle) {
+        asset = node.right.kind === 'oracle_price' ? node.right.asset : undefined
+        literal = oracleThresholdNormalised(node.left)
+      }
+      if (asset !== undefined && literal !== undefined) {
+        visit(asset, node.op, literal)
+      }
+      return
+    }
+    case 'in':
+      return
+  }
+}
+
+/** Oracle prices normalise to 9 decimals; mirrors NORMALISED_DECIMALS in
+ *  oracle.rs. */
+const NORMALISED_DECIMALS = 9n
+
+/** A threshold restated on the normalised basis, so a derived permit price is
+ *  comparable to it. Thresholds carry their own basis, so the conversion has
+ *  to happen here - reading the digits raw would build a context off by a
+ *  factor of 10^(decimals-9). Returns undefined for any other leaf. */
+function oracleThresholdNormalised(leaf: PredicateLeaf): bigint | undefined {
+  if (leaf.kind !== 'oracle_threshold') return undefined
+  let value: bigint
+  try {
+    value = BigInt(leaf.value)
+  } catch {
+    return undefined
+  }
+  const decimals = BigInt(leaf.decimals)
+  if (decimals <= NORMALISED_DECIMALS) {
+    return value * 10n ** (NORMALISED_DECIMALS - decimals)
+  }
+  // Floor: a finer-grained threshold has no exact 9-dp representation. The
+  // caller only needs a price that lands on the right side of the bound, and
+  // it offsets by one from here.
+  return value / 10n ** (decimals - NORMALISED_DECIMALS)
+}

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

@@ -1004,11 +1004,22 @@ function visitOracleLeaves(
   }
 }
 
+/** An oracle threshold restated on the normalised 9-dp basis prices use.
+ *  Thresholds carry their own basis, so reading the digits raw would build a
+ *  permit context off by 10^(decimals-9) and the intended call would not
+ *  satisfy its own bound. Mirrors NORMALISED_DECIMALS in oracle.rs. */
 function oracleLiteralFromLeaf(leaf: PredicateLeaf): bigint | undefined {
-  if (leaf.kind !== 'literal_i128') return undefined
+  if (leaf.kind !== 'oracle_threshold') return undefined
+  let value: bigint
   try {
-    return BigInt(leaf.value)
+    value = BigInt(leaf.value)
   } catch {
     return undefined
   }
+  const normalised = 9n
+  const decimals = BigInt(leaf.decimals)
+  if (decimals <= normalised) return value * 10n ** (normalised - decimals)
+  // Floor: a finer-grained threshold has no exact 9-dp representation; the
+  // caller offsets by one from here to land on the right side of the bound.
+  return value / 10n ** (decimals - normalised)
 }

package/src/types.ts

@@ -155,6 +155,13 @@ export type PredicateLeaf =
   // recorded ScVal type. A non-vec arg, missing element, missing field, or
   // type mismatch all DENY (fail-closed).
   | { kind: 'call_arg_field'; index: number; element: number; field: string }
+  // `call_arg_scaled(index, num, den)` evaluates to `args[index] * num / den`
+  // (truncating toward zero). The slippage-floor leaf: a swap policy
+  // expresses `call_arg[out] >= call_arg_scaled(in, num, den)` as "the
+  // minimum output must be at least this ratio of the input". `num`/`den`
+  // are decimal strings on i128 (mirrors `literal_i128`); the contract
+  // refuses `den == 0` and `num <= 0` / `den <= 0` at install.
+  | { kind: 'call_arg_scaled'; index: number; num: string; den: string }
   // `call_sub_invocation[i]` is NOT in v1 grammar. OZ `Policy::enforce`
   // receives one `Context`, not a sub-invocation tree; sub-invocations live under
   // `InvokerContractAuthEntry::Contract(SubContractInvocation)`, not in the
@@ -166,6 +173,11 @@ export type PredicateLeaf =
   | { kind: 'valid_until' }
   | { kind: 'invocation_count_in_window'; windowSecs: number }
   | { kind: 'oracle_price'; asset: string } // Stellar Address (SAC address for SEP-41; XLM uses its network SAC)
+  // The right-hand side of an oracle comparison. It carries its own decimal
+  // basis because the contract cannot recover it: prices normalise to 9 dp, so
+  // a raw 14-dp threshold is ~10^5 too large and `price <= threshold` becomes
+  // trivially true. `value` is a decimal string on i128, like `literal_i128`.
+  | { kind: 'oracle_threshold'; value: string; decimals: number }
   // Literal leaves: bare ScVal on the wire (no selector-tuple wrapper). Right-hand side of
   // comparisons, elements of `in` haystacks, and operands to future arithmetic nodes.
   | { kind: 'literal_address'; value: string }