@crediolabs/policy-synth 0.2.0 → 0.3.1

package/src/install/build-install-policy.ts

@@ -19,6 +19,7 @@
 
 import { createHash } from 'node:crypto'
 import {
+  Account,
   Address,
   BASE_FEE,
   Contract,
@@ -30,7 +31,8 @@ import {
   TransactionBuilder,
   xdr,
 } from '@stellar/stellar-sdk'
-import { buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION } from './build-add-context-rule.ts'
+import type { ContextRuleDraft } from '../types.ts'
+import { buildAddContextRuleArgs } from './build-add-context-rule.ts'
 import {
   accountEntry,
   authDigest,
@@ -106,20 +108,14 @@ export interface BuildInstallPolicyArgs {
   sourceAccount: string
   /** Network passphrase - pins the hash the auth digest binds. */
   networkPassphrase: string
-  /** The new rule to install. Mirrors the core `ContextRuleDraft`. */
-  rule: BuildInstallPolicyRuleDraft
+  /** The new rule to install. */
+  rule: ContextRuleDraft
   /** Per-rule install nonce; 1 for a fresh install. */
   installNonce: number
   /** Already-encoded (base64) canonical ScVal of the predicate. */
   encodedPredicate: string
   /** Hex sha256 of the canonical predicate XDR bytes. */
   predicateHash: string
-  /** Per-policy oracle overrides. */
-  oracleParams?: {
-    maxStalenessSeconds?: number
-    maxDeviationBps?: number
-    maxCrossFeedDeviationBps?: number
-  }
   /** Grammar version override; defaults to 1. */
   grammarVersion?: number
   /** Base fee in stroops; defaults to BASE_FEE (100). */
@@ -130,36 +126,6 @@ export interface BuildInstallPolicyArgs {
   authValidUntilLedgers?: number
 }
 
-export type BuildInstallPolicyRuleDraft = {
-  contextRuleType:
-    | { kind: 'default' }
-    | { kind: 'call_contract'; contract: string }
-    | { kind: 'create_contract'; wasmHash: string }
-  name: string
-  validUntilLedger: number | null
-  signers: BuildInstallPolicySignerDraft[]
-  policies: BuildInstallPolicyPolicyRef[]
-}
-
-export type BuildInstallPolicySignerDraft =
-  | { kind: 'delegated'; address: string }
-  | { kind: 'external'; verifier: string; keyBytes: string }
-
-export type BuildInstallPolicyPolicyRef =
-  | {
-      kind: 'interpreter'
-      interpreterAddress: string
-      predicateBlobBase64: string
-    }
-  | {
-      kind: 'oz_builtin'
-      instanceAddress: string
-      primitive: {
-        primitive: 'spending_limit' | 'simple_threshold' | 'weighted_threshold'
-        params: Record<string, unknown>
-      }
-    }
-
 /** Human-readable description of the install call, decoded FROM the built
  *  XDR (not from the input args). The XDR is the source of truth: a
  *  human approving a review card needs the description to mirror the bytes
@@ -193,20 +159,13 @@ export interface InstallCallDescribes {
    *  sha256 of the predicate blob actually embedded in the XDR - so a
    *  mismatch between the wire bytes and the review card is detectable
    *  by reading `describes`. */
-  policies: Array<
-    | {
-        kind: 'interpreter'
-        address: string
-        installNonce: number
-        predicateHash: string
-        predicateSha256OfEmbeddedBytes: string
-      }
-    | {
-        kind: 'oz_builtin'
-        address: string
-        primitive: 'spending_limit' | 'simple_threshold' | 'weighted_threshold'
-      }
-  >
+  policies: Array<{
+    kind: 'interpreter'
+    address: string
+    installNonce: number
+    predicateHash: string
+    predicateSha256OfEmbeddedBytes: string
+  }>
   /** The install nonce, decoded from the interpreter policy's
    *  `install_nonce` field. Echoed at the top level for reviewer convenience;
    *  the per-policy entry is the source of truth. */
@@ -261,102 +220,30 @@ export async function buildInstallPolicyXdr(
       name: args.rule.name,
       validUntilLedger: args.rule.validUntilLedger,
       signers: args.rule.signers,
-      policies: args.rule.policies.map(adaptPolicyRef),
+      policies: args.rule.policies,
     },
     {
       signers: args.rule.signers,
-      policies: args.rule.policies.map(adaptPolicyRef),
+      policies: args.rule.policies,
       installNonce: args.installNonce,
       encodedPredicate: args.encodedPredicate,
       predicateHash: args.predicateHash,
-      ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
       ...(args.grammarVersion !== undefined ? { grammarVersion: args.grammarVersion } : {}),
     }
   )
 
-  // 2. Fetch the source sequence, then build the recording transaction with a
-  //    bare host call. The recording pass assigns the smart-account auth nonce
-  //    and root invocation needed to construct OZ's AuthPayload.
-  const source = await args.rpc.getAccount(args.sourceAccount)
-  const hostFunction = xdr.HostFunction.hostFunctionTypeInvokeContract(
-    new xdr.InvokeContractArgs({
-      contractAddress: new Address(args.smartAccount).toScAddress(),
-      functionName: 'add_context_rule',
-      args: [...callArgs],
-    })
-  )
-  const makeOperation = (auth: xdr.SorobanAuthorizationEntry[] = []) =>
-    Operation.invokeHostFunction({ func: hostFunction, auth })
-  const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE
-  const buildTx = (op: xdr.Operation) =>
-    buildUnsignedTx({
-      sourceAccount: args.sourceAccount,
-      sequence: source.sequenceNumber(),
-      fee: baseFee,
-      networkPassphrase: args.networkPassphrase,
-      op,
-    })
-  const recordingTx = buildTx(makeOperation())
-
-  // 3. Recording simulation: capture the smart account's nonce and invocation
-  //    tree. Nothing is signed here.
-  const recorded = await args.rpc.simulateTransaction(recordingTx)
-  if (rpc.Api.isSimulationError(recorded)) {
-    // Short, stable reason. The full `simulateTransaction` error (which
-    // carries host + URL detail) stays in the SDK's own logs - never
-    // reflected back into a user-facing message where it would
-    // reconnoitre the RPC.
-    throw new Error('install_policy: simulateTransaction failed')
-  }
-  const original = (recorded.result?.auth ?? []).find(
-    (entry) =>
-      entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
-      Address.fromScAddress(entry.credentials().address().address()).toString() ===
-        args.smartAccount
-  )
-  if (!original) {
-    throw new Error(
-      `install_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`
-    )
-  }
-
-  // 4. `add_context_rule` is authorised by the deploy-time admin rule (rule 0).
+  // 2. `add_context_rule` is authorised by the deploy-time admin rule (rule 0).
   //    The delegated signer uses source-account credentials, so its signature
   //    bytes stay empty and the ordinary transaction-envelope signature covers
   //    the call when the consumer signs it.
-  const validUntilLedger =
-    (await args.rpc.getLatestLedger()).sequence +
-    (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS)
-  const contextRuleIds = [0]
-  const digest = authDigest(
-    signaturePayload(
-      args.networkPassphrase,
-      original.credentials().address().nonce(),
-      validUntilLedger,
-      original.rootInvocation()
-    ),
-    contextRuleIds
+  const { finalTx, original, validUntilLedger } = await buildAuthorisedSmartAccountTx(
+    args,
+    'add_context_rule',
+    [...callArgs],
+    'install_policy'
   )
-  const authEntries = [
-    accountEntry(
-      original,
-      validUntilLedger,
-      authPayload([args.sourceAccount], contextRuleIds, () => Buffer.alloc(0))
-    ),
-    ...contextRuleIds.map(() => delegatedSignerEntry(args.smartAccount, digest)),
-  ]
 
-  // 5. Simulate again with the OZ entries already attached. The SDK preserves
-  //    existing auth during assembly and adds the simulated Soroban footprint +
-  //    resource fee, yielding a complete unsigned envelope.
-  const txWithAuth = buildTx(makeOperation(authEntries))
-  const enforcing = await args.rpc.simulateTransaction(txWithAuth)
-  if (rpc.Api.isSimulationError(enforcing)) {
-    throw new Error('install_policy: auth simulateTransaction failed')
-  }
-  const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build()
-
-  // 6. Decode the structured description FROM the final assembled transaction.
+  // 3. Decode the structured description FROM the final assembled transaction.
   //    The human approval binds to the exact bytes the wallet will sign.
   const describes = decodeInstallCallDescribes(finalTx, args.installNonce)
 
@@ -392,12 +279,75 @@ export async function buildRevokePolicyXdr(args: {
   baseFee?: number
   authValidUntilLedgers?: number
 }): Promise<BuildRevokePolicyResult> {
+  // Removal is master-only, so the deploy-time admin rule authorises it. The
+  // recorded rootInvocation still includes remove_context_rule(ruleId), binding
+  // the auth payload to the exact rule being removed. As with install,
+  // source-account credentials carry the delegated signer entry and the
+  // consumer supplies only the ordinary envelope signature.
+  const { finalTx, original, validUntilLedger } = await buildAuthorisedSmartAccountTx(
+    args,
+    'remove_context_rule',
+    [xdr.ScVal.scvU32(args.ruleId)],
+    'revoke_policy'
+  )
+
+  return {
+    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+    smartAccount: args.smartAccount,
+    sourceAccount: args.sourceAccount,
+    call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
+    authNonce: original.credentials().address().nonce().toString(),
+    authValidUntilLedger: validUntilLedger,
+    rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+  }
+}
+
+export interface BuildRevokePolicyResult {
+  unsignedXdr: string
+  smartAccount: string
+  sourceAccount: string
+  call: { contract: string; fn: 'remove_context_rule'; ruleId: number }
+  authNonce: string
+  authValidUntilLedger: number
+  rootInvocationXdr: string
+}
+
+/** ~25 minutes at 5s/ledger. */
+const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300
+
+// ---- internals ----
+
+/** Record a bare call to the smart account, attach the deploy-time admin rule's
+ *  auth entries, and re-simulate to assemble the footprint.
+ *
+ *  Install and revoke differ only in the call they wrap, so they share this
+ *  spine: the recording pass supplies the auth nonce and root invocation OZ's
+ *  AuthPayload binds to, and the second simulation adds the Soroban footprint +
+ *  resource fee. Nothing here is signed. `errorPrefix` names the calling tool in
+ *  the fail-closed messages so a caller can still tell which call failed. */
+async function buildAuthorisedSmartAccountTx(
+  args: {
+    smartAccount: string
+    sourceAccount: string
+    networkPassphrase: string
+    rpc: InstallRpcClient
+    baseFee?: number
+    authValidUntilLedgers?: number
+  },
+  functionName: string,
+  callArgs: xdr.ScVal[],
+  errorPrefix: string
+): Promise<{
+  finalTx: Transaction
+  original: xdr.SorobanAuthorizationEntry
+  validUntilLedger: number
+}> {
   const source = await args.rpc.getAccount(args.sourceAccount)
   const hostFunction = xdr.HostFunction.hostFunctionTypeInvokeContract(
     new xdr.InvokeContractArgs({
       contractAddress: new Address(args.smartAccount).toScAddress(),
-      functionName: 'remove_context_rule',
-      args: [xdr.ScVal.scvU32(args.ruleId)],
+      functionName,
+      args: callArgs,
     })
   )
   const makeOperation = (auth: xdr.SorobanAuthorizationEntry[] = []) =>
@@ -418,7 +368,7 @@ export async function buildRevokePolicyXdr(args: {
     // carries host + URL detail) stays in the SDK's own logs - never
     // reflected back into a user-facing message where it would
     // reconnoitre the RPC.
-    throw new Error('revoke_policy: simulateTransaction failed')
+    throw new Error(`${errorPrefix}: simulateTransaction failed`)
   }
   const original = (recorded.result?.auth ?? []).find(
     (entry) =>
@@ -428,15 +378,10 @@ export async function buildRevokePolicyXdr(args: {
   )
   if (!original) {
     throw new Error(
-      `revoke_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`
+      `${errorPrefix}: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`
     )
   }
 
-  // Removal is master-only, so the deploy-time admin rule authorises it. The
-  // recorded rootInvocation still includes remove_context_rule(ruleId), binding
-  // the auth payload to the exact rule being removed. As with install,
-  // source-account credentials carry the delegated signer entry and the
-  // consumer supplies only the ordinary envelope signature.
   const validUntilLedger =
     (await args.rpc.getLatestLedger()).sequence +
     (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS)
@@ -461,52 +406,12 @@ export async function buildRevokePolicyXdr(args: {
   const txWithAuth = buildTx(makeOperation(authEntries))
   const enforcing = await args.rpc.simulateTransaction(txWithAuth)
   if (rpc.Api.isSimulationError(enforcing)) {
-    throw new Error('revoke_policy: auth simulateTransaction failed')
-  }
-  const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build()
-
-  return {
-    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
-    smartAccount: args.smartAccount,
-    sourceAccount: args.sourceAccount,
-    call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
-    authNonce: original.credentials().address().nonce().toString(),
-    authValidUntilLedger: validUntilLedger,
-    rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
-  }
-}
-
-export interface BuildRevokePolicyResult {
-  unsignedXdr: string
-  smartAccount: string
-  sourceAccount: string
-  call: { contract: string; fn: 'remove_context_rule'; ruleId: number }
-  authNonce: string
-  authValidUntilLedger: number
-  rootInvocationXdr: string
-}
-
-/** ~25 minutes at 5s/ledger. */
-const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300
-
-// ---- internals ----
-
-/** Adapter: turn the install-policy wire `PolicyRef` shape into the core
- *  `PolicyRef` shape `buildAddContextRuleArgs` expects. Keeps the wire
- *  schema hand-rolled + flat (the strict union would need a recursive
- *  schema) while delegating to the proven encoder for the actual bytes. */
-function adaptPolicyRef(p: BuildInstallPolicyPolicyRef) {
-  if (p.kind === 'interpreter') {
-    return {
-      kind: 'interpreter' as const,
-      interpreterAddress: p.interpreterAddress,
-      predicateBlobBase64: p.predicateBlobBase64,
-    }
+    throw new Error(`${errorPrefix}: auth simulateTransaction failed`)
   }
   return {
-    kind: 'oz_builtin' as const,
-    instanceAddress: p.instanceAddress,
-    primitive: p.primitive,
+    finalTx: rpc.assembleTransaction(txWithAuth, enforcing).build(),
+    original,
+    validUntilLedger,
   }
 }
 
@@ -580,14 +485,13 @@ function decodeInstallCallDescribes(
       `install_policy: built op has ${scvArgs.length} args, expected 5 (context_type, name, valid_until, signers, policies)`
     )
   }
-  const contextType = scvArgs[0]
   const nameScv = scvArgs[1]
   const validUntilScv = scvArgs[2]
   const signersScv = scvArgs[3]
   const policiesScv = scvArgs[4]
   // The length check above pins these as defined; the local references
   // satisfy noUncheckedIndexedAccess on the accessors below.
-  if (!nameScv || !validUntilScv || !signersScv || !policiesScv || !contextType) {
+  if (!nameScv || !validUntilScv || !signersScv || !policiesScv) {
     throw new Error('install_policy: built op args include an undefined slot despite length check')
   }
 
@@ -672,7 +576,6 @@ function decodeInstallCallDescribes(
       fields.set(fk.sym().toString(), inner.val())
     }
     // Interpreter policy fields carry grammar_version/install_nonce/predicate.
-    // OZ primitives carry spending_limit/period_ledgers/threshold/signers.
     if (fields.has('predicate') || fields.has('grammar_version') || fields.has('install_nonce')) {
       const installNonceScv = fields.get('install_nonce')
       if (installNonceScv?.switch().name !== 'scvU32') {
@@ -706,21 +609,6 @@ function decodeInstallCallDescribes(
       observedInstallNonce = installNonce
       continue
     }
-    // OZ built-in primitive. Distinguish by the parameter shape we
-    // emitted; matching one of the three primitives exactly pins the
-    // kind we built.
-    if (fields.has('spending_limit') && fields.has('period_ledgers')) {
-      policies.push({ kind: 'oz_builtin', address, primitive: 'spending_limit' })
-      continue
-    }
-    if (fields.has('threshold') && fields.has('signer_weights')) {
-      policies.push({ kind: 'oz_builtin', address, primitive: 'weighted_threshold' })
-      continue
-    }
-    if (fields.has('threshold')) {
-      policies.push({ kind: 'oz_builtin', address, primitive: 'simple_threshold' })
-      continue
-    }
     throw new Error(
       `install_policy: policies[${address}] value has an unknown field set; the encoder may have drifted`
     )
@@ -752,12 +640,3 @@ function decodeInstallCallDescribes(
     installNonce,
   }
 }
-
-/** Re-export so the run-layer does not need to import from
- *  build-add-context-rule.ts (keeps the install/ -> install/ dependency
- *  direction intact). */
-export { Contract, DEFAULT_GRAMMAR_VERSION }
-
-// Local re-import to avoid pulling the class from the SDK module path
-// at the top of the file (avoids the unused-import lint).
-import { Account } from '@stellar/stellar-sdk'

package/src/install/index.ts

@@ -12,29 +12,6 @@
 // Exported here rather than from the package root to keep the root surface
 // about synthesis, and because these are transaction-building primitives whose
 // callers should know they are reaching for them.
-
-// Cross-rule authority analysis. A caller installing a policy needs to know
-// whether its signers can already reach the same calls through another context
-// rule, because OZ lets the signer name the rule and enforces only that one's
-// policies. Without this, a second, tighter rule reads as a restriction while
-// restricting nothing.
-export {
-  ANY,
-  type AuthorityOverlap,
-  type ContextType,
-  effectiveSelectors,
-  findAuthorityOverlaps,
-  type IntendedInstall,
-  intersectSelectors,
-  type MergeResult,
-  mergeIntoAnd,
-  type ObservedRule,
-  type OverlapSeverity,
-  permittedSelectors,
-  type RuleClass,
-  type Selector,
-  signerKey,
-} from './authority-overlap.ts'
 export {
   ADD_CONTEXT_RULE_SYMBOL,
   type AddContextRuleArgs,
@@ -42,14 +19,3 @@ export {
   buildAddContextRuleArgs,
   DEFAULT_GRAMMAR_VERSION,
 } from './build-add-context-rule.ts'
-export {
-  type AccountRuleReader,
-  accountRuleReaderFromServer,
-  type CollectedRules,
-  collectObservedRules,
-  decodeContextRule,
-  decodeContextType,
-  decodeSigner,
-  docLedgerKey,
-  MAX_RULE_ID_SCAN,
-} from './read-account-rules.ts'

package/src/predicate/decode.ts

@@ -64,21 +64,6 @@ function expectSymbol(v: xdr.ScVal | undefined, what: string): string {
   return v.sym().toString()
 }
 
-function expectAddress(v: xdr.ScVal | undefined, what: string): string {
-  if (!v || v.switch() !== xdr.ScValType.scvAddress()) throw malformed(`${what} is not an address`)
-  return Address.fromScAddress(v.address()).toString()
-}
-
-function expectU64(v: xdr.ScVal | undefined, what: string): string {
-  if (!v || v.switch() !== xdr.ScValType.scvU64()) throw malformed(`${what} is not a u64`)
-  return v.u64().toString()
-}
-
-function expectI128(v: xdr.ScVal | undefined, what: string): string {
-  if (!v || v.switch() !== xdr.ScValType.scvI128()) throw malformed(`${what} is not an i128`)
-  return scValToBigInt(v).toString()
-}
-
 /** Arity check with the same intent as the Rust `check_arity`: a selector with
  *  the wrong element count is malformed, not silently truncated. */
 function arity(items: xdr.ScVal[], n: number, selector: string): void {
@@ -109,48 +94,6 @@ function decodeSelectorLeaf(items: xdr.ScVal[], sym: string): PredicateLeaf {
         element: expectU32(items[2], 'call_arg_field element'),
         field: expectSymbol(items[3], 'call_arg_field field'),
       }
-    case 'call_arg_scaled':
-      arity(items, 4, sym)
-      return {
-        kind: 'call_arg_scaled',
-        index: expectU32(items[1], 'call_arg_scaled index'),
-        num: expectI128(items[2], 'call_arg_scaled num'),
-        den: expectI128(items[3], 'call_arg_scaled den'),
-      }
-    case 'amount':
-      arity(items, 2, sym)
-      return { kind: 'amount', token: expectAddress(items[1], 'amount token') }
-    case 'window_spent':
-      arity(items, 3, sym)
-      return {
-        kind: 'window_spent',
-        token: expectAddress(items[1], 'window_spent token'),
-        windowSeconds: Number(expectU64(items[2], 'window_spent windowSeconds')),
-      }
-    case 'now':
-      arity(items, 1, sym)
-      return { kind: 'now' }
-    case 'valid_until':
-      // The encoder refuses to emit this and the interpreter refuses it at
-      // install, so it cannot appear in a document that installed. Decoding it
-      // anyway would present a rule the chain would never have accepted.
-      throw malformed('valid_until is not a usable predicate leaf')
-    case 'invocation_count':
-      arity(items, 2, sym)
-      return {
-        kind: 'invocation_count_in_window',
-        windowSecs: Number(expectU64(items[1], 'invocation_count windowSecs')),
-      }
-    case 'oracle_price':
-      arity(items, 2, sym)
-      return { kind: 'oracle_price', asset: expectAddress(items[1], 'oracle_price asset') }
-    case 'oracle_threshold':
-      arity(items, 3, sym)
-      return {
-        kind: 'oracle_threshold',
-        value: expectI128(items[1], 'oracle_threshold value'),
-        decimals: expectU32(items[2], 'oracle_threshold decimals'),
-      }
     default:
       // Deliberately NOT a literal_vec fallback - see the header note.
       throw malformed(`unknown selector symbol '${sym}'`)
@@ -173,38 +116,27 @@ export function decodeLeaf(v: xdr.ScVal): PredicateLeaf {
       return { kind: 'literal_symbol', value: v.sym().toString() }
     case xdr.ScValType.scvU32():
       return { kind: 'literal_u32', value: v.u32() }
-    case xdr.ScValType.scvU64():
-      return { kind: 'literal_u64', value: v.u64().toString() }
     case xdr.ScValType.scvI128():
       return { kind: 'literal_i128', value: scValToBigInt(v).toString() }
-    case xdr.ScValType.scvBytes():
-      return { kind: 'literal_bytes', value: Buffer.from(v.bytes()).toString('hex') }
     default:
       throw malformed(`unsupported leaf value type ${v.switch().name}`)
   }
 }
 
-/** One node. `not` wraps a NODE; the comparison ops wrap two LEAVES. */
+/** One node. The comparison ops wrap two LEAVES. */
 export function decodeNode(v: xdr.ScVal): PredicateNode {
   const items = expectVec(v, 'node')
   const op = selectorSymbol(items)
   if (op === null) throw malformed('node does not start with an operator symbol')
   switch (op) {
-    case 'and':
-    case 'or': {
+    case 'and': {
       arity(items, 2, op)
       const children = expectVec(items[1] as xdr.ScVal, `${op} children`).map(decodeNode)
       if (children.length === 0) throw malformed(`${op} has no children`)
       return { op, children }
     }
-    case 'not':
-      arity(items, 2, op)
-      return { op: 'not', child: decodeNode(items[1] as xdr.ScVal) }
     case 'eq':
-    case 'lt':
     case 'lte':
-    case 'gt':
-    case 'gte':
       arity(items, 3, op)
       return {
         op,