kentucky-signer-viem 0.1.3 → 0.1.5

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { Address, LocalAccount, Chain, WalletClient, Transport } from 'viem';
+import { Address, LocalAccount, Hex, Chain, WalletClient, Transport } from 'viem';
 
 /**
  * Authenticated session with Kentucky Signer
@@ -29,16 +29,79 @@ interface TwoFactorCodes {
     /** PIN code */
     pin?: string;
 }
+/**
+ * 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;
+}
 /**
  * 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>;
 }
 
 /**
@@ -343,4 +406,403 @@ declare function useIsReady(): boolean;
  */
 declare function useAddress(): `0x${string}` | undefined;
 
-export { type KentuckySignerActions, type KentuckySignerContextValue, KentuckySignerProvider, type KentuckySignerProviderProps, type KentuckySignerState, type TwoFactorPromptState, type UseWalletClientOptions, useAddress, useIsReady, useKentuckySigner, useKentuckySignerAccount, useKentuckySignerContext, usePasskeyAuth, useSignMessage, useSignTypedData, useWalletClient };
+/**
+ * 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;
+/**
+ * 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>;
+
+/**
+ * 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;
+
+/**
+ * Hook for relaying intents through the relayer
+ */
+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)
+ *   }
+ * }
+ * ```
+ */
+declare function useRelayIntent(client: RelayerClient): UseRelayIntentResult;
+/**
+ * Hook for tracking transaction status
+ */
+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)
+ * }
+ * ```
+ */
+declare function useTransactionStatus(client: RelayerClient, chainId: number, txHash: Hex | null, pollInterval?: number): UseTransactionStatusResult;
+/**
+ * Hook for estimating gas and fees
+ */
+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)
+ * }
+ * ```
+ */
+declare function useEstimate(client: RelayerClient): UseEstimateResult;
+/**
+ * Hook for fetching account nonce
+ */
+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
+ */
+declare function useNonce(client: RelayerClient, chainId: number, address: Address | null): UseNonceResult;
+
+export { type Authorization7702, type EstimateResponse, type ExecutionIntent, type KentuckySignerActions, type KentuckySignerContextValue, KentuckySignerProvider, type KentuckySignerProviderProps, type KentuckySignerState, type PaymentMode, type RelayResponse, RelayerClient, type SignedIntent, type StatusResponse, type TokenOption, type TransactionStatus, type TwoFactorPromptState, type UseEstimateResult, type UseNonceResult, type UseRelayIntentResult, type UseTransactionStatusResult, type UseWalletClientOptions, createExecutionIntent, createRelayerClient, signIntent, useAddress, useEstimate, useIsReady, useKentuckySigner, useKentuckySignerAccount, useKentuckySignerContext, useNonce, usePasskeyAuth, useRelayIntent, useSignMessage, useSignTypedData, useTransactionStatus, useWalletClient };