aavegotchi-cli 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.1 - 2026-02-27
+
+### Added
+
+- `--dry-run` mode for write surfaces:
+  - `ag tx send --dry-run`
+  - `ag onchain send --dry-run`
+  - mapped writes (for example `ag token approve --dry-run`)
+- `scripts/smoke-write-dryrun.sh` and npm script `smoke:write-dryrun` for automated write-path smoke checks without broadcasting.
+
+### Changed
+
+- Dry-run execution now returns `status: "simulated"` with simulation details and skips journal mutation and transaction submission.
+- `--dry-run` is explicitly blocked with `--wait` / `--confirm`.
+
 ## 0.2.0 - 2026-02-27
 
 ### Added

package/README.md

@@ -55,6 +55,26 @@ Planned domain namespaces are stubbed for parity tracking:
 Many Base-era write flows are already executable as mapped aliases in those namespaces (internally routed through `onchain send`).
 Example: `ag lending create --abi-file ./abis/GotchiLendingFacet.json --address 0x... --args-json '[...]' --json`
 
+## Dry-run writes
+
+Use `--dry-run` on write commands to run full preflight without broadcasting:
+
+- runs simulation (`eth_call`)
+- runs gas + fee estimation
+- enforces policy checks
+- resolves nonce
+- returns `status: \"simulated\"` with simulation details
+
+Supported write surfaces:
+
+- `tx send --dry-run`
+- `onchain send --dry-run`
+- mapped write aliases (for example: `token approve --dry-run`)
+
+Safety rule:
+
+- `--dry-run` cannot be combined with `--wait` / `--confirm`
+
 ## Subgraph sources and endpoint policy
 
 Canonical source aliases:
@@ -186,5 +206,12 @@ npm run typecheck
 npm test
 npm run build
 npm run parity:check
+npm run smoke:write-dryrun
 npm run ag -- help
 ```
+
+Write dry-run smoke test notes:
+
+- `npm run smoke:write-dryrun` validates write paths without broadcasting any transaction.
+- To run against an installed binary instead of local source:
+  - `AG_BIN=/absolute/path/to/ag npm run smoke:write-dryrun`

package/dist/commands/onchain.js

@@ -184,6 +184,10 @@ async function runOnchainSendWithFunction(ctx, forcedFunctionName, commandOverri
         });
     }
     const waitForReceipt = (0, args_1.getFlagBoolean)(ctx.args.flags, "wait");
+    const dryRun = (0, args_1.getFlagBoolean)(ctx.args.flags, "dry-run");
+    if (dryRun && waitForReceipt) {
+        throw new errors_1.CliError("INVALID_ARGUMENT", "--dry-run cannot be combined with --wait.", 2);
+    }
     const intent = {
         idempotencyKey: (0, args_1.getFlagString)(ctx.args.flags, "idempotency-key"),
         profileName: profile.name,
@@ -197,6 +201,7 @@ async function runOnchainSendWithFunction(ctx, forcedFunctionName, commandOverri
         noncePolicy: noncePolicyRaw,
         nonce,
         waitForReceipt,
+        dryRun,
         timeoutMs: parseTimeoutMs((0, args_1.getFlagString)(ctx.args.flags, "timeout-ms")),
         command: commandOverride || `onchain send ${functionName}`,
     };

package/dist/commands/tx.js

@@ -75,10 +75,14 @@ async function runTxSendCommand(ctx) {
     const nonceValue = (0, args_1.getFlagString)(ctx.args.flags, "nonce");
     const nonce = nonceValue ? parseNumberFlag(nonceValue, "--nonce", 0) : undefined;
     const waitForReceipt = (0, args_1.getFlagBoolean)(ctx.args.flags, "wait") || (0, args_1.getFlagBoolean)(ctx.args.flags, "confirm");
+    const dryRun = (0, args_1.getFlagBoolean)(ctx.args.flags, "dry-run");
     const timeoutMs = parseNumberFlag((0, args_1.getFlagString)(ctx.args.flags, "timeout-ms"), "--timeout-ms", 120000);
     if (noncePolicy === "manual" && nonce === undefined) {
         throw new errors_1.CliError("MISSING_NONCE", "--nonce is required when --nonce-policy=manual.", 2);
     }
+    if (dryRun && waitForReceipt) {
+        throw new errors_1.CliError("INVALID_ARGUMENT", "--dry-run cannot be combined with --wait/--confirm.", 2);
+    }
     const intent = {
         idempotencyKey,
         profileName: profile.name,
@@ -92,6 +96,7 @@ async function runTxSendCommand(ctx) {
         noncePolicy,
         nonce,
         waitForReceipt,
+        dryRun,
         timeoutMs,
         command: "tx send",
     };

package/dist/output.js

@@ -69,7 +69,7 @@ Core commands:
   rpc check                          Verify RPC connectivity + signer backend health
 
 Tx commands:
-  tx send                            Send a raw EVM transaction with simulation + policy checks + journaling
+  tx send                            Send a raw EVM transaction (or simulate only with --dry-run)
   tx status                          Read tx status by idempotency key/hash or list recent
   tx resume                          Resume waiting for a previously submitted tx
   tx watch                           Poll journal until tx is confirmed
@@ -79,7 +79,7 @@ Automation commands:
 
 Power-user commands:
   onchain call                       Call any ABI function from --abi-file
-  onchain send                       Send any ABI function as a transaction
+  onchain send                       Send any ABI function as a transaction (or simulate with --dry-run)
   subgraph list|check|query          List/check/query canonical Goldsky subgraphs
 
 Domain namespaces:
@@ -112,6 +112,7 @@ Examples:
   ag bootstrap --mode agent --profile prod --chain base --signer env:AGCLI_PRIVATE_KEY --json
   AGCLI_KEYCHAIN_PASSPHRASE=... AGCLI_PRIVATE_KEY=0x... ag signer keychain import --account-id bot --private-key-env AGCLI_PRIVATE_KEY --json
   ag tx send --profile prod --to 0xabc... --value-wei 1000000000000000 --wait --json
+  ag tx send --profile prod --to 0xabc... --value-wei 0 --dry-run --json
   ag subgraph check --source core-base --json
   ag baazaar listing active --kind erc721 --first 20 --json
   ag auction active --first 20 --json

package/dist/tx-engine.js

@@ -72,9 +72,10 @@ async function waitForConfirmation(intent, ctx, txHash) {
 async function executeTxIntent(intent, chain, customHome) {
     const idempotencyKey = (0, idempotency_1.resolveIdempotencyKey)(intent);
     const journal = new journal_1.JournalStore((0, config_1.resolveJournalPath)(customHome));
+    const dryRun = Boolean(intent.dryRun);
     try {
         const preflight = await (0, rpc_1.runRpcPreflight)(chain, intent.rpcUrl);
-        const existing = journal.getByIdempotencyKey(idempotencyKey);
+        const existing = dryRun ? undefined : journal.getByIdempotencyKey(idempotencyKey);
         if (existing && existing.status === "confirmed") {
             return mapJournalToResult(existing);
         }
@@ -91,7 +92,13 @@ async function executeTxIntent(intent, chain, customHome) {
         }
         const viemChain = (0, chains_1.toViemChain)(chain, intent.rpcUrl);
         const signerRuntime = await (0, signer_1.resolveSignerRuntime)(intent.signer, preflight.client, intent.rpcUrl, viemChain, customHome);
-        if (!signerRuntime.summary.canSign || !signerRuntime.sendTransaction || !signerRuntime.summary.address) {
+        if (!signerRuntime.summary.address) {
+            throw new errors_1.CliError("MISSING_SIGNER_ADDRESS", "Signer address is required for simulation and transaction execution.", 2, {
+                signerType: signerRuntime.summary.signerType,
+                backendStatus: signerRuntime.summary.backendStatus,
+            });
+        }
+        if (!dryRun && (!signerRuntime.summary.canSign || !signerRuntime.sendTransaction)) {
             throw new errors_1.CliError("READONLY_SIGNER", "Selected signer cannot submit transactions.", 2, {
                 signerType: signerRuntime.summary.signerType,
                 backendStatus: signerRuntime.summary.backendStatus,
@@ -125,7 +132,7 @@ async function executeTxIntent(intent, chain, customHome) {
         const maxPriorityFeePerGas = feeEstimate.maxPriorityFeePerGas;
         const balanceWei = await preflight.client.getBalance({ address: fromAddress });
         const requiredWei = (intent.valueWei || 0n) + gasLimit * (maxFeePerGas || 0n);
-        if (balanceWei < requiredWei) {
+        if (!dryRun && balanceWei < requiredWei) {
             throw new errors_1.CliError("INSUFFICIENT_FUNDS_PRECHECK", "Account balance is below estimated transaction requirement.", 2, {
                 from: fromAddress,
                 balanceWei: balanceWei.toString(),
@@ -147,6 +154,31 @@ async function executeTxIntent(intent, chain, customHome) {
             existing,
         };
         const nonce = await resolveNonce(intent, ctx, fromAddress);
+        if (dryRun) {
+            return {
+                idempotencyKey,
+                from: fromAddress,
+                to: toAddress,
+                nonce,
+                gasLimit: gasLimit.toString(),
+                maxFeePerGasWei: maxFeePerGas?.toString(),
+                maxPriorityFeePerGasWei: maxPriorityFeePerGas?.toString(),
+                status: "simulated",
+                dryRun: true,
+                simulation: {
+                    requiredWei: requiredWei.toString(),
+                    balanceWei: balanceWei.toString(),
+                    signerCanSign: signerRuntime.summary.canSign,
+                    noncePolicy: intent.noncePolicy,
+                },
+            };
+        }
+        if (!signerRuntime.sendTransaction) {
+            throw new errors_1.CliError("READONLY_SIGNER", "Selected signer cannot submit transactions.", 2, {
+                signerType: signerRuntime.summary.signerType,
+                backendStatus: signerRuntime.summary.backendStatus,
+            });
+        }
         journal.upsertPrepared({
             idempotencyKey,
             profileName: intent.profileName,
@@ -208,14 +240,18 @@ async function executeTxIntent(intent, chain, customHome) {
     }
     catch (error) {
         if (error instanceof errors_1.CliError) {
-            journal.markFailed(idempotencyKey, error.code, error.message);
+            if (!dryRun) {
+                journal.markFailed(idempotencyKey, error.code, error.message);
+            }
             throw error;
         }
         const unknown = new errors_1.CliError("TX_EXECUTION_FAILED", "Transaction execution failed.", 1, {
             correlationId: (0, crypto_1.randomUUID)(),
             message: error instanceof Error ? error.message : String(error),
         });
-        journal.markFailed(idempotencyKey, unknown.code, unknown.message);
+        if (!dryRun) {
+            journal.markFailed(idempotencyKey, unknown.code, unknown.message);
+        }
         throw unknown;
     }
     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aavegotchi-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Agent-first CLI for automating Aavegotchi app and onchain workflows",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "parity:check": "node scripts/check-parity.mjs",
+    "smoke:write-dryrun": "bash scripts/smoke-write-dryrun.sh",
     "ag": "tsx src/index.ts",
     "prepack": "npm run build",
     "bootstrap:smoke": "AGCLI_HOME=/tmp/agcli-smoke tsx src/index.ts bootstrap --mode agent --profile smoke --chain base --signer readonly --json"