kentucky-signer-viem 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kentucky-signer-viem",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Custom Viem account integration for Kentucky Signer with passkey authentication",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/account.ts

@@ -8,11 +8,13 @@ import {
   type TransactionSerializable,
   type TypedData,
   type TypedDataDefinition,
+  type SignedAuthorizationList,
   hashMessage,
   hashTypedData,
   keccak256,
   serializeTransaction,
   toHex,
+  toRlp,
   concat,
   numberToHex,
 } from 'viem'
@@ -42,6 +44,66 @@ export type TwoFactorCallback = (requirements: {
   pinLength: number
 }) => Promise<TwoFactorCodes | null | undefined>
 
+/**
+ * EIP-7702 Magic byte used in authorization hash
+ * @see https://eips.ethereum.org/EIPS/eip-7702
+ */
+const EIP7702_MAGIC = '0x05' as const
+
+/**
+ * Parameters for signing an EIP-7702 authorization
+ */
+export interface SignAuthorizationParameters {
+  /** The contract address to delegate to */
+  contractAddress: Address
+  /** Chain ID (0 for all chains, defaults to client chain) */
+  chainId?: number
+  /** Nonce for the authorization (defaults to account's current nonce) */
+  nonce?: bigint
+  /**
+   * Whether the authorization will be executed by the signer themselves.
+   * If 'self', the nonce in the authorization will be incremented by 1
+   * over the transaction nonce.
+   */
+  executor?: 'self'
+}
+
+/**
+ * Signed EIP-7702 authorization
+ * Compatible with viem's SignedAuthorizationList
+ */
+export interface SignedAuthorization {
+  /** 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
+}
+
+/**
+ * Compute the hash for an EIP-7702 authorization
+ * Hash = keccak256(0x05 || rlp([chain_id, address, nonce]))
+ */
+function hashAuthorization(params: {
+  contractAddress: Address
+  chainId: number
+  nonce: bigint
+}): Hex {
+  const rlpEncoded = toRlp([
+    params.chainId === 0 ? '0x' : numberToHex(params.chainId),
+    params.contractAddress,
+    params.nonce === 0n ? '0x' : numberToHex(params.nonce),
+  ])
+  return keccak256(concat([EIP7702_MAGIC, rlpEncoded]))
+}
+
 /**
  * Options for creating a Kentucky Signer account
  */
@@ -63,13 +125,44 @@ export interface KentuckySignerAccountOptions {
 /**
  * Extended account type with Kentucky Signer specific properties
  */
-export interface KentuckySignerAccount extends LocalAccount<'kentuckySigner'> {
+export interface KentuckySignerAccount extends Omit<LocalAccount<'kentuckySigner'>, 'signAuthorization'> {
   /** Account ID */
   accountId: string
   /** Current session */
   session: AuthSession
   /** Update the session (e.g., after refresh) */
   updateSession: (session: AuthSession) => void
+  /**
+   * Sign an EIP-7702 authorization to delegate code to this account
+   *
+   * @param params - Authorization parameters
+   * @param nonce - Current account nonce (required if params.nonce not specified)
+   * @returns Signed authorization compatible with viem's authorizationList
+   *
+   * @example
+   * ```typescript
+   * // Get current nonce
+   * const nonce = await publicClient.getTransactionCount({ address: account.address })
+   *
+   * // Sign authorization
+   * const authorization = await account.sign7702Authorization({
+   *   contractAddress: '0x69007702764179f14F51cdce752f4f775d74E139', // Alchemy MA v2
+   *   chainId: 1,
+   *   executor: 'self', // Account will execute the tx
+   * }, nonce)
+   *
+   * // Send EIP-7702 transaction
+   * const hash = await walletClient.sendTransaction({
+   *   authorizationList: [authorization],
+   *   to: account.address,
+   *   data: initializeCalldata,
+   * })
+   * ```
+   */
+  sign7702Authorization: (
+    params: SignAuthorizationParameters,
+    nonce: bigint
+  ) => Promise<SignedAuthorization>
 }
 
 /**
@@ -132,20 +225,30 @@ export function createKentuckySignerAccount(
     return session.token
   }
 
+  /**
+   * Ensure a value is properly formatted as a Hex string with 0x prefix
+   */
+  function ensureHexPrefix(value: string): Hex {
+    return (value.startsWith('0x') ? value : `0x${value}`) as Hex
+  }
+
   /**
    * Sign a hash using Kentucky Signer and return full signature
    * Handles 2FA by detecting the error and calling the callback
+   *
+   * Note: v in returned signature is always 27 or 28 (standard format)
    */
-  async function signHash(hash: Hex, chainId: number): Promise<Hex> {
+  async function signHash(hash: Hex): Promise<Hex> {
     const token = await getToken()
 
     // First attempt without 2FA codes
     try {
       const response = await client.signEvmTransaction(
-        { tx_hash: hash, chain_id: chainId },
+        { tx_hash: hash },
         token
       )
-      return response.signature.full
+      // Ensure the signature has 0x prefix
+      return ensureHexPrefix(response.signature.full)
     } catch (err) {
       // Check if 2FA is required
       if (err instanceof KentuckySignerError && err.code === '2FA_REQUIRED' && on2FARequired) {
@@ -163,10 +266,11 @@ export function createKentuckySignerAccount(
 
         // Retry with 2FA codes
         const response = await client.signEvmTransactionWith2FA(
-          { tx_hash: hash, chain_id: chainId, totp_code: codes.totpCode, pin: codes.pin },
+          { tx_hash: hash, totp_code: codes.totpCode, pin: codes.pin },
           token
         )
-        return response.signature.full
+        // Ensure the signature has 0x prefix
+        return ensureHexPrefix(response.signature.full)
       }
       throw err
     }
@@ -175,19 +279,21 @@ export function createKentuckySignerAccount(
   /**
    * Sign a hash using Kentucky Signer and return signature components
    * Handles 2FA by detecting the error and calling the callback
+   *
+   * Note: v is always 27 or 28 (standard format, recovery_id + 27)
    */
-  async function signHashWithComponents(hash: Hex, chainId: number): Promise<{ r: Hex; s: Hex; v: number }> {
+  async function signHashWithComponents(hash: Hex): Promise<{ r: Hex; s: Hex; v: number }> {
     const token = await getToken()
 
     // First attempt without 2FA codes
     try {
       const response = await client.signEvmTransaction(
-        { tx_hash: hash, chain_id: chainId },
+        { tx_hash: hash },
         token
       )
       return {
-        r: response.signature.r,
-        s: response.signature.s,
+        r: ensureHexPrefix(response.signature.r),
+        s: ensureHexPrefix(response.signature.s),
         v: response.signature.v,
       }
     } catch (err) {
@@ -207,12 +313,12 @@ export function createKentuckySignerAccount(
 
         // Retry with 2FA codes
         const response = await client.signEvmTransactionWith2FA(
-          { tx_hash: hash, chain_id: chainId, totp_code: codes.totpCode, pin: codes.pin },
+          { tx_hash: hash, totp_code: codes.totpCode, pin: codes.pin },
           token
         )
         return {
-          r: response.signature.r,
-          s: response.signature.s,
+          r: ensureHexPrefix(response.signature.r),
+          s: ensureHexPrefix(response.signature.s),
           v: response.signature.v,
         }
       }
@@ -230,7 +336,7 @@ export function createKentuckySignerAccount(
      */
     async signMessage({ message }: { message: SignableMessage }): Promise<Hex> {
       const messageHash = hashMessage(message)
-      return signHash(messageHash, defaultChainId)
+      return signHash(messageHash)
     },
 
     /**
@@ -238,6 +344,9 @@ export function createKentuckySignerAccount(
      *
      * Serializes the transaction, hashes it, signs via Kentucky Signer,
      * and returns the signed serialized transaction.
+     *
+     * For legacy transactions, applies EIP-155 encoding (v = chainId * 2 + 35 + recoveryId)
+     * For modern transactions (EIP-1559, EIP-2930, etc.), uses yParity (0 or 1)
      */
     async signTransaction(
       transaction: TransactionSerializable
@@ -251,29 +360,37 @@ export function createKentuckySignerAccount(
       // Hash the serialized transaction
       const txHash = keccak256(serializedUnsigned)
 
-      // Sign the hash and get components directly from API
-      const { r, s, v } = await signHashWithComponents(txHash, chainId)
+      // Sign the hash - v is always 27 or 28 (recovery_id + 27)
+      const { r, s, v } = await signHashWithComponents(txHash)
+
+      // Convert v (27/28) to recovery ID (0/1)
+      const recoveryId = v - 27
 
-      // For EIP-1559 and EIP-2930 transactions, v is 0 or 1
-      // For legacy transactions, v is chainId * 2 + 35 + recovery
+      // Determine signature format based on transaction type
+      let signatureV: bigint
       let yParity: number
+
       if (
         transaction.type === 'eip1559' ||
         transaction.type === 'eip2930' ||
         transaction.type === 'eip4844' ||
         transaction.type === 'eip7702'
       ) {
-        yParity = v >= 27 ? v - 27 : v // Convert from 27/28 to 0/1 if needed
+        // Modern transactions use yParity directly (0 or 1)
+        yParity = recoveryId
+        signatureV = BigInt(yParity)
       } else {
-        // Legacy transaction - v already includes chain ID
-        yParity = v
+        // Legacy transaction - apply EIP-155 encoding
+        // v = chainId * 2 + 35 + recoveryId
+        signatureV = BigInt(chainId * 2 + 35 + recoveryId)
+        yParity = recoveryId
       }
 
       // Serialize with signature
       const serializedSigned = serializeTransaction(transaction, {
         r,
         s,
-        v: BigInt(yParity),
+        v: signatureV,
         yParity,
       } as any)
 
@@ -290,7 +407,7 @@ export function createKentuckySignerAccount(
       typedData: TypedDataDefinition<TTypedData, TPrimaryType>
     ): Promise<Hex> {
       const hash = hashTypedData(typedData)
-      return signHash(hash, defaultChainId)
+      return signHash(hash)
     },
   }) as KentuckySignerAccount
 
@@ -306,6 +423,49 @@ export function createKentuckySignerAccount(
     }
   }
 
+  /**
+   * Sign an EIP-7702 authorization
+   *
+   * This allows the EOA to delegate its code to a smart contract,
+   * enabling smart account features like batching and gas sponsorship.
+   */
+  account.sign7702Authorization = async (
+    params: SignAuthorizationParameters,
+    currentNonce: bigint
+  ): Promise<SignedAuthorization> => {
+    // Determine the nonce for the authorization
+    // If executor is 'self', increment by 1 because the tx will use currentNonce
+    const authNonce = params.executor === 'self'
+      ? currentNonce + 1n
+      : (params.nonce ?? currentNonce)
+
+    // Use provided chainId or default
+    const chainId = params.chainId ?? defaultChainId
+
+    // Compute the authorization hash
+    const authHash = hashAuthorization({
+      contractAddress: params.contractAddress,
+      chainId,
+      nonce: authNonce,
+    })
+
+    // Sign the hash using Kentucky Signer
+    // v is always 27 or 28 (recovery_id + 27)
+    const { r, s, v } = await signHashWithComponents(authHash)
+
+    // Convert v (27/28) to yParity (0/1) for EIP-7702
+    const yParity = v - 27
+
+    return {
+      chainId,
+      contractAddress: params.contractAddress,
+      nonce: authNonce,
+      yParity,
+      r,
+      s,
+    }
+  }
+
   return account
 }
 

package/src/client.ts

@@ -218,9 +218,9 @@ export class KentuckySignerClient {
   /**
    * Sign an EVM transaction hash
    *
-   * @param request - Sign request with tx_hash and chain_id
+   * @param request - Sign request with tx_hash
    * @param token - JWT token
-   * @returns Signature response with r, s, v components
+   * @returns Signature response with r, s, v components (v is always 27 or 28)
    */
   async signEvmTransaction(
     request: SignEvmRequest,
@@ -239,13 +239,12 @@ export class KentuckySignerClient {
    * Convenience method that wraps signEvmTransaction.
    *
    * @param hash - 32-byte hash to sign (hex encoded with 0x prefix)
-   * @param chainId - Chain ID
    * @param token - JWT token
    * @returns Full signature (hex encoded with 0x prefix)
    */
-  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/index.ts

@@ -15,8 +15,15 @@ export {
   type KentuckySignerAccountOptions,
   type TwoFactorCodes,
   type TwoFactorCallback,
+  // EIP-7702 types
+  type SignAuthorizationParameters,
+  type SignedAuthorization,
 } from './account'
 
+// EIP-7702 Constants
+/** Alchemy's SemiModularAccount7702 implementation address (same across all EVM chains) */
+export const ALCHEMY_SEMI_MODULAR_ACCOUNT_7702 = '0x69007702764179f14F51cdce752f4f775d74E139' as const
+
 // Client
 export {
   KentuckySignerClient,
@@ -127,3 +134,28 @@ export {
   formatError,
   withRetry,
 } from './utils'
+
+// Intent signing for relayer integration
+export {
+  createExecutionIntent,
+  signIntent,
+  signBatchIntents,
+  hashIntent,
+  hashBatchIntents,
+  type ExecutionIntent,
+  type SignedIntent,
+  type CreateIntentParams,
+} from './intent'
+
+// Relayer client
+export {
+  RelayerClient,
+  createRelayerClient,
+  type PaymentMode,
+  type TokenOption,
+  type EstimateResponse,
+  type RelayResponse,
+  type TransactionStatus,
+  type StatusResponse,
+  type RelayerClientOptions,
+} from './relayer-client'

package/src/intent.ts

@@ -0,0 +1,167 @@
+import {
+  type Address,
+  type Hex,
+  keccak256,
+  encodeAbiParameters,
+  parseAbiParameters,
+  encodePacked,
+} from 'viem'
+import type { KentuckySignerAccount } from './account'
+
+/**
+ * Execution intent to be signed by the EOA owner
+ */
+export interface ExecutionIntent {
+  /** Replay protection nonce */
+  nonce: bigint
+  /** Expiration timestamp (unix seconds) */
+  deadline: bigint
+  /** Contract to call */
+  target: Address
+  /** ETH value to send */
+  value: bigint
+  /** Calldata for the call */
+  data: Hex
+}
+
+/**
+ * Signed execution intent
+ */
+export interface SignedIntent {
+  /** The execution intent */
+  intent: ExecutionIntent
+  /** Owner's signature on the intent */
+  signature: Hex
+}
+
+/**
+ * Parameters for creating an execution intent
+ */
+export interface CreateIntentParams {
+  /** Account nonce (fetch from contract) */
+  nonce: bigint
+  /** Expiration timestamp (unix seconds) */
+  deadline?: bigint
+  /** Contract to call */
+  target: Address
+  /** ETH value to send */
+  value?: bigint
+  /** Calldata for the call */
+  data?: Hex
+}
+
+// EIP-712 type hash for ExecutionIntent
+const INTENT_TYPEHASH = keccak256(
+  encodePacked(
+    ['string'],
+    ['ExecutionIntent(uint256 nonce,uint256 deadline,address target,uint256 value,bytes data)']
+  )
+)
+
+/**
+ * Create an execution intent
+ *
+ * @param params - Intent parameters
+ * @returns Execution intent
+ *
+ * @example
+ * ```typescript
+ * const intent = createExecutionIntent({
+ *   nonce: 0n,
+ *   target: '0x...',
+ *   value: parseEther('0.1'),
+ *   data: '0x',
+ * })
+ * ```
+ */
+export function createExecutionIntent(params: CreateIntentParams): ExecutionIntent {
+  return {
+    nonce: params.nonce,
+    deadline: params.deadline ?? BigInt(Math.floor(Date.now() / 1000) + 3600), // 1 hour default
+    target: params.target,
+    value: params.value ?? 0n,
+    data: params.data ?? '0x',
+  }
+}
+
+/**
+ * Compute the hash of an execution intent
+ *
+ * @param intent - The execution intent
+ * @returns Intent hash
+ */
+export function hashIntent(intent: ExecutionIntent): Hex {
+  const dataHash = keccak256(intent.data)
+  return keccak256(
+    encodeAbiParameters(
+      parseAbiParameters('bytes32, uint256, uint256, address, uint256, bytes32'),
+      [INTENT_TYPEHASH, intent.nonce, intent.deadline, intent.target, intent.value, dataHash]
+    )
+  )
+}
+
+/**
+ * Sign an execution intent using a Kentucky Signer account
+ *
+ * @param account - Kentucky Signer account
+ * @param intent - The execution intent to sign
+ * @returns Signed intent
+ *
+ * @example
+ * ```typescript
+ * const account = useKentuckySignerAccount()
+ * const intent = createExecutionIntent({ nonce: 0n, target: '0x...' })
+ * const signedIntent = await signIntent(account, intent)
+ * ```
+ */
+export async function signIntent(
+  account: KentuckySignerAccount,
+  intent: ExecutionIntent
+): Promise<SignedIntent> {
+  // Compute intent hash
+  const intentHash = hashIntent(intent)
+
+  // Sign the hash as a message (will be recovered with ECDSA)
+  // Kentucky Signer returns signatures with v = 27 or 28 (standard format)
+  // which is directly compatible with OpenZeppelin's ECDSA.recover
+  const signature = await account.signMessage({
+    message: { raw: intentHash },
+  })
+
+  return {
+    intent,
+    signature,
+  }
+}
+
+/**
+ * Compute combined hash for batch intents
+ *
+ * @param intents - Array of execution intents
+ * @returns Combined hash
+ */
+export function hashBatchIntents(intents: ExecutionIntent[]): Hex {
+  const intentHashes = intents.map(hashIntent)
+  return keccak256(encodePacked(['bytes32[]'], [intentHashes]))
+}
+
+/**
+ * Sign multiple execution intents for batch execution
+ *
+ * @param account - Kentucky Signer account
+ * @param intents - Array of execution intents
+ * @returns Array of signed intents
+ */
+export async function signBatchIntents(
+  account: KentuckySignerAccount,
+  intents: ExecutionIntent[]
+): Promise<SignedIntent[]> {
+  const signedIntents: SignedIntent[] = []
+
+  for (const intent of intents) {
+    const signed = await signIntent(account, intent)
+    signedIntents.push(signed)
+  }
+
+  return signedIntents
+}

package/src/react/index.ts

@@ -30,3 +30,36 @@ export {
   useAddress,
   type UseWalletClientOptions,
 } from './hooks'
+
+// Relayer Hooks
+export {
+  useRelayIntent,
+  useTransactionStatus,
+  useEstimate,
+  useNonce,
+  type UseRelayIntentResult,
+  type UseTransactionStatusResult,
+  type UseEstimateResult,
+  type UseNonceResult,
+} from './relayer-hooks'
+
+// Re-export relayer types needed by hooks
+export {
+  RelayerClient,
+  createRelayerClient,
+  type PaymentMode,
+  type TokenOption,
+  type EstimateResponse,
+  type RelayResponse,
+  type TransactionStatus,
+  type StatusResponse,
+  type Authorization7702,
+} from '../relayer-client'
+
+// Re-export intent types needed by hooks
+export {
+  createExecutionIntent,
+  signIntent,
+  type ExecutionIntent,
+  type SignedIntent,
+} from '../intent'