From 9c45462f5083f7929609f4a377137e48c4a7ccac Mon Sep 17 00:00:00 2001
From: alexursol2 <ursolother@gmail.com>
Date: Tue, 4 Aug 2026 22:17:48 +0200
Subject: [PATCH] feat: add simulate to direct execution inputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/api/direct-execution.md prescribes a safe first-write sequence: send the
request with simulate: true and continue only when the response has
success: true and wouldRevert: false.

The SDK cannot currently express it. Neither simulate nor idempotency appears
anywhere in the published package, in the types or the compiled output, so a
caller has to drop to client.rawRequest to follow the documentation — which puts
the escape hatch on the safe path and the typed methods on the unsafe one.

Types only, and additive: the field is optional, and rawRequest already sends the
whole input as the request body, so no executor change is needed for it to work.
DirectSimulationResult describes what comes back.

Found while migrating a transaction firewall onto this SDK, where the simulate
step is the core of the product: https://github.com/alexursol2/tx-guardrail
---
 src/types.ts | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/types.ts b/src/types.ts
index fb9a118..14ab8a4 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -118,6 +118,11 @@ export interface DirectTransferInput {
   /** JSON string with token metadata for non-standard ERC-20s. */
   tokenConfig?: string;
   gasLimitMultiplier?: string;
+  /**
+   * Dry-run only: estimate gas and detect a revert without signing or broadcasting.
+   * See docs/api/direct-execution.md for the safe first-write sequence.
+   */
+  simulate?: boolean;
 }
 
 export interface DirectContractCallInput {
@@ -131,6 +136,24 @@ export interface DirectContractCallInput {
   /** Wei to send for payable functions. */
   value?: string;
   gasLimitMultiplier?: string;
+  /**
+   * Dry-run only: estimate gas and detect a revert without signing or broadcasting.
+   * See docs/api/direct-execution.md for the safe first-write sequence.
+   */
+  simulate?: boolean;
+}
+
+/** Returned by a direct-execution call made with `simulate: true`. */
+export interface DirectSimulationResult {
+  success: boolean;
+  status: "simulated";
+  wouldRevert: boolean;
+  /** Present when `wouldRevert` is true; carries the raw revert data. */
+  revertReason?: string;
+  gasEstimate?: string;
+  from?: string;
+  to?: string;
+  value?: string;
 }
 
 export interface DirectCondition {