@spectratools/tx-shared 0.4.2 → 0.5.1

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' | 'PRIVY_TRANSPORT_FAILED';
+type TxErrorCode = 'INSUFFICIENT_FUNDS' | 'NONCE_CONFLICT' | 'TX_REVERTED' | 'GAS_ESTIMATION_FAILED' | 'SIGNER_NOT_CONFIGURED' | 'KEYSTORE_DECRYPT_FAILED' | 'PRIVY_AUTH_FAILED' | 'PRIVY_TRANSPORT_FAILED' | 'PRIVY_POLICY_BLOCKED';
 declare class TxError extends Error {
     readonly code: TxErrorCode;
     constructor(code: TxErrorCode, message: string, cause?: unknown);

package/dist/execute-tx-DO8p_9dP.d.ts

@@ -0,0 +1,160 @@
+import { Address, PublicClient, WalletClient, Account, Abi, Chain } from 'viem';
+import { TxError } from './errors.js';
+import { TxResult } from './types.js';
+
+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 PrivyNormalizedPolicy {
+    id: string;
+    ownerId: string | null;
+    ruleCount: number;
+    allowlistedContracts: Address[];
+    maxValueWei?: bigint;
+}
+interface PrivyPolicyVisibility {
+    walletId: string;
+    policyIds: string[];
+    policies: PrivyNormalizedPolicy[];
+    contractAllowlist: Address[];
+    maxValueWei?: bigint;
+}
+type PrivyPolicyViolationType = 'contract-allowlist' | 'native-value-cap';
+interface PrivyPolicyViolation {
+    type: PrivyPolicyViolationType;
+    message: string;
+    policyIds: string[];
+    actual: string;
+    expected: string;
+}
+interface PrivyPolicyPreflightRequest {
+    to?: Address;
+    value?: bigint;
+}
+interface PrivyPolicyPreflightResult {
+    status: 'allowed' | 'blocked';
+    visibility: PrivyPolicyVisibility;
+    violations: PrivyPolicyViolation[];
+}
+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;
+/** Normalize a raw Privy policy object into tx-shared's policy model. */
+declare function normalizePrivyPolicy(policy: PrivyPolicyResponse): PrivyNormalizedPolicy;
+/** Fetch wallet policies and return normalized visibility data for callers. */
+declare function fetchPrivyPolicyVisibility(client: PrivyClient): Promise<PrivyPolicyVisibility>;
+/**
+ * Evaluate immediately-deterministic Privy constraints (contract allowlists + native value caps).
+ */
+declare function preflightPrivyTransactionPolicy(client: PrivyClient, request: PrivyPolicyPreflightRequest): Promise<PrivyPolicyPreflightResult>;
+/** Convert blocked preflight output into a deterministic structured TxError. */
+declare function toPrivyPolicyViolationError(result: PrivyPolicyPreflightResult): TxError;
+
+/** Options for the {@link executeTx} lifecycle. */
+interface ExecuteTxOptions {
+    /** Viem public client used for gas estimation, simulation, and receipt retrieval. */
+    publicClient: PublicClient;
+    /** Viem wallet client used to submit the transaction. */
+    walletClient: WalletClient;
+    /** Signer account. */
+    account: Account;
+    /** Target contract address. */
+    address: Address;
+    /** Contract ABI (must include the target function). */
+    abi: Abi;
+    /** Name of the contract function to call. */
+    functionName: string;
+    /** Optional chain to use for the transaction. */
+    chain?: Chain;
+    /** Arguments passed to the contract function. */
+    args?: unknown[];
+    /** Native value (in wei) to send with the transaction. */
+    value?: bigint;
+    /** Gas limit override. When provided the estimate is still performed but this value is used for submission. */
+    gasLimit?: bigint;
+    /** Max fee per gas override (EIP-1559). */
+    maxFeePerGas?: bigint;
+    /** Nonce override. */
+    nonce?: number;
+    /**
+     * When `true` the transaction is simulated but **not** broadcast.
+     * Returns a {@link DryRunResult} instead of a {@link TxResult}.
+     */
+    dryRun?: boolean;
+}
+/** Result returned when `dryRun` is `true`. */
+interface DryRunResult {
+    /** Discriminator — always `'dry-run'` for dry-run results. */
+    status: 'dry-run';
+    /** Estimated gas units for the call. */
+    estimatedGas: bigint;
+    /** Simulated return value from `simulateContract`. */
+    simulationResult: unknown;
+    /** Optional Privy policy visibility for Privy-backed accounts. */
+    privyPolicy?: PrivyPolicyPreflightResult;
+}
+/**
+ * Execute a full transaction lifecycle:
+ *
+ * 1. **Estimate** gas via `publicClient.estimateContractGas`.
+ * 2. **Simulate** contract call via `publicClient.simulateContract`.
+ * 3. **Preflight** Privy policies when a Privy-backed account is used.
+ *    - If `dryRun` is `true`, return a {@link DryRunResult} without broadcasting.
+ * 4. **Submit** the transaction via `walletClient.writeContract`.
+ * 5. **Wait** for the receipt via `publicClient.waitForTransactionReceipt`.
+ * 6. **Normalize** the receipt into a {@link TxResult}.
+ *
+ * Errors thrown by viem are mapped to structured {@link TxError} codes:
+ * - `INSUFFICIENT_FUNDS` — sender lacks balance for value + gas.
+ * - `NONCE_CONFLICT` — nonce already used or too low.
+ * - `GAS_ESTIMATION_FAILED` — gas estimation or simulation reverted.
+ * - `TX_REVERTED` — on-chain revert (includes reason when available).
+ * - `PRIVY_POLICY_BLOCKED` — Privy policy preflight determined the tx is not allowed.
+ */
+declare function executeTx(options: ExecuteTxOptions): Promise<TxResult | DryRunResult>;
+
+export { type DryRunResult as D, type ExecuteTxOptions as E, type PrivyClient as P, type PrivyNormalizedPolicy as a, type PrivyPolicyPreflightRequest as b, type PrivyPolicyPreflightResult as c, type PrivyPolicyViolation as d, type PrivyPolicyVisibility as e, createPrivyClient as f, executeTx as g, fetchPrivyPolicyVisibility as h, normalizePrivyPolicy as n, preflightPrivyTransactionPolicy as p, toPrivyPolicyViolationError as t };

package/dist/execute-tx.d.ts

@@ -1,63 +1,4 @@
-import { PublicClient, WalletClient, Account, Address, Abi, Chain } from 'viem';
-import { TxResult } from './types.js';
-
-/** Options for the {@link executeTx} lifecycle. */
-interface ExecuteTxOptions {
-    /** Viem public client used for gas estimation, simulation, and receipt retrieval. */
-    publicClient: PublicClient;
-    /** Viem wallet client used to submit the transaction. */
-    walletClient: WalletClient;
-    /** Signer account. */
-    account: Account;
-    /** Target contract address. */
-    address: Address;
-    /** Contract ABI (must include the target function). */
-    abi: Abi;
-    /** Name of the contract function to call. */
-    functionName: string;
-    /** Optional chain to use for the transaction. */
-    chain?: Chain;
-    /** Arguments passed to the contract function. */
-    args?: unknown[];
-    /** Native value (in wei) to send with the transaction. */
-    value?: bigint;
-    /** Gas limit override. When provided the estimate is still performed but this value is used for submission. */
-    gasLimit?: bigint;
-    /** Max fee per gas override (EIP-1559). */
-    maxFeePerGas?: bigint;
-    /** Nonce override. */
-    nonce?: number;
-    /**
-     * When `true` the transaction is simulated but **not** broadcast.
-     * Returns a {@link DryRunResult} instead of a {@link TxResult}.
-     */
-    dryRun?: boolean;
-}
-/** Result returned when `dryRun` is `true`. */
-interface DryRunResult {
-    /** Discriminator — always `'dry-run'` for dry-run results. */
-    status: 'dry-run';
-    /** Estimated gas units for the call. */
-    estimatedGas: bigint;
-    /** Simulated return value from `simulateContract`. */
-    simulationResult: unknown;
-}
-/**
- * Execute a full transaction lifecycle:
- *
- * 1. **Estimate** gas via `publicClient.estimateContractGas`.
- * 2. **Simulate** contract call via `publicClient.simulateContract`.
- *    - If `dryRun` is `true`, return a {@link DryRunResult} without broadcasting.
- * 3. **Submit** the transaction via `walletClient.writeContract`.
- * 4. **Wait** for the receipt via `publicClient.waitForTransactionReceipt`.
- * 5. **Normalize** the receipt into a {@link TxResult}.
- *
- * Errors thrown by viem are mapped to structured {@link TxError} codes:
- * - `INSUFFICIENT_FUNDS` — sender lacks balance for value + gas.
- * - `NONCE_CONFLICT` — nonce already used or too low.
- * - `GAS_ESTIMATION_FAILED` — gas estimation or simulation reverted.
- * - `TX_REVERTED` — on-chain revert (includes reason when available).
- */
-declare function executeTx(options: ExecuteTxOptions): Promise<TxResult | DryRunResult>;
-
-export { type DryRunResult, type ExecuteTxOptions, executeTx };
+import 'viem';
+export { D as DryRunResult, E as ExecuteTxOptions, g as executeTx } from './execute-tx-DO8p_9dP.js';
+import './types.js';
+import './errors.js';

package/dist/execute-tx.js

@@ -1,6 +1,6 @@
 import {
   executeTx
-} from "./chunk-4XI6TBKX.js";
+} from "./chunk-HFRJBEDT.js";
 import "./chunk-6T4D5UCR.js";
 export {
   executeTx

package/dist/index.d.ts

@@ -2,10 +2,11 @@ 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 { P as PrivyClient } from './execute-tx-DO8p_9dP.js';
+export { D as DryRunResult, E as ExecuteTxOptions, a as PrivyNormalizedPolicy, b as PrivyPolicyPreflightRequest, c as PrivyPolicyPreflightResult, d as PrivyPolicyViolation, e as PrivyPolicyVisibility, f as createPrivyClient, g as executeTx, h as fetchPrivyPolicyVisibility, n as normalizePrivyPolicy, p as preflightPrivyTransactionPolicy, t as toPrivyPolicyViolationError } from './execute-tx-DO8p_9dP.js';
 import { z } from 'incur';
+import { Address, Hex, Hash, SignableMessage, TypedData, TypedDataDefinition, SerializeTransactionFn, TransactionSerializable } from 'viem';
 import { KeyObject } from 'node:crypto';
-import 'viem';
 
 /**
  * Resolve the active signer provider using deterministic precedence:
@@ -60,50 +61,39 @@ interface KeystoreSignerOptions {
  */
 declare function createKeystoreSigner(options: KeystoreSignerOptions): TxSigner;
 
-interface PrivyRpcIntentRequest {
-    method: string;
-    params: Record<string, unknown>;
-    [key: string]: unknown;
+type PrivyNumberish = bigint | number | string;
+interface PrivySendTransactionRequest {
+    from?: Address;
+    to?: Address;
+    data?: Hex;
+    value?: PrivyNumberish;
+    nonce?: PrivyNumberish;
+    gas?: PrivyNumberish;
+    gasPrice?: PrivyNumberish;
+    maxFeePerGas?: PrivyNumberish;
+    maxPriorityFeePerGas?: PrivyNumberish;
+    chainId?: PrivyNumberish;
+    type?: number;
 }
-interface PrivyRpcIntentResponse {
-    intent_id: string;
-    status: string;
-    resource_id?: string;
-    request_details?: Record<string, unknown>;
-    [key: string]: unknown;
+type PrivySignTransactionRequest = PrivySendTransactionRequest;
+type PrivySignTypedDataRequest<typedData extends TypedData | Record<string, unknown> = TypedData, primaryType extends keyof typedData | 'EIP712Domain' = keyof typedData> = TypedDataDefinition<typedData, primaryType>;
+interface PrivyAccount {
+    address: Address;
+    type: 'json-rpc';
+    sendTransaction: (request: PrivySendTransactionRequest) => Promise<Hash>;
+    signMessage: ({ message }: {
+        message: SignableMessage;
+    }) => Promise<Hex>;
+    signTypedData: <const typedData extends TypedData | Record<string, unknown>, primaryType extends keyof typedData | 'EIP712Domain' = keyof typedData>(parameters: PrivySignTypedDataRequest<typedData, primaryType>) => Promise<Hex>;
+    signTransaction: <serializer extends SerializeTransactionFn<TransactionSerializable> = SerializeTransactionFn<TransactionSerializable>, transaction extends Parameters<serializer>[0] = Parameters<serializer>[0]>(transaction: transaction, options?: {
+        serializer?: serializer;
+    }) => Promise<Hex>;
 }
-interface PrivyWalletResponse {
-    id: string;
-    address: string;
-    owner_id: string | null;
-    policy_ids: string[];
-    [key: string]: unknown;
+interface CreatePrivyAccountOptions {
+    client: PrivyClient;
+    chainId?: number;
 }
-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;
+declare function createPrivyAccount(options: CreatePrivyAccountOptions): Promise<PrivyAccount>;
 
 type PrivyAuthorizationMethod = 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 interface PrivyAuthorizationPayloadHeaders {
@@ -136,7 +126,15 @@ interface PrivySignerOptions {
     privyAuthorizationKey?: string;
     privyApiUrl?: string;
 }
-interface PrivySigner extends TxSigner {
+interface PrivyPolicyContext {
+    appId: string;
+    walletId: string;
+    apiUrl: string;
+    client: PrivyClient;
+}
+interface PrivySigner {
+    account: PrivyAccount;
+    address: Address;
     provider: 'privy';
     privy: {
         appId: string;
@@ -145,12 +143,21 @@ interface PrivySigner extends TxSigner {
         client: PrivyClient;
     };
 }
+/**
+ * Attach Privy policy context to any account-like object so executeTx can run policy preflight checks.
+ */
+declare function attachPrivyPolicyContext<TAccount extends object>(account: TAccount, context: PrivyPolicyContext): TAccount;
+/** Read Privy policy context from an account when present. */
+declare function getPrivyPolicyContext(account: unknown): PrivyPolicyContext | undefined;
 /**
  * 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.
+ * The resolved account is backed by Privy RPC intents and supports:
+ * - `sendTransaction` via `eth_sendTransaction`
+ * - `signMessage` via `personal_sign`
+ * - `signTypedData` via `eth_signTypedData_v4`
+ * - `signTransaction` via `eth_signTransaction` (returns serialized tx hex; caller is responsible for broadcast)
  */
 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 };
+export { type KeystoreSignerOptions, type PrivyAccount, type PrivyAuthorizationPayload, type PrivyAuthorizationPayloadHeaders, PrivyClient, type PrivyPolicyContext, type PrivySendTransactionRequest, type PrivySignTransactionRequest, type PrivySignTypedDataRequest, type PrivySigner, type PrivySignerOptions, type SignerEnv, type SignerFlags, SignerOptions, TxSigner, attachPrivyPolicyContext, createKeystoreSigner, createPrivateKeySigner, createPrivyAccount, createPrivyAuthorizationPayload, createPrivySigner, generatePrivyAuthorizationSignature, getPrivyPolicyContext, normalizePrivyApiUrl, parsePrivyAuthorizationKey, resolveSigner, serializePrivyAuthorizationPayload, signerEnvSchema, signerFlagSchema, toSignerOptions };