@crediolabs/policy-synth 0.1.11 → 0.1.13

package/dist/run/schemas.js

@@ -219,6 +219,294 @@ export const SynthesizePolicyInputSchema = z.discriminatedUnion('source', [
     SynthesizePolicyMandateInputSchema,
     SynthesizePolicyRecordingInputSchema,
 ]);
+// ===== PredicateNode / PredicateLeaf =====
+//
+// Hand-written zod mirrors of the predicate grammar in types.ts:132-180.
+// Recursive (`and`/`or`/`not` nest), so the schemas use the same
+// `z.lazy` + explicit `z.ZodType<unknown>` annotation that ScValSchema
+// already uses - without the annotation TS's circular type inference
+// breaks the recursive reference. i128-shaped numerics (`num`, `den`)
+// are decimal STRINGS, never JS numbers, matching the on-chain i128
+// convention used everywhere else in this file. The grammar is the
+// single source of truth (types.ts); a drift test in this package
+// asserts the two stay in step.
+/** PredicateLeaf mirrors the core `PredicateLeaf` union. Every variant
+ *  is a `kind` discriminator; literals carry their primitive value inline.
+ *  `literal_vec.elements` is recursive (a vec may contain literals that
+ *  themselves nest) so the leaf schema is lazily self-referential. */
+export const PredicateLeafSchema = z.lazy(() => z.union([
+    z.object({ kind: z.literal('call_contract') }),
+    z.object({ kind: z.literal('call_fn') }),
+    z.object({ kind: z.literal('call_arg'), index: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('call_arg_len'), index: z.number().int().nonnegative() }),
+    z.object({
+        kind: z.literal('call_arg_field'),
+        index: z.number().int().nonnegative(),
+        element: z.number().int().nonnegative(),
+        field: z.string(),
+    }),
+    // num/den are i128 on chain; JSON numbers lose precision past 2^53,
+    // so the wire is a decimal string. The contract refuses `den == 0` and
+    // `num <= 0` / `den <= 0` at install (types.ts:162-163 + the install
+    // gate); mirroring that bound here closes the gap where simulate /
+    // verify green-light a policy the install gate will reject. The
+    // positive-only regex is the cheapest unambiguous check.
+    z.object({
+        kind: z.literal('call_arg_scaled'),
+        index: z.number().int().nonnegative(),
+        num: z.string().regex(/^[1-9][0-9]*$/),
+        den: z.string().regex(/^[1-9][0-9]*$/),
+    }),
+    z.object({ kind: z.literal('amount'), token: z.string() }),
+    z.object({
+        kind: z.literal('window_spent'),
+        token: z.string(),
+        windowSeconds: z.number().int().positive(),
+    }),
+    z.object({ kind: z.literal('now') }),
+    z.object({ kind: z.literal('valid_until') }),
+    z.object({
+        kind: z.literal('invocation_count_in_window'),
+        windowSecs: z.number().int().positive(),
+    }),
+    z.object({ kind: z.literal('oracle_price'), asset: z.string() }),
+    z.object({
+        kind: z.literal('oracle_threshold'),
+        value: z.string().regex(/^-?[0-9]+$/),
+        decimals: z.number().int().nonnegative(),
+    }),
+    z.object({ kind: z.literal('literal_address'), value: z.string() }),
+    z.object({ kind: z.literal('literal_i128'), value: z.string().regex(/^-?[0-9]+$/) }),
+    z.object({ kind: z.literal('literal_symbol'), value: z.string() }),
+    // `literal_u32` is u32 on chain. A negative value would wrap, and a
+    // value above U32_MAX would be refused at the encode boundary
+    // anyway. Bound at the schema so the wire cannot carry a value the
+    // contract will reject.
+    z.object({
+        kind: z.literal('literal_u32'),
+        value: z.number().int().nonnegative().max(U32_MAX),
+    }),
+    z.object({ kind: z.literal('literal_u64'), value: z.string().regex(/^[0-9]+$/) }),
+    // `literal_bytes` is hex on chain. `Buffer.from(value, 'hex')` silently
+    // drops non-hex chars AND yields an empty buffer when the whole input
+    // is non-hex - so a user passing 'zzzz' would get a predicate that
+    // compares against empty bytes instead of being rejected. The
+    // strict even-length hex regex closes that gap at the boundary.
+    z.object({
+        kind: z.literal('literal_bytes'),
+        value: z
+            .string()
+            .regex(/^[0-9a-fA-F]*$/)
+            .refine((v) => v.length % 2 === 0, 'must be even-length hex'),
+    }),
+    // elements are themselves PredicateLeaf; lazy to break the cycle.
+    z.object({ kind: z.literal('literal_vec'), elements: z.array(PredicateLeafSchema) }),
+]));
+/** PredicateNode mirrors the core `PredicateNode` union. Recursive through
+ *  `and`/`or`/`not`; the lazy + annotation pattern keeps the recursion
+ *  type-safe. */
+export const PredicateNodeSchema = z.lazy(() => z.union([
+    z.object({ op: z.literal('and'), children: z.array(PredicateNodeSchema) }),
+    z.object({ op: z.literal('or'), children: z.array(PredicateNodeSchema) }),
+    z.object({ op: z.literal('not'), child: PredicateNodeSchema }),
+    z.object({
+        op: z.literal('eq'),
+        left: PredicateLeafSchema,
+        right: PredicateLeafSchema,
+    }),
+    z.object({
+        op: z.enum(['lt', 'lte', 'gt', 'gte']),
+        left: PredicateLeafSchema,
+        right: PredicateLeafSchema,
+    }),
+    z.object({
+        op: z.literal('in'),
+        needle: PredicateLeafSchema,
+        haystack: z.array(PredicateLeafSchema),
+    }),
+]));
+// ===== simulate_policy / verify_policy =====
+//
+// The oracle fixture shape mirrors `SimulateOptions` / `VerifyOptions`
+// in packages/policy-synth/src/verify/{simulate,verify}.ts - the same
+// sorted set of error enum values is used by both engines. u32
+// `validUntilLedger` is bounded at the boundary so a hand-crafted
+// payload cannot leak a u32 overflow into the engine's permit context.
+/** Oracle price fixture - mirror of the entry type in `SimulateOptions` /
+ *  `VerifyOptions`. Discriminated by presence of `error` vs `price`. */
+export const OraclePriceFixtureSchema = z.union([
+    z.object({
+        price: z.string().regex(/^[0-9]+$/),
+        timestampSeconds: z.number().int().nonnegative(),
+    }),
+    z.object({
+        error: z.enum(['stale', 'missing', 'deviation', 'paused', 'decimals', 'fingerprint']),
+    }),
+]);
+export const SimulatePolicyInputSchema = z.object({
+    // simulatePolicy accepts a null predicate (OZ-only policy); verifyPolicy
+    // does not. The asymmetry is mirrored at the schema boundary.
+    predicate: PredicateNodeSchema.nullable(),
+    permitTx: RecordedTransactionSchema,
+    validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+    oraclePricesByAsset: z.record(z.string(), OraclePriceFixtureSchema).optional(),
+});
+export const VerifyPolicyInputSchema = z.object({
+    // verifyPolicy requires a non-null predicate; the engine refuses
+    // `null` outright. The schema mirrors that contract.
+    predicate: PredicateNodeSchema,
+    permitTx: RecordedTransactionSchema,
+    validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+    oraclePricesByAsset: z.record(z.string(), OraclePriceFixtureSchema).optional(),
+});
+// ===== install_policy / revoke_policy / get_interpreter_info =====
+//
+// The install/revoke pair drives the OZ smart-account admin flow. Both surface
+// unsigned Soroban transaction XDRs (base64) and the tool body NEVER signs:
+// the wallet signature IS the user-confirmation step. See `run/index.ts` for
+// the rationale (no `action_id` two-call pair; the MCP server is stateless).
+//
+// `get_interpreter_info` is a read-only fingerprint lookup. It returns the
+// pinned address + grammar version + wasm hash AND, when requested, runs an
+// optional `grammar_version()` RPC call to check whether the deployed contract
+// matches the pin. A mismatch is worth MORE than a fabricated audit field.
+//
+// All three input schemas live BELOW the MandateSpecSchemaForRule declaration
+// so the const reference there is not in the temporal dead zone (no JS hoisting
+// for `const`).
+/** Minimal rule-draft schema for the install input. Mirrors ContextRuleDraft
+ *  from the core (`types.ts`); we keep this hand-rolled + flat rather than
+ *  importing the recursive discriminated union because the wire shape is
+ *  fixed (the user supplies one rule, not a nested AST). Declared BEFORE
+ *  InstallPolicyInputSchema below so the const reference there is not in
+ *  the temporal dead zone (no JS hoisting for `const`). */
+const MAX_SIGNERS_PER_RULE = 15;
+const MAX_POLICIES_PER_RULE = 5;
+const MandateSpecSchemaForRule = z
+    .object({
+    contextRuleType: z.discriminatedUnion('kind', [
+        z.object({ kind: z.literal('default') }),
+        z.object({ kind: z.literal('call_contract'), contract: z.string() }),
+        z.object({ kind: z.literal('create_contract'), wasmHash: z.string() }),
+    ]),
+    name: z.string().min(1),
+    validUntilLedger: z.number().int().positive().max(U32_MAX).nullable(),
+    signers: z
+        .array(z.discriminatedUnion('kind', [
+        z.object({ kind: z.literal('delegated'), address: z.string() }),
+        z.object({
+            kind: z.literal('external'),
+            verifier: z.string(),
+            keyBytes: z.string(),
+        }),
+    ]))
+        .max(MAX_SIGNERS_PER_RULE),
+    policies: z
+        .array(z.discriminatedUnion('kind', [
+        z.object({
+            kind: z.literal('interpreter'),
+            interpreterAddress: z.string(),
+            predicateBlobBase64: z.string().min(1),
+        }),
+        z.object({
+            kind: z.literal('oz_builtin'),
+            primitive: z.object({
+                primitive: z.enum(['spending_limit', 'simple_threshold', 'weighted_threshold']),
+                params: z.record(z.unknown()),
+            }),
+            instanceAddress: z.string(),
+        }),
+    ]))
+        .max(MAX_POLICIES_PER_RULE),
+})
+    .passthrough()
+    .refine((v) => !(v.signers.length === 0 && v.policies.length === 0), 'a rule with no signers and no policies is refused at install (NoSignersAndPolicies)');
+// install/revoke/get_info schemas live HERE (after the helper) so the const
+// reference resolves at module init. They are the new tools on top of the
+// existing four.
+/** Pinned interpreter address (testnet). Mirrors DEPLOYMENTS.md:156-157.
+ *  Single source for the MCP layer; do not embed elsewhere. */
+export const PINNED_INTERPRETER_TESTNET_ADDRESS = 'CDR4NLV22STCXFGZPNKDQTEANWLF7LZ6AJLY6B7CLJXKHDZGYJWIOKGP';
+/** Pinned interpreter wasm sha256 (hex). Mirrors DEPLOYMENTS.md:156-157. */
+export const PINNED_INTERPRETER_WASM_SHA256 = '6e6c13d93e197aa380303a42cd120f5ddb080dd36ef2a343ee1dbd04ca52a443';
+/** The grammar version the interpreter enforces (matches SELF_VERSION in
+ *  packages/policy-interpreter/src/version.rs). */
+export const PINNED_INTERPRETER_GRAMMAR_VERSION = 1;
+/** Default Soroban RPC for the install / revoke / info tools. The recorder
+ *  keeps its own copy in record/rpc.ts because it hands back a fetcher rather
+ *  than a Server; the two are deliberately different surfaces, so this is
+ *  pinned beside the addresses it is used with rather than shared. */
+export const TESTNET_RPC_URL = 'https://soroban-testnet.stellar.org';
+/** Soroban `valid_until` window (ledgers) added to the latest ledger when
+ *  building the auth entry. ~25 minutes at 5s/ledger. */
+export const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300;
+/** Stellar network passphrases. Pinned here so the XDR envelope uses the
+ *  matching passphrase when the wallet signs (a mismatch yields invalid
+ *  hashes). */
+export const NETWORK_PASSPHRASES = {
+    testnet: 'Test SDF Network ; September 2015',
+    mainnet: 'Public Global Stellar Network ; September 2015',
+};
+export const InstallPolicyInputSchema = z
+    .object({
+    /** The smart account contract address (C...) that will receive the rule. */
+    smartAccount: z.string(),
+    /** The signer that authorises the install (G... wallet). Used only for
+     *  sequence number + auth nonce simulation; never persisted, never signed. */
+    sourceAccount: z.string(),
+    /** The proposed rule draft. Mirrors the core `ContextRuleDraft` shape. */
+    rule: MandateSpecSchemaForRule,
+    /** Per-rule install nonce; 1 for a fresh install. */
+    installNonce: z.number().int().positive(),
+    /** Optional RPC URL override. Defaults to the public testnet endpoint
+     *  (`TESTNET_RPC_URL`); the override is refused unless
+     *  `allowUnpinnedRpcUrl: true`, because the auth nonce and
+     *  rootInvocation in the response come from whichever RPC answered. */
+    rpcUrl: z.string().url().optional(),
+    /** Opt-in to using a non-pinned RPC URL. Without this flag the tool
+     *  refuses any `rpcUrl` other than `TESTNET_RPC_URL` because the
+     *  caller's auth-digest binds to whatever the RPC returned. */
+    allowUnpinnedRpcUrl: z.boolean().optional(),
+    /** Opt-in to pointing the rule's interpreter policy at any address
+     *  other than the pinned testnet interpreter. Default-deny: a caller
+     *  that controls the interpreter can permit everything. */
+    allowUnpinnedInterpreter: z.boolean().optional(),
+    /** Base fee in stroops; defaults to BASE_FEE (100). */
+    baseFee: z.number().int().positive().optional(),
+})
+    .refine((v) => Boolean(v.smartAccount) && Boolean(v.sourceAccount), {
+    message: 'smartAccount and sourceAccount are required',
+});
+export const RevokePolicyInputSchema = z
+    .object({
+    /** The smart account contract address (C...). */
+    smartAccount: z.string(),
+    /** The wallet that will sign the removal. The ACCOUNT decides whether it
+     *  accepts that signer; this schema does not assert a rule it cannot
+     *  verify, since the account's source is not in this repo. Proven on
+     *  testnet: the account's deployer can revoke. */
+    sourceAccount: z.string(),
+    /** The rule id to remove from the smart account + interpreter. */
+    ruleId: z.number().int().nonnegative(),
+    /** Optional RPC URL override; same pin as install. */
+    rpcUrl: z.string().url().optional(),
+    /** Opt-in to using a non-pinned RPC URL. Same semantics as install. */
+    allowUnpinnedRpcUrl: z.boolean().optional(),
+    /** Base fee in stroops; defaults to BASE_FEE (100). */
+    baseFee: z.number().int().positive().optional(),
+})
+    .refine((v) => Boolean(v.smartAccount) && Boolean(v.sourceAccount), {
+    message: 'smartAccount and sourceAccount are required',
+});
+export const GetInterpreterInfoInputSchema = z.object({
+    /** Network to query. The pin differs per network; defaults to testnet. */
+    network: NetworkSchema.optional(),
+    /** When true, perform an optional live `grammar_version()` RPC call to
+     *  verify the deployed contract matches the pin. */
+    verifyLive: z.boolean().optional(),
+    /** Optional RPC URL override. */
+    rpcUrl: z.string().url().optional(),
+});
 // ===== Error envelope (canonical) =====
 //
 // Mirrors ToolError from packages/policy-synth/src/errors.ts. We use a

package/dist/synth/compose-from-recording.d.ts

@@ -31,6 +31,20 @@ export interface ComposeUserResponses {
      *  `oracle_price(asset) OP value` compare in the interpreter IR. Multiple
      *  entries on the same asset emit multiple leaves. */
     oraclePriceBound?: OraclePriceBound[];
+    /** Minimum acceptable swap output per unit of input, as `num/den` (e.g.
+     *  `{num:'95',den:'100'}` = accept losing at most 5%). Emitted as a
+     *  slippage floor bounding the output arg against the input arg of the same
+     *  call.
+     *
+     *  REQUIRED to be supplied by the caller: it is never derived from the
+     *  recording. The recorded in/out pair is a price at one moment, and
+     *  freezing it as policy would deny ordinary trades as soon as the rate
+     *  moves. Absent, no floor is emitted and the existing unbounded-output
+     *  warning stands. */
+    swapMinOutRatio?: {
+        num: string;
+        den: string;
+    };
     /** Recipient allowlist for a swap (call_arg[3] on SoroSwap's
      *  swap_exact_tokens_for_tokens). When supplied, it REPLACES the default
      *  pin. Absent -> the recipient is pinned to the recorded value (mirroring

package/dist/synth/compose-from-recording.js

@@ -197,7 +197,7 @@ export function composeFromRecording(facts, scopeContract, topLevel, opts) {
         // the window_spent path above already consumed the limit, so the per-call
         // arg cap is skipped to avoid binding one limit to two different semantics.
         const swapInputAmountCap = spendTokens.length === 0 ? limitAmount : undefined;
-        appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, opts.userResponses?.swapRecipientAllowlist, swapInputAmountCap, interpreterEnabled);
+        appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, opts.userResponses?.swapRecipientAllowlist, swapInputAmountCap, opts.userResponses?.swapMinOutRatio, interpreterEnabled);
     }
     // `scope.method` is carried on BOTH IRs so each adapter produces a
     // self-consistent rule. The interpreter adapter lowers scope.method into a
@@ -239,7 +239,7 @@ export function composeFromRecording(facts, scopeContract, topLevel, opts) {
  *  SoroSwap's slippage / oracle / exact-path needs come from `userResponses`
  *  (oraclePriceBound + limitAmount) + the recorded path (eq_seq on
  *  call_arg[2]). */
-function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, swapRecipientAllowlist, swapInputAmountCap, interpreterEnabled) {
+function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, swapRecipientAllowlist, swapInputAmountCap, swapMinOutRatio, interpreterEnabled) {
     // SEP-41 transfer / mint: the `to` arg (index 1) is the recipient. Emit it as
     // a single-element allowlist; the interpreter adapter lowers it to `in`.
     // When interpreter is not enabled, route to OZ so the caller sees today's
@@ -447,6 +447,30 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
                 ozConstraints.push(cond);
             }
         }
+        // Slippage floor: `out >= in * num/den`. Only when the caller supplied the
+        // ratio - see `swapMinOutRatio`. Without it the output arg stays free,
+        // which is the case the unbounded-swap warning above describes.
+        const outMinArgIndex = soroswapMinOutArgIndex(protocol.fn);
+        const minOutRatio = swapMinOutRatio;
+        if (minOutRatio !== undefined &&
+            inputArgIndex !== undefined &&
+            outMinArgIndex !== undefined &&
+            inputAmountArg &&
+            inputAmountArg.type === 'i128') {
+            const floor = {
+                op: 'slippage_floor',
+                outArgIndex: outMinArgIndex,
+                inArgIndex: inputArgIndex,
+                num: minOutRatio.num,
+                den: minOutRatio.den,
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(floor);
+            }
+            else {
+                ozConstraints.push(floor);
+            }
+        }
         // Swap recipient (call_arg[3]): when the caller supplies
         // swapRecipientAllowlist, emit it as an `in` constraint on the recipient
         // arg. When absent, PIN the recipient to the recorded value - mirroring the
@@ -491,6 +515,21 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
  *  the exact input as arg[0]; `swap_tokens_for_exact_tokens` takes the maximum
  *  input (`amount_in_max`) as arg[1] - its arg[0] is the exact OUTPUT. Any other
  *  function has no positional input-amount argument -> undefined (no cap bound). */
+/** The argument carrying the swap's MINIMUM ACCEPTABLE OUTPUT.
+ *
+ *  Only the exact-input entrypoints have one: `swap_tokens_for_exact_tokens`
+ *  fixes the output and varies the input, so its output needs no floor (its
+ *  arg[1] is `amount_in_max`, already bounded by the input cap). Returning
+ *  undefined there keeps a floor from being pinned to the wrong argument. */
+function soroswapMinOutArgIndex(fn) {
+    switch (fn) {
+        case 'swap_exact_tokens_for_tokens':
+        case 'swap_exact_in_for_tokens':
+            return 1;
+        default:
+            return undefined;
+    }
+}
 function soroswapInputAmountArgIndex(fn) {
     switch (fn) {
         case 'swap_exact_tokens_for_tokens':

package/dist-cjs/adapters/interpreter/adapter.js

@@ -223,6 +223,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
@@ -286,6 +289,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':
@@ -463,6 +480,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':
@@ -501,6 +520,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-cjs/adapters/oz/adapter.js

@@ -212,6 +212,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-cjs/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 };