@crediolabs/policy-synth 0.1.11 → 0.1.13

package/dist/adapters/interpreter/adapter.js

@@ -218,6 +218,9 @@ function lowerRule(rule, config) {
  *  by `lowerRule` to populate `uncovered` before lowering. */
 function unsupportedConstruct(cond) {
     switch (cond.op) {
+        // Expressible: `call_arg_scaled` is exactly this construct.
+        case 'slippage_floor':
+            return null;
         case 'in':
             // The oracle position rule is a hard error and must be raised before a
             // construct can be written off as uncovered - otherwise a subtree that
@@ -281,6 +284,20 @@ function unsourceableSelector(s) {
  *  address -> SCOPE_SELF_CALL). */
 function lowerCondition(cond, config) {
     switch (cond.op) {
+        // `out >= in * num/den`. The contract refuses den == 0 or a non-positive
+        // ratio at install, so a malformed floor fails loudly rather than
+        // silently inverting the comparison.
+        case 'slippage_floor':
+            return {
+                op: 'gte',
+                left: { kind: 'call_arg', index: cond.outArgIndex },
+                right: {
+                    kind: 'call_arg_scaled',
+                    index: cond.inArgIndex,
+                    num: cond.num,
+                    den: cond.den,
+                },
+            };
         case 'and':
             return { op: 'and', children: cond.children.map((c) => lowerCondition(c, config)) };
         case 'or':
@@ -458,6 +475,8 @@ function assertNoOracleDescendants(node) {
 }
 function containsOracle(node) {
     switch (node.op) {
+        case 'slippage_floor':
+            return false;
         case 'compare':
             return node.compare.selector.kind === 'oracle_price';
         case 'in':
@@ -496,6 +515,8 @@ function assertOracleParamsTighten(params) {
  *  express. Mirrors the OZ adapter's `describeCondition` for parity. */
 function describeCondition(cond) {
     switch (cond.op) {
+        case 'slippage_floor':
+            return `slippage floor: arg[${cond.outArgIndex}] >= arg[${cond.inArgIndex}] * ${cond.num}/${cond.den}`;
         case 'in':
             return `value allowlist on ${describeSelector(cond.selector)} (predicate DSL)`;
         case 'eq_seq':

package/dist/adapters/oz/adapter.js

@@ -207,6 +207,10 @@ function matchSpendingLimit(c) {
  *  cannot express, used to populate `uncovered`. */
 function describeCondition(cond) {
     switch (cond.op) {
+        case 'slippage_floor':
+            // The OZ primitives bound a value against a constant; this bounds one
+            // call argument against another, which none of them can express.
+            return `slippage floor on arg[${cond.outArgIndex}] (OZ built-ins cannot bound one argument against another)`;
         case 'in':
             return `value allowlist on ${describeSelector(cond.selector)} (arg allowlist)`;
         case 'eq_seq':

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

@@ -0,0 +1,218 @@
+import { Contract, rpc, type Transaction } from '@stellar/stellar-sdk';
+import { DEFAULT_GRAMMAR_VERSION } from './build-add-context-rule.ts';
+/** Minimal Soroban RPC surface the install pipeline needs. Test seams
+ *  inject a stub so the builder stays deterministic; production builds
+ *  the real one via `createRpcServer` from `../record/rpc.ts`. */
+export interface InstallRpcClient {
+    getAccount(address: string): Promise<{
+        sequenceNumber(): string;
+    }>;
+    simulateTransaction(tx: Transaction | Parameters<rpc.Server['simulateTransaction']>[0]): Promise<rpc.Api.SimulateTransactionResponse>;
+    getLatestLedger(): Promise<{
+        sequence: number;
+    }>;
+    /** Live `grammar_version()` lookup. Returns the deployed u32. */
+    getContractVersion(address: string): Promise<number>;
+}
+/** Convert a real rpc.Server into the InstallRpcClient surface. The
+ *  `getContractVersion` lookup uses `simulateTransaction` against
+ *  `contract.call('grammar_version')` and decodes the returned u32.
+ *
+ *  The passphrase is a REQUIRED argument rather than something read off the
+ *  server: `rpc.Server` does not carry one, so reaching for
+ *  `server.networkPassphrase` yielded a non-string and every version probe
+ *  died with "Invalid passphrase provided to Transaction". The caller knows
+ *  which network it dialled; make it say so. */
+export declare function rpcClientFromServer(server: rpc.Server, networkPassphrase: string): InstallRpcClient;
+/** Inputs for the install-policy build. */
+export interface BuildInstallPolicyArgs {
+    /** The smart account contract address (C...). */
+    smartAccount: string;
+    /** The signer that authorises the install (G... wallet). */
+    sourceAccount: string;
+    /** Network passphrase - pins the hash the auth digest binds. */
+    networkPassphrase: string;
+    /** The new rule to install. Mirrors the core `ContextRuleDraft`. */
+    rule: BuildInstallPolicyRuleDraft;
+    /** 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). */
+    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;
+}
+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
+ *  the wallet will sign. Deriving `describes` from the input args would
+ *  re-describe the caller's intent rather than the transaction. */
+export interface InstallCallDescribes {
+    /** Smart account that owns the new rule (echoed from the XDR). */
+    targetContract: string;
+    /** The fn name on the target (always `add_context_rule` today). */
+    fnName: 'add_context_rule';
+    /** The new rule's display name, decoded from args[1]. */
+    ruleName: string;
+    /** The `validUntil` ledger sequence decoded from args[2] (null when void). */
+    validUntilLedger: number | null;
+    /** The signers attached to the rule, decoded from args[3]. The
+     *  `verifier`/`keyBytes` payload of an external signer is omitted - it
+     *  is not material to the review card and stays opaque to keep the
+     *  description focused on what the human has to recognise. */
+    signers: Array<{
+        kind: 'delegated';
+        address: string;
+    } | {
+        kind: 'external';
+        verifier: string;
+    }>;
+    /** One entry per policy attached to the rule, decoded from the policies
+     *  map (args[4]). The address is the map key; the kind + extras below
+     *  describe the value. The interpreter policy also reports the
+     *  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';
+    }>;
+    /** 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. */
+    installNonce: number;
+}
+/** Output of the install-policy build. The unsigned XDR is the wallet's
+ *  input; the captured auth nonce + invocation root make the response
+ *  self-describing for callers that want to inspect what they signed. */
+export interface BuildInstallPolicyResult {
+    /** Unsigned Soroban transaction envelope, base64 XDR. */
+    unsignedXdr: string;
+    /** Smart account contract address (echo). */
+    smartAccount: string;
+    /** Source account (echo) - the address that must sign. */
+    sourceAccount: string;
+    /** The host-call target + fn name. Call 2 (interpreter.install) is NOT
+     *  emitted here; the account assigns the rule id in call 1 and call 2
+     *  needs that id to bind its `context_rule_ids`. See `followUp` below. */
+    call: {
+        contract: string;
+        fn: 'add_context_rule';
+    };
+    /** The follow-up call the caller MUST issue after this one confirms.
+     *  The rule id the account assigns in call 1 is required to bind the
+     *  interpreter's `install` auth context. */
+    followUp: {
+        contract: 'interpreter';
+        fn: 'install';
+        requiresRuleIdFromCallOne: true;
+        hint: 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: InstallCallDescribes;
+    /** The auth nonce the host assigned to this call (snapshot). */
+    authNonce: string;
+    /** The ledger sequence + window the auth entry expires at. */
+    authValidUntilLedger: number;
+    /** The captured rootInvocation so a downstream caller can verify the
+     *  signature payload matches the one the host expects. */
+    rootInvocationXdr: string;
+}
+/** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
+ *  The output XDR is signed by the wallet, not by us. */
+export declare function buildInstallPolicyXdr(args: BuildInstallPolicyArgs): Promise<BuildInstallPolicyResult>;
+/** Build an unsigned XDR for `account.remove_context_rule(ruleId)`. The
+ *  smart account itself handles uninstalling each attached policy (calling
+ *  `interpreter.uninstall` for the interpreter policy); this builder only
+ *  emits the account-side removal call.
+ *
+ *  Who may authorise it is the ACCOUNT's decision, and the account's source is
+ *  not in this repo. The interpreter's own `uninstall` is master-gated, but
+ *  that is a different entry point from this one, so do not restate it as the
+ *  rule for this call. What is proven on testnet is that the account's
+ *  deployer can revoke. This builder does not pre-check the signer: it would
+ *  be guessing at a contract it cannot read, and the chain is the authority. */
+export declare function buildRevokePolicyXdr(args: {
+    smartAccount: string;
+    sourceAccount: string;
+    ruleId: number;
+    networkPassphrase: string;
+    rpc: InstallRpcClient;
+    baseFee?: number;
+    authValidUntilLedgers?: number;
+}): Promise<BuildRevokePolicyResult>;
+export interface BuildRevokePolicyResult {
+    unsignedXdr: string;
+    smartAccount: string;
+    sourceAccount: string;
+    call: {
+        contract: string;
+        fn: 'remove_context_rule';
+        ruleId: number;
+    };
+    authNonce: string;
+    authValidUntilLedger: number;
+    rootInvocationXdr: string;
+}
+/** 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 };