@crediolabs/policy-synth 0.2.0 → 0.3.0

package/src/types.ts

@@ -64,13 +64,11 @@ export const MAX_SCVAL_CLONE_DEPTH = 30 as const
  *    - MAX_DEPTH = 5:             3 walkthroughs need depth 2; budget = 2x growth + 1 for `not` chain.
  *    - MAX_LEAVES = 200:         allowlists (recipients, paths) typically < 100; budget = 2x + 1 nested allowlist.
  *    - MAX_PREDICATE_BYTES = 32 KB: well under the per-ledger-entry 64 KB persistent-storage limit.
- *    - MAX_ORACLE_READS = 6:     two-round confirmation per asset consumes 2 reads; cap accommodates a predicate that references up to 3 unique oracle assets (3 * 2 = 6 reads). Stays a fail-closed install-time cap.
  *    - MAX_IN_OPERAND_COUNT = 32: allowlist < 32 is a UX-natural bound. */
 export const PREDICATE_CAPS = {
   MAX_DEPTH: 5,
   MAX_LEAVES: 200,
   MAX_PREDICATE_BYTES: 32 * 1024,
-  MAX_ORACLE_READS: 6,
   MAX_IN_OPERAND_COUNT: 32,
 } as const
 
@@ -97,15 +95,23 @@ export type SignerDraft =
   | { kind: 'external'; verifier: string; keyBytes: string }
 
 /** Reference to one policy attached to a context rule. */
-export type PolicyRef =
-  | { kind: 'oz_builtin'; primitive: OZPrimitiveConfig; instanceAddress: string }
-  | { kind: 'interpreter'; interpreterAddress: string; predicateBlobBase64: string }
+export type PolicyRef = {
+  kind: 'interpreter'
+  interpreterAddress: string
+  predicateBlobBase64: string
+}
+
+/** Grammar version baked into the interpreter wasm, mirroring `SELF_VERSION` in
+ *  `contracts/policy-interpreter/src/version.rs`. Every value this package puts on
+ *  the wire derives from here; `grammar-version-parity.test.ts` pins it to the
+ *  contract so a skew cannot pass a green test run. */
+export const GRAMMAR_VERSION = 3 as const
 
 /** A serialised predicate document stored against a (smart_account, rule_id) pair. */
 export interface PolicyDocument {
   /** Grammar version baked into the interpreter wasm. Fail-closed strict match at install
    *  AND at evaluate (defence in depth). NOT the per-edit revision. */
-  grammarVersion: 1
+  grammarVersion: typeof GRAMMAR_VERSION
   /** Per-rule install nonce. Must equal the interpreter's stored nonce + 1 at install.
    *  First install accepts nonce = 1 with stored nonce = 0. Re-install is structurally
    *  possible by incrementing the nonce; uninstall removes the nonce with state so a
@@ -117,24 +123,13 @@ export interface PolicyDocument {
   /** Hash of the post-canonicalisation bytes of encodedPredicate. Stored alongside the
    *  doc and re-verified at evaluate. */
   predicateHash: string
-  /** Per-policy overrides of oracle thresholds; absent = use defaults.
-   *  Overrides may TIGHTEN only (never widen) - the interpreter rejects any per-policy
-   *  value looser than the wasm-level defaults at install. */
-  oracleParams?: {
-    /** Seconds; must be <= MAX_ORACLE_STALENESS_SECONDS (600). */
-    maxStalenessSeconds?: number
-    /** Basis points; must be <= MAX_ORACLE_DEVIATION_BPS (200). */
-    maxDeviationBps?: number
-  }
 }
 
 /** The versioned predicate AST (interpreter side). Tagged union. */
 export type PredicateNode =
   | { op: 'and'; children: PredicateNode[] }
-  | { op: 'or'; children: PredicateNode[] }
-  | { op: 'not'; child: PredicateNode }
   | { op: 'eq'; left: PredicateLeaf; right: PredicateLeaf }
-  | { op: 'lt' | 'lte' | 'gt' | 'gte'; left: PredicateLeaf; right: PredicateLeaf }
+  | { op: 'lte'; left: PredicateLeaf; right: PredicateLeaf }
   | {
       op: 'in'
       needle: PredicateLeaf
@@ -155,48 +150,18 @@ 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
-  // enforce Context. Scope is per-authorized-context; a v1.1 sub-invocation
-  // tree leaf is gated on the enforce-Context-shape spike result.
-  | { kind: 'amount'; token: string }
-  | { kind: 'window_spent'; token: string; windowSeconds: number }
-  | { kind: 'now' }
-  | { 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 }
   | { kind: 'literal_i128'; value: string }
   | { kind: 'literal_symbol'; value: string }
   | { kind: 'literal_u32'; value: number }
-  | { kind: 'literal_u64'; value: string }
-  | { kind: 'literal_bytes'; value: string } // hex string; wrapped as ScVal::Bytes at encode time
   // Exact ordered vector of literals (e.g. a swap hop path). Encodes to a bare
   // ScVal::Vec with the caller's order preserved verbatim - the order IS the
   // semantic. An exact ordered sequence equality is expressed by `eq(selector,
   // literal_vec([...]))`. `in` is reserved for pure set membership (sorted).
   | { kind: 'literal_vec'; elements: PredicateLeaf[] }
 
-export interface OZPrimitiveConfig {
-  primitive: 'spending_limit' | 'simple_threshold' | 'weighted_threshold'
-  params: Record<string, unknown>
-}
-
 export interface ContractInvocation {
   contract: string
   fn: string
@@ -263,7 +228,6 @@ export type AmbiguityCode =
   | 'AMOUNT_BOUND_MISSING'
   | 'RECIPIENT_ALLOWLIST_EMPTY'
   | 'FREQUENCY_BOUND_MISSING'
-  | 'ORACLE_ASSET_UNKNOWN'
   | 'MULTIPLE_UNRELATED_TARGETS'
 
 /** Structured recording freshness. `overall` is the gate threshold (default 1.0); the

package/dist/install/authority-overlap.d.ts

@@ -1,134 +0,0 @@
-import type { PredicateNode, SignerDraft } from '../types.ts';
-/** Wildcard component of a `Selector`: the predicate does not pin this half. */
-export declare const ANY = "*";
-/** A (contract, function) pair a predicate may permit. `ANY` in either half
- *  means unconstrained, so `{contract: ANY, fn: ANY}` is "any call at all". */
-export interface Selector {
-    contract: string;
-    fn: string;
-}
-export type ContextType = {
-    kind: 'default';
-} | {
-    kind: 'call_contract';
-    address: string;
-} | {
-    kind: 'create_contract';
-    wasmHash: string;
-};
-/** How much we can say about a neighbouring rule.
- *  - `interpreter`: policed by our interpreter and the predicate was readable,
- *    so its authority is known exactly and it can be merged.
- *  - `foreign`: policed by some other contract. The address is visible, the
- *    semantics are not, so it must be reviewed by hand.
- *  - `unpoliced`: no policy at all. Whatever the rule's context type allows,
- *    its signers may do without constraint. */
-export type RuleClass = 'interpreter' | 'foreign' | 'unpoliced';
-export interface ObservedRule {
-    id: number;
-    contextType: ContextType;
-    signers: SignerDraft[];
-    /** Policy contract addresses attached to the rule, in OZ's order. */
-    policyAddresses: string[];
-    /** OZ's global registry ids for those policies, index-aligned with
-     *  `policyAddresses`. `remove_policy` takes the id, not the address, so
-     *  detaching a policy is impossible without them. */
-    policyIds?: number[];
-    /** Per-policy oracle bounds from the stored document, when it was
-     *  readable. A merge must re-install these or it silently widens them. */
-    oracleBounds?: {
-        maxStalenessSeconds?: number;
-        maxDeviationBps?: number;
-        maxCrossFeedDeviationBps?: number;
-    };
-    /** Decoded predicate. Present only when the rule is policed by our
-     *  interpreter AND the stored document was readable. */
-    predicate?: PredicateNode;
-}
-export interface IntendedInstall {
-    /** Rule the predicate is being installed onto. A re-install onto the same
-     *  id is a replacement, not an overlap, so this id is skipped. */
-    ruleId: number;
-    contextType: ContextType;
-    signers: SignerDraft[];
-    predicate: PredicateNode;
-}
-export type OverlapSeverity = 
-/** A neighbouring rule imposes no constraint at all on the shared calls. */
-'bypass'
-/** A neighbouring policy exists but we cannot read what it permits. */
- | 'unknown'
-/** Both rules are ours. The new rule will not restrict the shared calls,
- *  because the signer can name whichever rule is more permissive. */
- | 'not-restricting';
-export interface AuthorityOverlap {
-    ruleId: number;
-    ruleClass: RuleClass;
-    severity: OverlapSeverity;
-    /** Signers present in both rules. Overlap is only reachable by a signer who
-     *  can name both rules, so a rule sharing no signer is not a collision. */
-    sharedSigners: SignerDraft[];
-    /** The selectors both rules can serve. Non-empty by construction. */
-    sharedSelectors: Selector[];
-    /** True when the neighbour is ours and can therefore be replaced by the
-     *  conjunction of the two predicates. */
-    mergeable: boolean;
-    advice: string;
-}
-/** Canonical key for signer equality. Mirrors OZ's `Signer` enum: a delegated
- *  signer is its address, an external signer is the verifier plus the key
- *  bytes, since one verifier may hold many keys. */
-export declare function signerKey(s: SignerDraft): string;
-/** Intersection of two selector SETS: every compatible pairing survives. */
-export declare function intersectSelectors(a: Selector[], b: Selector[]): Selector[];
-/**
- * The set of `(contract, fn)` selectors a predicate may permit.
- *
- * This is a deliberate OVER-approximation: every call the predicate actually
- * permits is covered by some returned selector, and unrecognised structure
- * widens to the wildcard rather than narrowing. That direction is what makes
- * the emptiness test below sound. A call carries exactly one `(contract, fn)`,
- * so if two predicates' over-approximations do not intersect, no single call
- * can be routed to either of them and the rules provably cannot collide.
- *
- * `not` is treated as unconstrained. Complementing a selector set would need
- * the universe of addresses and function names, which is not available and
- * would not be sound to guess.
- */
-export declare function permittedSelectors(node: PredicateNode): Selector[];
-/** Selectors a context type admits, before the predicate narrows them. */
-export declare function selectorsForContextType(ct: ContextType): Selector[];
-/** What a rule can actually authorise: its context type narrowed by its
- *  predicate. An unpoliced or unreadable rule contributes no narrowing. */
-export declare function effectiveSelectors(rule: ObservedRule): Selector[];
-/**
- * Every existing rule that a signer of the intended install could name instead.
- *
- * A rule collides when it shares at least one signer AND at least one selector,
- * because both conditions are needed for the signer to have a choice. The rule
- * being installed onto is skipped: re-installing over it replaces its
- * predicate rather than adding a second source of authority.
- */
-export declare function findAuthorityOverlaps(args: {
-    intended: IntendedInstall;
-    existing: ObservedRule[];
-}): AuthorityOverlap[];
-export interface MergeResult {
-    ok: boolean;
-    predicate?: PredicateNode;
-    /** Set when `ok` is false. */
-    reason?: string;
-}
-/**
- * Conjunction of an existing predicate with a new one, for the tightening case.
- *
- * `and` children are flattened so repeated merges do not nest, which keeps the
- * encoded form closer to the byte cap.
- *
- * The guard matters more than the merge. `and` is only correct when the caller
- * means to tighten. Applied to two predicates that pin DIFFERENT selectors it
- * produces a predicate permitting nothing, which silently disables the policy
- * instead of restricting it. That case is refused, because the caller wanted
- * two capabilities and two rules already express that correctly.
- */
-export declare function mergeIntoAnd(existing: PredicateNode, incoming: PredicateNode): MergeResult;

package/dist/install/build-install-predicate.d.ts

@@ -1,96 +0,0 @@
-import { Contract } from '@stellar/stellar-sdk';
-import type { InstallRpcClient } from './build-install-policy.ts';
-/** Inputs for the install-predicate build. */
-export interface BuildInstallPredicateArgs {
-    /** The smart account contract address (C...). The interpreter hashes
-     *  this rule's `signers` at install; we fetch it via `get_context_rule`
-     *  on this address, not reconstruct it. */
-    smartAccount: string;
-    /** The signer that authorises the install (G... wallet). */
-    sourceAccount: string;
-    /** The rule id the account assigned in call 1. */
-    ruleId: number;
-    /** The interpreter contract address (C...). */
-    interpreterAddress: string;
-    /** Network passphrase - pins the hash the auth digest binds. */
-    networkPassphrase: string;
-    /** Already-encoded (base64) canonical ScVal of the predicate. */
-    encodedPredicate: string;
-    /** Hex sha256 of the canonical predicate XDR bytes. */
-    predicateHash: string;
-    /** Grammar version override; defaults to 1. */
-    grammarVersion?: number;
-    /** Base fee in stroops; defaults to BASE_FEE (100). */
-    baseFee?: number;
-    /** RPC client to use for the simulation pass; injected for tests. */
-    rpc: InstallRpcClient;
-    /** Ledger window (in ledgers) for the auth entry's `validUntil`. */
-    authValidUntilLedgers?: number;
-}
-/** Human-readable description of the install-predicate call, decoded FROM
- *  the built XDR (not from the input args). The wallet signature binds
- *  to bytes; the review card has to bind to the same bytes, so this is
- *  the only safe source.
- *
- *  `ruleId` is NOT decoded from the XDR - it lives inside
- *  `raw_context_rule`, which is passed through verbatim. Decoding it
- *  here would re-introduce the client-side reconstruction the file
- *  header warns against. The top-level `BuildInstallPredicateResult`
- *  echoes the caller-supplied rule id instead. */
-export interface InstallPredicateCallDescribes {
-    /** The interpreter that will hold the predicate. */
-    targetContract: string;
-    /** The fn name on the target (always `install` today). */
-    fnName: 'install';
-    /** Grammar version the interpreter enforces; read off the wire. */
-    grammarVersion: number;
-    /** Per-rule install nonce; read off the wire. */
-    installNonce: number;
-    /** Hex sha256 of the encoded predicate blob; read off the wire. */
-    predicateHash: string;
-    /** Hex sha256 of the predicate bytes embedded in the params map. The
-     *  two values MUST match; a difference is a wire tampering signal. */
-    predicateSha256OfEmbeddedBytes: string;
-    /** The smart account address encoded in args[2], read off the wire. */
-    smartAccountOnWire: string;
-}
-/** Output of the install-predicate build. The unsigned XDR is the
- *  wallet's input; the wallet signs it (single envelope signature) and
- *  submits. The auth tree matches install_policy: account entry
- *  carrying OZ's AuthPayload + a source-account delegated signer entry.
- *  Both are covered by the envelope signature. */
-export interface BuildInstallPredicateResult {
-    /** Unsigned Soroban transaction envelope, base64 XDR. */
-    unsignedXdr: string;
-    /** Smart account contract address (echo). */
-    smartAccount: string;
-    /** Source account (echo) - the address that signs the envelope. */
-    sourceAccount: string;
-    /** The interpreter contract address (echo). */
-    interpreterAddress: string;
-    /** The rule id the account assigned in call 1 (echo). */
-    ruleId: number;
-    /** The host-call target + fn name. */
-    call: {
-        contract: string;
-        fn: 'install';
-    };
-    /** The smart-account auth nonce (snapshot). */
-    authNonce: string;
-    /** The ledger sequence + window the auth entry expires at. */
-    authValidUntilLedger: number;
-    /** The captured rootInvocation for the smart-account entry. */
-    rootInvocationXdr: string;
-    /** Human-readable description of the install call, decoded FROM the
-     *  built unsigned XDR (not from the input args). The wallet signature
-     *  binds to bytes; the review card has to bind to the same bytes, so
-     *  this is the only safe source. */
-    describes: InstallPredicateCallDescribes;
-}
-/** Build the unsigned transaction envelope for
- *  `interpreter.install(params, raw_context_rule, smart_account)`. The
- *  output XDR is signed by the wallet, not by us. */
-export declare function buildInstallPredicateXdr(args: BuildInstallPredicateArgs): Promise<BuildInstallPredicateResult>;
-/** Re-export `Contract` so the run-layer does not need to import the
- *  SDK directly. Mirrors the build-install-policy.ts convention. */
-export { Contract };