@crediolabs/policy-synth 0.2.0 → 0.3.0

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

@@ -1,134 +0,0 @@
-"use strict";
-//! Transactions for the merge remedy.
-//!
-//! `plan-merge-policy.ts` decides WHAT should happen; this builds the XDR for
-//! the step the caller asked for. Two calls, in order, because OZ refuses to
-//! attach a policy that is already on the rule:
-//!
-//!   step 1 `detach`    -> `account.remove_policy(rule_id, policy_id)`
-//!   step 2 `reinstall` -> `account.add_policy(rule_id, interpreter, param)`
-//!
-//! The two cannot be emitted together. Simulating step 2 while the old
-//! attachment is still there hits `DuplicatePolicy`, so the second transaction
-//! is only buildable once the first has confirmed.
-//!
-//! Both calls route through the smart account and are authorised the same way
-//! as `revoke_policy`: against the deploy-time admin rule, with the recorded
-//! `rootInvocation` binding the auth payload to this exact rule and policy.
-//! Detaching runs our `uninstall`, which is master-gated, so the signer has to
-//! be a master of the rule either way.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ADMIN_CONTEXT_RULE_ID = void 0;
-exports.buildMergePolicyXdr = buildMergePolicyXdr;
-const stellar_sdk_1 = require("@stellar/stellar-sdk");
-const build_add_context_rule_ts_1 = require("./build-add-context-rule.js");
-const oz_auth_ts_1 = require("./oz-auth.js");
-/** Matches the window the install and revoke builders use. */
-const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 100;
-/**
- * The context rule the merge authorises AGAINST, which is not the rule being
- * merged.
- *
- * Both calls mutate the smart account itself, so they need the account's own
- * authorisation, and this builder asks rule 0 for it - the same assumption the
- * install and revoke builders make. OpenZeppelin does NOT enforce any
- * admin semantic for rule 0: it is simply the first rule the account's
- * constructor created, and OZ's reference account creates it as `Default`
- * covering every context.
- *
- * The assumption is therefore load-bearing and unverified at build time. If
- * rule 0 does not exist, does not cover `CallContract(<smart account>)`, or
- * does not list the source account as a signer, the transaction is built and
- * then fails when submitted, and the operator pays the fee for a transaction
- * that was never signable. Changing it is a wire-visible change: the id is
- * hashed into the auth digest.
- */
-exports.ADMIN_CONTEXT_RULE_ID = 0;
-function hostFunctionFor(args) {
-    if (args.step === 'detach') {
-        return stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
-            contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
-            functionName: 'remove_policy',
-            args: [stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId), stellar_sdk_1.xdr.ScVal.scvU32(args.policyId)],
-        }));
-    }
-    if (!args.encodedPredicate || !args.predicateHash) {
-        throw new Error('merge_policy: reinstall needs the merged predicate and its hash');
-    }
-    return stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
-        contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
-        functionName: 'add_policy',
-        args: [
-            stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId),
-            new stellar_sdk_1.Address(args.interpreterAddress).toScVal(),
-            // Same encoder as a fresh install: the field order is ABI-significant
-            // and it re-hashes the predicate to confirm the supplied hash.
-            (0, build_add_context_rule_ts_1.encodePolicyInstallParams)({
-                encodedPredicate: args.encodedPredicate,
-                predicateHash: args.predicateHash,
-                installNonce: args.installNonce ?? 1,
-                grammarVersion: build_add_context_rule_ts_1.DEFAULT_GRAMMAR_VERSION,
-                ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
-            }),
-        ],
-    }));
-}
-/**
- * Build the unsigned transaction for one step of the merge.
- *
- * The auth dance mirrors `buildRevokePolicyXdr`: simulate once to record the
- * account's auth entry, rebuild with the payload bound to that recorded
- * `rootInvocation`, then assemble. Binding to the recorded invocation rather
- * than to the input arguments is what makes the signature commit to the exact
- * rule and policy being changed.
- */
-async function buildMergePolicyXdr(args) {
-    const fn = args.step === 'detach' ? 'remove_policy' : 'add_policy';
-    const source = await args.rpc.getAccount(args.sourceAccount);
-    const hostFunction = hostFunctionFor(args);
-    const makeOperation = (auth = []) => stellar_sdk_1.Operation.invokeHostFunction({ func: hostFunction, auth });
-    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : stellar_sdk_1.BASE_FEE;
-    const buildTx = (op) => new stellar_sdk_1.TransactionBuilder(new stellar_sdk_1.Account(args.sourceAccount, source.sequenceNumber()), {
-        fee: baseFee,
-        networkPassphrase: args.networkPassphrase,
-    })
-        .addOperation(op)
-        .setTimeout(0)
-        .build();
-    const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()));
-    if (stellar_sdk_1.rpc.Api.isSimulationError(recorded)) {
-        // Short and stable, like the other builders: the SDK's full error carries
-        // host and URL detail that has no business in a user-facing message.
-        throw new Error(`merge_policy: ${fn} simulateTransaction failed`);
-    }
-    const original = (recorded.result?.auth ?? []).find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
-        stellar_sdk_1.Address.fromScAddress(entry.credentials().address().address()).toString() ===
-            args.smartAccount);
-    if (!original) {
-        throw new Error(`merge_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
-    }
-    const validUntilLedger = (await args.rpc.getLatestLedger()).sequence +
-        (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS);
-    const contextRuleIds = [exports.ADMIN_CONTEXT_RULE_ID];
-    const digest = (0, oz_auth_ts_1.authDigest)((0, oz_auth_ts_1.signaturePayload)(args.networkPassphrase, original.credentials().address().nonce(), validUntilLedger, original.rootInvocation()), contextRuleIds);
-    const authEntries = [
-        (0, oz_auth_ts_1.accountEntry)(original, validUntilLedger, (0, oz_auth_ts_1.authPayload)([args.sourceAccount], contextRuleIds, () => Buffer.alloc(0))),
-        ...contextRuleIds.map(() => (0, oz_auth_ts_1.delegatedSignerEntry)(args.smartAccount, digest)),
-    ];
-    const txWithAuth = buildTx(makeOperation(authEntries));
-    const enforcing = await args.rpc.simulateTransaction(txWithAuth);
-    if (stellar_sdk_1.rpc.Api.isSimulationError(enforcing)) {
-        throw new Error(`merge_policy: ${fn} auth simulateTransaction failed`);
-    }
-    const finalTx = stellar_sdk_1.rpc.assembleTransaction(txWithAuth, enforcing).build();
-    return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
-        smartAccount: args.smartAccount,
-        sourceAccount: args.sourceAccount,
-        step: args.step,
-        call: { contract: args.smartAccount, fn, ruleId: args.ruleId },
-        authNonce: original.credentials().address().nonce().toString(),
-        authValidUntilLedger: validUntilLedger,
-        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
-    };
-}

package/dist-cjs/install/plan-merge-policy.d.ts

@@ -1,49 +0,0 @@
-import type { PredicateNode } from '../types.ts';
-import type { ObservedRule } from './authority-overlap.ts';
-export type MergeStep = 'detach' | 'reinstall';
-export interface MergePlanRefused {
-    ok: false;
-    /** Why the merge cannot proceed, in terms the caller can act on. */
-    reason: string;
-}
-export interface MergePlanAccepted {
-    ok: true;
-    /** The conjunction to install in step 2. */
-    predicate: PredicateNode;
-    /** OZ registry id of the interpreter policy on this rule, for
-     *  `remove_policy`. */
-    policyId: number;
-    /** Oracle bounds to re-install with the merged predicate. Carried from the
-     *  document being replaced: they are tighten-only overrides against the wasm
-     *  defaults, so omitting them would quietly widen the policy while the
-     *  operator believed they were tightening it. */
-    oracleParams?: {
-        maxStalenessSeconds?: number;
-        maxDeviationBps?: number;
-        maxCrossFeedDeviationBps?: number;
-    };
-    /** Consequences the caller must see BEFORE signing step 1, because step 1 is
-     *  the destructive one. */
-    warnings: string[];
-    /** What the caller should do after the requested step confirms. */
-    followUp: string;
-}
-export type MergePlan = MergePlanRefused | MergePlanAccepted;
-/** The interpreter's registry id on a rule, or null when it is not attached
- *  or the ids were not readable. */
-export declare function interpreterPolicyId(rule: ObservedRule, interpreterAddress: string): number | null;
-/**
- * Decide whether the merge can proceed, and say what it will cost.
- *
- * Refuses rather than guesses whenever the account is not in the shape the
- * remedy assumes: the rule must be policed by our interpreter, its predicate
- * must have been readable, and the ids needed to detach it must be present. A
- * merge built on a predicate we could not read would silently replace a rule
- * with something narrower or wider than its author wrote.
- */
-export declare function planMergePolicy(args: {
-    rule: ObservedRule;
-    interpreterAddress: string;
-    incoming: PredicateNode;
-    step: MergeStep;
-}): MergePlan;

package/dist-cjs/install/plan-merge-policy.js

@@ -1,90 +0,0 @@
-"use strict";
-//! Planning the merge remedy for a cross-rule authority overlap.
-//!
-//! When two rules our interpreter polices can serve the same calls, the
-//! tightening remedy is to replace one rule's predicate with the conjunction
-//! of both (see `authority-overlap.ts`). Carrying that out against an OZ smart
-//! account is not one call, and the reasons are worth stating because they
-//! shape the whole tool:
-//!
-//!   1. A Soroban transaction carries exactly ONE operation - "smart contract
-//!      transactions can only have one operation per transaction" - so the
-//!      detach and the re-attach cannot be bundled even though the host would
-//!      run them in order happily. And `add_policy` panics `DuplicatePolicy`
-//!      while the policy is still attached (`smart_account/storage.rs`
-//!      `add_policy`), so the second transaction cannot even be simulated
-//!      until the first has confirmed.
-//!   2. `remove_policy` calls `try_uninstall` and DISCARDS the result
-//!      (`smart_account/storage.rs`: `let _ = ...try_uninstall(...)`), so the
-//!      policy is detached whether or not our `uninstall` succeeded. When it
-//!      succeeded the document, nonce, signer hash, master set and counters
-//!      are gone and the re-install is a fresh install at nonce 1. When it
-//!      panicked - our `uninstall` panics `MissingState` if the master set has
-//!      been archived - the nonce SURVIVES, and re-installing at 1 would be
-//!      refused on chain as a replay, leaving the rule stuck unpoliced. The
-//!      nonce is therefore READ at reinstall time rather than assumed.
-//!   3. Because of (2), any rate-limit or spend window on that rule is reset
-//!      by the merge. A signer who had consumed most of a window gets a clean
-//!      one. That is a real cost of tightening this way and the caller has to
-//!      be told, not discover it.
-//!   4. So the caller performs step 1, waits for it to confirm, then asks for
-//!      step 2.
-//!
-//! This module is pure. It decides what should happen and why; the XDR is
-//! built by `build-merge-policy.ts`.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.interpreterPolicyId = interpreterPolicyId;
-exports.planMergePolicy = planMergePolicy;
-const authority_overlap_ts_1 = require("./authority-overlap.js");
-/** The interpreter's registry id on a rule, or null when it is not attached
- *  or the ids were not readable. */
-function interpreterPolicyId(rule, interpreterAddress) {
-    const index = rule.policyAddresses.indexOf(interpreterAddress);
-    if (index < 0)
-        return null;
-    const id = rule.policyIds?.[index];
-    return typeof id === 'number' ? id : null;
-}
-/**
- * Decide whether the merge can proceed, and say what it will cost.
- *
- * Refuses rather than guesses whenever the account is not in the shape the
- * remedy assumes: the rule must be policed by our interpreter, its predicate
- * must have been readable, and the ids needed to detach it must be present. A
- * merge built on a predicate we could not read would silently replace a rule
- * with something narrower or wider than its author wrote.
- */
-function planMergePolicy(args) {
-    const policyId = interpreterPolicyId(args.rule, args.interpreterAddress);
-    if (policyId === null) {
-        return {
-            ok: false,
-            reason: `rule ${args.rule.id} is not policed by the interpreter at ${args.interpreterAddress}, or its policy ids could not be read, so there is nothing to merge into and no id to detach. The merge hard-pins to that interpreter and has no opt-out: the auth digest it builds binds to the audited deployment. A rule installed against a different interpreter has to be replaced rather than merged.`,
-        };
-    }
-    const existing = args.rule.predicate;
-    if (!existing) {
-        return {
-            ok: false,
-            reason: `the predicate installed on rule ${args.rule.id} could not be read, so it cannot be conjoined; merging against an unknown predicate would replace the rule with something other than what its author wrote`,
-        };
-    }
-    const merged = (0, authority_overlap_ts_1.mergeIntoAnd)(existing, args.incoming);
-    if (!merged.ok || !merged.predicate) {
-        return { ok: false, reason: merged.reason ?? 'the two predicates cannot be conjoined' };
-    }
-    const warnings = [
-        `detaching the policy uninstalls it, which removes every counter on rule ${args.rule.id}: any rate limit or spend window there restarts from zero after the merge`,
-        'the rule is unpoliced between the two transactions, so a signer of it is unconstrained by this policy until step 2 confirms',
-    ];
-    return {
-        ok: true,
-        predicate: merged.predicate,
-        policyId,
-        ...(args.rule.oracleBounds ? { oracleParams: args.rule.oracleBounds } : {}),
-        warnings,
-        followUp: args.step === 'detach'
-            ? "sign and submit this transaction, wait for it to confirm, then call again with step: 'reinstall' to install the merged predicate"
-            : 'sign and submit this transaction; the merged predicate is then the only policy governing this rule',
-    };
-}

package/dist-cjs/install/read-account-rules.d.ts

@@ -1,100 +0,0 @@
-import { rpc, xdr } from '@stellar/stellar-sdk';
-import type { SignerDraft } from '../types.ts';
-import type { ContextType, ObservedRule } from './authority-overlap.ts';
-/** `storage.rs:295` - the third element of the persistent doc key tuple. */
-export declare const K_DOC = 1;
-/** Persistent-storage key for a rule's stored document:
- *  `(account, rule_id, K_DOC)`, per `storage.rs:4`. */
-export declare function docKeyScVal(smartAccount: string, ruleId: number): xdr.ScVal;
-/** Ledger key for the interpreter's persistent entry holding that document. */
-export declare function docLedgerKey(interpreter: string, smartAccount: string, ruleId: number): xdr.LedgerKey;
-/** OZ `ContextRuleType`. An unrecognised tag is reported as `default`, which
- *  is the widest reading and therefore the safe one: it makes the rule look
- *  like it could serve any call, so overlap is over-reported, never missed. */
-export declare function decodeContextType(v: xdr.ScVal | undefined): ContextType;
-/** OZ `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
-export declare function decodeSigner(v: xdr.ScVal): SignerDraft | undefined;
-/** A full OZ `ContextRule` as returned by `get_context_rule(id)`.
- *  `predicate` is filled in separately from the ledger entry. */
-export declare function decodeContextRule(v: xdr.ScVal): ObservedRule | undefined;
-/** `storage.rs:296` - the third element of the persistent nonce key tuple. */
-export declare const K_NONCE = 2;
-/** Ledger key for a rule's stored install nonce. Read directly for the same
- *  reason as the document: the interpreter publishes no getter. */
-export declare function nonceLedgerKey(interpreter: string, smartAccount: string, ruleId: number): xdr.LedgerKey;
-/** Per-policy oracle bounds carried on a `StoredDoc`.
- *
- *  These must survive a merge. They are tighten-only overrides against the
- *  wasm defaults, so dropping them does not fail loudly: the rule keeps
- *  working and silently tolerates staler prices and wider deviation than its
- *  author chose. */
-export interface StoredOracleBounds {
-    maxStalenessSeconds?: number;
-    maxDeviationBps?: number;
-    maxCrossFeedDeviationBps?: number;
-}
-export declare function decodeStoredOracleBounds(v: xdr.ScVal): StoredOracleBounds;
-/** Raw predicate bytes out of a `StoredDoc` ledger entry value. */
-export declare function decodeStoredPredicateBytes(v: xdr.ScVal): Buffer | undefined;
-/** The three reads the scan needs. Kept as an interface so the collection
- *  below is testable without a network, matching the `InstallRpcClient`
- *  pattern in `build-install-policy.ts`. */
-export interface AccountRuleReader {
-    /** OZ `get_context_rules_count()`. */
-    getContextRuleCount(smartAccount: string): Promise<number>;
-    /** OZ `get_context_rule(id)`. Undefined when the id is absent. */
-    getContextRule(smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
-    /** The interpreter's persistent `StoredDoc` entry, read as a ledger entry.
-     *  Undefined when no document is stored for that rule. */
-    getStoredDoc(interpreter: string, smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
-}
-/** How far the id scan will probe before giving up. OZ imposes no per-account
- *  rule cap, so there is no exact bound to derive; this one is far above any
- *  realistic account and keeps a malformed `Count` from spinning forever. */
-export declare const MAX_RULE_ID_SCAN = 512;
-export interface CollectedRules {
-    rules: ObservedRule[];
-    /** Rule ids whose stored predicate could not be read even though the
-     *  interpreter is attached. Such a rule is reported without a predicate,
-     *  which classifies it as opaque rather than as safely narrow. */
-    unreadablePredicateRuleIds: number[];
-    /** True when the scan stopped before accounting for every live rule. The
-     *  result is then a SUBSET of the account's rules, so an empty overlap list
-     *  proves nothing and the caller must not present it as safety. */
-    incomplete: boolean;
-}
-/**
- * Every context rule on the account, with predicates filled in for the rules
- * our interpreter polices.
- *
- * Rule ids are NOT contiguous. OZ assigns them from a monotonic `NextId` and
- * decrements `Count` on removal without ever reusing an id
- * (`smart_account/storage.rs`: `add_context_rule` bumps `NextId`,
- * `remove_context_rule` only lowers `Count`), so after any removal
- * `Count < NextId` and the live ids have gaps. Iterating `0..Count-1` would
- * silently skip live rules at higher ids, and a skipped rule is a missed
- * overlap - the one error that reports safety which does not exist. Instead
- * the scan walks ids upward until it has accounted for `Count` live rules.
- *
- * A rule whose predicate cannot be read is deliberately left without one. That
- * demotes it to the `foreign` class, so the scan reports it as opaque instead
- * of assuming it is narrow.
- */
-export declare function collectObservedRules(args: {
-    reader: AccountRuleReader;
-    smartAccount: string;
-    interpreterAddress: string;
-    maxRuleIdScan?: number;
-}): Promise<CollectedRules>;
-/**
- * An `AccountRuleReader` over a live RPC server.
- *
- * The two OZ getters are read-only simulations, built the same way as
- * `getContractVersion` in `build-install-policy.ts`: the source account is
- * constructed locally because a simulation never checks its sequence number,
- * and asking the network for a random key would 404.
- *
- * The stored document is fetched as a ledger entry rather than a contract
- * call, because the interpreter publishes no getter for it.
- */
-export declare function accountRuleReaderFromServer(server: rpc.Server, networkPassphrase: string): AccountRuleReader;

package/dist-cjs/install/read-account-rules.js

@@ -1,296 +0,0 @@
-"use strict";
-//! Reading an OpenZeppelin smart account's context rules back off chain.
-//!
-//! `authority-overlap.ts` needs to know what a signer can already do before a
-//! new policy is installed. That means every rule on the account: its context
-//! type, its signers, its attached policies, and - for rules our interpreter
-//! polices - the predicate itself.
-//!
-//! The predicate is NOT reachable through a contract call. The interpreter
-//! exposes no getter for `StoredDoc` (`lib.rs` publishes only `grammar_version`,
-//! `install`, `enforce`, the pause pair, `uninstall` and
-//! `rotate_master_signer_set`), so it is read as a ledger entry instead. That
-//! keeps this a pure client-side capability: adding a getter would change a
-//! deployed contract's ABI and force a redeploy plus re-audit to obtain data
-//! the ledger already exposes.
-//!
-//! The decoders here are pure so they can be tested without a network; the
-//! caller supplies raw `ScVal`s.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_RULE_ID_SCAN = exports.K_NONCE = exports.K_DOC = void 0;
-exports.docKeyScVal = docKeyScVal;
-exports.docLedgerKey = docLedgerKey;
-exports.decodeContextType = decodeContextType;
-exports.decodeSigner = decodeSigner;
-exports.decodeContextRule = decodeContextRule;
-exports.nonceLedgerKey = nonceLedgerKey;
-exports.decodeStoredOracleBounds = decodeStoredOracleBounds;
-exports.decodeStoredPredicateBytes = decodeStoredPredicateBytes;
-exports.collectObservedRules = collectObservedRules;
-exports.accountRuleReaderFromServer = accountRuleReaderFromServer;
-const stellar_sdk_1 = require("@stellar/stellar-sdk");
-const decode_ts_1 = require("../predicate/decode.js");
-/** `storage.rs:295` - the third element of the persistent doc key tuple. */
-exports.K_DOC = 1;
-/** Persistent-storage key for a rule's stored document:
- *  `(account, rule_id, K_DOC)`, per `storage.rs:4`. */
-function docKeyScVal(smartAccount, ruleId) {
-    return stellar_sdk_1.xdr.ScVal.scvVec([
-        new stellar_sdk_1.Address(smartAccount).toScVal(),
-        stellar_sdk_1.xdr.ScVal.scvU32(ruleId),
-        stellar_sdk_1.xdr.ScVal.scvU32(exports.K_DOC),
-    ]);
-}
-/** Ledger key for the interpreter's persistent entry holding that document. */
-function docLedgerKey(interpreter, smartAccount, ruleId) {
-    return stellar_sdk_1.xdr.LedgerKey.contractData(new stellar_sdk_1.xdr.LedgerKeyContractData({
-        contract: new stellar_sdk_1.Address(interpreter).toScAddress(),
-        key: docKeyScVal(smartAccount, ruleId),
-        durability: stellar_sdk_1.xdr.ContractDataDurability.persistent(),
-    }));
-}
-// ---- ScVal helpers -----
-/** Field of a `#[contracttype]` struct, which the host encodes as a map keyed
- *  by field-name symbol. Returns undefined when the field is absent so a
- *  caller can distinguish "not there" from "there and empty". */
-function mapField(v, name) {
-    if (v.switch() !== stellar_sdk_1.xdr.ScValType.scvMap())
-        return undefined;
-    for (const entry of v.map() ?? []) {
-        const key = entry.key();
-        if (key.switch() === stellar_sdk_1.xdr.ScValType.scvSymbol() && key.sym().toString() === name) {
-            return entry.val();
-        }
-    }
-    return undefined;
-}
-function u32Of(v) {
-    return v?.switch() === stellar_sdk_1.xdr.ScValType.scvU32() ? v.u32() : undefined;
-}
-function addressOf(v) {
-    if (!v || v.switch() !== stellar_sdk_1.xdr.ScValType.scvAddress())
-        return undefined;
-    return stellar_sdk_1.Address.fromScAddress(v.address()).toString();
-}
-/** An enum variant of a `#[contracttype]` enum: `ScVal::Vec([Symbol, ...args])`. */
-function enumVariant(v) {
-    if (!v || v.switch() !== stellar_sdk_1.xdr.ScValType.scvVec())
-        return undefined;
-    const items = v.vec() ?? [];
-    const head = items[0];
-    if (!head || head.switch() !== stellar_sdk_1.xdr.ScValType.scvSymbol())
-        return undefined;
-    return { tag: head.sym().toString(), args: items.slice(1) };
-}
-// ---- decoders -----
-/** OZ `ContextRuleType`. An unrecognised tag is reported as `default`, which
- *  is the widest reading and therefore the safe one: it makes the rule look
- *  like it could serve any call, so overlap is over-reported, never missed. */
-function decodeContextType(v) {
-    const variant = enumVariant(v);
-    if (!variant)
-        return { kind: 'default' };
-    if (variant.tag === 'CallContract') {
-        const addr = addressOf(variant.args[0]);
-        return addr ? { kind: 'call_contract', address: addr } : { kind: 'default' };
-    }
-    if (variant.tag === 'CreateContract') {
-        const arg = variant.args[0];
-        const hash = arg?.switch() === stellar_sdk_1.xdr.ScValType.scvBytes() ? arg.bytes().toString('hex') : '';
-        return { kind: 'create_contract', wasmHash: hash };
-    }
-    return { kind: 'default' };
-}
-/** OZ `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
-function decodeSigner(v) {
-    const variant = enumVariant(v);
-    if (!variant)
-        return undefined;
-    if (variant.tag === 'Delegated') {
-        const addr = addressOf(variant.args[0]);
-        return addr ? { kind: 'delegated', address: addr } : undefined;
-    }
-    if (variant.tag === 'External') {
-        const verifier = addressOf(variant.args[0]);
-        const keyArg = variant.args[1];
-        const keyBytes = keyArg?.switch() === stellar_sdk_1.xdr.ScValType.scvBytes() ? keyArg.bytes().toString('hex') : '';
-        return verifier ? { kind: 'external', verifier, keyBytes } : undefined;
-    }
-    return undefined;
-}
-/** A full OZ `ContextRule` as returned by `get_context_rule(id)`.
- *  `predicate` is filled in separately from the ledger entry. */
-function decodeContextRule(v) {
-    const id = u32Of(mapField(v, 'id'));
-    if (id === undefined)
-        return undefined;
-    const signersVal = mapField(v, 'signers');
-    const signers = [];
-    if (signersVal?.switch() === stellar_sdk_1.xdr.ScValType.scvVec()) {
-        for (const s of signersVal.vec() ?? []) {
-            const decoded = decodeSigner(s);
-            if (decoded)
-                signers.push(decoded);
-        }
-    }
-    const policiesVal = mapField(v, 'policies');
-    const policyAddresses = [];
-    if (policiesVal?.switch() === stellar_sdk_1.xdr.ScValType.scvVec()) {
-        for (const p of policiesVal.vec() ?? []) {
-            const addr = addressOf(p);
-            if (addr)
-                policyAddresses.push(addr);
-        }
-    }
-    // `policy_ids` is index-aligned with `policies` in OZ's ContextRule. Only
-    // the ids can be passed to `remove_policy`, so a detach is impossible
-    // without them; they are read here rather than looked up again later.
-    const policyIdsVal = mapField(v, 'policy_ids');
-    const policyIds = [];
-    if (policyIdsVal?.switch() === stellar_sdk_1.xdr.ScValType.scvVec()) {
-        for (const pid of policyIdsVal.vec() ?? []) {
-            const n = u32Of(pid);
-            if (n !== undefined)
-                policyIds.push(n);
-        }
-    }
-    return {
-        id,
-        contextType: decodeContextType(mapField(v, 'context_type')),
-        signers,
-        policyAddresses,
-        ...(policyIds.length > 0 ? { policyIds } : {}),
-    };
-}
-/** `storage.rs:296` - the third element of the persistent nonce key tuple. */
-exports.K_NONCE = 2;
-/** Ledger key for a rule's stored install nonce. Read directly for the same
- *  reason as the document: the interpreter publishes no getter. */
-function nonceLedgerKey(interpreter, smartAccount, ruleId) {
-    return stellar_sdk_1.xdr.LedgerKey.contractData(new stellar_sdk_1.xdr.LedgerKeyContractData({
-        contract: new stellar_sdk_1.Address(interpreter).toScAddress(),
-        key: stellar_sdk_1.xdr.ScVal.scvVec([
-            new stellar_sdk_1.Address(smartAccount).toScVal(),
-            stellar_sdk_1.xdr.ScVal.scvU32(ruleId),
-            stellar_sdk_1.xdr.ScVal.scvU32(exports.K_NONCE),
-        ]),
-        durability: stellar_sdk_1.xdr.ContractDataDurability.persistent(),
-    }));
-}
-function decodeStoredOracleBounds(v) {
-    const read = (name) => u32Of(mapField(v, name));
-    const staleness = read('oracle_max_staleness_seconds');
-    const deviation = read('oracle_max_deviation_bps');
-    const xfeed = read('oracle_max_xfeed_dev_bps');
-    return {
-        ...(staleness !== undefined ? { maxStalenessSeconds: staleness } : {}),
-        ...(deviation !== undefined ? { maxDeviationBps: deviation } : {}),
-        ...(xfeed !== undefined ? { maxCrossFeedDeviationBps: xfeed } : {}),
-    };
-}
-/** Raw predicate bytes out of a `StoredDoc` ledger entry value. */
-function decodeStoredPredicateBytes(v) {
-    const field = mapField(v, 'predicate_bytes');
-    if (!field || field.switch() !== stellar_sdk_1.xdr.ScValType.scvBytes())
-        return undefined;
-    return field.bytes();
-}
-/** How far the id scan will probe before giving up. OZ imposes no per-account
- *  rule cap, so there is no exact bound to derive; this one is far above any
- *  realistic account and keeps a malformed `Count` from spinning forever. */
-exports.MAX_RULE_ID_SCAN = 512;
-/**
- * Every context rule on the account, with predicates filled in for the rules
- * our interpreter polices.
- *
- * Rule ids are NOT contiguous. OZ assigns them from a monotonic `NextId` and
- * decrements `Count` on removal without ever reusing an id
- * (`smart_account/storage.rs`: `add_context_rule` bumps `NextId`,
- * `remove_context_rule` only lowers `Count`), so after any removal
- * `Count < NextId` and the live ids have gaps. Iterating `0..Count-1` would
- * silently skip live rules at higher ids, and a skipped rule is a missed
- * overlap - the one error that reports safety which does not exist. Instead
- * the scan walks ids upward until it has accounted for `Count` live rules.
- *
- * A rule whose predicate cannot be read is deliberately left without one. That
- * demotes it to the `foreign` class, so the scan reports it as opaque instead
- * of assuming it is narrow.
- */
-async function collectObservedRules(args) {
-    const count = await args.reader.getContextRuleCount(args.smartAccount);
-    const limit = args.maxRuleIdScan ?? exports.MAX_RULE_ID_SCAN;
-    const rules = [];
-    const unreadablePredicateRuleIds = [];
-    let id = 0;
-    while (rules.length < count && id < limit) {
-        const raw = await args.reader.getContextRule(args.smartAccount, id);
-        id++;
-        if (!raw)
-            continue;
-        const rule = decodeContextRule(raw);
-        if (!rule)
-            continue;
-        if (rule.policyAddresses.includes(args.interpreterAddress)) {
-            const doc = await args.reader.getStoredDoc(args.interpreterAddress, args.smartAccount, rule.id);
-            const bytes = doc ? decodeStoredPredicateBytes(doc) : undefined;
-            if (bytes) {
-                try {
-                    rule.predicate = (0, decode_ts_1.decodePredicate)(bytes);
-                    // Carried so a merge can re-install the SAME bounds. They are
-                    // tighten-only overrides, so losing them widens the policy quietly.
-                    if (doc)
-                        rule.oracleBounds = decodeStoredOracleBounds(doc);
-                }
-                catch {
-                    unreadablePredicateRuleIds.push(rule.id);
-                }
-            }
-            else {
-                unreadablePredicateRuleIds.push(rule.id);
-            }
-        }
-        rules.push(rule);
-    }
-    return { rules, unreadablePredicateRuleIds, incomplete: rules.length < count };
-}
-/**
- * An `AccountRuleReader` over a live RPC server.
- *
- * The two OZ getters are read-only simulations, built the same way as
- * `getContractVersion` in `build-install-policy.ts`: the source account is
- * constructed locally because a simulation never checks its sequence number,
- * and asking the network for a random key would 404.
- *
- * The stored document is fetched as a ledger entry rather than a contract
- * call, because the interpreter publishes no getter for it.
- */
-function accountRuleReaderFromServer(server, networkPassphrase) {
-    async function simulateCall(contract, method, ...args) {
-        const account = new stellar_sdk_1.Account(stellar_sdk_1.Keypair.random().publicKey(), '0');
-        const tx = new stellar_sdk_1.TransactionBuilder(account, { fee: stellar_sdk_1.BASE_FEE, networkPassphrase })
-            .addOperation(new stellar_sdk_1.Contract(contract).call(method, ...args))
-            .setTimeout(30)
-            .build();
-        const sim = await server.simulateTransaction(tx);
-        if (stellar_sdk_1.rpc.Api.isSimulationError(sim))
-            return undefined;
-        return sim.result?.retval;
-    }
-    return {
-        async getContextRuleCount(smartAccount) {
-            const val = await simulateCall(smartAccount, 'get_context_rules_count');
-            return u32Of(val) ?? 0;
-        },
-        async getContextRule(smartAccount, ruleId) {
-            return simulateCall(smartAccount, 'get_context_rule', stellar_sdk_1.xdr.ScVal.scvU32(ruleId));
-        },
-        async getStoredDoc(interpreter, smartAccount, ruleId) {
-            const key = docLedgerKey(interpreter, smartAccount, ruleId);
-            const res = await server.getLedgerEntries(key);
-            const entry = res.entries?.[0]?.val;
-            if (!entry || entry.switch() !== stellar_sdk_1.xdr.LedgerEntryType.contractData())
-                return undefined;
-            return entry.contractData().val();
-        },
-    };
-}