@spectratools/tx-shared 0.2.0 → 0.4.1

package/README.md

@@ -1,3 +1,200 @@
 # @spectratools/tx-shared
 
-Shared transaction primitives for Spectra tools: signer/result types, structured tx errors, and Abstract chain client helpers.
+Shared transaction primitives for Spectra tools:
+
+- signer resolution (`resolveSigner`)
+- transaction lifecycle execution (`executeTx`)
+- shared signer CLI/env parsing helpers (`toSignerOptions`)
+- structured transaction errors (`TxError`)
+- Abstract chain helpers (`abstractMainnet`, `createAbstractClient`)
+
+This package is designed for consuming CLIs (for example `@spectratools/assembly-cli`) so write-capable commands follow the same signer precedence, dry-run behavior, and error handling.
+
+## Install
+
+```bash
+pnpm add @spectratools/tx-shared
+```
+
+## Signer Providers
+
+`resolveSigner()` uses deterministic precedence:
+
+1. `privateKey`
+2. `keystorePath` (+ `keystorePassword`)
+3. `privy` / `PRIVY_*`
+
+If no provider is configured, it throws `TxError` with code `SIGNER_NOT_CONFIGURED`.
+
+### Provider setup
+
+#### 1) Private key
+
+```bash
+export PRIVATE_KEY="0x<64-hex-chars>"
+```
+
+Or pass `privateKey` directly in code.
+
+#### 2) Keystore
+
+```bash
+# CLI convention
+--keystore /path/to/keystore.json --password "$KEYSTORE_PASSWORD"
+
+# env fallback for password
+export KEYSTORE_PASSWORD="..."
+```
+
+`resolveSigner()` requires a password when `keystorePath` is provided.
+
+#### 3) Privy
+
+```bash
+export PRIVY_APP_ID="..."
+export PRIVY_WALLET_ID="..."
+export PRIVY_AUTHORIZATION_KEY="..."
+```
+
+> Privy signer execution is intentionally stubbed right now and throws `PRIVY_AUTH_FAILED` with a deterministic message. Full implementation is tracked in [issue #117](https://github.com/spectra-the-bot/spectra-tools/issues/117).
+
+## `resolveSigner()` usage
+
+### Direct options
+
+```ts
+import { resolveSigner } from '@spectratools/tx-shared';
+
+const signer = await resolveSigner({
+  privateKey: process.env.PRIVATE_KEY,
+});
+
+console.log(signer.provider); // 'private-key' | 'keystore' | 'privy'
+console.log(signer.address);  // 0x...
+```
+
+### From shared CLI flags + env
+
+```ts
+import {
+  resolveSigner,
+  signerEnvSchema,
+  signerFlagSchema,
+  toSignerOptions,
+} from '@spectratools/tx-shared';
+
+const flags = signerFlagSchema.parse({
+  'private-key': process.env.PRIVATE_KEY,
+  privy: false,
+});
+
+const env = signerEnvSchema.parse(process.env);
+const signer = await resolveSigner(toSignerOptions(flags, env));
+```
+
+## `executeTx()` lifecycle
+
+`executeTx()` performs this flow:
+
+1. estimate gas (`estimateContractGas`)
+2. simulate (`simulateContract`)
+3. submit (`writeContract`) unless `dryRun: true`
+4. wait for receipt (`waitForTransactionReceipt`)
+5. normalize result into a shared output shape
+
+### Live transaction example
+
+```ts
+import { executeTx } from '@spectratools/tx-shared';
+
+const result = await executeTx({
+  publicClient,
+  walletClient,
+  account: signer.account,
+  address,
+  abi,
+  functionName: 'register',
+  value: registrationFee,
+});
+
+console.log(result.hash, result.status, result.gasUsed.toString());
+```
+
+### Dry-run example
+
+```ts
+const result = await executeTx({
+  publicClient,
+  walletClient,
+  account: signer.account,
+  address,
+  abi,
+  functionName: 'register',
+  value: registrationFee,
+  dryRun: true,
+});
+
+if (result.status === 'dry-run') {
+  console.log('estimatedGas', result.estimatedGas.toString());
+  console.log('simulationResult', result.simulationResult);
+}
+```
+
+## Structured errors
+
+`executeTx()` and signer helpers throw `TxError` with stable `code` values:
+
+- `INSUFFICIENT_FUNDS`
+- `NONCE_CONFLICT`
+- `GAS_ESTIMATION_FAILED`
+- `TX_REVERTED`
+- `SIGNER_NOT_CONFIGURED`
+- `KEYSTORE_DECRYPT_FAILED`
+- `PRIVY_AUTH_FAILED`
+
+```ts
+import { TxError } from '@spectratools/tx-shared';
+
+try {
+  // resolveSigner(...) + executeTx(...)
+} catch (error) {
+  if (error instanceof TxError) {
+    switch (error.code) {
+      case 'INSUFFICIENT_FUNDS':
+      case 'NONCE_CONFLICT':
+      case 'GAS_ESTIMATION_FAILED':
+      case 'TX_REVERTED':
+      case 'SIGNER_NOT_CONFIGURED':
+      case 'KEYSTORE_DECRYPT_FAILED':
+      case 'PRIVY_AUTH_FAILED':
+        throw error;
+    }
+  }
+
+  throw error;
+}
+```
+
+## Troubleshooting
+
+- **`SIGNER_NOT_CONFIGURED`**
+  - check signer input precedence
+  - confirm at least one provider is configured
+- **`KEYSTORE_DECRYPT_FAILED`**
+  - verify file path and password
+  - ensure keystore is valid V3 JSON
+- **`PRIVY_AUTH_FAILED`**
+  - verify all `PRIVY_*` variables are set
+  - note: provider is not live yet (see #117)
+- **`GAS_ESTIMATION_FAILED` / `TX_REVERTED`**
+  - validate function args and `value`
+  - run with `dryRun: true` first
+- **`NONCE_CONFLICT`**
+  - refresh nonce and retry once with an explicit override if needed
+
+## Consumer integration examples
+
+- tx-shared assembly-style example:
+  - [`src/examples/assembly-write.ts`](./src/examples/assembly-write.ts)
+- assembly consumer reference wiring:
+  - [`../assembly/src/examples/tx-shared-register.ts`](../assembly/src/examples/tx-shared-register.ts)

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,73 @@
-export { SignerOptions, SignerProvider, TxResult, TxSigner } from './types.js';
+import { SignerOptions, TxSigner } from './types.js';
+export { 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 { z } from 'incur';
 import 'viem';
+
+/**
+ * Resolve the active signer provider using deterministic precedence:
+ * private key -> keystore -> privy -> SIGNER_NOT_CONFIGURED.
+ */
+declare function resolveSigner(opts: SignerOptions): Promise<TxSigner>;
+
+/** Shared signer-related CLI flags for write-capable commands. */
+declare const signerFlagSchema: z.ZodObject<{
+    'private-key': z.ZodOptional<z.ZodString>;
+    keystore: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    privy: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Shared signer-related environment variables for write-capable commands. */
+declare const signerEnvSchema: z.ZodObject<{
+    PRIVATE_KEY: z.ZodOptional<z.ZodString>;
+    KEYSTORE_PASSWORD: z.ZodOptional<z.ZodString>;
+    PRIVY_APP_ID: z.ZodOptional<z.ZodString>;
+    PRIVY_WALLET_ID: z.ZodOptional<z.ZodString>;
+    PRIVY_AUTHORIZATION_KEY: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SignerFlags = z.infer<typeof signerFlagSchema>;
+type SignerEnv = z.infer<typeof signerEnvSchema>;
+/** Map parsed CLI context into tx-shared SignerOptions. */
+declare function toSignerOptions(flags: SignerFlags, env: SignerEnv): SignerOptions;
+
+/**
+ * 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;
+
+interface PrivySignerOptions {
+    privyAppId?: string;
+    privyWalletId?: string;
+    privyAuthorizationKey?: string;
+}
+/**
+ * Privy signer adapter entrypoint.
+ *
+ * Full Privy integration is tracked in issue #117. Until that lands,
+ * this adapter provides deterministic, structured failures for callers.
+ */
+declare function createPrivySigner(options: PrivySignerOptions): Promise<TxSigner>;
+
+export { type KeystoreSignerOptions, type PrivySignerOptions, type SignerEnv, type SignerFlags, SignerOptions, TxSigner, createKeystoreSigner, createPrivateKeySigner, createPrivySigner, resolveSigner, signerEnvSchema, signerFlagSchema, toSignerOptions };

package/dist/index.js

@@ -2,14 +2,162 @@ 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" };
+}
+
+// src/signers/privy.ts
+var REQUIRED_FIELDS = [
+  "privyAppId",
+  "privyWalletId",
+  "privyAuthorizationKey"
+];
+async function createPrivySigner(options) {
+  const missing = REQUIRED_FIELDS.filter((field) => options[field] === void 0);
+  if (missing.length > 0) {
+    const missingLabels = missing.map((field) => {
+      if (field === "privyAppId") {
+        return "PRIVY_APP_ID";
+      }
+      if (field === "privyWalletId") {
+        return "PRIVY_WALLET_ID";
+      }
+      return "PRIVY_AUTHORIZATION_KEY";
+    }).join(", ");
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      `Privy signer requires configuration: missing ${missingLabels}`
+    );
+  }
+  throw new TxError(
+    "PRIVY_AUTH_FAILED",
+    "Privy signer is not yet available in tx-shared. Track progress in issue #117."
+  );
+}
+
+// src/resolve-signer.ts
+function hasPrivyConfig(opts) {
+  return opts.privyAppId !== void 0 || opts.privyWalletId !== void 0 || opts.privyAuthorizationKey !== void 0;
+}
+async function resolveSigner(opts) {
+  if (opts.privateKey !== void 0) {
+    return createPrivateKeySigner(opts.privateKey);
+  }
+  if (opts.keystorePath !== void 0) {
+    if (opts.keystorePassword === void 0) {
+      throw new TxError(
+        "SIGNER_NOT_CONFIGURED",
+        "Keystore password is required when --keystore is provided (use --password or KEYSTORE_PASSWORD)."
+      );
+    }
+    return createKeystoreSigner({
+      keystorePath: opts.keystorePath,
+      keystorePassword: opts.keystorePassword
+    });
+  }
+  if (opts.privy === true || hasPrivyConfig(opts)) {
+    return createPrivySigner({
+      ...opts.privyAppId !== void 0 ? { privyAppId: opts.privyAppId } : {},
+      ...opts.privyWalletId !== void 0 ? { privyWalletId: opts.privyWalletId } : {},
+      ...opts.privyAuthorizationKey !== void 0 ? { privyAuthorizationKey: opts.privyAuthorizationKey } : {}
+    });
+  }
+  throw new TxError(
+    "SIGNER_NOT_CONFIGURED",
+    "No signer configured. Set --private-key, or --keystore + --password, or enable --privy with PRIVY_* credentials."
+  );
+}
+
+// src/incur-params.ts
+import { z } from "incur";
+var signerFlagSchema = z.object({
+  "private-key": z.string().optional().describe("Raw private key (0x-prefixed 32-byte hex) for signing transactions"),
+  keystore: z.string().optional().describe("Path to an encrypted V3 keystore JSON file"),
+  password: z.string().optional().describe("Keystore password (non-interactive mode)"),
+  privy: z.boolean().default(false).describe("Use Privy server wallet signer mode")
+});
+var signerEnvSchema = z.object({
+  PRIVATE_KEY: z.string().optional().describe("Raw private key (0x-prefixed 32-byte hex)"),
+  KEYSTORE_PASSWORD: z.string().optional().describe("Password for decrypting --keystore"),
+  PRIVY_APP_ID: z.string().optional().describe("Privy app id used to authorize wallet intents"),
+  PRIVY_WALLET_ID: z.string().optional().describe("Privy wallet id used for transaction intents"),
+  PRIVY_AUTHORIZATION_KEY: z.string().optional().describe("Privy authorization private key used to sign intent requests")
+});
+function toSignerOptions(flags, env) {
+  const privateKey = flags["private-key"] ?? env.PRIVATE_KEY;
+  const keystorePassword = flags.password ?? env.KEYSTORE_PASSWORD;
+  return {
+    ...privateKey !== void 0 ? { privateKey } : {},
+    ...flags.keystore !== void 0 ? { keystorePath: flags.keystore } : {},
+    ...keystorePassword !== void 0 ? { keystorePassword } : {},
+    ...flags.privy ? { privy: true } : {},
+    ...env.PRIVY_APP_ID !== void 0 ? { privyAppId: env.PRIVY_APP_ID } : {},
+    ...env.PRIVY_WALLET_ID !== void 0 ? { privyWalletId: env.PRIVY_WALLET_ID } : {},
+    ...env.PRIVY_AUTHORIZATION_KEY !== void 0 ? { privyAuthorizationKey: env.PRIVY_AUTHORIZATION_KEY } : {}
+  };
+}
 export {
   TxError,
   abstractMainnet,
   createAbstractClient,
+  createKeystoreSigner,
+  createPrivateKeySigner,
+  createPrivySigner,
+  executeTx,
+  resolveSigner,
+  signerEnvSchema,
+  signerFlagSchema,
+  toSignerOptions,
   toTxError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/tx-shared",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Shared transaction primitives, signer types, and chain config for spectra tools",
   "type": "module",
   "license": "MIT",
@@ -30,9 +30,14 @@
     "./chain": {
       "types": "./dist/chain.d.ts",
       "default": "./dist/chain.js"
+    },
+    "./execute-tx": {
+      "types": "./dist/execute-tx.d.ts",
+      "default": "./dist/execute-tx.js"
     }
   },
   "dependencies": {
+    "incur": "^0.2.2",
     "ox": "^0.14.0",
     "viem": "^2.47.0"
   },