feat: Add Privy Server Wallet Integration for Policy-Controlled Trading

[fengtality]

Overview

Add support for Privy server wallets to enable wallet-level transaction policies (allowlisted contracts, max amounts, time restrictions). Policies are managed in Privy Dashboard; Gateway just registers wallets and signs transactions.

Design Document

Full implementation spec: privy-gateway-design.md

Why Privy?

The main value is wallet-level policies:

• Restrict transactions to specific contracts (DEX routers only)
• Set maximum transfer amounts per transaction
• Allowlist/denylist recipient addresses
• Time-based access controls
• Block private key exports

Policies are configured in the Privy Dashboard and enforced server-side on every signing request.

Implementation Summary

Files to Create

1. src/wallet/privy/privy-client.ts - REST client for Privy API
2. src/wallet/privy/privy-evm-signer.ts - ethers.Signer implementation for EVM chains
3. src/wallet/privy/privy-solana-signer.ts - Solana transaction signer

Files to Modify

4. src/templates/apiKeys.yml - Add privyAppId, privyAppSecret
5. src/templates/namespace/apiKeys-schema.json - Add Privy properties
6. src/wallet/utils.ts - Add Privy wallet utilities (mirrors hardware wallet pattern)
7. src/chains/ethereum/ethereum.ts - Add isPrivyWallet() and getPrivySigner() methods
8. src/chains/solana/solana.ts - Add isPrivyWallet() and getPrivySigner() methods
9. src/wallet/wallet.routes.ts - Add /wallet/add-privy and /wallet/remove-privy routes
10. Connectors (Jupiter, Raydium, Meteora, Uniswap) - Add Privy wallet branching

Key Design Decisions

1. Uses existing apiKeys.yml - No new config namespace; Privy credentials go in centralized API keys
2. Follows existing hardware wallet pattern - Uses isPrivyWallet() check and branching like existing isHardwareWallet() pattern
3. Policies managed in Privy Dashboard - Gateway doesn't manage policies; it just registers wallets and signs transactions
4. Minimal connector changes - Connectors add else if (isPrivyWallet) branch to existing hardware wallet logic
5. No new dependencies - Uses native fetch for Privy API calls

API Endpoints

• POST /wallet/add-privy - Register a Privy wallet (chain, privyWalletId)
• DELETE /wallet/remove-privy - Unregister a Privy wallet (chain, address)

Connector Update Pattern

const isHardwareWallet = await solana.isHardwareWallet(walletAddress);
const isPrivyWallet = await solana.isPrivyWallet(walletAddress);

if (isHardwareWallet) {
  // existing hardware wallet code...
} else if (isPrivyWallet) {
  transaction = await jupiter.buildSwapTransactionForHardwareWallet(walletAddress, quote, ...);
  const privySigner = await solana.getPrivySigner(walletAddress);
  transaction = await privySigner.signTransaction(transaction);
} else {
  // existing local wallet code...
}

Implementation Checklist

• Add Privy credentials to src/templates/apiKeys.yml
• Add Privy properties to src/templates/namespace/apiKeys-schema.json
• Create src/wallet/privy/ directory
• Create src/wallet/privy/privy-client.ts
• Create src/wallet/privy/privy-evm-signer.ts
• Create src/wallet/privy/privy-solana-signer.ts
• Add Privy wallet functions to src/wallet/utils.ts
• Add isPrivyWallet() and getPrivySigner() to src/chains/ethereum/ethereum.ts
• Add isPrivyWallet() and getPrivySigner() to src/chains/solana/solana.ts
• Add /wallet/add-privy and /wallet/remove-privy routes
• Update Jupiter connector with Privy support
• Update Raydium connector with Privy support
• Update Meteora connector with Privy support
• Update Uniswap connector with Privy support (if needed)
• Run pnpm build to verify no TypeScript errors
• Run pnpm test to verify existing tests pass
• Create unit tests for Privy client and signers

References

• Privy Server Wallets
• Privy Policies
• Ethereum Policy Examples
• Solana Policy Examples