@meshconnect/uwc-types 0.2.0

package/src/react-hooks.ts

@@ -0,0 +1,256 @@
+import type {
+  NetworkId,
+  Network,
+  ConnectionMode,
+  Session,
+  AvailableAddress,
+  TransactionRequest,
+  TransactionResult,
+  WalletError
+} from './index'
+
+// useConnection hook types
+
+/**
+ * WalletConnect connection interface for the useConnection hook
+ */
+export interface WalletConnectConnection {
+  /**
+   * Connects to the specified wallet using WalletConnect protocol
+   * @param networkId - Optional network ID to connect to. If not provided, uses the default network
+   * @returns Promise that resolves when connection is established
+   */
+  connect: (networkId?: NetworkId) => Promise<void>
+  /**
+   * The WalletConnect connection URI for QR code display
+   * Will be undefined if not using WalletConnect or if connection is already established
+   */
+  connectionURI: string | undefined
+  /**
+   * Indicates if the WalletConnect connection is currently being established
+   */
+  isLoading: boolean
+  /**
+   * Error from the last connection attempt, undefined if no error occurred
+   */
+  error: WalletError | undefined
+  /**
+   * Indicates if WalletConnect is currently available for use
+   * This depends on whether the wallet supports WalletConnect
+   */
+  available: boolean
+}
+
+/**
+ * Injected wallet connection interface for the useConnection hook
+ */
+export interface InjectedConnection {
+  /**
+   * Connects to the specified wallet using browser injection (MetaMask, Trust Wallet, etc.)
+   * @param networkId - Optional network ID to connect to. If not provided, uses the default network
+   * @returns Promise that resolves when connection is established
+   */
+  connect: (networkId?: NetworkId) => Promise<void>
+  /**
+   * Indicates if the injected wallet connection is currently being established
+   */
+  isLoading: boolean
+  /**
+   * Error from the last connection attempt, undefined if no error occurred
+   */
+  error: WalletError | undefined
+  /**
+   * Indicates if injected connection is currently available for use
+   */
+  available: boolean
+}
+
+/**
+ * Return type for the useConnection hook
+ * @example
+ * ```tsx
+ * const { walletConnect, injected } = useConnection('metamask')
+ *
+ * // Connect with WalletConnect
+ * await walletConnect.connect('eip155:1')
+ * console.log(walletConnect.connectionURI) // Display QR code
+ *
+ * // Connect with injected wallet
+ * await injected.connect('eip155:1')
+ * ```
+ */
+export interface UseConnectionReturn {
+  /**
+   * WalletConnect connection methods and state
+   */
+  walletConnect: WalletConnectConnection
+  /**
+   * Injected wallet connection methods and state
+   */
+  injected: InjectedConnection
+  /**
+   * Indicates if wallet detection has completed and the connector is ready to use
+   */
+  isReady: boolean
+}
+
+// useSession hook types
+
+/**
+ * Return type for the useSession hook
+ * Provides access to the current wallet session state
+ * @example
+ * ```tsx
+ * const { activeAddress, activeNetwork, session } = useSession()
+ *
+ * if (activeAddress) {
+ *   console.log(`Connected to ${activeNetwork?.name} with ${activeAddress}`)
+ * }
+ * ```
+ */
+export interface UseSessionReturn {
+  /**
+   * The complete session object containing all wallet connection state
+   */
+  session: Session
+  /**
+   * The currently connected wallet address, or null if not connected
+   */
+  activeAddress: string | null
+  /**
+   * The currently selected network, or null if not connected
+   */
+  activeNetwork: Network | null
+  /**
+   * List of networks available for the connected wallet
+   */
+  availableNetworks: Network[]
+  /**
+   * The active connection mode ('injected' or 'walletConnect'), or null if not connected
+   */
+  activeConnector: ConnectionMode | null
+  /**
+   * List of available addresses for the connected wallet
+   */
+  availableAddresses: AvailableAddress[]
+}
+
+// useSwitchNetwork hook types
+
+/**
+ * Return type for the useSwitchNetwork hook
+ * Provides network switching functionality with loading states
+ * @example
+ * ```tsx
+ * const { switchNetwork, isLoading, isWaitingForUserApproval } = useSwitchNetwork()
+ *
+ * const handleNetworkSwitch = async () => {
+ *   await switchNetwork('eip155:8453') // Switch to Base
+ *
+ *   if (isWaitingForUserApproval) {
+ *     console.log('Waiting for user to approve in wallet...')
+ *   }
+ * }
+ * ```
+ */
+export interface UseSwitchNetworkReturn {
+  /**
+   * Switches the connected wallet to the specified network
+   * @param networkId - The ID of the network to switch to (e.g., 'eip155:1' for Ethereum mainnet)
+   * @returns Promise that resolves when the network switch is complete
+   * @throws Error if network switch fails or is rejected by the user
+   */
+  switchNetwork: (networkId: NetworkId) => Promise<void>
+  /**
+   * Indicates if a network switch operation is currently in progress
+   */
+  isLoading: boolean
+  /**
+   * Indicates if the wallet is waiting for user approval to switch networks
+   * This depends on the wallet's metadata configuration (requiresUserApprovalOnNetworkSwitch)
+   */
+  isWaitingForUserApproval: boolean
+  /**
+   * Error from the last network switch attempt, undefined if no error occurred
+   */
+  error: WalletError | undefined
+}
+
+// useSignMessage hook types
+
+/**
+ * Return type for the useSignMessage hook
+ * Provides message signing functionality with loading state and signature result
+ * @example
+ * ```tsx
+ * const { signMessage, isLoading, signature } = useSignMessage()
+ *
+ * const handleSign = async () => {
+ *   const sig = await signMessage('Hello World')
+ *   console.log('Signature:', sig)
+ *   // The signature state will also contain the result
+ * }
+ * ```
+ */
+export interface UseSignMessageReturn {
+  /**
+   * Signs a message with the connected wallet
+   * @param message - The message to sign
+   * @returns Promise that resolves to the signature string
+   * @throws Error if no wallet is connected or signing fails
+   */
+  signMessage: (message: string) => Promise<string>
+  /**
+   * Indicates if a message signing operation is currently in progress
+   */
+  isLoading: boolean
+  /**
+   * The last signature result, undefined if no message has been signed yet
+   */
+  signature: string | undefined
+  /**
+   * Error from the last signing attempt, undefined if no error occurred
+   */
+  error: WalletError | undefined
+}
+
+// useTransaction hook types
+
+/**
+ * Return type for the useTransaction hook
+ * Provides transaction sending functionality with loading state and result
+ * @example
+ * ```tsx
+ * const { sendTransaction, isLoading, transactionResult } = useTransaction()
+ *
+ * const handleSend = async () => {
+ *   const result = await sendTransaction({
+ *     to: '0x...',
+ *     amount: BigInt('1000000000000000000'),
+ *     from: session.activeAddress
+ *   })
+ *   console.log('Transaction hash:', result.hash)
+ * }
+ * ```
+ */
+export interface UseTransactionReturn {
+  /**
+   * Sends a transaction with the connected wallet
+   * @param request - The transaction request object
+   * @returns Promise that resolves to the transaction result
+   * @throws Error if no wallet is connected or transaction fails
+   */
+  sendTransaction: (request: TransactionRequest) => Promise<TransactionResult>
+  /**
+   * Indicates if a transaction is currently being processed
+   */
+  isLoading: boolean
+  /**
+   * The last transaction result, undefined if no transaction has been sent yet
+   */
+  transactionResult: TransactionResult | undefined
+  /**
+   * Error from the last transaction attempt, undefined if no error occurred
+   */
+  error: WalletError | undefined
+}

package/src/session.ts

@@ -0,0 +1,17 @@
+import type { ConnectionMode } from './connection-mode'
+import type { Network, NetworkId } from './networks'
+import type { WalletMetadata } from './UWC-state'
+
+export interface AvailableAddress {
+  address: string
+  networkId: NetworkId
+}
+
+export interface Session {
+  connectionMode: ConnectionMode | null
+  activeNetwork: Network | null
+  activeAddress: string | null
+  availableNetworks: Network[]
+  activeWallet: WalletMetadata | null
+  availableAddresses: AvailableAddress[]
+}

package/src/signature.ts

@@ -0,0 +1,36 @@
+import type {
+  ExtensionInjectedProvider,
+  IntegratedBrowserInjectedProvider
+} from './UWC-state'
+
+/**
+ * Result interface for signature operations
+ */
+export interface SignatureResult {
+  signature: string
+  address: string
+}
+
+/**
+ * Error types for signature operations
+ */
+export interface SignatureError {
+  code: number
+  message: string
+}
+
+/**
+ * Signature service interface
+ */
+export interface SignatureService {
+  /**
+   * Sign a message with the connected wallet
+   * @param message The message to sign
+   * @param provider The wallet provider to use for signing
+   * @returns A promise that resolves to the signature result
+   */
+  signMessage(
+    message: string,
+    provider: ExtensionInjectedProvider | IntegratedBrowserInjectedProvider
+  ): Promise<SignatureResult>
+}

package/src/transactions.ts

@@ -0,0 +1,127 @@
+/**
+ * EVM Transaction Types
+ */
+
+/**
+ * Gas configuration for EVM transactions
+ */
+export interface EVMGasConfig {
+  gasLimit?: number | null
+  maxFeePerGas?: number | null
+  maxPriorityFeePerGas?: number | null
+}
+
+/**
+ * Request for native EVM token transfer (ETH, BNB, MATIC, etc.)
+ */
+export interface EVMNativeTransferRequest {
+  to: string
+  amount: bigint
+  from: string
+  gasConfig?: EVMGasConfig
+}
+
+/**
+ * Request for EVM smart contract interaction
+ */
+export interface EVMContractCallRequest {
+  contractAddress: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  abi: any[] // ethers.InterfaceAbi
+  functionName: string
+  args: unknown[]
+  from: string
+  value?: string // For payable functions (in wei)
+  gasConfig?: EVMGasConfig
+}
+
+/**
+ * Single call in a batch transaction
+ */
+export interface EVMBatchCall {
+  to: string
+  value: string
+  data?: string
+}
+
+/**
+ * Request for batch EVM transactions (EIP-5792)
+ */
+export interface EVMBatchTransactionRequest {
+  version: string
+  from: string
+  chainId: string
+  atomicRequired: boolean
+  calls: EVMBatchCall[]
+}
+
+/**
+ * EVM wallet capabilities
+ */
+export interface EVMCapabilities {
+  atomicBatch?: {
+    supported: boolean
+  }
+  paymasterService?: {
+    supported: boolean
+  }
+}
+
+/**
+ * Solana Transaction Types
+ */
+
+/**
+ * Request for native SOL transfer
+ */
+export interface SolanaNativeTransferRequest {
+  from: string
+  to: string
+  amount: bigint
+  blockhash: string
+}
+
+/**
+ * Configuration for Solana transactions (internal use)
+ */
+export interface SolanaTransactionConfig {
+  fromAddress: string
+  toAddress: string
+  amount: string | number
+  blockhash: string
+  // Token-specific
+  tokenMint?: string
+  tokenDecimals?: number
+  tokenProgram?: string
+  createATA?: boolean
+}
+
+/**
+ * Common Transaction Types
+ */
+
+/**
+ * Result of a transaction
+ */
+export type TransactionResult = string // Transaction hash
+
+/**
+ * Result of a batch transaction
+ */
+export interface BatchTransactionResult {
+  id: string
+  status: number
+  atomic: boolean
+  receipts: Array<{
+    transactionHash: string
+  }>
+}
+
+/**
+ * Generic transaction request that can be either EVM or Solana
+ */
+export type TransactionRequest =
+  | EVMNativeTransferRequest
+  | EVMContractCallRequest
+  | EVMBatchTransactionRequest
+  | SolanaNativeTransferRequest

package/src/wallet-connect-connector.ts

@@ -0,0 +1,12 @@
+/**
+ * Configuration for WalletConnect connector
+ */
+export interface WalletConnectConfig {
+  projectId?: string
+  metadata?: {
+    name: string
+    description: string
+    url: string
+    icons: string[]
+  }
+}