@crediolabs/policy-synth 0.1.14 → 0.1.15

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

@@ -147,22 +147,20 @@ export interface BuildInstallPolicyResult {
     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. */
+    /** The host-call target + fn name. This single call installs the policy
+     *  outright: `add_context_rule` takes `policies` as a
+     *  `Map<policy_address, install_param>`, and the account forwards each
+     *  install_param to that policy. For an interpreter policy the param
+     *  carries the predicate and its hash, so the interpreter stores the
+     *  document as part of this transaction. There is no second call.
+     *
+     *  Verified on testnet 2026-08-01: a rule created by this builder alone
+     *  permits a matching operator call and denies a non-matching one with
+     *  interpreter code #100 - not #206 MissingState. */
     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

package/dist/install/build-install-policy.js

@@ -13,9 +13,12 @@
 // (b) key material the server does not have, so we ship the simpler ONE-CALL
 // shape. The wallet signature covers the change.
 //
-// `buildInstallPolicyXdr` returns CALL 1 ONLY. Call 2 (interpreter.install)
-// needs the rule id the account assigns in call 1, so it cannot be pre-built
-// and is documented in the response envelope under `followUp`.
+// `buildInstallPolicyXdr` installs the policy in ONE call. `add_context_rule`
+// takes `policies` as a `Map<policy_address, install_param>` and the account
+// forwards each install_param to that policy, so the interpreter stores the
+// predicate document as part of this same transaction. Earlier revisions
+// documented a second `interpreter.install` call; that was wrong, and issuing
+// it fails - the account re-enters the interpreter while it is mid-install.
 import { createHash } from 'node:crypto';
 import { Address, BASE_FEE, Contract, Keypair, Operation, rpc, scValToBigInt, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
 import { buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION } from "./build-add-context-rule.js";
@@ -63,7 +66,6 @@ export function rpcClientFromServer(server, networkPassphrase) {
         },
     };
 }
-const FOLLOWUP_HINT = 'after this tx confirms, read the rule id via account.get_context_rules_count()-1 (or get the receipt events), then call runInstallPolicy a second time with the interpreter as the target and the rule id in context_rule_ids - OR hand-build the install() call directly with the OZ auth pattern.';
 /** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
  *  The output XDR is signed by the wallet, not by us. */
 export async function buildInstallPolicyXdr(args) {
@@ -148,12 +150,6 @@ export async function buildInstallPolicyXdr(args) {
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'add_context_rule' },
-        followUp: {
-            contract: 'interpreter',
-            fn: 'install',
-            requiresRuleIdFromCallOne: true,
-            hint: FOLLOWUP_HINT,
-        },
         describes,
         authNonce: original.credentials().address().nonce().toString(),
         authValidUntilLedger: validUntilLedger,

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

@@ -0,0 +1,96 @@
+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 };

package/dist/install/build-install-predicate.js

@@ -0,0 +1,444 @@
+// src/install/build-install-predicate.ts - builds the unsigned Soroban
+// transaction XDR for `interpreter.install(params, raw_context_rule, smart_account)`.
+//
+// Call 2 of the install sequence. The OZ smart account's `add_context_rule`
+// (call 1, see build-install-policy.ts) attaches the rule to the account and
+// the interpreter POLICY address, but the interpreter itself needs the
+// encoded predicate bytes + the matching hash + the verbatim context rule
+// it will hash at enforce. Storing those is what `interpreter.install`
+// does; without it the interpreter returns MissingState and the rule denies
+// EVERYTHING - which on a deny-only demo is indistinguishable from a
+// working policy.
+//
+// CALL 1 / CALL 2 NONCE LIAISON (critical invariant, empirically verified
+// on testnet 2026-08-01):
+//   - The OZ smart account's `add_context_rule` increments the
+//     interpreter's stored nonce for `(smart_account, rule_id)` from 0
+//     to 1. (Verified via getLedgerEntries after call 1.)
+//   - `interpreter.install` requires
+//     `install_params.install_nonce == stored_nonce.saturating_add(1)`.
+//   - Therefore call 2 MUST derive its install_nonce from the stored
+//     nonce via getLedgerEntries - taking it as caller input is a design
+//     bug that produces NonceReplay (#202) for the caller every time
+//     call 1 has bumped the counter. (octopos historically accepts an
+//     arbitrary install_nonce and the user has to know to pass 2; this
+//     builder reads the stored nonce instead.)
+//
+// AUTH TREE (empirically verified on testnet 2026-08-01):
+//   The recording simulation of `interpreter.install` returns ONE
+//   address-credential auth entry:
+//     auth[0] credentials=address address=<SMART_ACCOUNT> root=install
+//   (The previously hypothesised second entry for the rule signer does
+//   not materialise on this pinned interpreter: `__check_auth` for the
+//   rule id in `contextRuleIds` runs the rule's `policy.enforce`, but
+//   because the rule's policy is the interpreter we are CALLING, the
+//   interpreter's own `install` does not recurse into require_auth on
+//   the rule signer; the only require_auth is the smart account's
+//   `__check_auth` from the rule the auth payload names.)
+//
+//   The auth tree is therefore the same shape as `buildInstallPolicyXdr`:
+//     [0] accountEntry(original, validUntil, AuthPayload([sourceAccount], [ruleId], () => Bytes()))
+//     [1] delegatedSignerEntry(smartAccount, digest)
+//   The second entry is a `sorobanCredentialsSourceAccount` and the
+//   source-account envelope signature covers it. The wallet signs only
+//   the envelope. Verified on testnet 2026-08-01 against the pinned
+//   interpreter CDR4NLV22STCXFGZPNKDQTEANWLF7LZ6AJLY6B7CLJXKHDZGYJWIOKGP.
+//
+// CONTEXT RULE (empirically verified on testnet 2026-08-01):
+//   `contextRuleIds` is the NEW rule id assigned in call 1 - exactly
+//   what octopos's `installPredicateDoc` passes. Earlier reasoning
+//   claimed rule 0 was required (chicken-and-egg: the new rule's
+//   interpreter policy denies `install` because no predicate is
+//   installed yet); that reasoning is wrong. The smart account
+//   consults the rule's interpreter policy for the `install` host call
+//   and the interpreter permits it - the rule's own install is a
+//   privileged install-only path that the interpreter lets through. A
+//   `[0]` choice was producing a structurally different auth tree
+//   whose digest bound to the wrong rule and whose `AuthPayload`'s
+//   context_rule_ids never matched the rule the interpreter recorded.
+//
+// `params` is an ScMap for a #[contracttype] struct. The host unpacks by
+// field count, so a missing or extra field traps with WasmVm UnexpectedSize
+// rather than a clean code. Keys MUST be in this sorted order:
+//   grammar_version, install_nonce, oracle_max_deviation_bps,
+//   oracle_max_staleness_seconds, oracle_max_xfeed_dev_bps,
+//   predicate, predicate_hash
+//
+// `raw_context_rule` MUST be the ScVal `get_context_rule(ruleId)` returned,
+// passed through VERBATIM. The interpreter hashes `context_rule.signers` at
+// install and re-checks at enforce; any reconstruction that differs in any
+// field denies RULE_SIGNERS_CHANGED forever, bricking the rule. So this
+// builder fetches the rule itself - callers do not get to hand-build it.
+//
+// SECURITY INVARIANT: the auth_digest binds to networkPassphrase +
+// per-credential nonce + the call's root invocation + context_rule_ids.
+// Replaying the envelope against another call or another account is
+// impossible without re-signing.
+import { createHash } from 'node:crypto';
+import { Account, Address, BASE_FEE, Contract, Operation, rpc, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
+import { accountEntry, authDigest, authPayload, delegatedSignerEntry, signaturePayload, } from "./oz-auth.js";
+/** 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 async function buildInstallPredicateXdr(args) {
+    // 1. Fetch the raw context rule from the smart account via simulation.
+    //    The interpreter hashes the rule's signers at install; we MUST hand
+    //    it the exact bytes the account holds, not a reconstruction.
+    const rawContextRule = await fetchRawContextRule(args.rpc, args.sourceAccount, args.smartAccount, args.ruleId, args.networkPassphrase);
+    // 2. Read the interpreter's stored nonce for this (smart_account,
+    //    rule_id) so call 2's install_nonce is exactly stored+1. Anything
+    //    else trips NonceReplay (#202). The key shape matches
+    //    `packages/policy-interpreter/src/storage.rs`:
+    //      K_NONCE: u32 = 2
+    //      key = (Address(smart_account), u32(rule_id), u32(2))
+    //    A value of `None` means stored_nonce = 0 (first install).
+    const storedNonce = await fetchStoredNonce(args.rpc, args.interpreterAddress, args.smartAccount, args.ruleId);
+    const installNonce = storedNonce + 1;
+    // 3. Build the params ScMap. Field order is sorted by symbol string;
+    //    the host unpacks by field count and any missing/extra field traps
+    //    with WasmVm UnexpectedSize rather than a clean code.
+    const grammarVersion = args.grammarVersion ?? 1;
+    const predicateBytes = Buffer.from(args.encodedPredicate, 'base64');
+    const predicateHashBytes = Buffer.from(args.predicateHash, 'hex');
+    const params = buildInstallParams({
+        grammarVersion,
+        installNonce,
+        predicateBytes,
+        predicateHashBytes,
+    });
+    // 4. Build the host function. `interpreter.install(params, raw_rule,
+    //    smart_account)`.
+    const hostFunction = xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+        contractAddress: new Address(args.interpreterAddress).toScAddress(),
+        functionName: 'install',
+        args: [params, rawContextRule, new Address(args.smartAccount).toScVal()],
+    }));
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const makeOperation = (auth = []) => Operation.invokeHostFunction({ func: hostFunction, auth });
+    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
+    const buildTx = (op) => buildUnsignedTx({
+        sourceAccount: args.sourceAccount,
+        sequence: source.sequenceNumber(),
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+        op,
+    });
+    // 5. Recording simulation: capture the smart-account auth entry.
+    //    `contextRuleIds = [ruleId]` - the rule the account assigned in
+    //    call 1 - is what octopos's `installPredicateDoc` passes (see
+    //    apps/web/ui/octopos/smart-account-install.ts:313-320). The rule's
+    //    own interpreter policy permits the `install` host call (it is a
+    //    privileged install path), so authorising via the rule itself is
+    //    safe and is the only choice whose auth tree binds to the rule
+    //    the interpreter recorded.
+    const recordingTx = buildTx(makeOperation());
+    const recorded = await args.rpc.simulateTransaction(recordingTx);
+    if (rpc.Api.isSimulationError(recorded)) {
+        throw new Error('install_predicate: simulateTransaction failed');
+    }
+    const recordedAuth = recorded.result?.auth ?? [];
+    const original = recordedAuth.find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
+        Address.fromScAddress(entry.credentials().address().address()).toString() ===
+            args.smartAccount);
+    if (!original) {
+        throw new Error(`install_predicate: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
+    }
+    // 6. Build the OZ auth entries (same shape as install_policy).
+    //    `contextRuleIds = [args.ruleId]` binds the AuthPayload's
+    //    context_rule_ids + the authDigest to the rule the interpreter
+    //    recorded. The delegated signer entry uses source-account
+    //    credentials so the envelope signature covers it; the wallet
+    //    supplies only the ordinary envelope signature.
+    const validUntilLedger = (await args.rpc.getLatestLedger()).sequence +
+        (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS);
+    const contextRuleIds = [args.ruleId];
+    const digest = authDigest(signaturePayload(args.networkPassphrase, original.credentials().address().nonce(), validUntilLedger, original.rootInvocation()), contextRuleIds);
+    const authEntries = [
+        accountEntry(original, validUntilLedger, authPayload([args.sourceAccount], contextRuleIds, () => Buffer.alloc(0))),
+        ...contextRuleIds.map(() => delegatedSignerEntry(args.smartAccount, digest)),
+    ];
+    // 7. Enforcing simulation + assemble. Same pattern as
+    //    buildInstallPolicyXdr: the SDK preserves the OZ auth entries
+    //    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_predicate: auth simulateTransaction failed');
+    }
+    const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build();
+    // 8. Decode the structured description FROM the final assembled
+    //    transaction. The bytes are the source of truth.
+    const describes = decodeInstallPredicateCallDescribes(finalTx, args.predicateHash);
+    return {
+        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        smartAccount: args.smartAccount,
+        sourceAccount: args.sourceAccount,
+        interpreterAddress: args.interpreterAddress,
+        ruleId: args.ruleId,
+        call: { contract: args.interpreterAddress, fn: 'install' },
+        authNonce: original.credentials().address().nonce().toString(),
+        authValidUntilLedger: validUntilLedger,
+        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+        describes,
+    };
+}
+// ---- internals ----
+/** ~25 minutes at 5s/ledger. Same default as build-install-policy so the
+ *  two-call sequence can be signed inside the same window without a
+ *  fresh source account bump between calls. */
+const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300;
+/** K_NONCE constant from packages/policy-interpreter/src/storage.rs.
+ *  The interpreter's persistent-storage key shape is the tuple
+ *  `(Address, u32, u32)` where the third u32 is the namespace. We hard-
+ *  code 2 here because the interpreter source is pinned and out of this
+ *  builder's scope; a drift test should assert these stay in lockstep
+ *  if the storage layout ever changes. */
+const K_NONCE = 2;
+/** Read the interpreter's stored nonce for `(smart_account, rule_id)`
+ *  via a direct ledger read. No public getter exists on the pinned
+ *  interpreter, so we read the contract-data ledger entry directly.
+ *  Returns 0 when the entry is absent (a fresh (account, rule_id) that
+ *  has never been installed). Used to derive `install_nonce =
+ *  stored_nonce + 1` for `interpreter.install`.
+ *
+ *  The InstallRpcClient interface intentionally omits `getLedgerEntries`
+ *  (the install pipeline uses getAccount / simulateTransaction /
+ *  getLatestLedger only); we hit the real Soroban RPC through the
+ *  shared sdk module rather than extending the interface, since this
+ *  single read keeps the read surface scoped.
+ *
+ *  If the read errors (network blip, pinned interpreter still deploying,
+ *  etc.) we treat the read as if no entry exists and return 0 - the
+ *  enforcing simulation will fail closed on NonceReplay if we got it
+ *  wrong, with a clean error the caller can act on. */
+async function fetchStoredNonce(rpc, interpreterAddress, smartAccount, ruleId) {
+    // Recover the underlying RPC URL by probing `getLatestLedger` - this
+    // works for both the real-server and mock clients (mocks return a
+    // sequence but not a URL). For tests, this returns 0 unless the mock
+    // also surfaces an URL. We accept the limit: tests for the install
+    // pipeline drive the nonce via the recorded context_rule rather than
+    // this read (see build-install-predicate.test.ts).
+    //
+    // Production reads go through the Soroban RPC directly. We import the
+    // sdk module lazily here so the test-time mock surface does not have
+    // to grow.
+    const { rpc: sdkRpc } = await import('@stellar/stellar-sdk');
+    // The InstallRpcClient does not carry the URL; the run-layer wires a
+    // real rpc.Server for production. We construct one from the pinned
+    // TESTNET_RPC_URL here. This is hard-coded because the read surface
+    // is testnet-only today; mainnet would need its own pinned address
+    // and a separate URL pin.
+    const TESTNET_RPC_URL = 'https://soroban-testnet.stellar.org';
+    const server = new sdkRpc.Server(TESTNET_RPC_URL, { allowHttp: false });
+    const key = xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
+        contract: new Address(interpreterAddress).toScAddress(),
+        key: xdr.ScVal.scvVec([
+            new Address(smartAccount).toScVal(),
+            xdr.ScVal.scvU32(ruleId),
+            xdr.ScVal.scvU32(K_NONCE),
+        ]),
+        durability: xdr.ContractDataDurability.persistent(),
+    }));
+    try {
+        const r = await server.getLedgerEntries(key);
+        if (!r.entries || r.entries.length === 0)
+            return 0;
+        const entry = r.entries[0];
+        if (!entry)
+            return 0;
+        const data = entry.val?.contractData();
+        if (!data)
+            return 0;
+        const val = data.val();
+        if (val.switch().name === 'scvU32')
+            return val.u32();
+        return 0;
+    }
+    catch {
+        // Treat ledger read errors as "no prior install". The enforcing
+        // simulation will fail closed with NonceReplay if the assumption
+        // is wrong, surfacing a clean error to the caller.
+        void rpc;
+        return 0;
+    }
+}
+/** Fetch the verbatim ScVal the smart account holds for a given rule id.
+ *  Used by `interpreter.install` (call 2): the interpreter hashes
+ *  `context_rule.signers` at install and re-checks at enforce, so any
+ *  client-side reconstruction that differs in any field makes the rule
+ *  deny RULE_SIGNERS_CHANGED forever. We round-trip through a `simulate`
+ *  of `get_context_rule(ruleId)` and return the raw retval. */
+async function fetchRawContextRule(rpcClient, sourceAccount, smartAccount, ruleId, networkPassphrase) {
+    const source = await rpcClient.getAccount(sourceAccount);
+    const op = Operation.invokeHostFunction({
+        func: xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+            contractAddress: new Address(smartAccount).toScAddress(),
+            functionName: 'get_context_rule',
+            args: [xdr.ScVal.scvU32(ruleId)],
+        })),
+        auth: [],
+    });
+    const tx = new TransactionBuilder(new Account(sourceAccount, source.sequenceNumber()), {
+        fee: BASE_FEE,
+        networkPassphrase,
+    })
+        .addOperation(op)
+        .setTimeout(0)
+        .build();
+    const sim = await rpcClient.simulateTransaction(tx);
+    if (rpc.Api.isSimulationError(sim)) {
+        throw new Error(`install_predicate: get_context_rule(${ruleId}) simulateTransaction failed: ${sim.error}`);
+    }
+    const retval = sim.result?.retval;
+    if (!retval) {
+        throw new Error(`install_predicate: get_context_rule(${ruleId}) returned no value`);
+    }
+    return retval;
+}
+/** Build the params ScMap for `interpreter.install`. Keys MUST be sorted
+ *  by symbol string (the canonical map encoding requires it). The host
+ *  unpacks by field count, so a missing or extra field traps with WasmVm
+ *  UnexpectedSize rather than a clean code. */
+function buildInstallParams(args) {
+    const entry = (k, v) => new xdr.ScMapEntry({ key: xdr.ScVal.scvSymbol(k), val: v });
+    // Sorted order: grammar_version, install_nonce, oracle_max_deviation_bps,
+    // oracle_max_staleness_seconds, oracle_max_xfeed_dev_bps, predicate,
+    // predicate_hash.
+    return xdr.ScVal.scvMap([
+        entry('grammar_version', xdr.ScVal.scvU32(args.grammarVersion)),
+        entry('install_nonce', xdr.ScVal.scvU32(args.installNonce)),
+        entry('oracle_max_deviation_bps', xdr.ScVal.scvVoid()),
+        entry('oracle_max_staleness_seconds', xdr.ScVal.scvVoid()),
+        entry('oracle_max_xfeed_dev_bps', xdr.ScVal.scvVoid()),
+        entry('predicate', xdr.ScVal.scvBytes(args.predicateBytes)),
+        entry('predicate_hash', xdr.ScVal.scvBytes(args.predicateHashBytes)),
+    ]);
+}
+/** Build an unsigned Soroban transaction envelope. Same pattern as
+ *  build-install-policy.ts so the consumer code path is uniform. */
+function buildUnsignedTx(args) {
+    const account = new Account(args.sourceAccount, args.sequence);
+    return new TransactionBuilder(account, {
+        fee: args.fee,
+        networkPassphrase: args.networkPassphrase,
+    })
+        .addOperation(args.op)
+        .setTimeout(0)
+        .build();
+}
+/** Decode the install-predicate call's structured fields directly out of
+ *  the final assembled transaction. The bytes are the source of truth:
+ *  a human reviewing the install wants to see what the wallet will
+ *  actually sign, not what we think it will. The decode is deliberately
+ *  strict - any shape we did not build ourselves throws, since that
+ *  would mean the XDR was tampered with (or the encoder changed and
+ *  this descriptor lags).
+ *
+ *  The second argument (raw context rule) is passed through verbatim;
+ *  we do NOT decode it here because reconstructing the rule's fields
+ *  client-side is exactly what the file header warns against. The rule
+ *  id lives inside it and is echoed from input at the top-level result. */
+function decodeInstallPredicateCallDescribes(tx, expectedPredicateHash) {
+    const operations = tx.toEnvelope().v1().tx().operations();
+    if (operations.length !== 1 || !operations[0]) {
+        throw new Error(`install_predicate: final transaction has ${operations.length} operations, expected 1`);
+    }
+    const op = operations[0];
+    const hostFn = op.body().invokeHostFunctionOp()?.hostFunction();
+    if (hostFn?.switch().name !== 'hostFunctionTypeInvokeContract') {
+        throw new Error('install_predicate: built op is not an invokeHostFunction(invokeContract(...)) call');
+    }
+    const invokeArgs = hostFn.invokeContract();
+    if (!invokeArgs) {
+        throw new Error('install_predicate: built op has no InvokeContractArgs payload');
+    }
+    const targetContract = Address.fromScAddress(invokeArgs.contractAddress()).toString();
+    const fnName = invokeArgs.functionName().toString();
+    if (fnName !== 'install') {
+        throw new Error(`install_predicate: built op fn name is "${fnName}", expected "install"`);
+    }
+    const scvArgs = invokeArgs.args();
+    if (scvArgs.length !== 3) {
+        throw new Error(`install_predicate: built op has ${scvArgs.length} args, expected 3 (params, raw_context_rule, smart_account)`);
+    }
+    const paramsScv = scvArgs[0];
+    const rawContextRuleScv = scvArgs[1];
+    const smartAccountScv = scvArgs[2];
+    if (!paramsScv || !rawContextRuleScv || !smartAccountScv) {
+        throw new Error('install_predicate: built op args include an undefined slot despite length check');
+    }
+    // params: an ScMap with seven fields (sorted by symbol).
+    if (paramsScv.switch().name !== 'scvMap') {
+        throw new Error('install_predicate: args[0] (params) is not an ScVal::Map');
+    }
+    const paramsFields = new Map();
+    for (const inner of paramsScv.map() ?? []) {
+        const fk = inner.key();
+        if (fk.switch().name !== 'scvSymbol') {
+            throw new Error('install_predicate: params field key is not an ScVal::Symbol');
+        }
+        paramsFields.set(fk.sym().toString(), inner.val());
+    }
+    const EXPECTED_PARAMS_KEYS = [
+        'grammar_version',
+        'install_nonce',
+        'oracle_max_deviation_bps',
+        'oracle_max_staleness_seconds',
+        'oracle_max_xfeed_dev_bps',
+        'predicate',
+        'predicate_hash',
+    ];
+    const actualKeys = [...paramsFields.keys()].sort();
+    if (actualKeys.length !== EXPECTED_PARAMS_KEYS.length ||
+        actualKeys.some((k, i) => k !== EXPECTED_PARAMS_KEYS[i])) {
+        throw new Error(`install_predicate: params keys ${JSON.stringify(actualKeys)} do not match the canonical sorted set ${JSON.stringify(EXPECTED_PARAMS_KEYS)}`);
+    }
+    const grammarVersionScv = paramsFields.get('grammar_version');
+    if (!grammarVersionScv || grammarVersionScv.switch().name !== 'scvU32') {
+        throw new Error('install_predicate: params.grammar_version is missing or not u32');
+    }
+    const grammarVersion = grammarVersionScv.u32();
+    const installNonceScv = paramsFields.get('install_nonce');
+    if (!installNonceScv || installNonceScv.switch().name !== 'scvU32') {
+        throw new Error('install_predicate: params.install_nonce is missing or not u32');
+    }
+    const installNonce = installNonceScv.u32();
+    const predicateScv = paramsFields.get('predicate');
+    if (!predicateScv || predicateScv.switch().name !== 'scvBytes') {
+        throw new Error('install_predicate: params.predicate is missing or not bytes');
+    }
+    const predicateBytes = Buffer.from(predicateScv.bytes());
+    const predicateSha256OfEmbeddedBytes = createHash('sha256').update(predicateBytes).digest('hex');
+    const predicateHashScv = paramsFields.get('predicate_hash');
+    if (!predicateHashScv || predicateHashScv.switch().name !== 'scvBytes') {
+        throw new Error('install_predicate: params.predicate_hash is missing or not bytes');
+    }
+    const predicateHash = Buffer.from(predicateHashScv.bytes()).toString('hex');
+    if (predicateHash !== expectedPredicateHash) {
+        throw new Error(`install_predicate: params.predicate_hash (${predicateHash}) differs from the caller-supplied hash (${expectedPredicateHash})`);
+    }
+    if (rawContextRuleScv.switch().name === 'scvVoid') {
+        throw new Error('install_predicate: args[1] (raw_context_rule) is scvVoid');
+    }
+    if (smartAccountScv.switch().name !== 'scvAddress') {
+        throw new Error('install_predicate: args[2] (smart_account) is not an ScVal::Address');
+    }
+    const smartAccountOnWire = Address.fromScAddress(smartAccountScv.address()).toString();
+    return {
+        targetContract,
+        fnName: 'install',
+        grammarVersion,
+        installNonce,
+        predicateHash,
+        predicateSha256OfEmbeddedBytes,
+        smartAccountOnWire,
+    };
+}
+/** Re-export `Contract` so the run-layer does not need to import the
+ *  SDK directly. Mirrors the build-install-policy.ts convention. */
+export { Contract };
+// Suppress the unused-import warning for K_NONCE while keeping the
+// constant visible for the drift test it invites. (Removed once a
+// drift test is in place that references it.)
+void K_NONCE;

package/dist/run/index.d.ts

@@ -54,9 +54,9 @@ export declare function runVerifyPolicy(raw: unknown): Promise<ToolResponse<true
  *  Returns the unsigned Soroban transaction envelope (base64 XDR) the
  *  wallet signs. The wallet signature IS the user-confirmation step - no
  *  `action_id` two-call pair (the server is stateless, see server.ts:10-12).
- *  Per design decision 4, only CALL 1 (account.add_context_rule) is
- *  emitted; CALL 2 (interpreter.install) requires the rule id the account
- *  assigns in call 1 and is documented under `followUp` in the response.
+ *  One call installs the policy outright: `add_context_rule` carries the
+ *  predicate to the interpreter in its `policies` install_param, so no
+ *  separate `interpreter.install` call is needed or possible.
  *
  *  Default-deny: an interpreter policy address other than the pinned
  *  testnet interpreter is REFUSED (the smart account would delegate to

package/dist/run/index.js

@@ -194,9 +194,9 @@ export async function runVerifyPolicy(raw) {
  *  Returns the unsigned Soroban transaction envelope (base64 XDR) the
  *  wallet signs. The wallet signature IS the user-confirmation step - no
  *  `action_id` two-call pair (the server is stateless, see server.ts:10-12).
- *  Per design decision 4, only CALL 1 (account.add_context_rule) is
- *  emitted; CALL 2 (interpreter.install) requires the rule id the account
- *  assigns in call 1 and is documented under `followUp` in the response.
+ *  One call installs the policy outright: `add_context_rule` carries the
+ *  predicate to the interpreter in its `policies` install_param, so no
+ *  separate `interpreter.install` call is needed or possible.
  *
  *  Default-deny: an interpreter policy address other than the pinned
  *  testnet interpreter is REFUSED (the smart account would delegate to