@spectratools/tx-shared 0.3.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/index.d.ts

@@ -1,10 +1,37 @@
-import { TxSigner } from './types.js';
-export { SignerOptions, SignerProvider, TxResult } 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.
  *
@@ -30,4 +57,17 @@ interface KeystoreSignerOptions {
  */
 declare function createKeystoreSigner(options: KeystoreSignerOptions): TxSigner;
 
-export { type KeystoreSignerOptions, TxSigner, createKeystoreSigner, createPrivateKeySigner };
+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

@@ -56,12 +56,108 @@ function createKeystoreSigner(options) {
   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.3.0",
+  "version": "0.4.1",
   "description": "Shared transaction primitives, signer types, and chain config for spectra tools",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,7 @@
     }
   },
   "dependencies": {
+    "incur": "^0.2.2",
     "ox": "^0.14.0",
     "viem": "^2.47.0"
   },