kentucky-signer-viem 0.1.4 → 0.1.5

package/src/react/relayer-hooks.ts

@@ -0,0 +1,318 @@
+import { useState, useCallback, useEffect, useRef } from 'react'
+import type { Address, Hex } from 'viem'
+import type {
+  RelayerClient,
+  PaymentMode,
+  EstimateResponse,
+  RelayResponse,
+  StatusResponse,
+  TransactionStatus,
+  Authorization7702,
+} from '../relayer-client'
+import type { ExecutionIntent, SignedIntent } from '../intent'
+
+/**
+ * Hook for relaying intents through the relayer
+ */
+export interface UseRelayIntentResult {
+  /** Relay a signed intent */
+  relay: (
+    chainId: number,
+    accountAddress: Address,
+    signedIntent: SignedIntent,
+    paymentMode: PaymentMode,
+    authorization?: Authorization7702
+  ) => Promise<RelayResponse>
+  /** Whether a relay is in progress */
+  isRelaying: boolean
+  /** Last relay response */
+  response: RelayResponse | null
+  /** Last error */
+  error: Error | null
+  /** Reset state */
+  reset: () => void
+}
+
+/**
+ * Hook for relaying signed intents through the Kentucky Signer Relayer
+ *
+ * @param client - Relayer client instance
+ * @returns Relay functions and state
+ *
+ * @example
+ * ```tsx
+ * const relayer = useRelayerClient('https://relayer.example.com')
+ * const { relay, isRelaying, response, error } = useRelayIntent(relayer)
+ *
+ * const handleSubmit = async () => {
+ *   const result = await relay(42161, accountAddress, signedIntent, 'sponsored')
+ *   if (result.success) {
+ *     console.log('TX:', result.txHash)
+ *   }
+ * }
+ * ```
+ */
+export function useRelayIntent(client: RelayerClient): UseRelayIntentResult {
+  const [isRelaying, setIsRelaying] = useState(false)
+  const [response, setResponse] = useState<RelayResponse | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+
+  const relay = useCallback(
+    async (
+      chainId: number,
+      accountAddress: Address,
+      signedIntent: SignedIntent,
+      paymentMode: PaymentMode,
+      authorization?: Authorization7702
+    ): Promise<RelayResponse> => {
+      setIsRelaying(true)
+      setError(null)
+
+      try {
+        const result = await client.relay(chainId, accountAddress, signedIntent, paymentMode, authorization)
+        setResponse(result)
+        return result
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Relay failed')
+        setError(error)
+        return { success: false, error: error.message }
+      } finally {
+        setIsRelaying(false)
+      }
+    },
+    [client]
+  )
+
+  const reset = useCallback(() => {
+    setResponse(null)
+    setError(null)
+  }, [])
+
+  return { relay, isRelaying, response, error, reset }
+}
+
+/**
+ * Hook for tracking transaction status
+ */
+export interface UseTransactionStatusResult {
+  /** Current transaction status */
+  status: TransactionStatus | null
+  /** Full status response */
+  statusResponse: StatusResponse | null
+  /** Whether status is being fetched */
+  isLoading: boolean
+  /** Last error */
+  error: Error | null
+  /** Manually refresh status */
+  refresh: () => void
+}
+
+/**
+ * Hook for tracking transaction status with polling
+ *
+ * @param client - Relayer client instance
+ * @param chainId - Chain ID
+ * @param txHash - Transaction hash to track (null to disable)
+ * @param pollInterval - Polling interval in ms (default: 3000)
+ * @returns Transaction status and state
+ *
+ * @example
+ * ```tsx
+ * const { status, statusResponse, isLoading } = useTransactionStatus(
+ *   relayer,
+ *   42161,
+ *   txHash
+ * )
+ *
+ * if (status === 'confirmed') {
+ *   console.log('Transaction confirmed in block:', statusResponse?.blockNumber)
+ * }
+ * ```
+ */
+export function useTransactionStatus(
+  client: RelayerClient,
+  chainId: number,
+  txHash: Hex | null,
+  pollInterval: number = 3000
+): UseTransactionStatusResult {
+  const [status, setStatus] = useState<TransactionStatus | null>(null)
+  const [statusResponse, setStatusResponse] = useState<StatusResponse | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const intervalRef = useRef<NodeJS.Timeout | null>(null)
+
+  const fetchStatus = useCallback(async () => {
+    if (!txHash) return
+
+    setIsLoading(true)
+    try {
+      const response = await client.getStatus(chainId, txHash)
+      setStatusResponse(response)
+      setStatus(response.status)
+      setError(null)
+
+      // Stop polling if transaction is finalized
+      if (response.status === 'confirmed' || response.status === 'failed') {
+        if (intervalRef.current) {
+          clearInterval(intervalRef.current)
+          intervalRef.current = null
+        }
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to fetch status'))
+    } finally {
+      setIsLoading(false)
+    }
+  }, [client, chainId, txHash])
+
+  // Start polling when txHash is set
+  useEffect(() => {
+    if (!txHash) {
+      setStatus(null)
+      setStatusResponse(null)
+      return
+    }
+
+    // Fetch immediately
+    fetchStatus()
+
+    // Start polling
+    intervalRef.current = setInterval(fetchStatus, pollInterval)
+
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current)
+        intervalRef.current = null
+      }
+    }
+  }, [txHash, pollInterval, fetchStatus])
+
+  return { status, statusResponse, isLoading, error, refresh: fetchStatus }
+}
+
+/**
+ * Hook for estimating gas and fees
+ */
+export interface UseEstimateResult {
+  /** Estimate gas and fees */
+  estimate: (
+    chainId: number,
+    accountAddress: Address,
+    intent: ExecutionIntent
+  ) => Promise<EstimateResponse | null>
+  /** Last estimate response */
+  estimateResponse: EstimateResponse | null
+  /** Whether estimate is in progress */
+  isEstimating: boolean
+  /** Last error */
+  error: Error | null
+}
+
+/**
+ * Hook for estimating gas and token fees
+ *
+ * @param client - Relayer client instance
+ * @returns Estimate functions and state
+ *
+ * @example
+ * ```tsx
+ * const { estimate, estimateResponse, isEstimating } = useEstimate(relayer)
+ *
+ * useEffect(() => {
+ *   estimate(42161, accountAddress, intent)
+ * }, [intent])
+ *
+ * if (estimateResponse) {
+ *   console.log('Gas:', estimateResponse.gasEstimate)
+ *   console.log('Tokens:', estimateResponse.tokenOptions)
+ * }
+ * ```
+ */
+export function useEstimate(client: RelayerClient): UseEstimateResult {
+  const [estimateResponse, setEstimateResponse] = useState<EstimateResponse | null>(null)
+  const [isEstimating, setIsEstimating] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+
+  const estimate = useCallback(
+    async (
+      chainId: number,
+      accountAddress: Address,
+      intent: ExecutionIntent
+    ): Promise<EstimateResponse | null> => {
+      setIsEstimating(true)
+      setError(null)
+
+      try {
+        const response = await client.estimate(chainId, accountAddress, intent)
+        setEstimateResponse(response)
+        return response
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Estimate failed')
+        setError(error)
+        return null
+      } finally {
+        setIsEstimating(false)
+      }
+    },
+    [client]
+  )
+
+  return { estimate, estimateResponse, isEstimating, error }
+}
+
+/**
+ * Hook for fetching account nonce
+ */
+export interface UseNonceResult {
+  /** Current nonce */
+  nonce: bigint | null
+  /** Whether nonce is being fetched */
+  isLoading: boolean
+  /** Last error */
+  error: Error | null
+  /** Refresh nonce */
+  refresh: () => void
+}
+
+/**
+ * Hook for fetching account nonce
+ *
+ * @param client - Relayer client instance
+ * @param chainId - Chain ID
+ * @param address - Account address (null to disable)
+ * @returns Nonce and state
+ */
+export function useNonce(
+  client: RelayerClient,
+  chainId: number,
+  address: Address | null
+): UseNonceResult {
+  const [nonce, setNonce] = useState<bigint | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+
+  const fetchNonce = useCallback(async () => {
+    if (!address) return
+
+    setIsLoading(true)
+    try {
+      const result = await client.getNonce(chainId, address)
+      setNonce(result)
+      setError(null)
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to fetch nonce'))
+    } finally {
+      setIsLoading(false)
+    }
+  }, [client, chainId, address])
+
+  useEffect(() => {
+    if (address) {
+      fetchNonce()
+    } else {
+      setNonce(null)
+    }
+  }, [address, fetchNonce])
+
+  return { nonce, isLoading, error, refresh: fetchNonce }
+}

package/src/relayer-client.ts

@@ -0,0 +1,305 @@
+import type { Address, Hex } from 'viem'
+import type { ExecutionIntent, SignedIntent } from './intent'
+
+/**
+ * Payment mode for relaying
+ */
+export type PaymentMode = 'sponsored' | { token: Address }
+
+/**
+ * EIP-7702 Authorization for gasless onboarding
+ * When provided to relay(), allows users with 0 ETH to delegate their EOA
+ * to the smart account delegate in the same transaction as execution
+ */
+export interface Authorization7702 {
+  /** Chain ID (0 for all chains) */
+  chainId: number
+  /** Contract address to delegate to */
+  contractAddress: Address
+  /** Nonce for the authorization */
+  nonce: bigint
+  /** Recovery identifier (0 or 1) */
+  yParity: number
+  /** Signature r component */
+  r: Hex
+  /** Signature s component */
+  s: Hex
+}
+
+/**
+ * Token payment option returned by estimate
+ */
+export interface TokenOption {
+  /** Token address */
+  token: Address
+  /** Token symbol */
+  symbol: string
+  /** Estimated fee in token units */
+  estimatedFee: string
+  /** Fee percentage (e.g., 5 = 5%) */
+  feePercentage: number
+}
+
+/**
+ * Gas estimate response
+ */
+export interface EstimateResponse {
+  /** Estimated gas units */
+  gasEstimate: string
+  /** Estimated gas cost in wei */
+  gasCostWei: string
+  /** Whether sponsored mode is available */
+  sponsoredAvailable: boolean
+  /** Available token payment options */
+  tokenOptions: TokenOption[]
+}
+
+/**
+ * Relay response
+ */
+export interface RelayResponse {
+  /** Whether the relay was successful */
+  success: boolean
+  /** Transaction hash if successful */
+  txHash?: Hex
+  /** Error message if failed */
+  error?: string
+}
+
+/**
+ * Transaction status
+ */
+export type TransactionStatus = 'pending' | 'confirmed' | 'failed'
+
+/**
+ * Status response
+ */
+export interface StatusResponse {
+  /** Current status */
+  status: TransactionStatus
+  /** Transaction hash */
+  txHash: Hex
+  /** Block number if confirmed */
+  blockNumber?: number
+  /** Gas used if confirmed */
+  gasUsed?: string
+  /** Token amount paid if applicable */
+  tokenPaid?: string
+}
+
+/**
+ * Relayer client options
+ */
+export interface RelayerClientOptions {
+  /** Relayer API base URL */
+  baseUrl: string
+  /** Request timeout in ms (default: 30000) */
+  timeout?: number
+}
+
+/**
+ * Client for interacting with the Kentucky Signer Relayer API
+ *
+ * @example
+ * ```typescript
+ * const relayer = new RelayerClient({ baseUrl: 'https://relayer.example.com' })
+ *
+ * // Get nonce
+ * const nonce = await relayer.getNonce(42161, accountAddress)
+ *
+ * // Create and sign intent
+ * const intent = createExecutionIntent({ nonce, target: '0x...' })
+ * const signed = await signIntent(account, intent)
+ *
+ * // Estimate fees
+ * const estimate = await relayer.estimate(42161, accountAddress, intent)
+ *
+ * // Relay transaction
+ * const result = await relayer.relay(42161, accountAddress, signed, 'sponsored')
+ * console.log('TX Hash:', result.txHash)
+ *
+ * // Check status
+ * const status = await relayer.getStatus(42161, result.txHash!)
+ * ```
+ */
+export class RelayerClient {
+  private baseUrl: string
+  private timeout: number
+
+  constructor(options: RelayerClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, '') // Remove trailing slash
+    this.timeout = options.timeout ?? 30000
+  }
+
+  /**
+   * Check if the relayer is healthy
+   */
+  async health(): Promise<{ status: string; relayer: Address; timestamp: string }> {
+    const response = await this.fetch('/health')
+    return response
+  }
+
+  /**
+   * Get the current nonce for an account
+   *
+   * @param chainId - Chain ID
+   * @param address - Account address
+   * @returns Current nonce as bigint
+   */
+  async getNonce(chainId: number, address: Address): Promise<bigint> {
+    const response = await this.fetch(`/nonce/${chainId}/${address}`)
+    return BigInt(response.nonce)
+  }
+
+  /**
+   * Estimate gas and fees for an intent
+   *
+   * @param chainId - Chain ID
+   * @param accountAddress - Account address (the delegated EOA)
+   * @param intent - Execution intent
+   * @returns Estimate response
+   */
+  async estimate(
+    chainId: number,
+    accountAddress: Address,
+    intent: ExecutionIntent
+  ): Promise<EstimateResponse> {
+    const response = await this.fetch('/estimate', {
+      method: 'POST',
+      body: JSON.stringify({
+        chainId,
+        accountAddress,
+        intent: {
+          nonce: intent.nonce.toString(),
+          deadline: intent.deadline.toString(),
+          target: intent.target,
+          value: intent.value.toString(),
+          data: intent.data,
+        },
+      }),
+    })
+    return response
+  }
+
+  /**
+   * Relay a signed intent
+   *
+   * @param chainId - Chain ID
+   * @param accountAddress - Account address (the delegated EOA)
+   * @param signedIntent - Signed execution intent
+   * @param paymentMode - Payment mode ('sponsored' or { token: Address })
+   * @param authorization - Optional EIP-7702 authorization for gasless onboarding
+   * @returns Relay response with transaction hash
+   *
+   * @example Gasless onboarding (delegate + execute in one tx)
+   * ```typescript
+   * // Get current nonce for authorization
+   * const txNonce = await publicClient.getTransactionCount({ address: accountAddress })
+   *
+   * // Sign EIP-7702 authorization
+   * const authorization = await account.sign7702Authorization({
+   *   contractAddress: delegateAddress,
+   *   chainId: 42161,
+   * }, txNonce)
+   *
+   * // Relay with authorization
+   * const result = await relayer.relay(
+   *   42161,
+   *   accountAddress,
+   *   signedIntent,
+   *   'sponsored',
+   *   authorization
+   * )
+   * ```
+   */
+  async relay(
+    chainId: number,
+    accountAddress: Address,
+    signedIntent: SignedIntent,
+    paymentMode: PaymentMode,
+    authorization?: Authorization7702
+  ): Promise<RelayResponse> {
+    const body: any = {
+      chainId,
+      accountAddress,
+      intent: {
+        nonce: signedIntent.intent.nonce.toString(),
+        deadline: signedIntent.intent.deadline.toString(),
+        target: signedIntent.intent.target,
+        value: signedIntent.intent.value.toString(),
+        data: signedIntent.intent.data,
+      },
+      ownerSignature: signedIntent.signature,
+      paymentMode,
+    }
+
+    // Include authorization for gasless onboarding if provided
+    if (authorization) {
+      body.authorization = {
+        chainId: authorization.chainId,
+        contractAddress: authorization.contractAddress,
+        nonce: authorization.nonce.toString(),
+        yParity: authorization.yParity,
+        r: authorization.r,
+        s: authorization.s,
+      }
+    }
+
+    const response = await this.fetch('/relay', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    })
+    return response
+  }
+
+  /**
+   * Get transaction status
+   *
+   * @param chainId - Chain ID
+   * @param txHash - Transaction hash
+   * @returns Status response
+   */
+  async getStatus(chainId: number, txHash: Hex): Promise<StatusResponse> {
+    const response = await this.fetch(`/status/${chainId}/${txHash}`)
+    return response
+  }
+
+  /**
+   * Make a fetch request to the relayer API
+   */
+  private async fetch(path: string, options?: RequestInit): Promise<any> {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout)
+
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        ...options,
+        headers: {
+          'Content-Type': 'application/json',
+          ...options?.headers,
+        },
+        signal: controller.signal,
+      })
+
+      const data = await response.json()
+
+      if (!response.ok) {
+        throw new Error(data.error || `Request failed: ${response.status}`)
+      }
+
+      return data
+    } finally {
+      clearTimeout(timeoutId)
+    }
+  }
+}
+
+/**
+ * Create a relayer client
+ *
+ * @param baseUrl - Relayer API base URL
+ * @returns Relayer client instance
+ */
+export function createRelayerClient(baseUrl: string): RelayerClient {
+  return new RelayerClient({ baseUrl })
+}

package/src/secure-client.ts

@@ -296,9 +296,9 @@ export class SecureKentuckySignerClient {
   /**
    * Sign a raw hash for EVM (signed request)
    */
-  async signHash(hash: Hex, chainId: number, token: string): Promise<Hex> {
+  async signHash(hash: Hex, token: string): Promise<Hex> {
     const response = await this.signEvmTransaction(
-      { tx_hash: hash, chain_id: chainId },
+      { tx_hash: hash },
       token
     )
     return response.signature.full

package/src/types.ts

@@ -66,16 +66,19 @@ export interface AccountInfoResponse {
 
 /**
  * EVM signature response from Kentucky Signer
+ *
+ * Note: v is always 27 or 28 (standard format).
+ * EIP-155 encoding should be applied by the caller when needed for legacy transactions.
  */
 export interface EvmSignatureResponse {
   success: boolean
   signature: {
     r: Hex
     s: Hex
+    /** v value: 27 or 28 (recovery_id + 27) */
     v: number
     full: Hex
   }
-  chain_id: number
   signer_address: string
 }
 
@@ -163,8 +166,6 @@ export interface ClientOptions {
 export interface SignEvmRequest {
   /** Transaction hash to sign (32 bytes, hex encoded) */
   tx_hash: Hex
-  /** Chain ID */
-  chain_id: number
 }
 
 /**