feat(sdk): add preflight simulation helpers for round transactions (#65)

Introduce typed preflight* methods on SubRosaClient so integrators can
simulate create, commit, reveal, clear, settle, and void calls before
submitting signed transactions.

Closes #43

Co-authored-by: Heazzy500 <285961681+Heazzy500@users.noreply.github.com>
Co-authored-by: David-patrick-chuks <pd3072894@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

docs/INTEGRATION.md

@@ -57,6 +57,59 @@ await client.commit({
 After Drand round `R` is published, any keeper or participant can submit the
 Drand signature, reveal valid entries, clear the round, and settle escrow.
 
+## Preflight simulation
+
+Before signing and submitting a state-changing call, integrators can simulate
+the transaction against Soroban RPC to see whether it is likely to succeed:
+
+```ts
+const preflight = await client.preflightCommit({
+  roundId,
+  sealed,
+  escrow,
+});
+
+if (!preflight.ok) {
+  if (preflight.error.kind === "contract_error") {
+    console.error(
+      "Contract rejected commit:",
+      preflight.error.contractErrorMessage,
+    );
+  } else {
+    console.error("Preflight failed:", preflight.error.message);
+  }
+  return;
+}
+
+console.log("Estimated fee (stroops):", preflight.fee.transactionFee);
+console.log("Min resource fee:", preflight.fee.minResourceFee?.toString());
+
+await client.commit({ roundId, sealed, escrow });
+```
+
+Each mutating `SubRosaClient` method has a matching `preflight*` helper:
+
+| Submit | Preflight |
+| --- | --- |
+| `createRound` | `preflightCreateRound` |
+| `commit` | `preflightCommit` |
+| `openReveal` | `preflightOpenReveal` |
+| `reveal` | `preflightReveal` |
+| `clear` | `preflightClear` |
+| `settle` | `preflightSettle` |
+| `void` | `preflightVoid` |
+
+Preflight results include:
+
+- `ok` — whether simulation indicates the call would succeed
+- `fee` — estimated transaction and minimum resource fees when available
+- `resources` — CPU/memory footprint estimates when available
+- `error` — typed `SubRosaPreflightError` for RPC failures, simulation errors,
+  expired contract state, or decoded Round contract error codes
+
+Existing submit methods are unchanged; preflight is optional and does not
+require live signing credentials beyond a source `publicKey` (or `secretKey`).
+
 ## Grant scoring pilot template
 
 For SCF-style sealed grant scoring (multiple projects, panel judges, ranked

packages/sdk/package.json

@@ -24,7 +24,7 @@
     ".": "./src/index.ts"
   },
   "scripts": {
-    "test": "node --import tsx --test src/client.test.ts src/encoding.test.ts src/errors.test.ts src/mainnet-readiness.test.ts src/redact.test.ts",
+    "test": "node --import tsx --test src/client.test.ts src/encoding.test.ts src/errors.test.ts src/ids.test.ts src/mainnet-readiness.test.ts src/preflight.test.ts src/public-api-snapshot.test.ts src/redact.test.ts src/verify.test.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {

packages/sdk/src/client.ts

@@ -26,6 +26,12 @@ import type { RoundReceipt } from "./receipt.js";
 import { validateEncryptedBlob } from "./encrypted-blob.js";
 import { networkFingerprint } from "./receipt.js";
 import type { TransactionSubmitter } from "./submitter.js";
+import {
+  evaluatePreflight,
+  classifyPreflightBuildError,
+  type PreflightOperation,
+  type PreflightResult,
+} from "./preflight.js";
 import {
   SubRosaClientConfigError,
   SubRosaMissingReturnValueError,
@@ -71,6 +77,10 @@ export interface SubRosaClientConfig {
    * @internal Testing hook: override the poll-loop sleep function.
    */
   _sleep?: (ms: number) => Promise<void>;
+  /**
+   * @internal Testing hook: inject a mock Soroban RPC server for simulation.
+   */
+  _server?: rpc.Server;
 }
 
 export type ClearingRuleTag = ClearingRule["tag"];
@@ -174,6 +184,7 @@ export class SubRosaClient {
       allowHttp,
       ...(source ? { publicKey: source } : {}),
       ...(signer ? { signTransaction: signer.signTransaction } : {}),
+      ...(config._server ? { server: config._server } : {}),
     });
   }
 
@@ -348,6 +359,117 @@ export class SubRosaClient {
     await this.#sendUnwrap(tx);
   }
 
+  // ── Preflight simulation (no signing/submission) ─────────────────────
+
+  async #preflight<T>(
+    operation: PreflightOperation,
+    buildTx: () => Promise<AssembledTransaction<Result<T>>>,
+  ): Promise<PreflightResult<T>> {
+    try {
+      const tx = await buildTx();
+      return evaluatePreflight(operation, tx);
+    } catch (error) {
+      if (error instanceof SubRosaClientConfigError) {
+        throw error;
+      }
+      return {
+        ok: false,
+        operation,
+        error: classifyPreflightBuildError(operation, error),
+      };
+    }
+  }
+
+  /** Simulate `createRound` without signing or submitting. */
+  preflightCreateRound(params: CreateRoundParams): Promise<PreflightResult<bigint>> {
+    return this.#preflight("create_round", () => {
+      const operator = params.operator ?? this.#requireSource("operator");
+      const clearing_rule = {
+        tag: params.clearingRule ?? "HighestBid",
+        values: undefined,
+      } as ClearingRule;
+      return this.contract.create_round({
+        operator,
+        item_ref: toBuffer(params.itemRef),
+        reveal_round: toBigInt(params.revealRound),
+        clearing_rule,
+        commit_deadline: toBigInt(params.commitDeadline),
+        reveal_deadline: toBigInt(params.revealDeadline),
+        auditor_pubkey: toBuffer(params.auditorPubkey),
+      });
+    });
+  }
+
+  /** Simulate `commit` without signing or submitting. */
+  preflightCommit(params: CommitParams): Promise<PreflightResult<void>> {
+    return this.#preflight("commit", () => {
+      const bidder = params.bidder ?? this.#requireSource("bidder");
+      return this.contract.commit({
+        round_id: toBigInt(params.roundId),
+        bidder,
+        commitment: toBuffer(params.sealed.commitment),
+        ciphertext: toBuffer(params.sealed.ciphertext),
+        escrow: params.escrow,
+        auditor_blob: toBuffer(params.sealed.auditorBlob),
+      });
+    });
+  }
+
+  /** Simulate `openReveal` without signing or submitting. */
+  preflightOpenReveal(
+    roundId: number | bigint,
+    drandSignature: Uint8Array,
+  ): Promise<PreflightResult<void>> {
+    return this.#preflight("open_reveal", () =>
+      this.contract.open_reveal({
+        round_id: toBigInt(roundId),
+        drand_signature: toBuffer(drandSignature),
+      }),
+    );
+  }
+
+  /** Simulate `reveal` without signing or submitting. */
+  preflightReveal(params: RevealParams): Promise<PreflightResult<void>> {
+    return this.#preflight("reveal", () =>
+      this.contract.reveal({
+        round_id: toBigInt(params.roundId),
+        bidder: params.bidder,
+        value: params.value,
+        nonce: toBuffer(params.nonce),
+      }),
+    );
+  }
+
+  /** Simulate `clear` without signing or submitting. */
+  async preflightClear(
+    roundId: number | bigint,
+  ): Promise<PreflightResult<string | undefined>> {
+    const result = await this.#preflight<string | null | undefined>("clear", () =>
+      this.contract.clear({ round_id: toBigInt(roundId) }),
+    );
+    if (!result.ok) {
+      return result;
+    }
+    return {
+      ...result,
+      result: result.result ?? undefined,
+    };
+  }
+
+  /** Simulate `settle` without signing or submitting. */
+  preflightSettle(roundId: number | bigint): Promise<PreflightResult<void>> {
+    return this.#preflight("settle", () =>
+      this.contract.settle({ round_id: toBigInt(roundId) }),
+    );
+  }
+
+  /** Simulate `void` without signing or submitting. */
+  preflightVoid(roundId: number | bigint): Promise<PreflightResult<void>> {
+    return this.#preflight("void", () =>
+      this.contract.void({ round_id: toBigInt(roundId) }),
+    );
+  }
+
   // ── Read-only views (simulation only; no signing/submission) ───────────
 
   async getRound(roundId: number | bigint): Promise<Round> {

packages/sdk/src/errors.ts

@@ -44,6 +44,45 @@ export interface TimeoutErrorParams {
   pollIntervalMs: number;
 }
 
+export type PreflightFailureKind =
+  | "rpc_error"
+  | "simulation_error"
+  | "expired_state"
+  | "contract_error"
+  | "malformed_response";
+
+export interface SubRosaPreflightErrorParams {
+  kind: PreflightFailureKind;
+  operation: string;
+  message: string;
+  simulationError?: string;
+  contractErrorCode?: number;
+  contractErrorMessage?: string;
+  restoreMinResourceFee?: bigint;
+  cause?: unknown;
+}
+
+/** Typed error for preflight/simulation failures before transaction submission. */
+export class SubRosaPreflightError extends Error {
+  readonly name = "SubRosaPreflightError";
+  readonly kind: PreflightFailureKind;
+  readonly operation: string;
+  readonly simulationError?: string;
+  readonly contractErrorCode?: number;
+  readonly contractErrorMessage?: string;
+  readonly restoreMinResourceFee?: bigint;
+
+  constructor(params: SubRosaPreflightErrorParams) {
+    super(params.message, params.cause ? { cause: params.cause } : undefined);
+    this.kind = params.kind;
+    this.operation = params.operation;
+    this.simulationError = params.simulationError;
+    this.contractErrorCode = params.contractErrorCode;
+    this.contractErrorMessage = params.contractErrorMessage;
+    this.restoreMinResourceFee = params.restoreMinResourceFee;
+  }
+}
+
 export class SubRosaTimeoutError extends Error {
   readonly name = "SubRosaTimeoutError";
   readonly hash: string;

packages/sdk/src/index.ts

@@ -7,6 +7,16 @@ export {
   type ClearingRuleTag,
 } from "./client.js";
 export { normalizeRoundId, normalizeSorobanContractId } from "./ids.js";
+export {
+  type PreflightOperation,
+  type PreflightResult,
+  type PreflightSuccess,
+  type PreflightFailureResult,
+  type PreflightFeeEstimate,
+  type PreflightResourceEstimate,
+  evaluatePreflight,
+  contractErrorCode,
+} from "./preflight.js";
 export {
   createOzChannelsSubmitter,
   createOzChannelsSubmitterFromEnv,
@@ -18,11 +28,16 @@ export {
 export {
   SubRosaClientConfigError,
   SubRosaMissingReturnValueError,
+  SubRosaPreflightError,
   SubRosaSubmitError,
   SubRosaTimeoutError,
   SubRosaTransactionError,
 } from "./errors.js";
-export type { TimeoutErrorParams } from "./errors.js";
+export type {
+  PreflightFailureKind,
+  SubRosaPreflightErrorParams,
+  TimeoutErrorParams,
+} from "./errors.js";
 
 export {
   validateEncryptedBlob,