kentucky-signer-viem 0.1.3 → 0.1.5

package/README.md

@@ -15,6 +15,9 @@ A custom Viem account integration for the Kentucky Signer service, enabling EVM
 - **React Integration** - Hooks and context for easy React app integration
 - **TypeScript Support** - Full type definitions included
 - **Session Management** - Automatic refresh and persistence options
+- **EIP-7702 Support** - Sign authorizations for EOA code delegation
+- **Relayer Integration** - Client for gasless transactions via relayer service
+- **Intent Signing** - Sign execution intents for smart account operations
 
 ## Installation
 
@@ -204,6 +207,205 @@ const account = createKentuckySignerAccount({
 })
 ```
 
+## EIP-7702 Authorization
+
+Sign authorizations to delegate your EOA's code to a smart contract, enabling features like batching and gas sponsorship.
+
+```typescript
+import { createPublicClient, http } from 'viem'
+import { arbitrum } from 'viem/chains'
+
+const publicClient = createPublicClient({
+  chain: arbitrum,
+  transport: http(),
+})
+
+// Get current transaction count for the account
+const txNonce = await publicClient.getTransactionCount({
+  address: account.address,
+})
+
+// Sign EIP-7702 authorization
+const authorization = await account.sign7702Authorization({
+  contractAddress: '0x...', // Smart account delegate contract
+  chainId: 42161, // Arbitrum
+}, BigInt(txNonce))
+
+// Result:
+// {
+//   chainId: 42161,
+//   contractAddress: '0x...',
+//   nonce: 0n,
+//   yParity: 0,
+//   r: '0x...',
+//   s: '0x...'
+// }
+```
+
+The authorization can be included in an EIP-7702 transaction's `authorizationList` to delegate the EOA.
+
+## Intent Signing for Relayed Execution
+
+Sign execution intents for gasless transactions via a relayer.
+
+```typescript
+import {
+  createExecutionIntent,
+  signIntent,
+  RelayerClient,
+} from 'kentucky-signer-viem'
+import { encodeFunctionData, parseEther } from 'viem'
+
+// Create relayer client
+const relayer = new RelayerClient({
+  baseUrl: 'https://relayer.example.com',
+})
+
+// Get current nonce from the delegate contract
+const nonce = await relayer.getNonce(42161, account.address)
+
+// Create an execution intent
+const intent = createExecutionIntent({
+  nonce,
+  target: '0x...', // Contract to call
+  value: parseEther('0.1'), // ETH to send (optional)
+  data: encodeFunctionData({
+    abi: [...],
+    functionName: 'transfer',
+    args: ['0x...', 1000n],
+  }),
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600), // 1 hour (optional)
+})
+
+// Sign the intent
+const signedIntent = await signIntent(account, intent)
+```
+
+## Relayer Client
+
+The `RelayerClient` communicates with a relayer service to submit transactions on behalf of users.
+
+### Basic Usage
+
+```typescript
+import { RelayerClient, createRelayerClient } from 'kentucky-signer-viem'
+
+// Create client
+const relayer = new RelayerClient({
+  baseUrl: 'https://relayer.example.com',
+  timeout: 30000, // Optional, default 30s
+})
+
+// Or use the factory function
+const relayer = createRelayerClient('https://relayer.example.com')
+
+// Check health
+const health = await relayer.health()
+// { status: 'ok', relayer: '0x...', timestamp: '2024-...' }
+```
+
+### Get Nonce
+
+```typescript
+const nonce = await relayer.getNonce(42161, account.address)
+// Returns bigint nonce from the delegate contract
+```
+
+### Estimate Gas
+
+```typescript
+const estimate = await relayer.estimate(42161, account.address, intent)
+// {
+//   gasEstimate: '150000',
+//   gasCostWei: '30000000000000',
+//   sponsoredAvailable: true,
+//   tokenOptions: [
+//     { token: '0x...', symbol: 'USDC', estimatedFee: '0.05', feePercentage: 5 }
+//   ]
+// }
+```
+
+### Relay Transaction
+
+```typescript
+// Sponsored (relayer pays gas)
+const result = await relayer.relay(
+  42161,
+  account.address,
+  signedIntent,
+  'sponsored'
+)
+
+// Pay with ERC20 token
+const result = await relayer.relay(
+  42161,
+  account.address,
+  signedIntent,
+  { token: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' } // USDC on Arbitrum
+)
+
+if (result.success) {
+  console.log('TX Hash:', result.txHash)
+} else {
+  console.error('Failed:', result.error)
+}
+```
+
+### Gasless Onboarding
+
+For users with zero ETH, combine EIP-7702 authorization with relay to delegate and execute in a single transaction:
+
+```typescript
+import { createPublicClient, http } from 'viem'
+import { arbitrum } from 'viem/chains'
+
+const publicClient = createPublicClient({
+  chain: arbitrum,
+  transport: http(),
+})
+
+// Get current nonce
+const txNonce = await publicClient.getTransactionCount({
+  address: account.address,
+})
+
+// Sign EIP-7702 authorization to delegate EOA
+const authorization = await account.sign7702Authorization({
+  contractAddress: delegateAddress,
+  chainId: 42161,
+}, BigInt(txNonce))
+
+// Create and sign execution intent
+const nonce = await relayer.getNonce(42161, account.address)
+const intent = createExecutionIntent({
+  nonce,
+  target: '0x...',
+  data: '0x...',
+})
+const signedIntent = await signIntent(account, intent)
+
+// Relay with authorization - delegates EOA and executes in one tx
+const result = await relayer.relay(
+  42161,
+  account.address,
+  signedIntent,
+  'sponsored',
+  authorization // Include EIP-7702 authorization
+)
+```
+
+### Check Transaction Status
+
+```typescript
+const status = await relayer.getStatus(42161, txHash)
+// {
+//   status: 'confirmed', // 'pending' | 'confirmed' | 'failed'
+//   txHash: '0x...',
+//   blockNumber: 12345678,
+//   gasUsed: '120000'
+// }
+```
+
 ## Two-Factor Authentication
 
 ### Setup TOTP (Authenticator App)
@@ -270,32 +472,39 @@ Set up trusted guardians for account recovery:
 ```typescript
 const client = new KentuckySignerClient({ baseUrl })
 
-// Add a guardian
-await client.addGuardian(accountId, {
-  guardian_account_id: 'guardian_hex_id',
+// Add a guardian (requires WebAuthn attestation from guardian's device)
+const { guardian_index, guardian_count } = await client.addGuardian({
+  attestation_object: guardianAttestationBase64url,
   label: 'My Friend',
 }, token)
 
 // List guardians
-const { guardians } = await client.getGuardians(accountId, token)
+const { guardians } = await client.getGuardians(token)
+// guardians: [{ index: 1, label: 'My Friend' }, ...]
+
+// Initiate recovery (when locked out - register new passkey first)
+const recovery = await client.initiateRecovery(
+  accountId,
+  newPasskeyAttestationObject,
+  'New Owner Passkey'
+)
+// Returns: { challenges, guardian_count, threshold, timelock_seconds }
 
-// Initiate recovery (when locked out)
-const recovery = await client.initiateRecovery({
+// Guardian signs their challenge with their passkey
+await client.verifyGuardian({
   account_id: accountId,
-  new_password: 'new-secure-password',
+  guardian_index: 1,
+  authenticator_data: authDataBase64url,
+  client_data_json: clientDataBase64url,
+  signature: signatureBase64url,
 })
 
-// Guardian approves recovery
-await client.verifyGuardianRecovery({
-  recovery_id: recovery.recovery_id,
-  guardian_account_id: guardianId,
-  signature: guardianSignature,
-}, guardianToken)
+// Check recovery status
+const status = await client.getRecoveryStatus(accountId)
+// { verified_count, threshold, can_complete, timelock_remaining }
 
-// Complete recovery after threshold met
-await client.completeRecovery({
-  recovery_id: recovery.recovery_id,
-}, token)
+// Complete recovery after threshold met and timelock expired
+await client.completeRecovery(accountId)
 ```
 
 ## API Reference
@@ -311,6 +520,16 @@ await client.completeRecovery({
 | `createAccountWithPassword(options)` | Create new account with password |
 | `authenticateWithToken(...)` | Create session from JWT token |
 
+### Intent & Relayer Functions
+
+| Function | Description |
+|----------|-------------|
+| `createExecutionIntent(params)` | Create an execution intent for relayed execution |
+| `signIntent(account, intent)` | Sign an execution intent |
+| `signBatchIntents(account, intents)` | Sign multiple intents for batch execution |
+| `hashIntent(intent)` | Compute the hash of an execution intent |
+| `createRelayerClient(baseUrl)` | Create a relayer client |
+
 ### React Hooks
 
 | Hook | Description |
@@ -328,8 +547,9 @@ await client.completeRecovery({
 
 #### Authentication
 - `getChallenge(accountId)` - Get WebAuthn challenge
-- `authenticatePasskey(accountId, credential)` - Authenticate with passkey
-- `authenticatePassword(accountId, password)` - Authenticate with password
+- `authenticatePasskey(accountId, credential, ephemeralPublicKey?)` - Authenticate with passkey
+- `authenticatePassword(request)` - Authenticate with password (`{ account_id, password }`)
+- `refreshToken(token)` - Refresh JWT token
 - `logout(token)` - Invalidate session
 
 #### Signing
@@ -338,9 +558,10 @@ await client.completeRecovery({
 
 #### Account Management
 - `getAccountInfo(accountId, token)` - Get account info
+- `getAccountInfoExtended(accountId, token)` - Get account info with auth config
 - `addPassword(accountId, request, token)` - Add password auth
 - `addPasskey(accountId, request, token)` - Add passkey
-- `removePasskey(accountId, credentialId, token)` - Remove passkey
+- `removePasskey(accountId, passkeyIndex, token)` - Remove passkey by index
 
 #### Two-Factor Authentication
 - `get2FAStatus(token)` - Get 2FA status
@@ -350,13 +571,28 @@ await client.completeRecovery({
 - `setupPIN(pin, token)` - Setup PIN
 - `disablePIN(pin, token)` - Disable PIN
 
+### Account Methods
+
+#### EIP-7702 Authorization
+- `account.sign7702Authorization(params, nonce)` - Sign authorization to delegate EOA code
+
+### Relayer Client Methods
+
+- `health()` - Check relayer health
+- `getNonce(chainId, address)` - Get account nonce from delegate contract
+- `estimate(chainId, address, intent)` - Estimate gas and fees
+- `relay(chainId, address, signedIntent, paymentMode, authorization?)` - Submit transaction
+- `getStatus(chainId, txHash)` - Get transaction status
+
 #### Guardian Recovery
-- `addGuardian(accountId, request, token)` - Add guardian
-- `removeGuardian(accountId, guardianId, token)` - Remove guardian
-- `getGuardians(accountId, token)` - List guardians
-- `initiateRecovery(request)` - Start recovery
-- `verifyGuardianRecovery(request, token)` - Guardian approval
-- `completeRecovery(request, token)` - Complete recovery
+- `addGuardian(request, token)` - Add guardian passkey
+- `removeGuardian(guardianIndex, token)` - Remove guardian
+- `getGuardians(token)` - List guardians
+- `initiateRecovery(accountId, attestationObject, label?)` - Start recovery
+- `verifyGuardian(request)` - Submit guardian signature
+- `getRecoveryStatus(accountId)` - Check recovery status
+- `completeRecovery(accountId)` - Complete recovery
+- `cancelRecovery(token)` - Cancel recovery (owner only)
 
 ## Error Handling