@crediolabs/policy-synth 0.1.12 → 0.1.14

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

@@ -0,0 +1,462 @@
+"use strict";
+// src/install/build-install-policy.ts - builds the unsigned Soroban
+// transaction XDR for `account.add_context_rule(...)` and
+// `account.remove_context_rule(...)`.
+//
+// The MCP server is stateless and holds no key material (server.ts:10-12),
+// so this module NEVER signs. The caller (the wallet / CLI / SDK consumer)
+// wraps the returned XDR in a transaction envelope and signs that envelope
+// with their wallet; the wallet signature IS the user-confirmation step.
+//
+// We deliberately depart from the spec in plans/phase-04 which calls for a
+// two-call `install_policy`/`confirm_install` pair backed by a host-signed
+// short-TTL `action_id`. That contract requires (a) a stateful store and
+// (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`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GRAMMAR_VERSION = exports.Contract = void 0;
+exports.rpcClientFromServer = rpcClientFromServer;
+exports.buildInstallPolicyXdr = buildInstallPolicyXdr;
+exports.buildRevokePolicyXdr = buildRevokePolicyXdr;
+const node_crypto_1 = require("node:crypto");
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+Object.defineProperty(exports, "Contract", { enumerable: true, get: function () { return stellar_sdk_1.Contract; } });
+const build_add_context_rule_ts_1 = require("./build-add-context-rule.js");
+Object.defineProperty(exports, "DEFAULT_GRAMMAR_VERSION", { enumerable: true, get: function () { return build_add_context_rule_ts_1.DEFAULT_GRAMMAR_VERSION; } });
+const oz_auth_ts_1 = require("./oz-auth.js");
+/** Convert a real rpc.Server into the InstallRpcClient surface. The
+ *  `getContractVersion` lookup uses `simulateTransaction` against
+ *  `contract.call('grammar_version')` and decodes the returned u32.
+ *
+ *  The passphrase is a REQUIRED argument rather than something read off the
+ *  server: `rpc.Server` does not carry one, so reaching for
+ *  `server.networkPassphrase` yielded a non-string and every version probe
+ *  died with "Invalid passphrase provided to Transaction". The caller knows
+ *  which network it dialled; make it say so. */
+function rpcClientFromServer(server, networkPassphrase) {
+    return {
+        getAccount: (address) => server.getAccount(address),
+        simulateTransaction: (tx) => server.simulateTransaction(tx),
+        getLatestLedger: () => server.getLatestLedger(),
+        async getContractVersion(address) {
+            // The source account is constructed locally rather than fetched. This is
+            // a read-only simulation, so the sequence number is never checked, and a
+            // random key does NOT exist on chain - asking the network for it returns
+            // 404 and the version probe fails for a reason that has nothing to do
+            // with the contract being probed.
+            const account = new stellar_sdk_2.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(address).call('grammar_version'))
+                .setTimeout(30)
+                .build();
+            const sim = await server.simulateTransaction(tx);
+            if (stellar_sdk_1.rpc.Api.isSimulationError(sim)) {
+                throw new Error(`getContractVersion: simulateTransaction failed: ${sim.error}`);
+            }
+            if (!sim.result?.retval) {
+                throw new Error('getContractVersion: grammar_version() returned no value');
+            }
+            const native = (0, stellar_sdk_1.scValToBigInt)(sim.result.retval);
+            if (typeof native !== 'bigint') {
+                throw new Error('getContractVersion: grammar_version() did not return an integer');
+            }
+            return Number(native);
+        },
+    };
+}
+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. */
+async function buildInstallPolicyXdr(args) {
+    // 1. Pure arg encoding first - fail closed on any limit / shape problem
+    //    BEFORE we burn a network round-trip on a malformed call.
+    const callArgs = (0, build_add_context_rule_ts_1.buildAddContextRuleArgs)({
+        contextRuleType: args.rule.contextRuleType,
+        name: args.rule.name,
+        validUntilLedger: args.rule.validUntilLedger,
+        signers: args.rule.signers,
+        policies: args.rule.policies.map(adaptPolicyRef),
+    }, {
+        signers: args.rule.signers,
+        policies: args.rule.policies.map(adaptPolicyRef),
+        installNonce: args.installNonce,
+        encodedPredicate: args.encodedPredicate,
+        predicateHash: args.predicateHash,
+        ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
+        ...(args.grammarVersion !== undefined ? { grammarVersion: args.grammarVersion } : {}),
+    });
+    // 2. Fetch the source sequence, then build the recording transaction with a
+    //    bare host call. The recording pass assigns the smart-account auth nonce
+    //    and root invocation needed to construct OZ's AuthPayload.
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const hostFunction = stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+        contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
+        functionName: 'add_context_rule',
+        args: [...callArgs],
+    }));
+    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) => buildUnsignedTx({
+        sourceAccount: args.sourceAccount,
+        sequence: source.sequenceNumber(),
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+        op,
+    });
+    const recordingTx = buildTx(makeOperation());
+    // 3. Recording simulation: capture the smart account's nonce and invocation
+    //    tree. Nothing is signed here.
+    const recorded = await args.rpc.simulateTransaction(recordingTx);
+    if (stellar_sdk_1.rpc.Api.isSimulationError(recorded)) {
+        // Short, stable reason. The full `simulateTransaction` error (which
+        // carries host + URL detail) stays in the SDK's own logs - never
+        // reflected back into a user-facing message where it would
+        // reconnoitre the RPC.
+        throw new Error('install_policy: 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(`install_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
+    }
+    // 4. `add_context_rule` is authorised by the deploy-time admin rule (rule 0).
+    //    The delegated signer uses source-account credentials, so its signature
+    //    bytes stay empty and the ordinary transaction-envelope signature covers
+    //    the call when the consumer signs it.
+    const validUntilLedger = (await args.rpc.getLatestLedger()).sequence +
+        (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS);
+    const contextRuleIds = [0];
+    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)),
+    ];
+    // 5. Simulate again with the OZ entries already attached. The SDK preserves
+    //    existing auth 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 (stellar_sdk_1.rpc.Api.isSimulationError(enforcing)) {
+        throw new Error('install_policy: auth simulateTransaction failed');
+    }
+    const finalTx = stellar_sdk_1.rpc.assembleTransaction(txWithAuth, enforcing).build();
+    // 6. Decode the structured description FROM the final assembled transaction.
+    //    The human approval binds to the exact bytes the wallet will sign.
+    const describes = decodeInstallCallDescribes(finalTx, args.installNonce);
+    return {
+        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        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,
+        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+    };
+}
+/** Build an unsigned XDR for `account.remove_context_rule(ruleId)`. The
+ *  smart account itself handles uninstalling each attached policy (calling
+ *  `interpreter.uninstall` for the interpreter policy); this builder only
+ *  emits the account-side removal call.
+ *
+ *  Who may authorise it is the ACCOUNT's decision, and the account's source is
+ *  not in this repo. The interpreter's own `uninstall` is master-gated, but
+ *  that is a different entry point from this one, so do not restate it as the
+ *  rule for this call. What is proven on testnet is that the account's
+ *  deployer can revoke. This builder does not pre-check the signer: it would
+ *  be guessing at a contract it cannot read, and the chain is the authority. */
+async function buildRevokePolicyXdr(args) {
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const hostFunction = stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+        contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
+        functionName: 'remove_context_rule',
+        args: [stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId)],
+    }));
+    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) => buildUnsignedTx({
+        sourceAccount: args.sourceAccount,
+        sequence: source.sequenceNumber(),
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+        op,
+    });
+    const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()));
+    if (stellar_sdk_1.rpc.Api.isSimulationError(recorded)) {
+        // Short, stable reason. The full `simulateTransaction` error (which
+        // carries host + URL detail) stays in the SDK's own logs - never
+        // reflected back into a user-facing message where it would
+        // reconnoitre the RPC.
+        throw new Error('revoke_policy: 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(`revoke_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
+    }
+    // Removal is master-only, so the deploy-time admin rule authorises it. The
+    // recorded rootInvocation still includes remove_context_rule(ruleId), binding
+    // the auth payload to the exact rule being removed. As with install,
+    // source-account credentials carry the delegated signer entry and the
+    // consumer supplies only the ordinary envelope signature.
+    const validUntilLedger = (await args.rpc.getLatestLedger()).sequence +
+        (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS);
+    const contextRuleIds = [0];
+    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('revoke_policy: 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,
+        call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
+        authNonce: original.credentials().address().nonce().toString(),
+        authValidUntilLedger: validUntilLedger,
+        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+    };
+}
+/** ~25 minutes at 5s/ledger. */
+const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300;
+// ---- internals ----
+/** Adapter: turn the install-policy wire `PolicyRef` shape into the core
+ *  `PolicyRef` shape `buildAddContextRuleArgs` expects. Keeps the wire
+ *  schema hand-rolled + flat (the strict union would need a recursive
+ *  schema) while delegating to the proven encoder for the actual bytes. */
+function adaptPolicyRef(p) {
+    if (p.kind === 'interpreter') {
+        return {
+            kind: 'interpreter',
+            interpreterAddress: p.interpreterAddress,
+            predicateBlobBase64: p.predicateBlobBase64,
+        };
+    }
+    return {
+        kind: 'oz_builtin',
+        instanceAddress: p.instanceAddress,
+        primitive: p.primitive,
+    };
+}
+/** Build an unsigned Soroban transaction envelope. The `sequence` is
+ *  whatever `getAccount().sequenceNumber()` returned (a string of digits
+ *  the SDK accepts). No signing. The returned Transaction is what
+ *  `simulateTransaction` accepts. */
+function buildUnsignedTx(args) {
+    const account = new stellar_sdk_2.Account(args.sourceAccount, args.sequence);
+    const tx = new stellar_sdk_1.TransactionBuilder(account, {
+        fee: args.fee,
+        networkPassphrase: args.networkPassphrase,
+    })
+        .addOperation(args.op)
+        .setTimeout(0)
+        .build();
+    // `TransactionBuilder.build()` returns a Transaction whose envelope
+    // has empty signatures. The wallet re-reads the unsigned XDR, appends
+    // its signature, and broadcasts. We do NOT sign here.
+    return tx;
+}
+/** Decode the install 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).
+ *
+ *  `expectedInstallNonce` is a fallback for the rare case where the
+ *  install has no interpreter policy (no `install_nonce` to read); the
+ *  caller already knows it. */
+function decodeInstallCallDescribes(tx, expectedInstallNonce) {
+    const operations = tx.toEnvelope().v1().tx().operations();
+    if (operations.length !== 1 || !operations[0]) {
+        throw new Error(`install_policy: 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_policy: built op is not an invokeHostFunction(invokeContract(...)) call');
+    }
+    const invokeArgs = hostFn.invokeContract();
+    if (!invokeArgs) {
+        throw new Error('install_policy: built op has no InvokeContractArgs payload');
+    }
+    const targetContract = stellar_sdk_1.Address.fromScAddress(invokeArgs.contractAddress()).toString();
+    const fnName = invokeArgs.functionName().toString();
+    if (fnName !== 'add_context_rule') {
+        throw new Error(`install_policy: built op fn name is "${fnName}", expected "add_context_rule"`);
+    }
+    const scvArgs = invokeArgs.args();
+    if (scvArgs.length !== 5) {
+        throw new Error(`install_policy: built op has ${scvArgs.length} args, expected 5 (context_type, name, valid_until, signers, policies)`);
+    }
+    const contextType = scvArgs[0];
+    const nameScv = scvArgs[1];
+    const validUntilScv = scvArgs[2];
+    const signersScv = scvArgs[3];
+    const policiesScv = scvArgs[4];
+    // The length check above pins these as defined; the local references
+    // satisfy noUncheckedIndexedAccess on the accessors below.
+    if (!nameScv || !validUntilScv || !signersScv || !policiesScv || !contextType) {
+        throw new Error('install_policy: built op args include an undefined slot despite length check');
+    }
+    // name
+    if (nameScv.switch().name !== 'scvString') {
+        throw new Error('install_policy: args[1] (name) is not an ScVal::String');
+    }
+    const ruleName = nameScv.str().toString();
+    // valid_until (Option<u32> -> void when absent)
+    let validUntilLedger;
+    if (validUntilScv.switch().name === 'scvVoid') {
+        validUntilLedger = null;
+    }
+    else if (validUntilScv.switch().name === 'scvU32') {
+        validUntilLedger = validUntilScv.u32();
+    }
+    else {
+        throw new Error('install_policy: args[2] (valid_until) is neither void nor u32');
+    }
+    // signers (Vec<Vec<Symbol, Address[, Bytes]>>)
+    if (signersScv.switch().name !== 'scvVec') {
+        throw new Error('install_policy: args[3] (signers) is not an ScVal::Vec');
+    }
+    const signers = [];
+    for (const signerScv of signersScv.vec() ?? []) {
+        if (signerScv.switch().name !== 'scvVec') {
+            throw new Error('install_policy: a signer entry is not an ScVal::Vec');
+        }
+        const tuple = signerScv.vec() ?? [];
+        const tag = tuple[0]?.sym().toString();
+        const inner = tuple[1];
+        if (tag === 'Delegated') {
+            if (!inner || inner.switch().name !== 'scvAddress') {
+                throw new Error('install_policy: a Delegated signer is missing its Address');
+            }
+            signers.push({
+                kind: 'delegated',
+                address: stellar_sdk_1.Address.fromScAddress(inner.address()).toString(),
+            });
+            continue;
+        }
+        if (tag === 'External') {
+            if (!inner || inner.switch().name !== 'scvAddress') {
+                throw new Error('install_policy: an External signer is missing its verifier Address');
+            }
+            signers.push({
+                kind: 'external',
+                verifier: stellar_sdk_1.Address.fromScAddress(inner.address()).toString(),
+            });
+            continue;
+        }
+        throw new Error(`install_policy: signer tag "${tag ?? '<missing>'}" is not Delegated|External`);
+    }
+    // policies (Map<Address, Val>). Re-derive an interpreter-vs-OZ primitive
+    // classification by inspecting the value's map keys (PolicyInstallParams
+    // starts with `grammar_version`/`install_nonce`/`predicate`; OZ primitive
+    // params start with `spending_limit`/`threshold`/`period_ledgers`).
+    if (policiesScv.switch().name !== 'scvMap') {
+        throw new Error('install_policy: args[4] (policies) is not an ScVal::Map');
+    }
+    const policies = [];
+    let observedInstallNonce = null;
+    for (const entry of policiesScv.map() ?? []) {
+        const key = entry.key();
+        if (key.switch().name !== 'scvAddress') {
+            throw new Error('install_policy: a policies map entry has a non-Address key');
+        }
+        const address = stellar_sdk_1.Address.fromScAddress(key.address()).toString();
+        const val = entry.val();
+        if (val.switch().name !== 'scvMap') {
+            throw new Error(`install_policy: policies[${address}] value is not an ScVal::Map (got ${val.switch().name})`);
+        }
+        const fields = new Map();
+        for (const inner of val.map() ?? []) {
+            const fk = inner.key();
+            if (fk.switch().name !== 'scvSymbol') {
+                throw new Error(`install_policy: policies[${address}] field key is not an ScVal::Symbol`);
+            }
+            fields.set(fk.sym().toString(), inner.val());
+        }
+        // Interpreter policy fields carry grammar_version/install_nonce/predicate.
+        // OZ primitives carry spending_limit/period_ledgers/threshold/signers.
+        if (fields.has('predicate') || fields.has('grammar_version') || fields.has('install_nonce')) {
+            const installNonceScv = fields.get('install_nonce');
+            if (!installNonceScv || installNonceScv.switch().name !== 'scvU32') {
+                throw new Error(`install_policy: interpreter policy ${address} is missing a u32 install_nonce`);
+            }
+            const installNonce = installNonceScv.u32();
+            const predicateScv = fields.get('predicate');
+            if (!predicateScv || predicateScv.switch().name !== 'scvBytes') {
+                throw new Error(`install_policy: interpreter policy ${address} is missing its bytes predicate`);
+            }
+            const predicateBytes = Buffer.from(predicateScv.bytes());
+            const predicateSha256OfEmbeddedBytes = (0, node_crypto_1.createHash)('sha256')
+                .update(predicateBytes)
+                .digest('hex');
+            const predicateHashScv = fields.get('predicate_hash');
+            const predicateHash = predicateHashScv && predicateHashScv.switch().name === 'scvBytes'
+                ? Buffer.from(predicateHashScv.bytes()).toString('hex')
+                : '';
+            policies.push({
+                kind: 'interpreter',
+                address,
+                installNonce,
+                predicateHash,
+                predicateSha256OfEmbeddedBytes,
+            });
+            observedInstallNonce = installNonce;
+            continue;
+        }
+        // OZ built-in primitive. Distinguish by the parameter shape we
+        // emitted; matching one of the three primitives exactly pins the
+        // kind we built.
+        if (fields.has('spending_limit') && fields.has('period_ledgers')) {
+            policies.push({ kind: 'oz_builtin', address, primitive: 'spending_limit' });
+            continue;
+        }
+        if (fields.has('threshold') && fields.has('signer_weights')) {
+            policies.push({ kind: 'oz_builtin', address, primitive: 'weighted_threshold' });
+            continue;
+        }
+        if (fields.has('threshold')) {
+            policies.push({ kind: 'oz_builtin', address, primitive: 'simple_threshold' });
+            continue;
+        }
+        throw new Error(`install_policy: policies[${address}] value has an unknown field set; the encoder may have drifted`);
+    }
+    // `observedInstallNonce` is the nonce baked into whichever interpreter
+    // policy is present; when none, fall back to the caller-supplied value.
+    const installNonce = observedInstallNonce ?? expectedInstallNonce;
+    return {
+        targetContract,
+        fnName: 'add_context_rule',
+        ruleName,
+        validUntilLedger,
+        signers,
+        policies,
+        installNonce,
+    };
+}
+// Local re-import to avoid pulling the class from the SDK module path
+// at the top of the file (avoids the unused-import lint).
+const stellar_sdk_2 = require("@stellar/stellar-sdk");

package/dist-cjs/install/get-interpreter-info.d.ts

@@ -0,0 +1,29 @@
+import type { Network } from '../types.ts';
+export interface InterpreterInfo {
+    /** Pinned interpreter contract address. */
+    pinnedAddress: string;
+    /** Pinned grammar version (matches SELF_VERSION in version.rs). */
+    pinnedGrammarVersion: number;
+    /** Pinned wasm sha256 (hex). */
+    pinnedWasmHash: string;
+    /** Network this pin applies to (the address + hash are network-scoped). */
+    network: Network;
+    /** Present only when the caller supplied a live `deployedGrammarVersion`. */
+    deployedGrammarVersion?: number;
+    /** True when `deployedGrammarVersion` matches `pinnedGrammarVersion`.
+     *  Absent when no live verification was performed. */
+    liveMatchesPin?: boolean;
+}
+/** Build the interpreter-info response. When `deployedGrammarVersion` is
+ *  supplied (after a live RPC `grammar_version()` call by the run layer),
+ *  compares it to the pin and sets `liveMatchesPin`. When absent, returns
+ *  the pin alone. */
+export declare function getInterpreterInfo(args: {
+    pinnedAddress: string;
+    pinnedGrammarVersion: number;
+    pinnedWasmHash: string;
+    network: Network;
+    /** When supplied, the u32 returned by the live contract's
+     *  `grammar_version()` RPC call. */
+    deployedGrammarVersion?: number;
+}): InterpreterInfo;

package/dist-cjs/install/get-interpreter-info.js

@@ -0,0 +1,44 @@
+"use strict";
+// src/install/get-interpreter-info.ts - read-only fingerprint lookup for
+// the interpreter contract.
+//
+// Returns the pinned deployment fingerprint + (optionally) compares a
+// caller-supplied live `grammar_version` against the pin. No fabricated
+// audit field; a real deployed-contract check is worth more than a fake
+// reference.
+//
+// Per design decision 5: phase-04's "audit #44" is aspirational and has no
+// source-of-truth in the repo. Returning a fabricated audit id would be a
+// lie on a security surface. The honest outputs are:
+//   - the pinned address (DEPLOYMENTS.md)
+//   - the pinned grammar version (SELF_VERSION in version.rs)
+//   - the pinned wasm sha256 (DEPLOYMENTS.md)
+//   - an OPTIONAL `deployedGrammarVersion` returned by a live `grammar_version()`
+//     RPC call, with a `liveMatchesPin` boolean the caller can dispatch on. A
+//     mismatch means the deployed wasm is NOT the pinned artifact - the caller
+//     should refuse to install until they redeploy.
+//
+// The RPC plumbing lives in the run layer (`run/index.ts`); this module
+// stays pure so it is testable without a network.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInterpreterInfo = getInterpreterInfo;
+/** Build the interpreter-info response. When `deployedGrammarVersion` is
+ *  supplied (after a live RPC `grammar_version()` call by the run layer),
+ *  compares it to the pin and sets `liveMatchesPin`. When absent, returns
+ *  the pin alone. */
+function getInterpreterInfo(args) {
+    const info = {
+        pinnedAddress: args.pinnedAddress,
+        pinnedGrammarVersion: args.pinnedGrammarVersion,
+        pinnedWasmHash: args.pinnedWasmHash,
+        network: args.network,
+    };
+    if (typeof args.deployedGrammarVersion === 'number') {
+        return {
+            ...info,
+            deployedGrammarVersion: args.deployedGrammarVersion,
+            liveMatchesPin: args.deployedGrammarVersion === args.pinnedGrammarVersion,
+        };
+    }
+    return info;
+}

package/dist-cjs/install/oz-auth.d.ts

@@ -0,0 +1,27 @@
+import { xdr } from '@stellar/stellar-sdk';
+/** `Signer::Delegated(addr)`. */
+export declare const delegatedSigner: (a: string) => xdr.ScVal;
+/** The standard Soroban authorization preimage hash for one entry. */
+export declare function signaturePayload(networkPassphrase: string, nonce: xdr.Int64, signatureExpirationLedger: number, invocation: xdr.SorobanAuthorizedInvocation): Buffer;
+/**
+ * `sha256(signature_payload || xdr(context_rule_ids))`.
+ *
+ * OZ binds the selected rule ids into the digest so a signature for one rule
+ * cannot be replayed against another.
+ */
+export declare function authDigest(payload: Buffer, contextRuleIds: number[]): Buffer;
+/** `AuthPayload { signers, context_rule_ids }` - the account's "signature". */
+export declare function authPayload(signerAddresses: string[], contextRuleIds: number[], signatureFor: (addr: string) => Buffer): xdr.ScVal;
+/**
+ * The nested entry a `Delegated` signer needs.
+ *
+ * `require_auth_for_args` authorizes the CURRENT frame, which while
+ * `__check_auth` is running is the account contract executing `__check_auth`,
+ * with the digest as its single argument.
+ *
+ * The signer is the transaction source here, so source-account credentials
+ * carry it and no separate signature is required.
+ */
+export declare function delegatedSignerEntry(accountId: string, digest: Buffer): xdr.SorobanAuthorizationEntry;
+/** Rebuild the account's entry with the AuthPayload in the signature slot. */
+export declare function accountEntry(original: xdr.SorobanAuthorizationEntry, signatureExpirationLedger: number, payload: xdr.ScVal): xdr.SorobanAuthorizationEntry;