kentucky-signer-viem 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -61,16 +61,19 @@ 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.
  */
 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;
 }
 /**
@@ -142,8 +145,6 @@ interface ClientOptions {
 interface SignEvmRequest {
     /** Transaction hash to sign (32 bytes, hex encoded) */
     tx_hash: Hex;
-    /** Chain ID */
-    chain_id: number;
 }
 /**
  * Passkey registration options (for account creation)
@@ -745,7 +746,7 @@ declare class SecureKentuckySignerClient {
     /**
      * Sign a raw hash for EVM (signed request)
      */
-    signHash(hash: Hex, chainId: number, token: string): Promise<Hex>;
+    signHash(hash: Hex, token: string): Promise<Hex>;
     /**
      * Add password to account (signed request)
      */
@@ -794,6 +795,41 @@ type TwoFactorCallback = (requirements: {
     pinRequired: boolean;
     pinLength: number;
 }) => Promise<TwoFactorCodes | null | undefined>;
+/**
+ * Parameters for signing an EIP-7702 authorization
+ */
+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
+ */
+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;
+}
 /**
  * Options for creating a Kentucky Signer account
  */
@@ -814,13 +850,41 @@ interface KentuckySignerAccountOptions {
 /**
  * Extended account type with Kentucky Signer specific properties
  */
-interface KentuckySignerAccount extends LocalAccount<'kentuckySigner'> {
+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>;
 }
 /**
  * Create a custom Viem account backed by Kentucky Signer
@@ -941,9 +1005,9 @@ declare 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)
      */
     signEvmTransaction(request: SignEvmRequest, token: string): Promise<EvmSignatureResponse>;
     /**
@@ -952,11 +1016,10 @@ declare 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)
      */
-    signHash(hash: Hex, chainId: number, token: string): Promise<Hex>;
+    signHash(hash: Hex, token: string): Promise<Hex>;
     /**
      * Create a new account with passkey authentication
      *
@@ -1395,4 +1458,307 @@ declare function getJwtExpiration(token: string): number | null;
  */
 declare function formatError(error: unknown): string;
 
-export { type AccountCreationResponse, type AccountInfoExtendedResponse, type AccountInfoResponse, type AddGuardianRequest, type AddGuardianResponse, type AddPasskeyRequest, type AddPasskeyResponse, type AddPasswordRequest, type AddPasswordResponse, type ApiErrorResponse, type AuthConfig, type AuthResponse, type AuthResponseWithEphemeral, type AuthSession, type CancelRecoveryResponse, type ChallengeResponse, type ClientOptions, type CompleteRecoveryRequest, type CompleteRecoveryResponse, type CreatePasswordAccountRequest, EphemeralKeyManager, type EphemeralKeyPair, type EphemeralKeyStorage, type EvmSignatureResponse, type GetGuardiansResponse, type GuardianInfo, IndexedDBEphemeralKeyStorage, type InitiateRecoveryRequest, type InitiateRecoveryResponse, type KentuckySignerAccount, type KentuckySignerAccountOptions, KentuckySignerClient, type KentuckySignerConfig, KentuckySignerError, LocalStorageTokenStorage, MemoryEphemeralKeyStorage, MemoryTokenStorage, type PasskeyAuthOptions, type PasskeyCredential, type PasskeyRegistrationOptions, type PasswordAccountCreationOptions, type PasswordAuthOptions, type PasswordAuthRequest, type PinSetupRequest, type PinSetupResponse, type RecoveryStatusRequest, type RecoveryStatusResponse, type RemoveGuardianResponse, type RemovePasskeyResponse, type SecureClientOptions, SecureKentuckySignerClient, type SignEvmRequest, type SignEvmRequestWith2FA, type SignedPayload, type TokenStorage, type TotpEnableRequest, type TotpSetupResponse, type TwoFactorCallback, type TwoFactorCodes, type TwoFactorResponse, type TwoFactorStatusResponse, type TwoFactorVerifyResponse, type VerifyGuardianRequest, type VerifyGuardianResponse, authenticateWithPasskey, authenticateWithPassword, authenticateWithToken, base64UrlDecode, base64UrlEncode, bytesToHex, createAccountWithPassword, createClient, createKentuckySignerAccount, createSecureClient, createServerAccount, formatError, generateEphemeralKeyPair, getJwtExpiration, hexToBytes, isSessionValid, isValidAccountId, isValidEvmAddress, isWebAuthnAvailable, isWebCryptoAvailable, parseJwt, refreshSessionIfNeeded, registerPasskey, signPayload, verifyPayload, withRetry };
+/**
+ * Execution intent to be signed by the EOA owner
+ */
+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
+ */
+interface SignedIntent {
+    /** The execution intent */
+    intent: ExecutionIntent;
+    /** Owner's signature on the intent */
+    signature: Hex;
+}
+/**
+ * Parameters for creating an execution intent
+ */
+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;
+}
+/**
+ * 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',
+ * })
+ * ```
+ */
+declare function createExecutionIntent(params: CreateIntentParams): ExecutionIntent;
+/**
+ * Compute the hash of an execution intent
+ *
+ * @param intent - The execution intent
+ * @returns Intent hash
+ */
+declare function hashIntent(intent: ExecutionIntent): Hex;
+/**
+ * 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)
+ * ```
+ */
+declare function signIntent(account: KentuckySignerAccount, intent: ExecutionIntent): Promise<SignedIntent>;
+/**
+ * Compute combined hash for batch intents
+ *
+ * @param intents - Array of execution intents
+ * @returns Combined hash
+ */
+declare function hashBatchIntents(intents: ExecutionIntent[]): Hex;
+/**
+ * Sign multiple execution intents for batch execution
+ *
+ * @param account - Kentucky Signer account
+ * @param intents - Array of execution intents
+ * @returns Array of signed intents
+ */
+declare function signBatchIntents(account: KentuckySignerAccount, intents: ExecutionIntent[]): Promise<SignedIntent[]>;
+
+/**
+ * Payment mode for relaying
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+interface RelayResponse {
+    /** Whether the relay was successful */
+    success: boolean;
+    /** Transaction hash if successful */
+    txHash?: Hex;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Transaction status
+ */
+type TransactionStatus = 'pending' | 'confirmed' | 'failed';
+/**
+ * Status response
+ */
+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
+ */
+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!)
+ * ```
+ */
+declare class RelayerClient {
+    private baseUrl;
+    private timeout;
+    constructor(options: RelayerClientOptions);
+    /**
+     * Check if the relayer is healthy
+     */
+    health(): Promise<{
+        status: string;
+        relayer: Address;
+        timestamp: string;
+    }>;
+    /**
+     * Get the current nonce for an account
+     *
+     * @param chainId - Chain ID
+     * @param address - Account address
+     * @returns Current nonce as bigint
+     */
+    getNonce(chainId: number, address: Address): Promise<bigint>;
+    /**
+     * 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
+     */
+    estimate(chainId: number, accountAddress: Address, intent: ExecutionIntent): Promise<EstimateResponse>;
+    /**
+     * 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
+     * )
+     * ```
+     */
+    relay(chainId: number, accountAddress: Address, signedIntent: SignedIntent, paymentMode: PaymentMode, authorization?: Authorization7702): Promise<RelayResponse>;
+    /**
+     * Get transaction status
+     *
+     * @param chainId - Chain ID
+     * @param txHash - Transaction hash
+     * @returns Status response
+     */
+    getStatus(chainId: number, txHash: Hex): Promise<StatusResponse>;
+    /**
+     * Make a fetch request to the relayer API
+     */
+    private fetch;
+}
+/**
+ * Create a relayer client
+ *
+ * @param baseUrl - Relayer API base URL
+ * @returns Relayer client instance
+ */
+declare function createRelayerClient(baseUrl: string): RelayerClient;
+
+/**
+ * Kentucky Signer Viem Integration
+ *
+ * A custom Viem account implementation for signing EVM transactions
+ * using the Kentucky Signer service with passkey authentication.
+ *
+ * @packageDocumentation
+ */
+
+/** Alchemy's SemiModularAccount7702 implementation address (same across all EVM chains) */
+declare const ALCHEMY_SEMI_MODULAR_ACCOUNT_7702: "0x69007702764179f14F51cdce752f4f775d74E139";
+
+export { ALCHEMY_SEMI_MODULAR_ACCOUNT_7702, type AccountCreationResponse, type AccountInfoExtendedResponse, type AccountInfoResponse, type AddGuardianRequest, type AddGuardianResponse, type AddPasskeyRequest, type AddPasskeyResponse, type AddPasswordRequest, type AddPasswordResponse, type ApiErrorResponse, type AuthConfig, type AuthResponse, type AuthResponseWithEphemeral, type AuthSession, type CancelRecoveryResponse, type ChallengeResponse, type ClientOptions, type CompleteRecoveryRequest, type CompleteRecoveryResponse, type CreateIntentParams, type CreatePasswordAccountRequest, EphemeralKeyManager, type EphemeralKeyPair, type EphemeralKeyStorage, type EstimateResponse, type EvmSignatureResponse, type ExecutionIntent, type GetGuardiansResponse, type GuardianInfo, IndexedDBEphemeralKeyStorage, type InitiateRecoveryRequest, type InitiateRecoveryResponse, type KentuckySignerAccount, type KentuckySignerAccountOptions, KentuckySignerClient, type KentuckySignerConfig, KentuckySignerError, LocalStorageTokenStorage, MemoryEphemeralKeyStorage, MemoryTokenStorage, type PasskeyAuthOptions, type PasskeyCredential, type PasskeyRegistrationOptions, type PasswordAccountCreationOptions, type PasswordAuthOptions, type PasswordAuthRequest, type PaymentMode, type PinSetupRequest, type PinSetupResponse, type RecoveryStatusRequest, type RecoveryStatusResponse, type RelayResponse, RelayerClient, type RelayerClientOptions, type RemoveGuardianResponse, type RemovePasskeyResponse, type SecureClientOptions, SecureKentuckySignerClient, type SignAuthorizationParameters, type SignEvmRequest, type SignEvmRequestWith2FA, type SignedAuthorization, type SignedIntent, type SignedPayload, type StatusResponse, type TokenOption, type TokenStorage, type TotpEnableRequest, type TotpSetupResponse, type TransactionStatus, type TwoFactorCallback, type TwoFactorCodes, type TwoFactorResponse, type TwoFactorStatusResponse, type TwoFactorVerifyResponse, type VerifyGuardianRequest, type VerifyGuardianResponse, authenticateWithPasskey, authenticateWithPassword, authenticateWithToken, base64UrlDecode, base64UrlEncode, bytesToHex, createAccountWithPassword, createClient, createExecutionIntent, createKentuckySignerAccount, createRelayerClient, createSecureClient, createServerAccount, formatError, generateEphemeralKeyPair, getJwtExpiration, hashBatchIntents, hashIntent, hexToBytes, isSessionValid, isValidAccountId, isValidEvmAddress, isWebAuthnAvailable, isWebCryptoAvailable, parseJwt, refreshSessionIfNeeded, registerPasskey, signBatchIntents, signIntent, signPayload, verifyPayload, withRetry };