@spectratools/tx-shared 0.4.2 → 0.5.1

package/dist/chunk-HFRJBEDT.js

@@ -0,0 +1,1144 @@
+import {
+  TxError
+} from "./chunk-6T4D5UCR.js";
+
+// src/signers/privy-client.ts
+import { isAddress } from "viem";
+
+// 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
+        }
+      });
+    }
+  };
+}
+var ALLOWLIST_KEYS = /* @__PURE__ */ new Set([
+  "allowedcontracts",
+  "allowlistedcontracts",
+  "contractallowlist",
+  "toallowlist",
+  "allowedtoaddresses"
+]);
+var MAX_VALUE_KEYS = /* @__PURE__ */ new Set([
+  "maxvalue",
+  "maxvaluewei",
+  "maxnativevalue",
+  "maxnativevaluewei",
+  "maxtransferamount",
+  "maxtransferamountwei",
+  "valuecap",
+  "valuecapwei"
+]);
+function normalizePrivyPolicy(policy) {
+  const constraints = extractConstraintsFromValue(policy.rules);
+  const allowlistedContracts = Array.from(constraints.allowlistedContracts).sort((left, right) => left.localeCompare(right)).map((value) => value);
+  const maxValueWei = selectLowestValue(constraints.maxValueWeiCandidates);
+  return {
+    id: policy.id,
+    ownerId: policy.owner_id,
+    ruleCount: Array.isArray(policy.rules) ? policy.rules.length : 0,
+    allowlistedContracts,
+    ...maxValueWei !== void 0 ? { maxValueWei } : {}
+  };
+}
+async function fetchPrivyPolicyVisibility(client) {
+  const wallet = await client.getWallet();
+  const policyIds = normalizePolicyIds(wallet.policy_ids);
+  const policies = [];
+  for (const policyId of policyIds) {
+    const policy = await client.getPolicy(policyId);
+    policies.push(normalizePrivyPolicy(policy));
+  }
+  const contractAllowlistSet = /* @__PURE__ */ new Set();
+  const maxValueCandidates = [];
+  for (const policy of policies) {
+    for (const contractAddress of policy.allowlistedContracts) {
+      contractAllowlistSet.add(contractAddress.toLowerCase());
+    }
+    if (policy.maxValueWei !== void 0) {
+      maxValueCandidates.push(policy.maxValueWei);
+    }
+  }
+  const contractAllowlist = Array.from(contractAllowlistSet).sort((left, right) => left.localeCompare(right)).map((value) => value);
+  const maxValueWei = selectLowestValue(maxValueCandidates);
+  return {
+    walletId: wallet.id,
+    policyIds,
+    policies,
+    contractAllowlist,
+    ...maxValueWei !== void 0 ? { maxValueWei } : {}
+  };
+}
+async function preflightPrivyTransactionPolicy(client, request) {
+  const visibility = await fetchPrivyPolicyVisibility(client);
+  const violations = [];
+  if (request.to !== void 0 && visibility.contractAllowlist.length > 0) {
+    const toAddress = request.to.toLowerCase();
+    const isAllowed = visibility.contractAllowlist.some(
+      (allowedContract) => allowedContract.toLowerCase() === toAddress
+    );
+    if (!isAllowed) {
+      const constrainedPolicyIds = visibility.policies.filter((policy) => policy.allowlistedContracts.length > 0).map((policy) => policy.id).sort((left, right) => left.localeCompare(right));
+      violations.push({
+        type: "contract-allowlist",
+        message: `Target contract ${request.to} is not allowlisted by active Privy policies`,
+        policyIds: constrainedPolicyIds,
+        actual: request.to,
+        expected: visibility.contractAllowlist.join(", ")
+      });
+    }
+  }
+  if (request.value !== void 0 && visibility.maxValueWei !== void 0) {
+    if (request.value > visibility.maxValueWei) {
+      const constrainedPolicyIds = visibility.policies.filter((policy) => policy.maxValueWei === visibility.maxValueWei).map((policy) => policy.id).sort((left, right) => left.localeCompare(right));
+      violations.push({
+        type: "native-value-cap",
+        message: `Native value ${request.value.toString()} exceeds Privy policy max ${visibility.maxValueWei.toString()}`,
+        policyIds: constrainedPolicyIds,
+        actual: request.value.toString(),
+        expected: visibility.maxValueWei.toString()
+      });
+    }
+  }
+  return {
+    status: violations.length > 0 ? "blocked" : "allowed",
+    visibility,
+    violations
+  };
+}
+function toPrivyPolicyViolationError(result) {
+  const message = result.violations.length > 0 ? result.violations.map((violation) => {
+    const policies = violation.policyIds.length > 0 ? ` (policies: ${violation.policyIds.join(", ")})` : "";
+    return `${violation.message}${policies}`;
+  }).join("; ") : "Privy policy preflight blocked transaction";
+  return new TxError(
+    "PRIVY_POLICY_BLOCKED",
+    `Privy policy preflight blocked transaction: ${message}`
+  );
+}
+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 extractConstraintsFromValue(value) {
+  const constraints = {
+    allowlistedContracts: /* @__PURE__ */ new Set(),
+    maxValueWeiCandidates: []
+  };
+  visitConstraintNode(value, constraints);
+  return constraints;
+}
+function visitConstraintNode(value, constraints) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      visitConstraintNode(item, constraints);
+    }
+    return;
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    const normalizedKey = normalizeConstraintKey(key);
+    if (ALLOWLIST_KEYS.has(normalizedKey)) {
+      for (const address of parseAddressList(entry)) {
+        constraints.allowlistedContracts.add(address.toLowerCase());
+      }
+    }
+    if (MAX_VALUE_KEYS.has(normalizedKey)) {
+      const parsedValue = parseWeiValue(entry);
+      if (parsedValue !== void 0) {
+        constraints.maxValueWeiCandidates.push(parsedValue);
+      }
+    }
+    visitConstraintNode(entry, constraints);
+  }
+}
+function normalizeConstraintKey(value) {
+  return value.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+}
+function parseAddressList(value) {
+  const entries = Array.isArray(value) ? value : [value];
+  const addresses = [];
+  for (const entry of entries) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+    if (!isAddress(entry)) {
+      continue;
+    }
+    addresses.push(entry);
+  }
+  return addresses;
+}
+function parseWeiValue(value) {
+  if (typeof value === "bigint") {
+    return value >= 0n ? value : void 0;
+  }
+  if (typeof value === "number") {
+    if (!Number.isInteger(value) || value < 0) {
+      return void 0;
+    }
+    return BigInt(value);
+  }
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return void 0;
+  }
+  try {
+    if (/^0x[0-9a-fA-F]+$/.test(trimmed)) {
+      return BigInt(trimmed);
+    }
+    if (/^[0-9]+$/.test(trimmed)) {
+      return BigInt(trimmed);
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function selectLowestValue(values) {
+  if (values.length === 0) {
+    return void 0;
+  }
+  let minimum = values[0];
+  for (const value of values.slice(1)) {
+    if (value < minimum) {
+      minimum = value;
+    }
+  }
+  return minimum;
+}
+function normalizePolicyIds(policyIds) {
+  if (!Array.isArray(policyIds)) {
+    return [];
+  }
+  const ids = /* @__PURE__ */ new Set();
+  for (const entry of policyIds) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+    const normalized = entry.trim();
+    if (normalized.length === 0) {
+      continue;
+    }
+    ids.add(normalized);
+  }
+  return Array.from(ids).sort((left, right) => left.localeCompare(right));
+}
+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-account.ts
+import {
+  isAddress as isAddress2,
+  toHex
+} from "viem";
+var DEFAULT_CHAIN_ID = 2741;
+var HASH_REGEX = /^0x[a-fA-F0-9]{64}$/;
+var HEX_REGEX = /^0x(?:[a-fA-F0-9]{2})+$/;
+async function createPrivyAccount(options) {
+  const wallet = await options.client.getWallet();
+  if (typeof wallet.address !== "string" || !isAddress2(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);
+    },
+    async signMessage({ message }) {
+      const rpcRequest = createPersonalSignRpcRequest(message);
+      const response = await options.client.createRpcIntent(rpcRequest);
+      return parsePrivySignature(response, "personal_sign");
+    },
+    async signTypedData(parameters) {
+      const rpcRequest = createSignTypedDataRpcRequest(parameters);
+      const response = await options.client.createRpcIntent(rpcRequest);
+      return parsePrivySignature(response, "eth_signTypedData_v4");
+    },
+    async signTransaction(transaction) {
+      const request = transaction;
+      const chainId = normalizeChainId(request.chainId ?? defaultChainId);
+      const rpcRequest = createSignTransactionRpcRequest(address, chainId, request);
+      const response = await options.client.createRpcIntent(rpcRequest);
+      return parsePrivySignedTransaction(response);
+    }
+  };
+}
+function createSendTransactionRpcRequest(from, chainId, request) {
+  const transaction = createPrivyTransactionPayload(from, chainId, request, "eth_sendTransaction");
+  return {
+    method: "eth_sendTransaction",
+    caip2: `eip155:${chainId}`,
+    params: {
+      transaction
+    }
+  };
+}
+function createSignTransactionRpcRequest(from, chainId, request) {
+  const transaction = createPrivyTransactionPayload(from, chainId, request, "eth_signTransaction");
+  return {
+    method: "eth_signTransaction",
+    params: {
+      transaction
+    }
+  };
+}
+function createPersonalSignRpcRequest(message) {
+  if (typeof message === "string") {
+    return {
+      method: "personal_sign",
+      params: {
+        message,
+        encoding: "utf-8"
+      }
+    };
+  }
+  const raw = message.raw;
+  const encodedMessage = raw instanceof Uint8Array ? toHex(raw) : raw;
+  if (!isHexString(encodedMessage)) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      "Failed to build Privy personal_sign payload: message.raw must be a hex string or Uint8Array"
+    );
+  }
+  return {
+    method: "personal_sign",
+    params: {
+      message: encodedMessage,
+      encoding: "hex"
+    }
+  };
+}
+function createSignTypedDataRpcRequest(parameters) {
+  const primaryType = parameters.primaryType;
+  if (typeof primaryType !== "string" || primaryType.trim().length === 0) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      "Failed to build Privy eth_signTypedData_v4 payload: primaryType is required"
+    );
+  }
+  return {
+    method: "eth_signTypedData_v4",
+    params: {
+      typed_data: {
+        domain: normalizeJsonValue(parameters.domain ?? {}),
+        types: normalizeJsonValue(parameters.types),
+        message: normalizeJsonValue(parameters.message),
+        primary_type: primaryType
+      }
+    }
+  };
+}
+function createPrivyTransactionPayload(from, chainId, request, rpcMethod) {
+  if (request.from !== void 0 && request.from.toLowerCase() !== from.toLowerCase()) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Failed to build Privy ${rpcMethod} payload: from does not match wallet address`
+    );
+  }
+  const transaction = {
+    from,
+    chain_id: chainId
+  };
+  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, rpcMethod, "value");
+  }
+  if (request.nonce !== void 0) {
+    transaction.nonce = normalizeNumberish(request.nonce, rpcMethod, "nonce");
+  }
+  if (request.gas !== void 0) {
+    transaction.gas_limit = normalizeNumberish(request.gas, rpcMethod, "gas");
+  }
+  if (request.gasPrice !== void 0) {
+    transaction.gas_price = normalizeNumberish(request.gasPrice, rpcMethod, "gasPrice");
+  }
+  if (request.maxFeePerGas !== void 0) {
+    transaction.max_fee_per_gas = normalizeNumberish(
+      request.maxFeePerGas,
+      rpcMethod,
+      "maxFeePerGas"
+    );
+  }
+  if (request.maxPriorityFeePerGas !== void 0) {
+    transaction.max_priority_fee_per_gas = normalizeNumberish(
+      request.maxPriorityFeePerGas,
+      rpcMethod,
+      "maxPriorityFeePerGas"
+    );
+  }
+  if (request.type !== void 0) {
+    transaction.type = request.type;
+  }
+  return transaction;
+}
+function parsePrivyTransactionHash(response) {
+  assertIntentExecuted(response, "eth_sendTransaction");
+  const hash = extractDataString(response, "hash");
+  if (hash === void 0 || !HASH_REGEX.test(hash)) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Privy rpc intent ${response.intent_id} executed without a valid transaction hash`
+    );
+  }
+  return hash;
+}
+function parsePrivySignature(response, method) {
+  assertIntentExecuted(response, method);
+  const signature = extractDataString(response, "signature");
+  if (signature === void 0 || !isHexString(signature)) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Privy rpc intent ${response.intent_id} executed without a valid signature`
+    );
+  }
+  return signature;
+}
+function parsePrivySignedTransaction(response) {
+  assertIntentExecuted(response, "eth_signTransaction");
+  const signedTransaction = extractDataString(response, "signed_transaction");
+  if (signedTransaction === void 0 || !isHexString(signedTransaction)) {
+    throw new TxError(
+      "PRIVY_TRANSPORT_FAILED",
+      `Privy rpc intent ${response.intent_id} executed without a valid signed transaction`
+    );
+  }
+  return signedTransaction;
+}
+function assertIntentExecuted(response, rpcMethod) {
+  const intentId = response.intent_id;
+  if (response.status === "executed") {
+    return;
+  }
+  const reason = extractIntentReason(response) ?? "no reason provided";
+  if (response.status === "failed") {
+    if (rpcMethod === "eth_sendTransaction") {
+      throw new TxError("TX_REVERTED", `Privy rpc intent ${intentId} failed: ${reason}`);
+    }
+    throw new TxError("PRIVY_TRANSPORT_FAILED", `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})`
+  );
+}
+function extractDataString(response, key) {
+  if (!isRecord2(response.action_result)) {
+    return void 0;
+  }
+  const responseBody = response.action_result.response_body;
+  if (!isRecord2(responseBody)) {
+    return void 0;
+  }
+  const data = responseBody.data;
+  if (!isRecord2(data)) {
+    return void 0;
+  }
+  const value = data[key];
+  return typeof value === "string" ? value : void 0;
+}
+function extractIntentReason(response) {
+  if (typeof response.dismissal_reason === "string" && response.dismissal_reason.length > 0) {
+    return response.dismissal_reason;
+  }
+  if (isRecord2(response.action_result)) {
+    const responseBody = response.action_result.response_body;
+    if (isRecord2(responseBody)) {
+      const error = responseBody.error;
+      if (typeof error === "string" && error.length > 0) {
+        return error;
+      }
+      if (isRecord2(error)) {
+        const errorMessage2 = error.message;
+        if (typeof errorMessage2 === "string" && errorMessage2.length > 0) {
+          return errorMessage2;
+        }
+      }
+      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 chain 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 chain 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 chain 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 chain 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 chain 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 chain payload: chainId must be a positive safe integer"
+    );
+  }
+  return parsed;
+}
+function normalizeNumberish(value, rpcMethod, fieldName) {
+  if (typeof value === "bigint") {
+    if (value < 0n) {
+      throw new TxError(
+        "PRIVY_TRANSPORT_FAILED",
+        `Failed to build Privy ${rpcMethod} 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 ${rpcMethod} 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 ${rpcMethod} payload: ${fieldName} is empty`
+    );
+  }
+  return trimmed;
+}
+function normalizeJsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "bigint") {
+    return value.toString(10);
+  }
+  if (value instanceof Uint8Array) {
+    return toHex(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeJsonValue(item));
+  }
+  if (isRecord2(value)) {
+    const normalized = {};
+    for (const [key, entry] of Object.entries(value)) {
+      if (entry === void 0) {
+        continue;
+      }
+      normalized[key] = normalizeJsonValue(entry);
+    }
+    return normalized;
+  }
+  throw new TxError(
+    "PRIVY_TRANSPORT_FAILED",
+    "Failed to build Privy typed data payload: unsupported value type"
+  );
+}
+function isHexString(value) {
+  return HEX_REGEX.test(value);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// 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}$/;
+var PRIVY_POLICY_CONTEXT_SYMBOL = /* @__PURE__ */ Symbol.for("spectratools.tx-shared.privy.policy-context");
+function attachPrivyPolicyContext(account, context) {
+  Object.defineProperty(account, PRIVY_POLICY_CONTEXT_SYMBOL, {
+    value: context,
+    configurable: false,
+    enumerable: false,
+    writable: false
+  });
+  return account;
+}
+function getPrivyPolicyContext(account) {
+  if (typeof account !== "object" || account === null) {
+    return void 0;
+  }
+  const withContext = account;
+  return withContext[PRIVY_POLICY_CONTEXT_SYMBOL];
+}
+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 = attachPrivyPolicyContext(await createPrivyAccount({ client }), {
+    appId,
+    walletId,
+    apiUrl,
+    client
+  });
+  return {
+    provider: "privy",
+    account,
+    address: account.address,
+    privy: {
+      appId,
+      walletId,
+      apiUrl,
+      client
+    }
+  };
+}
+
+// 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");
+  }
+  const privyPolicy = await runPrivyPolicyPreflight({
+    account,
+    address,
+    ...value !== void 0 ? { value } : {}
+  });
+  if (dryRun) {
+    return {
+      status: "dry-run",
+      estimatedGas,
+      simulationResult,
+      ...privyPolicy !== void 0 ? { privyPolicy } : {}
+    };
+  }
+  if (privyPolicy?.status === "blocked") {
+    throw toPrivyPolicyViolationError(privyPolicy);
+  }
+  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
+  };
+}
+async function runPrivyPolicyPreflight(request) {
+  const context = getPrivyPolicyContext(request.account);
+  if (context === void 0) {
+    return void 0;
+  }
+  return preflightPrivyTransactionPolicy(context.client, {
+    to: request.address,
+    ...request.value !== void 0 ? { value: request.value } : {}
+  });
+}
+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 {
+  normalizePrivyApiUrl,
+  parsePrivyAuthorizationKey,
+  createPrivyAuthorizationPayload,
+  serializePrivyAuthorizationPayload,
+  generatePrivyAuthorizationSignature,
+  createPrivyClient,
+  normalizePrivyPolicy,
+  fetchPrivyPolicyVisibility,
+  preflightPrivyTransactionPolicy,
+  toPrivyPolicyViolationError,
+  createPrivyAccount,
+  attachPrivyPolicyContext,
+  getPrivyPolicyContext,
+  createPrivySigner,
+  executeTx
+};