@spectratools/tx-shared 0.4.3 → 0.5.2

package/README.md

@@ -16,13 +16,13 @@ This package is designed for consuming CLIs (for example `@spectratools/assembly
 pnpm add @spectratools/tx-shared
 ```
 
-## Signer Providers
+## Signer providers
 
 `resolveSigner()` uses deterministic precedence:
 
 1. `privateKey`
 2. `keystorePath` (+ `keystorePassword`)
-3. `privy` / `PRIVY_*`
+3. Privy (`privy` flag and/or `PRIVY_*` env)
 
 If no provider is configured, it throws `TxError` with code `SIGNER_NOT_CONFIGURED`.
 
@@ -50,13 +50,36 @@ export KEYSTORE_PASSWORD="..."
 
 #### 3) Privy
 
+Required env:
+
 ```bash
 export PRIVY_APP_ID="..."
 export PRIVY_WALLET_ID="..."
-export PRIVY_AUTHORIZATION_KEY="..."
+export PRIVY_AUTHORIZATION_KEY="wallet-auth:<base64-pkcs8-p256-private-key>"
+```
+
+Optional env:
+
+```bash
+export PRIVY_API_URL="https://api.sandbox.privy.io"
+```
+
+Optional CLI flags (from `signerFlagSchema`):
+
+```bash
+--privy
+--privy-api-url "https://api.sandbox.privy.io"
 ```
 
-> 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).
+Notes:
+
+- `--privy` is optional when `PRIVY_APP_ID` + `PRIVY_WALLET_ID` + `PRIVY_AUTHORIZATION_KEY` are present; `resolveSigner()` auto-detects Privy config.
+- `--privy-api-url` / `PRIVY_API_URL` override the default `https://api.privy.io`.
+- Privy account methods are mapped as:
+  - `sendTransaction` → `eth_sendTransaction`
+  - `signMessage` → `personal_sign`
+  - `signTypedData` → `eth_signTypedData_v4`
+  - `signTransaction` → `eth_signTransaction` (returns serialized tx hex; broadcast separately if needed)
 
 ## `resolveSigner()` usage
 
@@ -70,7 +93,7 @@ const signer = await resolveSigner({
 });
 
 console.log(signer.provider); // 'private-key' | 'keystore' | 'privy'
-console.log(signer.address);  // 0x...
+console.log(signer.address); // 0x...
 ```
 
 ### From shared CLI flags + env
@@ -84,8 +107,8 @@ import {
 } from '@spectratools/tx-shared';
 
 const flags = signerFlagSchema.parse({
-  'private-key': process.env.PRIVATE_KEY,
-  privy: false,
+  privy: true,
+  'privy-api-url': process.env.PRIVY_API_URL,
 });
 
 const env = signerEnvSchema.parse(process.env);
@@ -98,46 +121,108 @@ const signer = await resolveSigner(toSignerOptions(flags, env));
 
 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
+3. preflight Privy policies (when signer is Privy-backed)
+4. submit (`writeContract`) unless `dryRun: true`
+5. wait for receipt (`waitForTransactionReceipt`)
+6. normalize result into a shared output shape
 
-### Live transaction example
+### Privy transaction flow example (dry-run + live)
 
 ```ts
-import { executeTx } from '@spectratools/tx-shared';
+import { http, createPublicClient, createWalletClient, parseAbi } from 'viem';
+import {
+  abstractMainnet,
+  executeTx,
+  resolveSigner,
+  signerEnvSchema,
+  signerFlagSchema,
+  toSignerOptions,
+} from '@spectratools/tx-shared';
+
+const flags = signerFlagSchema.parse({
+  privy: true,
+  'privy-api-url': process.env.PRIVY_API_URL,
+});
+const env = signerEnvSchema.parse(process.env);
+const signer = await resolveSigner(toSignerOptions(flags, env));
+
+const publicClient = createPublicClient({
+  chain: abstractMainnet,
+  transport: http(process.env.ABSTRACT_RPC_URL),
+});
+const walletClient = createWalletClient({
+  account: signer.account,
+  chain: abstractMainnet,
+  transport: http(process.env.ABSTRACT_RPC_URL),
+});
+
+const registryAbi = parseAbi(['function register() payable']);
 
-const result = await executeTx({
+const dryRun = await executeTx({
   publicClient,
   walletClient,
   account: signer.account,
-  address,
-  abi,
+  address: '0x1111111111111111111111111111111111111111',
+  abi: registryAbi,
   functionName: 'register',
-  value: registrationFee,
+  value: 1000000000000000n,
+  dryRun: true,
 });
 
-console.log(result.hash, result.status, result.gasUsed.toString());
-```
-
-### Dry-run example
+if (dryRun.status === 'dry-run') {
+  console.log(dryRun.estimatedGas.toString());
+  console.log(dryRun.privyPolicy?.status); // 'allowed' | 'blocked'
+}
 
-```ts
-const result = await executeTx({
+const live = await executeTx({
   publicClient,
   walletClient,
   account: signer.account,
-  address,
-  abi,
+  address: '0x1111111111111111111111111111111111111111',
+  abi: registryAbi,
   functionName: 'register',
-  value: registrationFee,
-  dryRun: true,
+  value: 1000000000000000n,
 });
 
-if (result.status === 'dry-run') {
-  console.log('estimatedGas', result.estimatedGas.toString());
-  console.log('simulationResult', result.simulationResult);
-}
+console.log(live.hash, live.status);
+```
+
+### Privy signing flow example
+
+```ts
+const signer = await resolveSigner({
+  privy: true,
+  privyAppId: process.env.PRIVY_APP_ID,
+  privyWalletId: process.env.PRIVY_WALLET_ID,
+  privyAuthorizationKey: process.env.PRIVY_AUTHORIZATION_KEY,
+  privyApiUrl: process.env.PRIVY_API_URL,
+});
+
+if (signer.provider !== 'privy') throw new Error('Expected Privy signer');
+
+const messageSig = await signer.account.signMessage({ message: 'hello from tx-shared' });
+
+const typedDataSig = await signer.account.signTypedData({
+  domain: { name: 'SpectraTools', version: '1', chainId: 2741 },
+  primaryType: 'Ping',
+  types: {
+    Ping: [{ name: 'message', type: 'string' }],
+  },
+  message: { message: 'privy typed data' },
+});
+
+const signedTxHex = await signer.account.signTransaction({
+  to: '0x1111111111111111111111111111111111111111',
+  chainId: 2741,
+  nonce: 1,
+  gas: 21000n,
+  maxFeePerGas: 1000000000n,
+  maxPriorityFeePerGas: 1000000000n,
+  value: 0n,
+  data: '0x',
+});
+
+console.log(messageSig, typedDataSig, signedTxHex);
 ```
 
 ## Structured errors
@@ -151,6 +236,8 @@ if (result.status === 'dry-run') {
 - `SIGNER_NOT_CONFIGURED`
 - `KEYSTORE_DECRYPT_FAILED`
 - `PRIVY_AUTH_FAILED`
+- `PRIVY_TRANSPORT_FAILED`
+- `PRIVY_POLICY_BLOCKED`
 
 ```ts
 import { TxError } from '@spectratools/tx-shared';
@@ -167,6 +254,8 @@ try {
       case 'SIGNER_NOT_CONFIGURED':
       case 'KEYSTORE_DECRYPT_FAILED':
       case 'PRIVY_AUTH_FAILED':
+      case 'PRIVY_TRANSPORT_FAILED':
+      case 'PRIVY_POLICY_BLOCKED':
         throw error;
     }
   }
@@ -184,8 +273,15 @@ try {
   - verify file path and password
   - ensure keystore is valid V3 JSON
 - **`PRIVY_AUTH_FAILED`**
-  - verify all `PRIVY_*` variables are set
-  - check signer/owner policy constraints for the Privy wallet
+  - verify required env: `PRIVY_APP_ID`, `PRIVY_WALLET_ID`, `PRIVY_AUTHORIZATION_KEY`
+  - validate `PRIVY_AUTHORIZATION_KEY` format: `wallet-auth:<base64-pkcs8-p256-private-key>`
+  - verify `PRIVY_API_URL` override points at a valid Privy API host
+- **`PRIVY_TRANSPORT_FAILED`**
+  - check Privy API availability and credentials
+  - inspect upstream intent failure payloads for status + reason
+- **`PRIVY_POLICY_BLOCKED`**
+  - review active wallet policy allowlists and native value caps
+  - use `dryRun: true` and inspect `result.privyPolicy` before broadcasting
 - **`GAS_ESTIMATION_FAILED` / `TX_REVERTED`**
   - validate function args and `value`
   - run with `dryRun: true` first