@spectratools/tx-shared 0.4.1 → 0.4.3

package/README.md

@@ -56,7 +56,7 @@ 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).
+> Privy signer resolution now performs wallet address lookup and exposes a Privy-backed account helper for `eth_sendTransaction` intents. Additional signing methods (for example `personal_sign` and typed-data) are tracked in [issue #117](https://github.com/spectra-the-bot/spectra-tools/issues/117).
 
 ## `resolveSigner()` usage
 
@@ -185,7 +185,7 @@ try {
   - ensure keystore is valid V3 JSON
 - **`PRIVY_AUTH_FAILED`**
   - verify all `PRIVY_*` variables are set
-  - note: provider is not live yet (see #117)
+  - check signer/owner policy constraints for the Privy wallet
 - **`GAS_ESTIMATION_FAILED` / `TX_REVERTED`**
   - validate function args and `value`
   - run with `dryRun: true` first

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

@@ -4,7 +4,8 @@ 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';
+import { Account, Address, Hex, Hash } from 'viem';
+import { KeyObject } from 'node:crypto';
 
 /**
  * Resolve the active signer provider using deterministic precedence:
@@ -18,6 +19,7 @@ declare const signerFlagSchema: z.ZodObject<{
     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<{
@@ -26,6 +28,7 @@ declare const signerEnvSchema: z.ZodObject<{
     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>;
@@ -57,17 +60,128 @@ interface KeystoreSignerOptions {
  */
 declare function createKeystoreSigner(options: KeystoreSignerOptions): TxSigner;
 
+interface PrivyRpcIntentRequest {
+    method: string;
+    params: Record<string, unknown>;
+    [key: string]: unknown;
+}
+type PrivyIntentStatus = 'pending' | 'executed' | 'failed' | 'expired' | 'rejected' | 'dismissed' | string;
+interface PrivyRpcIntentResponse {
+    intent_id: string;
+    status: PrivyIntentStatus;
+    resource_id?: string;
+    request_details?: Record<string, unknown>;
+    dismissal_reason?: string;
+    action_result?: {
+        response_body?: Record<string, unknown>;
+        [key: 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 PrivyNumberish = bigint | number | string;
+interface PrivySendTransactionRequest {
+    to?: Address;
+    data?: Hex;
+    value?: PrivyNumberish;
+    nonce?: PrivyNumberish;
+    gas?: PrivyNumberish;
+    gasPrice?: PrivyNumberish;
+    maxFeePerGas?: PrivyNumberish;
+    maxPriorityFeePerGas?: PrivyNumberish;
+    chainId?: PrivyNumberish;
+    type?: number;
+}
+type PrivyAccount = Extract<Account, {
+    type: 'json-rpc';
+}> & {
+    sendTransaction: (request: PrivySendTransactionRequest) => Promise<Hash>;
+};
+interface CreatePrivyAccountOptions {
+    client: PrivyClient;
+    chainId?: number;
+}
+declare function createPrivyAccount(options: CreatePrivyAccountOptions): Promise<PrivyAccount>;
+
+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 {
+    account: PrivyAccount;
+    provider: 'privy';
+    privy: {
+        appId: string;
+        walletId: string;
+        apiUrl: string;
+        client: PrivyClient;
+    };
 }
 /**
- * Privy signer adapter entrypoint.
+ * Create a Privy signer envelope with reusable transport and request-signing primitives.
  *
- * Full Privy integration is tracked in issue #117. Until that lands,
- * this adapter provides deterministic, structured failures for callers.
+ * The resolved account is backed by Privy RPC intents and includes a `sendTransaction`
+ * helper that submits `eth_sendTransaction` intents and returns the resulting tx hash.
  */
-declare function createPrivySigner(options: PrivySignerOptions): Promise<TxSigner>;
+declare function createPrivySigner(options: PrivySignerOptions): Promise<PrivySigner>;
 
-export { type KeystoreSignerOptions, type PrivySignerOptions, type SignerEnv, type SignerFlags, SignerOptions, TxSigner, createKeystoreSigner, createPrivateKeySigner, createPrivySigner, resolveSigner, signerEnvSchema, signerFlagSchema, toSignerOptions };
+export { type KeystoreSignerOptions, type PrivyAccount, type PrivyAuthorizationPayload, type PrivyAuthorizationPayloadHeaders, type PrivyClient, type PrivySendTransactionRequest, type PrivySigner, type PrivySignerOptions, type SignerEnv, type SignerFlags, SignerOptions, TxSigner, createKeystoreSigner, createPrivateKeySigner, createPrivyAccount, createPrivyAuthorizationPayload, createPrivyClient, createPrivySigner, generatePrivyAuthorizationSignature, normalizePrivyApiUrl, parsePrivyAuthorizationKey, resolveSigner, serializePrivyAuthorizationPayload, signerEnvSchema, signerFlagSchema, toSignerOptions };

package/dist/index.js

@@ -57,14 +57,545 @@ function createKeystoreSigner(options) {
   return { account, address: account.address, provider: "keystore" };
 }
 
+// src/signers/privy-account.ts
+import { isAddress } from "viem";
+var DEFAULT_CHAIN_ID = 2741;
+var HASH_REGEX = /^0x[a-fA-F0-9]{64}$/;
+async function createPrivyAccount(options) {
+  const wallet = await options.client.getWallet();
+  if (typeof wallet.address !== "string" || !isAddress(wallet.address)) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      "Privy get wallet request failed: wallet address is missing or invalid"
+    );
+  }
+  const address = wallet.address;
+  const defaultChainId = options.chainId ?? DEFAULT_CHAIN_ID;
+  return {
+    address,
+    type: "json-rpc",
+    async sendTransaction(request) {
+      const chainId = normalizeChainId(request.chainId ?? defaultChainId);
+      const rpcRequest = createSendTransactionRpcRequest(address, chainId, request);
+      const response = await options.client.createRpcIntent(rpcRequest);
+      return parsePrivyTransactionHash(response);
+    }
+  };
+}
+function createSendTransactionRpcRequest(from, chainId, request) {
+  const transaction = {
+    from
+  };
+  if (request.to !== void 0) {
+    transaction.to = request.to;
+  }
+  if (request.data !== void 0) {
+    transaction.data = request.data;
+  }
+  if (request.value !== void 0) {
+    transaction.value = normalizeNumberish(request.value, "value");
+  }
+  if (request.nonce !== void 0) {
+    transaction.nonce = normalizeNumberish(request.nonce, "nonce");
+  }
+  if (request.gas !== void 0) {
+    transaction.gas_limit = normalizeNumberish(request.gas, "gas");
+  }
+  if (request.gasPrice !== void 0) {
+    transaction.gas_price = normalizeNumberish(request.gasPrice, "gasPrice");
+  }
+  if (request.maxFeePerGas !== void 0) {
+    transaction.max_fee_per_gas = normalizeNumberish(request.maxFeePerGas, "maxFeePerGas");
+  }
+  if (request.maxPriorityFeePerGas !== void 0) {
+    transaction.max_priority_fee_per_gas = normalizeNumberish(
+      request.maxPriorityFeePerGas,
+      "maxPriorityFeePerGas"
+    );
+  }
+  if (request.type !== void 0) {
+    transaction.type = request.type;
+  }
+  transaction.chain_id = chainId;
+  return {
+    method: "eth_sendTransaction",
+    caip2: `eip155:${chainId}`,
+    params: {
+      transaction
+    }
+  };
+}
+function parsePrivyTransactionHash(response) {
+  const intentId = response.intent_id;
+  if (response.status !== "executed") {
+    const reason = extractIntentReason(response) ?? "no reason provided";
+    if (response.status === "failed") {
+      throw new TxError("TX_REVERTED", `Privy rpc intent ${intentId} failed: ${reason}`);
+    }
+    if (response.status === "rejected" || response.status === "dismissed" || response.status === "expired") {
+      throw new TxError(
+        "PRIVY_AUTH_FAILED",
+        `Privy rpc intent ${intentId} ${response.status}: ${reason}`
+      );
+    }
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Privy rpc intent ${intentId} did not execute (status: ${response.status})`
+    );
+  }
+  const hash = extractIntentHash(response);
+  if (hash === void 0 || !HASH_REGEX.test(hash)) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Privy rpc intent ${intentId} executed without a valid transaction hash`
+    );
+  }
+  return hash;
+}
+function extractIntentHash(response) {
+  if (!isRecord(response.action_result)) {
+    return void 0;
+  }
+  const responseBody = response.action_result.response_body;
+  if (!isRecord(responseBody)) {
+    return void 0;
+  }
+  const data = responseBody.data;
+  if (!isRecord(data)) {
+    return void 0;
+  }
+  return typeof data.hash === "string" ? data.hash : void 0;
+}
+function extractIntentReason(response) {
+  if (typeof response.dismissal_reason === "string" && response.dismissal_reason.length > 0) {
+    return response.dismissal_reason;
+  }
+  if (isRecord(response.action_result)) {
+    const responseBody = response.action_result.response_body;
+    if (isRecord(responseBody)) {
+      const error = responseBody.error;
+      if (typeof error === "string" && error.length > 0) {
+        return error;
+      }
+      if (isRecord(error)) {
+        const errorMessage = error.message;
+        if (typeof errorMessage === "string" && errorMessage.length > 0) {
+          return errorMessage;
+        }
+      }
+      const message = responseBody.message;
+      if (typeof message === "string" && message.length > 0) {
+        return message;
+      }
+    }
+  }
+  return void 0;
+}
+function normalizeChainId(chainId) {
+  if (typeof chainId === "number") {
+    if (!Number.isInteger(chainId) || chainId <= 0) {
+      throw new TxError(
+        "PRIVY_TRANSPORT_FAILED",
+        "Failed to build Privy eth_sendTransaction payload: chainId must be a positive integer"
+      );
+    }
+    return chainId;
+  }
+  if (typeof chainId === "bigint") {
+    if (chainId <= 0n || chainId > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new TxError(
+        "PRIVY_TRANSPORT_FAILED",
+        "Failed to build Privy eth_sendTransaction payload: chainId must be a positive safe integer"
+      );
+    }
+    return Number(chainId);
+  }
+  const trimmed = chainId.trim();
+  if (trimmed.length === 0) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      "Failed to build Privy eth_sendTransaction payload: chainId is empty"
+    );
+  }
+  if (/^0x[0-9a-fA-F]+$/.test(trimmed)) {
+    const parsed2 = Number.parseInt(trimmed.slice(2), 16);
+    if (!Number.isSafeInteger(parsed2) || parsed2 <= 0) {
+      throw new TxError(
+        "PRIVY_TRANSPORT_FAILED",
+        "Failed to build Privy eth_sendTransaction payload: chainId must be a positive safe integer"
+      );
+    }
+    return parsed2;
+  }
+  if (!/^[0-9]+$/.test(trimmed)) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      "Failed to build Privy eth_sendTransaction payload: chainId must be a positive safe integer"
+    );
+  }
+  const parsed = Number(trimmed);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      "Failed to build Privy eth_sendTransaction payload: chainId must be a positive safe integer"
+    );
+  }
+  return parsed;
+}
+function normalizeNumberish(value, fieldName) {
+  if (typeof value === "bigint") {
+    if (value < 0n) {
+      throw new TxError(
+        "PRIVY_TRANSPORT_FAILED",
+        `Failed to build Privy eth_sendTransaction payload: ${fieldName} cannot be negative`
+      );
+    }
+    return value.toString(10);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new TxError(
+        "PRIVY_TRANSPORT_FAILED",
+        `Failed to build Privy eth_sendTransaction payload: ${fieldName} must be a non-negative number`
+      );
+    }
+    return Number.isInteger(value) ? value : value.toString();
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Failed to build Privy eth_sendTransaction payload: ${fieldName} is empty`
+    );
+  }
+  return trimmed;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// 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 (!isRecord2(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 isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function extractPrivyErrorMessage(payload) {
+  if (!isRecord2(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 (isRecord2(errorValue)) {
+    const nestedMessage = errorValue.message;
+    if (typeof nestedMessage === "string" && nestedMessage.length > 0) {
+      return nestedMessage;
+    }
+  }
+  return void 0;
+}
+
 // src/signers/privy.ts
 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) => options[field] === void 0);
+  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") {
@@ -80,10 +611,43 @@ async function createPrivySigner(options) {
       `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."
-  );
+  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 = await createPrivyAccount({
+    client
+  });
+  return {
+    provider: "privy",
+    account,
+    address: account.address,
+    privy: {
+      appId,
+      walletId,
+      apiUrl,
+      client
+    }
+  };
 }
 
 // src/resolve-signer.ts
@@ -110,7 +674,8 @@ async function resolveSigner(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.privyAuthorizationKey !== void 0 ? { privyAuthorizationKey: opts.privyAuthorizationKey } : {},
+      ...opts.privyApiUrl !== void 0 ? { privyApiUrl: opts.privyApiUrl } : {}
     });
   }
   throw new TxError(
@@ -125,18 +690,21 @@ 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: 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_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 } : {},
@@ -144,7 +712,8 @@ function toSignerOptions(flags, env) {
     ...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 } : {}
+    ...env.PRIVY_AUTHORIZATION_KEY !== void 0 ? { privyAuthorizationKey: env.PRIVY_AUTHORIZATION_KEY } : {},
+    ...privyApiUrl !== void 0 ? { privyApiUrl } : {}
   };
 }
 export {
@@ -153,9 +722,16 @@ export {
   createAbstractClient,
   createKeystoreSigner,
   createPrivateKeySigner,
+  createPrivyAccount,
+  createPrivyAuthorizationPayload,
+  createPrivyClient,
   createPrivySigner,
   executeTx,
+  generatePrivyAuthorizationSignature,
+  normalizePrivyApiUrl,
+  parsePrivyAuthorizationKey,
   resolveSigner,
+  serializePrivyAuthorizationPayload,
   signerEnvSchema,
   signerFlagSchema,
   toSignerOptions,

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.4.1",
+  "version": "0.4.3",
   "description": "Shared transaction primitives, signer types, and chain config for spectra tools",
   "type": "module",
   "license": "MIT",