@spectratools/tx-shared 0.2.0 → 0.3.0

package/dist/chunk-4XI6TBKX.js

@@ -0,0 +1,130 @@
+import {
+  TxError
+} from "./chunk-6T4D5UCR.js";
+
+// src/execute-tx.ts
+async function executeTx(options) {
+  const {
+    publicClient,
+    walletClient,
+    account,
+    address,
+    abi,
+    functionName,
+    chain,
+    args,
+    value,
+    gasLimit,
+    maxFeePerGas,
+    nonce,
+    dryRun = false
+  } = options;
+  let estimatedGas;
+  try {
+    estimatedGas = await publicClient.estimateContractGas({
+      account,
+      address,
+      abi,
+      functionName,
+      args,
+      value
+    });
+  } catch (error) {
+    throw mapError(error, "estimation");
+  }
+  let simulationResult;
+  try {
+    const sim = await publicClient.simulateContract({
+      account,
+      address,
+      abi,
+      functionName,
+      args,
+      value
+    });
+    simulationResult = sim.result;
+  } catch (error) {
+    throw mapError(error, "simulation");
+  }
+  if (dryRun) {
+    return {
+      status: "dry-run",
+      estimatedGas,
+      simulationResult
+    };
+  }
+  let hash;
+  try {
+    hash = await walletClient.writeContract({
+      account,
+      address,
+      abi,
+      functionName,
+      args,
+      value,
+      chain,
+      gas: gasLimit ?? estimatedGas,
+      maxFeePerGas,
+      nonce
+    });
+  } catch (error) {
+    throw mapError(error, "submit");
+  }
+  let receipt;
+  try {
+    receipt = await publicClient.waitForTransactionReceipt({ hash });
+  } catch (error) {
+    throw mapError(error, "receipt");
+  }
+  if (receipt.status === "reverted") {
+    throw new TxError("TX_REVERTED", `Transaction ${hash} reverted on-chain`);
+  }
+  return receiptToTxResult(receipt);
+}
+function receiptToTxResult(receipt) {
+  return {
+    hash: receipt.transactionHash,
+    blockNumber: receipt.blockNumber,
+    gasUsed: receipt.gasUsed,
+    status: receipt.status === "success" ? "success" : "reverted",
+    from: receipt.from,
+    to: receipt.to,
+    effectiveGasPrice: receipt.effectiveGasPrice
+  };
+}
+function mapError(error, phase) {
+  const msg = errorMessage(error);
+  if (matchesInsufficientFunds(msg)) {
+    return new TxError("INSUFFICIENT_FUNDS", `Insufficient funds: ${msg}`, error);
+  }
+  if (matchesNonceConflict(msg)) {
+    return new TxError("NONCE_CONFLICT", `Nonce conflict: ${msg}`, error);
+  }
+  if (phase === "estimation" || phase === "simulation") {
+    return new TxError("GAS_ESTIMATION_FAILED", `Gas estimation/simulation failed: ${msg}`, error);
+  }
+  if (matchesRevert(msg)) {
+    return new TxError("TX_REVERTED", `Transaction reverted: ${msg}`, error);
+  }
+  return new TxError("TX_REVERTED", `Transaction failed (${phase}): ${msg}`, error);
+}
+function errorMessage(error) {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+function matchesInsufficientFunds(msg) {
+  const lower = msg.toLowerCase();
+  return lower.includes("insufficient funds") || lower.includes("insufficient balance") || lower.includes("sender doesn't have enough funds");
+}
+function matchesNonceConflict(msg) {
+  const lower = msg.toLowerCase();
+  return lower.includes("nonce too low") || lower.includes("nonce has already been used") || lower.includes("already known") || lower.includes("replacement transaction underpriced");
+}
+function matchesRevert(msg) {
+  const lower = msg.toLowerCase();
+  return lower.includes("revert") || lower.includes("execution reverted") || lower.includes("transaction failed");
+}
+
+export {
+  executeTx
+};

package/dist/execute-tx.d.ts

@@ -0,0 +1,63 @@
+import { PublicClient, WalletClient, Account, Address, Abi, Chain } from 'viem';
+import { TxResult } from './types.js';
+
+/** Options for the {@link executeTx} lifecycle. */
+interface ExecuteTxOptions {
+    /** Viem public client used for gas estimation, simulation, and receipt retrieval. */
+    publicClient: PublicClient;
+    /** Viem wallet client used to submit the transaction. */
+    walletClient: WalletClient;
+    /** Signer account. */
+    account: Account;
+    /** Target contract address. */
+    address: Address;
+    /** Contract ABI (must include the target function). */
+    abi: Abi;
+    /** Name of the contract function to call. */
+    functionName: string;
+    /** Optional chain to use for the transaction. */
+    chain?: Chain;
+    /** Arguments passed to the contract function. */
+    args?: unknown[];
+    /** Native value (in wei) to send with the transaction. */
+    value?: bigint;
+    /** Gas limit override. When provided the estimate is still performed but this value is used for submission. */
+    gasLimit?: bigint;
+    /** Max fee per gas override (EIP-1559). */
+    maxFeePerGas?: bigint;
+    /** Nonce override. */
+    nonce?: number;
+    /**
+     * When `true` the transaction is simulated but **not** broadcast.
+     * Returns a {@link DryRunResult} instead of a {@link TxResult}.
+     */
+    dryRun?: boolean;
+}
+/** Result returned when `dryRun` is `true`. */
+interface DryRunResult {
+    /** Discriminator — always `'dry-run'` for dry-run results. */
+    status: 'dry-run';
+    /** Estimated gas units for the call. */
+    estimatedGas: bigint;
+    /** Simulated return value from `simulateContract`. */
+    simulationResult: unknown;
+}
+/**
+ * Execute a full transaction lifecycle:
+ *
+ * 1. **Estimate** gas via `publicClient.estimateContractGas`.
+ * 2. **Simulate** contract call via `publicClient.simulateContract`.
+ *    - If `dryRun` is `true`, return a {@link DryRunResult} without broadcasting.
+ * 3. **Submit** the transaction via `walletClient.writeContract`.
+ * 4. **Wait** for the receipt via `publicClient.waitForTransactionReceipt`.
+ * 5. **Normalize** the receipt into a {@link TxResult}.
+ *
+ * Errors thrown by viem are mapped to structured {@link TxError} codes:
+ * - `INSUFFICIENT_FUNDS` — sender lacks balance for value + gas.
+ * - `NONCE_CONFLICT` — nonce already used or too low.
+ * - `GAS_ESTIMATION_FAILED` — gas estimation or simulation reverted.
+ * - `TX_REVERTED` — on-chain revert (includes reason when available).
+ */
+declare function executeTx(options: ExecuteTxOptions): Promise<TxResult | DryRunResult>;
+
+export { type DryRunResult, type ExecuteTxOptions, executeTx };

package/dist/execute-tx.js

@@ -0,0 +1,7 @@
+import {
+  executeTx
+} from "./chunk-4XI6TBKX.js";
+import "./chunk-6T4D5UCR.js";
+export {
+  executeTx
+};

package/dist/index.d.ts

@@ -1,4 +1,33 @@
-export { SignerOptions, SignerProvider, TxResult, TxSigner } from './types.js';
+import { TxSigner } from './types.js';
+export { SignerOptions, SignerProvider, TxResult } from './types.js';
 export { TxError, TxErrorCode, toTxError } from './errors.js';
 export { abstractMainnet, createAbstractClient } from './chain.js';
+export { DryRunResult, ExecuteTxOptions, executeTx } from './execute-tx.js';
 import 'viem';
+
+/**
+ * Create a {@link TxSigner} from a raw private key.
+ *
+ * @param privateKey - `0x`-prefixed 32-byte hex string.
+ * @returns A signer backed by `viem/accounts.privateKeyToAccount`.
+ * @throws {TxError} `SIGNER_NOT_CONFIGURED` when the key format is invalid.
+ */
+declare function createPrivateKeySigner(privateKey: string): TxSigner;
+
+/** Options for {@link createKeystoreSigner}. */
+interface KeystoreSignerOptions {
+    /** Path to the V3 keystore JSON file. */
+    keystorePath: string;
+    /** Password used to decrypt the keystore. */
+    keystorePassword: string;
+}
+/**
+ * Create a {@link TxSigner} by decrypting a V3 keystore file.
+ *
+ * Uses `ox` for key derivation (scrypt / pbkdf2) and AES-128-CTR decryption.
+ *
+ * @throws {TxError} `KEYSTORE_DECRYPT_FAILED` when the file cannot be read, parsed, or decrypted.
+ */
+declare function createKeystoreSigner(options: KeystoreSignerOptions): TxSigner;
+
+export { type KeystoreSignerOptions, TxSigner, createKeystoreSigner, createPrivateKeySigner };

package/dist/index.js

@@ -2,14 +2,66 @@ import {
   abstractMainnet,
   createAbstractClient
 } from "./chunk-P4ACSL6N.js";
+import {
+  executeTx
+} from "./chunk-4XI6TBKX.js";
 import {
   TxError,
   toTxError
 } from "./chunk-6T4D5UCR.js";
 import "./chunk-6F4PWJZI.js";
+
+// src/signers/private-key.ts
+import { privateKeyToAccount } from "viem/accounts";
+var PRIVATE_KEY_REGEX = /^0x[0-9a-fA-F]{64}$/;
+function createPrivateKeySigner(privateKey) {
+  if (!PRIVATE_KEY_REGEX.test(privateKey)) {
+    throw new TxError(
+      "SIGNER_NOT_CONFIGURED",
+      "Invalid private key format: expected 0x-prefixed 32-byte hex string"
+    );
+  }
+  const account = privateKeyToAccount(privateKey);
+  return { account, address: account.address, provider: "private-key" };
+}
+
+// src/signers/keystore.ts
+import { readFileSync } from "fs";
+import { Keystore } from "ox";
+import { privateKeyToAccount as privateKeyToAccount2 } from "viem/accounts";
+function createKeystoreSigner(options) {
+  const { keystorePath, keystorePassword } = options;
+  let keystoreJson;
+  try {
+    const raw = readFileSync(keystorePath, "utf-8");
+    keystoreJson = JSON.parse(raw);
+  } catch (cause) {
+    throw new TxError(
+      "KEYSTORE_DECRYPT_FAILED",
+      `Failed to read keystore file: ${keystorePath}`,
+      cause
+    );
+  }
+  let privateKey;
+  try {
+    const key = Keystore.toKey(keystoreJson, { password: keystorePassword });
+    privateKey = Keystore.decrypt(keystoreJson, key);
+  } catch (cause) {
+    throw new TxError(
+      "KEYSTORE_DECRYPT_FAILED",
+      `Failed to decrypt keystore: ${cause instanceof Error ? cause.message : String(cause)}`,
+      cause
+    );
+  }
+  const account = privateKeyToAccount2(privateKey);
+  return { account, address: account.address, provider: "keystore" };
+}
 export {
   TxError,
   abstractMainnet,
   createAbstractClient,
+  createKeystoreSigner,
+  createPrivateKeySigner,
+  executeTx,
   toTxError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/tx-shared",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared transaction primitives, signer types, and chain config for spectra tools",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,10 @@
     "./chain": {
       "types": "./dist/chain.d.ts",
       "default": "./dist/chain.js"
+    },
+    "./execute-tx": {
+      "types": "./dist/execute-tx.d.ts",
+      "default": "./dist/execute-tx.js"
     }
   },
   "dependencies": {