@crediolabs/policy-synth 1.2.0 → 1.3.0

package/src/install/read-account-rules.ts

@@ -27,12 +27,13 @@ import {
   Contract,
   Keypair,
   rpc,
+  scValToNative,
   TransactionBuilder,
   xdr,
 } from '@stellar/stellar-sdk'
 import { decodePredicate } from '../predicate/decode.ts'
 import type { SignerDraft } from '../types.ts'
-import type { ContextType, ObservedRule } from './authority-overlap.ts'
+import type { ContextType, ObservedRule, SpendCap } from './authority-overlap.ts'
 
 /** `storage.rs` - the third element of the persistent doc key tuple. */
 export const K_DOC = 1
@@ -173,6 +174,49 @@ export function decodeStoredPredicateBytes(v: xdr.ScVal): Buffer | undefined {
   return field.bytes()
 }
 
+/** Persistent-storage key for a rule's spend-cap data:
+ *  `SpendingLimitStorageKey::AccountContext(account, rule_id)`, which the host
+ *  encodes as an enum variant - the symbol first, then the payload. */
+export function spendCapKeyScVal(smartAccount: string, ruleId: number): xdr.ScVal {
+  return xdr.ScVal.scvVec([
+    xdr.ScVal.scvSymbol('AccountContext'),
+    new Address(smartAccount).toScVal(),
+    xdr.ScVal.scvU32(ruleId),
+  ])
+}
+
+/** Ledger key for the OZ spend cap's own persistent entry. The policy exposes
+ *  `get_spending_limit_data`, but that PANICS when nothing is installed, and a
+ *  panic is indistinguishable from an RPC fault at the call site. Reading the
+ *  entry lets "no cap here" come back as an absence instead. */
+export function spendCapLedgerKey(
+  spendingLimit: string,
+  smartAccount: string,
+  ruleId: number
+): xdr.LedgerKey {
+  return xdr.LedgerKey.contractData(
+    new xdr.LedgerKeyContractData({
+      contract: new Address(spendingLimit).toScAddress(),
+      key: spendCapKeyScVal(smartAccount, ruleId),
+      durability: xdr.ContractDataDurability.persistent(),
+    })
+  )
+}
+
+/** `SpendingLimitData`, of which only the two installed parameters matter here.
+ *  The running total and the history are deliberately ignored: they say what
+ *  has been spent so far, which changes every call, while the scan is about
+ *  what the rule PERMITS. */
+export function decodeSpendCap(v: xdr.ScVal): SpendCap | undefined {
+  const periodLedgers = u32Of(mapField(v, 'period_ledgers'))
+  const limit = mapField(v, 'spending_limit')
+  if (periodLedgers === undefined || !limit) return undefined
+  if (limit.switch() !== xdr.ScValType.scvI128()) return undefined
+  const amount = scValToNative(limit)
+  if (typeof amount !== 'bigint') return undefined
+  return { amount: amount.toString(), periodLedgers }
+}
+
 // ---- collection -----
 
 /** The three reads the scan needs. Kept as an interface so the collection
@@ -189,6 +233,14 @@ export interface AccountRuleReader {
     smartAccount: string,
     ruleId: number
   ): Promise<xdr.ScVal | undefined>
+  /** The OZ spend cap's persistent entry for this rule, read as a ledger entry.
+   *  Optional so an existing reader keeps working: without it the scan simply
+   *  reports no cap parameters, which is the same as it behaved before. */
+  getSpendCapData?(
+    spendingLimit: string,
+    smartAccount: string,
+    ruleId: number
+  ): Promise<xdr.ScVal | undefined>
 }
 
 /** How far the id scan will probe before giving up. OZ imposes no per-account
@@ -227,6 +279,10 @@ export async function collectObservedRules(args: {
   reader: AccountRuleReader
   smartAccount: string
   interpreterAddress: string
+  /** The pinned OZ spend cap. Supplying it fills in the PARAMETERS of a
+   *  neighbour's cap; whether one is attached at all is decided from the
+   *  rule's policy addresses and does not depend on this read succeeding. */
+  spendingLimitAddress?: string
   maxRuleIdScan?: number
 }): Promise<CollectedRules> {
   const count = await args.reader.getContextRuleCount(args.smartAccount)
@@ -259,6 +315,16 @@ export async function collectObservedRules(args: {
         unreadablePredicateRuleIds.push(rule.id)
       }
     }
+
+    const spendCapAddress = args.spendingLimitAddress
+    if (spendCapAddress !== undefined && rule.policyAddresses.includes(spendCapAddress)) {
+      const data = await args.reader.getSpendCapData?.(spendCapAddress, args.smartAccount, rule.id)
+      const cap = data ? decodeSpendCap(data) : undefined
+      // An unreadable cap is left absent rather than guessed at. The rule still
+      // counts as capped, because attachment came from its policy addresses,
+      // so failing this read weakens the REPORT and never the refusal.
+      if (cap) rule.spendCap = cap
+    }
     rules.push(rule)
   }
 
@@ -309,5 +375,12 @@ export function accountRuleReaderFromServer(
       if (!entry || entry.switch() !== xdr.LedgerEntryType.contractData()) return undefined
       return entry.contractData().val()
     },
+    async getSpendCapData(spendingLimit, smartAccount, ruleId) {
+      const key = spendCapLedgerKey(spendingLimit, smartAccount, ruleId)
+      const res = await server.getLedgerEntries(key)
+      const entry = res.entries?.[0]?.val
+      if (!entry || entry.switch() !== xdr.LedgerEntryType.contractData()) return undefined
+      return entry.contractData().val()
+    },
   }
 }

package/src/run/index.ts

@@ -240,9 +240,12 @@ export async function runSynthesizePolicy(raw: unknown): Promise<
 /** The refusal message for an install the cross-rule scan proves cannot bind,
  *  or `undefined` when the install may proceed.
  *
- *  Only `bypass` refuses. That class means the neighbouring rule carries NO
- *  policy, so a shared signer names it and the new predicate never runs - a
- *  proof, from data already in hand, that the rule constrains nothing.
+ *  Only `bypass` refuses, and it covers two proofs. Either the neighbouring
+ *  rule carries NO policy, so a shared signer names it and the new predicate
+ *  never runs; or the install carries a rolling total and a fully recognised
+ *  neighbour serves the same calls without one, so the total is not a bound on
+ *  the key. Both are proofs from data already in hand.
+ *
  *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
  *  advisory: it may well be tighter, and refusing on "cannot decode" would
  *  block installs on a guess. A `null` scan is NOT CHECKED, which is not
@@ -258,7 +261,12 @@ export function authorityBypassRefusal(
   const proven = scan.filter((o) => o.severity === 'bypass')
   if (proven.length === 0) return undefined
   const ids = proven.map((o) => o.ruleId).join(', ')
-  return `install_policy: ${proven[0]?.advice ?? ''} This rule would install cleanly and constrain nothing, so it is refused (rule ${ids}); remove the shared signer from that rule, attach a policy to it, or set \`allowAuthorityOverlap: true\` to install anyway.`
+  // A cap bypass leaves the predicate working, so "constrains nothing" would
+  // overstate it and send the caller looking for the wrong defect.
+  const consequence = proven.every((o) => o.capBypass === true)
+    ? 'This rule would install cleanly and its rolling total would not hold'
+    : 'This rule would install cleanly and constrain nothing'
+  return `install_policy: ${proven[0]?.advice ?? ''} ${consequence}, so it is refused (rule ${ids}); set \`allowAuthorityOverlap: true\` to install anyway.`
 }
 
 export async function runInstallPolicy(
@@ -475,8 +483,24 @@ export async function runInstallPolicy(
               contextType: rule.contextRuleType,
               signers: rule.signers,
               predicate: decodePredicate(encodedPredicate),
+              ...(input.spendingLimit !== undefined
+                ? {
+                    spendCap: {
+                      amount: input.spendingLimit.amount,
+                      periodLedgers: input.spendingLimit.periodLedgers,
+                    },
+                  }
+                : {}),
             },
             existing: observed,
+            // Both addresses are pinned, so a neighbour's policies can be
+            // named rather than merely counted - which is what lets the scan
+            // say a rule has no spend cap instead of that it has something
+            // unreadable.
+            knownPolicies: {
+              interpreter: expectedInterpreter,
+              spendingLimit: PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
+            },
           })
     // A `bypass` overlap is not a warning, it is a proof that this rule cannot
     // bind the key it names: the neighbour carries NO policy, so the signer
@@ -940,6 +964,7 @@ async function resolveExistingRules(
       reader: accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[network]),
       smartAccount: input.smartAccount,
       interpreterAddress,
+      spendingLimitAddress: PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
     })
     if (collected.incomplete) return null
     return collected.rules

package/src/run/schemas.ts

@@ -381,6 +381,15 @@ export const ObservedRuleSchema = z.object({
   signers: z.array(SignerDraftSchema),
   policyAddresses: z.array(z.string()),
   predicate: PredicateNodeSchema.optional(),
+  /** Parameters of an OZ spend cap already on this rule. Reporting only:
+   *  whether a neighbour is capped is read from `policyAddresses`, so omitting
+   *  this never turns a capped rule into an uncapped one. */
+  spendCap: z
+    .object({
+      amount: z.string().regex(/^[0-9]+$/),
+      periodLedgers: z.number().int().positive().max(U32_MAX),
+    })
+    .optional(),
 })
 
 const ContextRuleDraftSchema = z