@spectratools/tx-shared 0.3.0 → 0.4.2

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/errors.d.ts

@@ -1,4 +1,4 @@
-type TxErrorCode = 'INSUFFICIENT_FUNDS' | 'NONCE_CONFLICT' | 'TX_REVERTED' | 'GAS_ESTIMATION_FAILED' | 'SIGNER_NOT_CONFIGURED' | 'KEYSTORE_DECRYPT_FAILED' | 'PRIVY_AUTH_FAILED';
+type TxErrorCode = 'INSUFFICIENT_FUNDS' | 'NONCE_CONFLICT' | 'TX_REVERTED' | 'GAS_ESTIMATION_FAILED' | 'SIGNER_NOT_CONFIGURED' | 'KEYSTORE_DECRYPT_FAILED' | 'PRIVY_AUTH_FAILED' | 'PRIVY_TRANSPORT_FAILED';
 declare class TxError extends Error {
     readonly code: TxErrorCode;
     constructor(code: TxErrorCode, message: string, cause?: unknown);

package/dist/index.d.ts

@@ -1,10 +1,40 @@
-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 { KeyObject } from 'node:crypto';
 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>;
+    'privy-api-url': z.ZodOptional<z.ZodString>;
+}, 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>;
+    PRIVY_API_URL: 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 +60,97 @@ interface KeystoreSignerOptions {
  */
 declare function createKeystoreSigner(options: KeystoreSignerOptions): TxSigner;
 
-export { type KeystoreSignerOptions, TxSigner, createKeystoreSigner, createPrivateKeySigner };
+interface PrivyRpcIntentRequest {
+    method: string;
+    params: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface PrivyRpcIntentResponse {
+    intent_id: string;
+    status: string;
+    resource_id?: string;
+    request_details?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface PrivyWalletResponse {
+    id: string;
+    address: string;
+    owner_id: string | null;
+    policy_ids: string[];
+    [key: string]: unknown;
+}
+interface PrivyPolicyResponse {
+    id: string;
+    owner_id: string | null;
+    rules: unknown[];
+    [key: string]: unknown;
+}
+interface CreatePrivyClientOptions {
+    appId: string;
+    walletId: string;
+    authorizationKey: string;
+    apiUrl?: string;
+    fetchImplementation?: typeof fetch;
+}
+interface PrivyRequestOptions {
+    idempotencyKey?: string;
+}
+interface PrivyClient {
+    readonly appId: string;
+    readonly walletId: string;
+    readonly apiUrl: string;
+    createRpcIntent(request: PrivyRpcIntentRequest, options?: PrivyRequestOptions): Promise<PrivyRpcIntentResponse>;
+    getWallet(): Promise<PrivyWalletResponse>;
+    getPolicy(policyId: string): Promise<PrivyPolicyResponse>;
+}
+declare function createPrivyClient(options: CreatePrivyClientOptions): PrivyClient;
+
+type PrivyAuthorizationMethod = 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+interface PrivyAuthorizationPayloadHeaders {
+    'privy-app-id': string;
+    'privy-idempotency-key'?: string;
+}
+interface PrivyAuthorizationPayload<TBody extends Record<string, unknown>> {
+    version: 1;
+    method: PrivyAuthorizationMethod;
+    url: string;
+    headers: PrivyAuthorizationPayloadHeaders;
+    body: TBody;
+}
+interface CreatePrivyAuthorizationPayloadOptions<TBody extends Record<string, unknown>> {
+    appId: string;
+    method: PrivyAuthorizationMethod;
+    url: string;
+    body: TBody;
+    idempotencyKey?: string;
+}
+declare function normalizePrivyApiUrl(apiUrl?: string): string;
+declare function parsePrivyAuthorizationKey(authorizationKey: string): KeyObject;
+declare function createPrivyAuthorizationPayload<TBody extends Record<string, unknown>>(options: CreatePrivyAuthorizationPayloadOptions<TBody>): PrivyAuthorizationPayload<TBody>;
+declare function serializePrivyAuthorizationPayload(payload: PrivyAuthorizationPayload<Record<string, unknown>>): string;
+declare function generatePrivyAuthorizationSignature(payload: PrivyAuthorizationPayload<Record<string, unknown>>, authorizationKey: string): string;
+
+interface PrivySignerOptions {
+    privyAppId?: string;
+    privyWalletId?: string;
+    privyAuthorizationKey?: string;
+    privyApiUrl?: string;
+}
+interface PrivySigner extends TxSigner {
+    provider: 'privy';
+    privy: {
+        appId: string;
+        walletId: string;
+        apiUrl: string;
+        client: PrivyClient;
+    };
+}
+/**
+ * Create a Privy signer envelope with reusable transport and request-signing primitives.
+ *
+ * This initializes the shared client utilities used by tx-shared Privy integrations.
+ * Transaction account execution is implemented in follow-up work for issue #191.
+ */
+declare function createPrivySigner(options: PrivySignerOptions): Promise<PrivySigner>;
+
+export { type KeystoreSignerOptions, type PrivyAuthorizationPayload, type PrivyAuthorizationPayloadHeaders, type PrivyClient, type PrivySigner, type PrivySignerOptions, type SignerEnv, type SignerFlags, SignerOptions, TxSigner, createKeystoreSigner, createPrivateKeySigner, createPrivyAuthorizationPayload, createPrivyClient, createPrivySigner, generatePrivyAuthorizationSignature, normalizePrivyApiUrl, parsePrivyAuthorizationKey, resolveSigner, serializePrivyAuthorizationPayload, signerEnvSchema, signerFlagSchema, toSignerOptions };

package/dist/index.js

@@ -56,12 +56,468 @@ function createKeystoreSigner(options) {
   const account = privateKeyToAccount2(privateKey);
   return { account, address: account.address, provider: "keystore" };
 }
+
+// src/signers/privy-signature.ts
+import { createPrivateKey, sign as signWithCrypto } from "crypto";
+var PRIVY_AUTHORIZATION_KEY_PREFIX = "wallet-auth:";
+var PRIVY_AUTHORIZATION_KEY_REGEX = /^wallet-auth:[A-Za-z0-9+/]+={0,2}$/;
+var DEFAULT_PRIVY_API_URL = "https://api.privy.io";
+function normalizePrivyApiUrl(apiUrl) {
+  const value = (apiUrl ?? DEFAULT_PRIVY_API_URL).trim();
+  if (value.length === 0) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_API_URL format: expected a non-empty http(s) URL"
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch (cause) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_API_URL format: expected a non-empty http(s) URL",
+      cause
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_API_URL format: expected a non-empty http(s) URL"
+    );
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+function parsePrivyAuthorizationKey(authorizationKey) {
+  const normalizedKey = authorizationKey.trim();
+  if (!PRIVY_AUTHORIZATION_KEY_REGEX.test(normalizedKey)) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_AUTHORIZATION_KEY format: expected wallet-auth:<base64-pkcs8-p256-private-key>"
+    );
+  }
+  const rawPrivateKey = normalizedKey.slice(PRIVY_AUTHORIZATION_KEY_PREFIX.length);
+  let derKey;
+  try {
+    derKey = Buffer.from(rawPrivateKey, "base64");
+  } catch (cause) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_AUTHORIZATION_KEY format: expected wallet-auth:<base64-pkcs8-p256-private-key>",
+      cause
+    );
+  }
+  let keyObject;
+  try {
+    keyObject = createPrivateKey({
+      key: derKey,
+      format: "der",
+      type: "pkcs8"
+    });
+  } catch (cause) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_AUTHORIZATION_KEY format: expected wallet-auth:<base64-pkcs8-p256-private-key>",
+      cause
+    );
+  }
+  if (keyObject.asymmetricKeyType !== "ec") {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_AUTHORIZATION_KEY format: expected wallet-auth:<base64-pkcs8-p256-private-key>"
+    );
+  }
+  const details = keyObject.asymmetricKeyDetails;
+  const namedCurve = details !== void 0 && "namedCurve" in details ? details.namedCurve : void 0;
+  if (namedCurve !== void 0 && namedCurve !== "prime256v1") {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_AUTHORIZATION_KEY format: expected wallet-auth:<base64-pkcs8-p256-private-key>"
+    );
+  }
+  return keyObject;
+}
+function createPrivyAuthorizationPayload(options) {
+  const appId = options.appId.trim();
+  if (appId.length === 0) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_APP_ID format: expected non-empty string"
+    );
+  }
+  const url = options.url.trim().replace(/\/+$/, "");
+  if (url.length === 0) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      "Failed to build Privy authorization payload: request URL is empty"
+    );
+  }
+  return {
+    version: 1,
+    method: options.method,
+    url,
+    headers: {
+      "privy-app-id": appId,
+      ...options.idempotencyKey !== void 0 ? { "privy-idempotency-key": options.idempotencyKey } : {}
+    },
+    body: options.body
+  };
+}
+function serializePrivyAuthorizationPayload(payload) {
+  return canonicalizeJson(payload);
+}
+function generatePrivyAuthorizationSignature(payload, authorizationKey) {
+  const privateKey = parsePrivyAuthorizationKey(authorizationKey);
+  const serializedPayload = serializePrivyAuthorizationPayload(payload);
+  const signature = signWithCrypto("sha256", Buffer.from(serializedPayload), privateKey);
+  return signature.toString("base64");
+}
+function canonicalizeJson(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "string" || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TxError(
+        "PRIVY_TRANSPORT_FAILED",
+        "Failed to build Privy authorization payload: JSON payload contains a non-finite number"
+      );
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalizeJson(item)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const record = value;
+    const keys = Object.keys(record).sort((left, right) => left.localeCompare(right));
+    const entries = [];
+    for (const key of keys) {
+      const entryValue = record[key];
+      if (entryValue === void 0) {
+        continue;
+      }
+      entries.push(`${JSON.stringify(key)}:${canonicalizeJson(entryValue)}`);
+    }
+    return `{${entries.join(",")}}`;
+  }
+  throw new TxError(
+    "PRIVY_TRANSPORT_FAILED",
+    "Failed to build Privy authorization payload: JSON payload contains unsupported value type"
+  );
+}
+
+// src/signers/privy-client.ts
+function createPrivyClient(options) {
+  const appId = options.appId.trim();
+  const walletId = options.walletId.trim();
+  if (appId.length === 0) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_APP_ID format: expected non-empty string"
+    );
+  }
+  if (walletId.length === 0) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_WALLET_ID format: expected non-empty string"
+    );
+  }
+  const apiUrl = normalizePrivyApiUrl(options.apiUrl);
+  const fetchImplementation = options.fetchImplementation ?? fetch;
+  return {
+    appId,
+    walletId,
+    apiUrl,
+    async createRpcIntent(request, requestOptions) {
+      const url = `${apiUrl}/v1/intents/wallets/${walletId}/rpc`;
+      const payload = createPrivyAuthorizationPayload({
+        appId,
+        method: "POST",
+        url,
+        body: request,
+        ...requestOptions?.idempotencyKey !== void 0 ? { idempotencyKey: requestOptions.idempotencyKey } : {}
+      });
+      const signature = generatePrivyAuthorizationSignature(payload, options.authorizationKey);
+      return sendPrivyRequest({
+        fetchImplementation,
+        method: "POST",
+        url,
+        body: request,
+        operation: "create rpc intent",
+        headers: {
+          "privy-app-id": appId,
+          "privy-authorization-signature": signature,
+          ...requestOptions?.idempotencyKey !== void 0 ? { "privy-idempotency-key": requestOptions.idempotencyKey } : {}
+        }
+      });
+    },
+    async getWallet() {
+      const url = `${apiUrl}/v1/wallets/${walletId}`;
+      return sendPrivyRequest({
+        fetchImplementation,
+        method: "GET",
+        url,
+        operation: "get wallet",
+        headers: {
+          "privy-app-id": appId
+        }
+      });
+    },
+    async getPolicy(policyId) {
+      if (policyId.trim().length === 0) {
+        throw new TxError(
+          "PRIVY_TRANSPORT_FAILED",
+          "Failed to build Privy policy lookup request: policy id is empty"
+        );
+      }
+      const url = `${apiUrl}/v1/policies/${policyId}`;
+      return sendPrivyRequest({
+        fetchImplementation,
+        method: "GET",
+        url,
+        operation: "get policy",
+        headers: {
+          "privy-app-id": appId
+        }
+      });
+    }
+  };
+}
+async function sendPrivyRequest(options) {
+  let response;
+  try {
+    response = await options.fetchImplementation(options.url, {
+      method: options.method,
+      headers: {
+        ...options.headers,
+        ...options.body !== void 0 ? { "content-type": "application/json" } : {}
+      },
+      ...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {}
+    });
+  } catch (cause) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Privy ${options.operation} request failed: network error`,
+      cause
+    );
+  }
+  const payload = await parseJsonResponse(response, options.operation);
+  if (!response.ok) {
+    const message = extractPrivyErrorMessage(payload) ?? `HTTP ${response.status}`;
+    if (response.status === 401 || response.status === 403) {
+      throw new TxError(
+        "PRIVY_AUTH_FAILED",
+        `Privy authentication failed (${response.status}): ${message}`
+      );
+    }
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Privy ${options.operation} request failed (${response.status}): ${message}`
+    );
+  }
+  if (!isRecord(payload)) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Privy ${options.operation} request failed: invalid JSON response shape`
+    );
+  }
+  return payload;
+}
+async function parseJsonResponse(response, operation) {
+  const text = await response.text();
+  if (text.trim().length === 0) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Privy ${operation} request failed: invalid JSON response`,
+      cause
+    );
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function extractPrivyErrorMessage(payload) {
+  if (!isRecord(payload)) {
+    return void 0;
+  }
+  const directMessage = payload.message;
+  if (typeof directMessage === "string" && directMessage.length > 0) {
+    return directMessage;
+  }
+  const errorValue = payload.error;
+  if (typeof errorValue === "string" && errorValue.length > 0) {
+    return errorValue;
+  }
+  if (isRecord(errorValue)) {
+    const nestedMessage = errorValue.message;
+    if (typeof nestedMessage === "string" && nestedMessage.length > 0) {
+      return nestedMessage;
+    }
+  }
+  return void 0;
+}
+
+// src/signers/privy.ts
+import { zeroAddress } from "viem";
+var REQUIRED_FIELDS = [
+  "privyAppId",
+  "privyWalletId",
+  "privyAuthorizationKey"
+];
+var APP_ID_REGEX = /^[A-Za-z0-9_-]{8,128}$/;
+var WALLET_ID_REGEX = /^[A-Za-z0-9_-]{8,128}$/;
+async function createPrivySigner(options) {
+  const missing = REQUIRED_FIELDS.filter((field) => {
+    const value = options[field];
+    return typeof value !== "string" || value.trim().length === 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}`
+    );
+  }
+  const appId = options.privyAppId?.trim() ?? "";
+  const walletId = options.privyWalletId?.trim() ?? "";
+  const authorizationKey = options.privyAuthorizationKey?.trim() ?? "";
+  if (!APP_ID_REGEX.test(appId)) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_APP_ID format: expected 8-128 chars using letters, numbers, hyphen, or underscore"
+    );
+  }
+  if (!WALLET_ID_REGEX.test(walletId)) {
+    throw new TxError(
+      "PRIVY_AUTH_FAILED",
+      "Invalid PRIVY_WALLET_ID format: expected 8-128 chars using letters, numbers, hyphen, or underscore"
+    );
+  }
+  parsePrivyAuthorizationKey(authorizationKey);
+  const apiUrl = normalizePrivyApiUrl(options.privyApiUrl);
+  const client = createPrivyClient({
+    appId,
+    walletId,
+    authorizationKey,
+    apiUrl
+  });
+  const account = {
+    address: zeroAddress,
+    type: "json-rpc"
+  };
+  return {
+    provider: "privy",
+    account,
+    address: account.address,
+    privy: {
+      appId,
+      walletId,
+      apiUrl,
+      client
+    }
+  };
+}
+
+// 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 } : {},
+      ...opts.privyApiUrl !== void 0 ? { privyApiUrl: opts.privyApiUrl } : {}
+    });
+  }
+  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"),
+  "privy-api-url": z.string().optional().describe("Override Privy API base URL (defaults to https://api.privy.io)")
+});
+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"),
+  PRIVY_API_URL: z.string().optional().describe("Optional Privy API base URL override (default https://api.privy.io)")
+});
+function toSignerOptions(flags, env) {
+  const privateKey = flags["private-key"] ?? env.PRIVATE_KEY;
+  const keystorePassword = flags.password ?? env.KEYSTORE_PASSWORD;
+  const privyApiUrl = flags["privy-api-url"] ?? env.PRIVY_API_URL;
+  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 } : {},
+    ...privyApiUrl !== void 0 ? { privyApiUrl } : {}
+  };
+}
 export {
   TxError,
   abstractMainnet,
   createAbstractClient,
   createKeystoreSigner,
   createPrivateKeySigner,
+  createPrivyAuthorizationPayload,
+  createPrivyClient,
+  createPrivySigner,
   executeTx,
+  generatePrivyAuthorizationSignature,
+  normalizePrivyApiUrl,
+  parsePrivyAuthorizationKey,
+  resolveSigner,
+  serializePrivyAuthorizationPayload,
+  signerEnvSchema,
+  signerFlagSchema,
+  toSignerOptions,
   toTxError
 };

package/dist/types.d.ts

@@ -23,6 +23,7 @@ interface SignerOptions {
     privyAppId?: string;
     privyWalletId?: string;
     privyAuthorizationKey?: string;
+    privyApiUrl?: string;
 }
 
 export type { SignerOptions, SignerProvider, TxResult, TxSigner };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/tx-shared",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "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"
   },