w3pk 0.8.8 → 0.9.1

package/README.md

@@ -28,6 +28,12 @@ await w3pk.login()
 // Sign messages (EIP-191, SIWE, EIP-712, rawHash)
 const signature = await w3pk.signMessage('Hello World')
 
+// Send transactions on-chain
+const tx = await w3pk.sendTransaction({ to: '0x...', value: 1n * 10n**18n, chainId: 1 })
+
+// EIP-1193 provider (ethers, viem, wagmi, RainbowKit)
+const eip1193 = w3pk.getEIP1193Provider({ chainId: 1 })
+
 // Derive wallets (STANDARD/STRICT/YOLO modes)
 const wallet = await w3pk.deriveWallet('STANDARD', 'GAMING')
 
@@ -43,13 +49,17 @@ const endpoints = await w3pk.getEndpoints(1)
 - HD wallet generation (BIP39/BIP44)
 - Multi-address derivation with security modes (STANDARD/STRICT/YOLO)
 - Multiple signing methods (EIP-191, SIWE/EIP-4361, EIP-712, rawHash)
+- On-chain transaction sending with automatic RPC resolution (`sendTransaction`)
+- EIP-1193 provider for ethers, viem, wagmi, RainbowKit (`getEIP1193Provider`)
 - ERC-5564 stealth addresses (opt-in)
 - ZK primitives (zero-knowledge proof generation and verification)
 - Chainlist support (2390+ networks)
 - EIP-7702 network detection (329+ networks)
+- External wallet integration (delegate MetaMask/Ledger to w3pk via EIP-7702)
 - EIP-7951 PRIMARY mode (P-256 passkey signing)
-- Build verification (IPFS CIDv1 hashing)
+- Build verification (IPFS CID hashing + DAO-maintained onchain registry)
 - Three-layer backup & recovery (passkey sync, encrypted backups, social recovery)
+- AI-powered host app inspection
 
 ## API
 
@@ -124,6 +134,82 @@ const sensitiveSig = await w3pk.signMessage('Transfer $1000', {
 })
 ```
 
+### Sending Transactions
+
+```typescript
+// Check which address will be used before sending
+const from = await w3pk.getAddress('STANDARD', 'MAIN')
+console.log('sending from:', from)
+
+// Send ETH — defaults to STANDARD mode, MAIN tag, current origin
+// sender = getOriginSpecificAddress(mnemonic, window.location.origin, 'STANDARD', 'MAIN')
+const result = await w3pk.sendTransaction({
+  to: '0xRecipient...',
+  value: 1n * 10n**18n,  // 1 ETH in wei
+  chainId: 1
+})
+console.log('tx hash:', result.hash)
+console.log('from:', result.from)   // same address as `from` above
+console.log('mode:', result.mode)   // 'STANDARD'
+
+// Send contract call with custom RPC and STRICT auth
+const callResult = await w3pk.sendTransaction(
+  { to: '0xContract...', data: '0xabcd...', chainId: 10 },
+  { mode: 'STRICT', rpcUrl: 'https://mainnet.optimism.io' }
+)
+
+// YOLO mode — app-specific isolated address
+const yoloTx = await w3pk.sendTransaction(
+  { to: '0x...', value: 5n * 10n**17n, chainId: 8453 },
+  { mode: 'YOLO', tag: 'GAMING' }
+)
+```
+
+**Mode behaviour:**
+
+| Mode | Auth on send | Gas source |
+|------|-------------|------------|
+| STANDARD | Session (auto) | Sender address |
+| STRICT | Always (biometric) | Sender address |
+| YOLO | Session (auto) | Sender address |
+| PRIMARY | — (not supported, throws) | Requires bundler |
+
+### EIP-1193 Provider
+
+Use w3pk with any EIP-1193 consumer — ethers, viem, wagmi, RainbowKit — without exposing private keys.
+
+```typescript
+const eip1193 = w3pk.getEIP1193Provider({ chainId: 1 })
+```
+
+**ethers v6**
+```typescript
+import { BrowserProvider } from 'ethers'
+const provider = new BrowserProvider(eip1193)
+const signer = await provider.getSigner()
+const tx = await signer.sendTransaction({ to: '0x...', value: parseEther('1') })
+```
+
+**viem**
+```typescript
+import { createWalletClient, custom } from 'viem'
+import { mainnet } from 'viem/chains'
+const client = createWalletClient({ chain: mainnet, transport: custom(eip1193) })
+const [address] = await client.getAddresses()
+const hash = await client.sendTransaction({ to: '0x...', value: parseEther('1') })
+```
+
+**Supported JSON-RPC methods:**
+
+| Method | Action |
+|--------|--------|
+| `eth_accounts` / `eth_requestAccounts` | Returns derived address |
+| `eth_chainId` | Returns active chain as hex |
+| `eth_sendTransaction` | Delegates to `sendTransaction()` |
+| `personal_sign` / `eth_sign` | EIP-191 message signing |
+| `eth_signTypedData_v4` | EIP-712 typed data signing |
+| `wallet_switchEthereumChain` | Updates active chainId, emits `chainChanged` |
+
 ### Session Management
 
 ```typescript
@@ -193,6 +279,13 @@ const authorization = await w3pk.signAuthorization({
   nonce: 0n
 })
 // Returns: { chainId, address, nonce, yParity, r, s }
+
+// Delegate external wallet (MetaMask, Ledger, etc.) to w3pk account
+const auth = await w3pk.requestExternalWalletDelegation({
+  chainId: 1,
+  nonce: 0n
+})
+// User's external wallet account now controlled by w3pk WebAuthn
 ```
 
 ### EIP-7951 PRIMARY Mode
@@ -269,49 +362,98 @@ const invite = await w3pk.generateGuardianInvite(guardianShare)
 const { mnemonic } = await w3pk.recoverFromGuardians([share1, share2])
 
 // Restore from backup file
-await w3pk.restoreFromBackup(encryptedData, password)
+await w3pk.restoreFromBackupFile(encryptedData, password)
 
 // Simulate recovery scenarios
 const result = await w3pk.simulateRecoveryScenario({
   type: 'lost-device',
-  hasBackup: true,
-  hasSocialRecovery: true
+  description: 'Device lost with iCloud Keychain enabled'
 })
 ```
 
 ### Build Verification
 
 ```typescript
-import { getCurrentBuildHash, verifyBuildHash } from 'w3pk'
+import { getCurrentBuildHash } from 'w3pk'
+import { ethers } from 'ethers'
+import packageJson from './package.json'
+
+// Get installed w3pk version from package.json
+const installedVersion = packageJson.dependencies['w3pk'].replace(/^[~^]/, '') // Remove ^ or ~
 
 // Get IPFS hash of installed build
 const hash = await getCurrentBuildHash()
+console.log('Installed version:', installedVersion)
+console.log('Local build hash:', hash)
+
+// Verify against DAO-maintained onchain registry (OP Mainnet)
+const REGISTRY = '0xAF48C2DB335eD5da14A2C36a59Bc34407C63e01a'
+const ABI = ['function getCidByVersion(string version) view returns (string)']
+const provider = new ethers.JsonRpcProvider('https://mainnet.optimism.io')
+const registry = new ethers.Contract(REGISTRY, ABI, provider)
+
+// Query registry for the specific installed version (note: "v" prefix required)
+const onchainCid = await registry.getCidByVersion(`v${installedVersion}`)
+const isValid = hash === onchainCid
 
-// Verify against trusted hash
-const TRUSTED_HASH = 'bafybeig2xoiu2hfcjexz6cwtjcjf4u4vwxzcm66zhnqivhh6jvi7nx2qa4'
-const isValid = await verifyBuildHash(TRUSTED_HASH)
+console.log('Onchain CID:', onchainCid)
+console.log('Verified:', isValid ? '✅' : '❌')
 ```
 
-## Security & Verification
+### Security Inspection
 
-### Current Build Hash (v0.8.8)
+Analyze web3 applications to understand their transaction and signing methods:
 
+**Browser (analyze current page):**
+```typescript
+import { inspect, inspectNow } from 'w3pk'
+
+// Full inspection with custom options
+const result = await inspect({
+  appUrl: 'https://example.com',
+  rukhUrl: 'https://rukh.w3hc.org',
+  model: 'anthropic',
+  focusMode: 'transactions'
+})
+console.log(result.report)
+
+// Quick console inspection
+await inspectNow()  // Logs report directly to console
 ```
-bafybeig2xoiu2hfcjexz6cwtjcjf4u4vwxzcm66zhnqivhh6jvi7nx2qa4
+
+**Node.js (analyze local files):**
+```typescript
+import { inspect, gatherCode } from 'w3pk/inspect/node'
+
+// Generate security report via Rukh API
+const report = await inspect(
+  '../my-dapp',           // App path
+  'https://rukh.w3hc.org', // Rukh API URL
+  'w3pk',                  // Context
+  'anthropic',             // Model
+  'transactions'           // Focus mode
+)
+
+// Or just gather code for analysis
+const result = await gatherCode({
+  appPath: '../my-dapp',
+  focusMode: 'transactions',
+  maxFileSizeKB: 500
+})
+console.log(`Analyzed ${result.includedFiles.length} files`)
 ```
 
-**Verify package integrity:**
+## Security & Verification
 
-```typescript
-import { verifyBuildHash } from 'w3pk'
+### Onchain Build Registry
 
-const TRUSTED_HASH = 'bafybeig2xoiu2hfcjexz6cwtjcjf4u4vwxzcm66zhnqivhh6jvi7nx2qa4'
-const isValid = await verifyBuildHash(TRUSTED_HASH)
+W3PK maintains a DAO-controlled onchain registry of verified build hashes on OP Mainnet:
 
-if (!isValid) {
-  throw new Error('Package integrity check failed!')
-}
-```
+- **Registry Contract:** [`0xAF48C2DB335eD5da14A2C36a59Bc34407C63e01a`](https://optimistic.etherscan.io/address/0xAF48C2DB335eD5da14A2C36a59Bc34407C63e01a)
+- **Network:** OP Mainnet (Chain ID: 10)
+- **Purpose:** Immutable source of truth for official W3PK releases
+
+Host applications should verify their installed W3PK build against this registry. See [Build Verification](./docs/BUILD_VERIFICATION.md) for implementation details.
 
 ## Documentation
 
@@ -319,9 +461,11 @@ if (!isValid) {
 - [Integration Guidelines](./docs/INTEGRATION_GUIDELINES.md)
 - [API Reference](./docs/API_REFERENCE.md)
 - [Build Verification](./docs/BUILD_VERIFICATION.md)
+- [Security Inspection](./docs/INSPECTION.md)
 - [EIP-7951](./docs/EIP-7951.md)
 - [Security Architecture](./docs/SECURITY.md)
 - [Recovery & Backup System](./docs/RECOVERY.md)
+- [Portability Guide](./docs/PORTABILITY.md)
 - [ZK Proofs](./docs/ZK.md)
 - [Browser Compatibility](./docs/BROWSER_COMPATIBILITY.md)
 

package/dist/chainlist/index.d.mts

@@ -0,0 +1,96 @@
+/**
+ * Chainlist types
+ */
+interface Chain {
+    name: string;
+    chain: string;
+    icon?: string;
+    rpc: string[];
+    features?: Array<{
+        name: string;
+    }>;
+    faucets: string[];
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    infoURL: string;
+    shortName: string;
+    chainId: number;
+    networkId: number;
+    slip44?: number;
+    ens?: {
+        registry: string;
+    };
+    explorers?: Array<{
+        name: string;
+        url: string;
+        icon?: string;
+        standard: string;
+    }>;
+    title?: string;
+    status?: string;
+    redFlags?: string[];
+}
+interface ChainlistOptions {
+    /**
+     * Custom URL for chains.json data
+     * @default 'https://chainid.network/chains.json'
+     */
+    chainsJsonUrl?: string;
+    /**
+     * Cache duration in milliseconds
+     * @default 3600000 (1 hour)
+     */
+    cacheDuration?: number;
+}
+
+/**
+ * Chainlist module for fetching RPC endpoints
+ */
+
+/**
+ * Get RPC endpoints for a specific chain ID, excluding those that require API keys
+ *
+ * @param chainId - The chain ID to get endpoints for
+ * @param options - Optional configuration
+ * @returns Array of RPC URLs that don't require API keys
+ *
+ * @example
+ * ```typescript
+ * import { getEndpoints } from 'w3pk/chainlist'
+ *
+ * // Get Ethereum mainnet RPCs
+ * const endpoints = await getEndpoints(1)
+ * console.log(endpoints)
+ * // [
+ * //   "https://api.mycryptoapi.com/eth",
+ * //   "https://cloudflare-eth.com",
+ * //   "https://ethereum-rpc.publicnode.com",
+ * //   ...
+ * // ]
+ * ```
+ */
+declare function getEndpoints(chainId: number, options?: ChainlistOptions): Promise<string[]>;
+/**
+ * Get all available chains
+ *
+ * @param options - Optional configuration
+ * @returns Array of all chains
+ */
+declare function getAllChains(options?: ChainlistOptions): Promise<Chain[]>;
+/**
+ * Get chain information by chain ID
+ *
+ * @param chainId - The chain ID to get information for
+ * @param options - Optional configuration
+ * @returns Chain information or undefined if not found
+ */
+declare function getChainById(chainId: number, options?: ChainlistOptions): Promise<Chain | undefined>;
+/**
+ * Clear the chains data cache
+ */
+declare function clearCache(): void;
+
+export { type Chain, type ChainlistOptions, clearCache, getAllChains, getChainById, getEndpoints };

package/dist/chainlist/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Chainlist types
+ */
+interface Chain {
+    name: string;
+    chain: string;
+    icon?: string;
+    rpc: string[];
+    features?: Array<{
+        name: string;
+    }>;
+    faucets: string[];
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    infoURL: string;
+    shortName: string;
+    chainId: number;
+    networkId: number;
+    slip44?: number;
+    ens?: {
+        registry: string;
+    };
+    explorers?: Array<{
+        name: string;
+        url: string;
+        icon?: string;
+        standard: string;
+    }>;
+    title?: string;
+    status?: string;
+    redFlags?: string[];
+}
+interface ChainlistOptions {
+    /**
+     * Custom URL for chains.json data
+     * @default 'https://chainid.network/chains.json'
+     */
+    chainsJsonUrl?: string;
+    /**
+     * Cache duration in milliseconds
+     * @default 3600000 (1 hour)
+     */
+    cacheDuration?: number;
+}
+
+/**
+ * Chainlist module for fetching RPC endpoints
+ */
+
+/**
+ * Get RPC endpoints for a specific chain ID, excluding those that require API keys
+ *
+ * @param chainId - The chain ID to get endpoints for
+ * @param options - Optional configuration
+ * @returns Array of RPC URLs that don't require API keys
+ *
+ * @example
+ * ```typescript
+ * import { getEndpoints } from 'w3pk/chainlist'
+ *
+ * // Get Ethereum mainnet RPCs
+ * const endpoints = await getEndpoints(1)
+ * console.log(endpoints)
+ * // [
+ * //   "https://api.mycryptoapi.com/eth",
+ * //   "https://cloudflare-eth.com",
+ * //   "https://ethereum-rpc.publicnode.com",
+ * //   ...
+ * // ]
+ * ```
+ */
+declare function getEndpoints(chainId: number, options?: ChainlistOptions): Promise<string[]>;
+/**
+ * Get all available chains
+ *
+ * @param options - Optional configuration
+ * @returns Array of all chains
+ */
+declare function getAllChains(options?: ChainlistOptions): Promise<Chain[]>;
+/**
+ * Get chain information by chain ID
+ *
+ * @param chainId - The chain ID to get information for
+ * @param options - Optional configuration
+ * @returns Chain information or undefined if not found
+ */
+declare function getChainById(chainId: number, options?: ChainlistOptions): Promise<Chain | undefined>;
+/**
+ * Clear the chains data cache
+ */
+declare function clearCache(): void;
+
+export { type Chain, type ChainlistOptions, clearCache, getAllChains, getChainById, getEndpoints };