@crediolabs/policy-synth 0.1.13 → 0.1.15

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

@@ -147,22 +147,20 @@ export interface BuildInstallPolicyResult {
     smartAccount: string;
     /** Source account (echo) - the address that must sign. */
     sourceAccount: string;
-    /** The host-call target + fn name. Call 2 (interpreter.install) is NOT
-     *  emitted here; the account assigns the rule id in call 1 and call 2
-     *  needs that id to bind its `context_rule_ids`. See `followUp` below. */
+    /** The host-call target + fn name. This single call installs the policy
+     *  outright: `add_context_rule` takes `policies` as a
+     *  `Map<policy_address, install_param>`, and the account forwards each
+     *  install_param to that policy. For an interpreter policy the param
+     *  carries the predicate and its hash, so the interpreter stores the
+     *  document as part of this transaction. There is no second call.
+     *
+     *  Verified on testnet 2026-08-01: a rule created by this builder alone
+     *  permits a matching operator call and denies a non-matching one with
+     *  interpreter code #100 - not #206 MissingState. */
     call: {
         contract: string;
         fn: 'add_context_rule';
     };
-    /** The follow-up call the caller MUST issue after this one confirms.
-     *  The rule id the account assigns in call 1 is required to bind the
-     *  interpreter's `install` auth context. */
-    followUp: {
-        contract: 'interpreter';
-        fn: 'install';
-        requiresRuleIdFromCallOne: true;
-        hint: string;
-    };
     /** Human-readable description of the install call, decoded FROM the
      *  built unsigned XDR (not from the input args). The wallet signature
      *  binds to bytes; the review card has to bind to the same bytes, so

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

@@ -13,12 +13,16 @@
 // (b) key material the server does not have, so we ship the simpler ONE-CALL
 // shape. The wallet signature covers the change.
 //
-// `buildInstallPolicyXdr` returns CALL 1 ONLY. Call 2 (interpreter.install)
-// needs the rule id the account assigns in call 1, so it cannot be pre-built
-// and is documented in the response envelope under `followUp`.
+// `buildInstallPolicyXdr` installs the policy in ONE call. `add_context_rule`
+// takes `policies` as a `Map<policy_address, install_param>` and the account
+// forwards each install_param to that policy, so the interpreter stores the
+// predicate document as part of this same transaction. Earlier revisions
+// documented a second `interpreter.install` call; that was wrong, and issuing
+// it fails - the account re-enters the interpreter while it is mid-install.
 import { createHash } from 'node:crypto';
 import { Address, BASE_FEE, Contract, Keypair, Operation, rpc, scValToBigInt, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
 import { buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION } from "./build-add-context-rule.js";
+import { accountEntry, authDigest, authPayload, delegatedSignerEntry, signaturePayload, } from "./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.
@@ -62,7 +66,6 @@ export function rpcClientFromServer(server, networkPassphrase) {
         },
     };
 }
-const FOLLOWUP_HINT = 'after this tx confirms, read the rule id via account.get_context_rules_count()-1 (or get the receipt events), then call runInstallPolicy a second time with the interpreter as the target and the rule id in context_rule_ids - OR hand-build the install() call directly with the OZ auth pattern.';
 /** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
  *  The output XDR is signed by the wallet, not by us. */
 export async function buildInstallPolicyXdr(args) {
@@ -83,31 +86,28 @@ export async function buildInstallPolicyXdr(args) {
         ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
         ...(args.grammarVersion !== undefined ? { grammarVersion: args.grammarVersion } : {}),
     });
-    // 2. Network pass: source account sequence + latest ledger.
+    // 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 latest = await args.rpc.getLatestLedger();
-    const validUntilLedger = latest.sequence + (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_LEDGERS);
-    // 3. Build the unsigned transaction envelope with the bare host call.
-    const op = Operation.invokeHostFunction({
-        func: xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
-            contractAddress: new Address(args.smartAccount).toScAddress(),
-            functionName: 'add_context_rule',
-            args: [...callArgs],
-        })),
-        auth: [],
-    });
+    const hostFunction = xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+        contractAddress: new Address(args.smartAccount).toScAddress(),
+        functionName: 'add_context_rule',
+        args: [...callArgs],
+    }));
+    const makeOperation = (auth = []) => Operation.invokeHostFunction({ func: hostFunction, auth });
     const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
-    const tx = buildUnsignedTx({
+    const buildTx = (op) => buildUnsignedTx({
         sourceAccount: args.sourceAccount,
         sequence: source.sequenceNumber(),
         fee: baseFee,
         networkPassphrase: args.networkPassphrase,
         op,
     });
-    // 4. Simulation pass. Returns the auth nonce + rootInvocation the wallet
-    //    signature binds to. We do NOT add the AuthPayload here - the wallet
-    //    injects auth entries using its own __check_auth flow.
-    const recorded = await args.rpc.simulateTransaction(tx);
+    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 (rpc.Api.isSimulationError(recorded)) {
         // Short, stable reason. The full `simulateTransaction` error (which
         // carries host + URL detail) stays in the SDK's own logs - never
@@ -121,23 +121,35 @@ export async function buildInstallPolicyXdr(args) {
     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`);
     }
-    // 5. Decode the structured description FROM the unsigned XDR. The human
-    //    approval binds to the bytes the wallet will sign; deriving this from
-    //    the input args would re-describe the caller's intent rather than the
-    //    transaction. Re-parse the envelope we just built so the description
-    //    reflects what the wallet actually signs, not what we thought it would.
-    const describes = decodeInstallCallDescribes(tx, op, args.installNonce);
+    // 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 = 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)),
+    ];
+    // 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 (rpc.Api.isSimulationError(enforcing)) {
+        throw new Error('install_policy: auth simulateTransaction failed');
+    }
+    const finalTx = 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: tx.toEnvelope().toXDR().toString('base64'),
+        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,
@@ -157,25 +169,21 @@ export async function buildInstallPolicyXdr(args) {
  *  be guessing at a contract it cannot read, and the chain is the authority. */
 export async function buildRevokePolicyXdr(args) {
     const source = await args.rpc.getAccount(args.sourceAccount);
-    const latest = await args.rpc.getLatestLedger();
-    const validUntilLedger = latest.sequence + (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_LEDGERS);
-    const op = Operation.invokeHostFunction({
-        func: xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
-            contractAddress: new Address(args.smartAccount).toScAddress(),
-            functionName: 'remove_context_rule',
-            args: [xdr.ScVal.scvU32(args.ruleId)],
-        })),
-        auth: [],
-    });
+    const hostFunction = xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+        contractAddress: new Address(args.smartAccount).toScAddress(),
+        functionName: 'remove_context_rule',
+        args: [xdr.ScVal.scvU32(args.ruleId)],
+    }));
+    const makeOperation = (auth = []) => Operation.invokeHostFunction({ func: hostFunction, auth });
     const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
-    const tx = buildUnsignedTx({
+    const buildTx = (op) => buildUnsignedTx({
         sourceAccount: args.sourceAccount,
         sequence: source.sequenceNumber(),
         fee: baseFee,
         networkPassphrase: args.networkPassphrase,
         op,
     });
-    const recorded = await args.rpc.simulateTransaction(tx);
+    const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()));
     if (rpc.Api.isSimulationError(recorded)) {
         // Short, stable reason. The full `simulateTransaction` error (which
         // carries host + URL detail) stays in the SDK's own logs - never
@@ -189,8 +197,27 @@ export async function buildRevokePolicyXdr(args) {
     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 = 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('revoke_policy: auth simulateTransaction failed');
+    }
+    const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build();
     return {
-        unsignedXdr: tx.toEnvelope().toXDR().toString('base64'),
+        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
@@ -200,7 +227,7 @@ export async function buildRevokePolicyXdr(args) {
     };
 }
 /** ~25 minutes at 5s/ledger. */
-const DEFAULT_AUTH_VALID_LEDGERS = 300;
+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
@@ -238,20 +265,24 @@ function buildUnsignedTx(args) {
     // its signature, and broadcasts. We do NOT sign here.
     return tx;
 }
-/** Decode the install call's structured fields directly out of the
- *  built (transaction, operation) pair. 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
- *  a ToolError, since that would mean the XDR was tampered with (or
+/** 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, op, expectedInstallNonce) {
+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 || hostFn.switch().name !== 'hostFunctionTypeInvokeContract') {
+    if (hostFn?.switch().name !== 'hostFunctionTypeInvokeContract') {
         throw new Error('install_policy: built op is not an invokeHostFunction(invokeContract(...)) call');
     }
     const invokeArgs = hostFn.invokeContract();
@@ -404,10 +435,6 @@ function decodeInstallCallDescribes(tx, op, expectedInstallNonce) {
     // `observedInstallNonce` is the nonce baked into whichever interpreter
     // policy is present; when none, fall back to the caller-supplied value.
     const installNonce = observedInstallNonce ?? expectedInstallNonce;
-    // Touch `tx` so the linter does not flag it as unused - the parameter
-    // documents that the caller built this Transaction; we re-parse the
-    // operation off it as a sanity check.
-    void tx;
     return {
         targetContract,
         fnName: 'add_context_rule',

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

@@ -0,0 +1,96 @@
+import { Contract } from '@stellar/stellar-sdk';
+import type { InstallRpcClient } from './build-install-policy.ts';
+/** Inputs for the install-predicate build. */
+export interface BuildInstallPredicateArgs {
+    /** The smart account contract address (C...). The interpreter hashes
+     *  this rule's `signers` at install; we fetch it via `get_context_rule`
+     *  on this address, not reconstruct it. */
+    smartAccount: string;
+    /** The signer that authorises the install (G... wallet). */
+    sourceAccount: string;
+    /** The rule id the account assigned in call 1. */
+    ruleId: number;
+    /** The interpreter contract address (C...). */
+    interpreterAddress: string;
+    /** Network passphrase - pins the hash the auth digest binds. */
+    networkPassphrase: string;
+    /** Already-encoded (base64) canonical ScVal of the predicate. */
+    encodedPredicate: string;
+    /** Hex sha256 of the canonical predicate XDR bytes. */
+    predicateHash: string;
+    /** Grammar version override; defaults to 1. */
+    grammarVersion?: number;
+    /** Base fee in stroops; defaults to BASE_FEE (100). */
+    baseFee?: number;
+    /** RPC client to use for the simulation pass; injected for tests. */
+    rpc: InstallRpcClient;
+    /** Ledger window (in ledgers) for the auth entry's `validUntil`. */
+    authValidUntilLedgers?: number;
+}
+/** Human-readable description of the install-predicate call, decoded FROM
+ *  the built XDR (not from the input args). The wallet signature binds
+ *  to bytes; the review card has to bind to the same bytes, so this is
+ *  the only safe source.
+ *
+ *  `ruleId` is NOT decoded from the XDR - it lives inside
+ *  `raw_context_rule`, which is passed through verbatim. Decoding it
+ *  here would re-introduce the client-side reconstruction the file
+ *  header warns against. The top-level `BuildInstallPredicateResult`
+ *  echoes the caller-supplied rule id instead. */
+export interface InstallPredicateCallDescribes {
+    /** The interpreter that will hold the predicate. */
+    targetContract: string;
+    /** The fn name on the target (always `install` today). */
+    fnName: 'install';
+    /** Grammar version the interpreter enforces; read off the wire. */
+    grammarVersion: number;
+    /** Per-rule install nonce; read off the wire. */
+    installNonce: number;
+    /** Hex sha256 of the encoded predicate blob; read off the wire. */
+    predicateHash: string;
+    /** Hex sha256 of the predicate bytes embedded in the params map. The
+     *  two values MUST match; a difference is a wire tampering signal. */
+    predicateSha256OfEmbeddedBytes: string;
+    /** The smart account address encoded in args[2], read off the wire. */
+    smartAccountOnWire: string;
+}
+/** Output of the install-predicate build. The unsigned XDR is the
+ *  wallet's input; the wallet signs it (single envelope signature) and
+ *  submits. The auth tree matches install_policy: account entry
+ *  carrying OZ's AuthPayload + a source-account delegated signer entry.
+ *  Both are covered by the envelope signature. */
+export interface BuildInstallPredicateResult {
+    /** Unsigned Soroban transaction envelope, base64 XDR. */
+    unsignedXdr: string;
+    /** Smart account contract address (echo). */
+    smartAccount: string;
+    /** Source account (echo) - the address that signs the envelope. */
+    sourceAccount: string;
+    /** The interpreter contract address (echo). */
+    interpreterAddress: string;
+    /** The rule id the account assigned in call 1 (echo). */
+    ruleId: number;
+    /** The host-call target + fn name. */
+    call: {
+        contract: string;
+        fn: 'install';
+    };
+    /** The smart-account auth nonce (snapshot). */
+    authNonce: string;
+    /** The ledger sequence + window the auth entry expires at. */
+    authValidUntilLedger: number;
+    /** The captured rootInvocation for the smart-account entry. */
+    rootInvocationXdr: string;
+    /** Human-readable description of the install call, decoded FROM the
+     *  built unsigned XDR (not from the input args). The wallet signature
+     *  binds to bytes; the review card has to bind to the same bytes, so
+     *  this is the only safe source. */
+    describes: InstallPredicateCallDescribes;
+}
+/** Build the unsigned transaction envelope for
+ *  `interpreter.install(params, raw_context_rule, smart_account)`. The
+ *  output XDR is signed by the wallet, not by us. */
+export declare function buildInstallPredicateXdr(args: BuildInstallPredicateArgs): Promise<BuildInstallPredicateResult>;
+/** Re-export `Contract` so the run-layer does not need to import the
+ *  SDK directly. Mirrors the build-install-policy.ts convention. */
+export { Contract };