@crediolabs/policy-synth 0.2.0 → 0.3.0

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

@@ -1,444 +0,0 @@
-// 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/install/build-merge-policy.d.ts

@@ -1,70 +0,0 @@
-import type { InstallRpcClient } from './build-install-policy.ts';
-import type { MergeStep } from './plan-merge-policy.ts';
-/**
- * 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.
- */
-export declare const ADMIN_CONTEXT_RULE_ID = 0;
-export interface BuildMergePolicyArgs {
-    smartAccount: string;
-    sourceAccount: string;
-    networkPassphrase: string;
-    ruleId: number;
-    /** OZ registry id of the interpreter policy on this rule, from the plan. */
-    policyId: number;
-    interpreterAddress: string;
-    step: MergeStep;
-    /** Only needed for `reinstall`: the merged predicate, already encoded. */
-    encodedPredicate?: string;
-    predicateHash?: string;
-    /** Nonce for the reinstall. Read from chain rather than assumed: a detach
-     *  whose uninstall panicked leaves the old nonce in place. */
-    installNonce?: number;
-    /** Oracle bounds to carry over from the document being replaced. */
-    oracleParams?: {
-        maxStalenessSeconds?: number;
-        maxDeviationBps?: number;
-        maxCrossFeedDeviationBps?: number;
-    };
-    rpc: InstallRpcClient;
-    baseFee?: number;
-    authValidUntilLedgers?: number;
-}
-export interface BuildMergePolicyResult {
-    unsignedXdr: string;
-    smartAccount: string;
-    sourceAccount: string;
-    step: MergeStep;
-    call: {
-        contract: string;
-        fn: 'remove_policy' | 'add_policy';
-        ruleId: number;
-    };
-    authNonce: string;
-    authValidUntilLedger: number;
-    rootInvocationXdr: string;
-}
-/**
- * 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.
- */
-export declare function buildMergePolicyXdr(args: BuildMergePolicyArgs): Promise<BuildMergePolicyResult>;

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

@@ -1,130 +0,0 @@
-//! 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.
-import { Account, Address, BASE_FEE, Operation, rpc, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
-import { DEFAULT_GRAMMAR_VERSION, encodePolicyInstallParams } from "./build-add-context-rule.js";
-import { accountEntry, authDigest, authPayload, delegatedSignerEntry, signaturePayload, } from "./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.
- */
-export const ADMIN_CONTEXT_RULE_ID = 0;
-function hostFunctionFor(args) {
-    if (args.step === 'detach') {
-        return xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
-            contractAddress: new Address(args.smartAccount).toScAddress(),
-            functionName: 'remove_policy',
-            args: [xdr.ScVal.scvU32(args.ruleId), xdr.ScVal.scvU32(args.policyId)],
-        }));
-    }
-    if (!args.encodedPredicate || !args.predicateHash) {
-        throw new Error('merge_policy: reinstall needs the merged predicate and its hash');
-    }
-    return xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
-        contractAddress: new Address(args.smartAccount).toScAddress(),
-        functionName: 'add_policy',
-        args: [
-            xdr.ScVal.scvU32(args.ruleId),
-            new 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.
-            encodePolicyInstallParams({
-                encodedPredicate: args.encodedPredicate,
-                predicateHash: args.predicateHash,
-                installNonce: args.installNonce ?? 1,
-                grammarVersion: 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.
- */
-export 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 = []) => Operation.invokeHostFunction({ func: hostFunction, auth });
-    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
-    const buildTx = (op) => new TransactionBuilder(new Account(args.sourceAccount, source.sequenceNumber()), {
-        fee: baseFee,
-        networkPassphrase: args.networkPassphrase,
-    })
-        .addOperation(op)
-        .setTimeout(0)
-        .build();
-    const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()));
-    if (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' &&
-        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 = [ADMIN_CONTEXT_RULE_ID];
-    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)),
-    ];
-    const txWithAuth = buildTx(makeOperation(authEntries));
-    const enforcing = await args.rpc.simulateTransaction(txWithAuth);
-    if (rpc.Api.isSimulationError(enforcing)) {
-        throw new Error(`merge_policy: ${fn} auth simulateTransaction failed`);
-    }
-    const finalTx = 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'),
-    };
-}