viem 0.3.1 → 0.3.2

package/src/clients/decorators/wallet.ts

@@ -44,6 +44,23 @@ export type WalletActions<
   TChain extends Chain | undefined = Chain | undefined,
   TAccount extends Account | undefined = Account | undefined,
 > = {
+  /**
+   * Adds an EVM chain to the wallet.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/addChain.html
+   * - JSON-RPC Methods: [`eth_addEthereumChain`](https://eips.ethereum.org/EIPS/eip-3085)
+   *
+   * @param args - {@link AddChainParameters}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { optimism } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   transport: custom(window.ethereum),
+   * })
+   * await client.addChain({ chain: optimism })
+   */
   addChain: (args: AddChainParameters) => Promise<void>
   /**
    * Deploys a contract to the network, given bytecode and constructor arguments.
@@ -51,7 +68,7 @@ export type WalletActions<
    * - Docs: https://viem.sh/docs/contract/deployContract.html
    * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/contracts/deploying-contracts
    *
-   * @param parameters - {@link DeployContractParameters}
+   * @param args - {@link DeployContractParameters}
    * @returns The [Transaction](https://viem.sh/docs/glossary/terms#transaction) hash. {@link DeployContractReturnType}
    *
    * @example
@@ -60,7 +77,7 @@ export type WalletActions<
    * import { mainnet } from 'viem/chains'
    *
    * const client = createWalletClient({
-   *   account = privateKeyToAccount('0x…'),
+   *   account: privateKeyToAccount('0x…'),
    *   chain: mainnet,
    *   transport: http(),
    * })
@@ -76,27 +93,397 @@ export type WalletActions<
   >(
     args: DeployContractParameters<TAbi, TChain, TAccount, TChainOverride>,
   ) => Promise<DeployContractReturnType>
+  /**
+   * Returns a list of account addresses owned by the wallet or client.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/getAddresses.html
+   * - JSON-RPC Methods: [`eth_accounts`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_accounts)
+   *
+   * @returns List of account addresses owned by the wallet or client. {@link GetAddressesReturnType}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const accounts = await client.getAddresses()
+   */
   getAddresses: () => Promise<GetAddressesReturnType>
+  /**
+   * Returns the chain ID associated with the current network.
+   *
+   * - Docs: https://viem.sh/docs/actions/public/getChainId.html
+   * - JSON-RPC Methods: [`eth_chainId`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_chainid)
+   *
+   * @returns The current chain ID. {@link GetChainIdReturnType}
+   *
+   * @example
+   * import { createWalletClient, http } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const chainId = await client.getChainId()
+   * // 1
+   */
   getChainId: () => Promise<GetChainIdReturnType>
+  /**
+   * Gets the wallets current permissions.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/getPermissions.html
+   * - JSON-RPC Methods: [`wallet_getPermissions`](https://eips.ethereum.org/EIPS/eip-2255)
+   *
+   * @returns The wallet permissions. {@link GetPermissionsReturnType}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const permissions = await client.getPermissions()
+   */
   getPermissions: () => Promise<GetPermissionsReturnType>
+  /**
+   * Requests a list of accounts managed by a wallet.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/requestAddresses.html
+   * - JSON-RPC Methods: [`eth_requestAccounts`](https://eips.ethereum.org/EIPS/eip-1102)
+   *
+   * Sends a request to the wallet, asking for permission to access the user's accounts. After the user accepts the request, it will return a list of accounts (addresses).
+   *
+   * This API can be useful for dapps that need to access the user's accounts in order to execute transactions or interact with smart contracts.
+   *
+   * @returns List of accounts managed by a wallet {@link RequestAddressesReturnType}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const accounts = await client.requestAddresses()
+   */
   requestAddresses: () => Promise<RequestAddressesReturnType>
+  /**
+   * Requests permissions for a wallet.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/requestPermissions.html
+   * - JSON-RPC Methods: [`wallet_requestPermissions`](https://eips.ethereum.org/EIPS/eip-2255)
+   *
+   * @param args - {@link RequestPermissionsParameters}
+   * @returns The wallet permissions. {@link RequestPermissionsReturnType}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const permissions = await client.requestPermissions({
+   *   eth_accounts: {}
+   * })
+   */
   requestPermissions: (
     args: RequestPermissionsParameters,
   ) => Promise<RequestPermissionsReturnType>
+  /**
+   * Creates, signs, and sends a new transaction to the network.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/sendTransaction.html
+   * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/transactions/sending-transactions
+   * - JSON-RPC Methods:
+   *   - JSON-RPC Accounts: [`eth_sendTransaction`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendtransaction)
+   *   - Local Accounts: [`eth_sendRawTransaction`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendrawtransaction)
+   *
+   * @param args - {@link SendTransactionParameters}
+   * @returns The [Transaction](https://viem.sh/docs/glossary/terms.html#transaction) hash. {@link SendTransactionReturnType}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const hash = await client.sendTransaction({
+   *   account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+   *   to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+   *   value: 1000000000000000000n,
+   * })
+   *
+   * @example
+   * // Account Hoisting
+   * import { createWalletClient, http } from 'viem'
+   * import { privateKeyToAccount } from 'viem/accounts'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   account: privateKeyToAccount('0x…'),
+   *   chain: mainnet,
+   *   transport: http(),
+   * })
+   * const hash = await client.sendTransaction({
+   *   to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+   *   value: 1000000000000000000n,
+   * })
+   */
   sendTransaction: <TChainOverride extends Chain | undefined>(
     args: SendTransactionParameters<TChain, TAccount, TChainOverride>,
   ) => Promise<SendTransactionReturnType>
+  /**
+   * Calculates an Ethereum-specific signature in [EIP-191 format](https://eips.ethereum.org/EIPS/eip-191): `keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))`.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/signMessage.html
+   * - JSON-RPC Methods:
+   *   - JSON-RPC Accounts: [`personal_sign`](https://docs.metamask.io/guide/signing-data.html#personal-sign)
+   *   - Local Accounts: Signs locally. No JSON-RPC request.
+   *
+   * With the calculated signature, you can:
+   * - use [`verifyMessage`](https://viem.sh/docs/utilities/verifyMessage) to verify the signature,
+   * - use [`recoverMessageAddress`](https://viem.sh/docs/utilities/recoverMessageAddress) to recover the signing address from a signature.
+   *
+   * @param args - {@link SignMessageParameters}
+   * @returns The signed message. {@link SignMessageReturnType}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const signature = await client.signMessage({
+   *   account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+   *   message: 'hello world',
+   * })
+   *
+   * @example
+   * // Account Hoisting
+   * import { createWalletClient, http } from 'viem'
+   * import { privateKeyToAccount } from 'viem/accounts'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   account: privateKeyToAccount('0x…'),
+   *   chain: mainnet,
+   *   transport: http(),
+   * })
+   * const signature = await client.signMessage({
+   *   message: 'hello world',
+   * })
+   */
   signMessage: (
     args: SignMessageParameters<TAccount>,
   ) => Promise<SignMessageReturnType>
+  /**
+   * Signs typed data and calculates an Ethereum-specific signature in [EIP-191 format](https://eips.ethereum.org/EIPS/eip-191): `keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))`.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/signTypedData.html
+   * - JSON-RPC Methods:
+   *   - JSON-RPC Accounts: [`eth_signTypedData_v4`](https://docs.metamask.io/guide/signing-data.html#signtypeddata-v4)
+   *   - Local Accounts: Signs locally. No JSON-RPC request.
+   *
+   * @param client - Client to use
+   * @param args - {@link SignTypedDataParameters}
+   * @returns The signed data. {@link SignTypedDataReturnType}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const signature = await client.signTypedData({
+   *   account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
+   *   domain: {
+   *     name: 'Ether Mail',
+   *     version: '1',
+   *     chainId: 1,
+   *     verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC',
+   *   },
+   *   types: {
+   *     Person: [
+   *       { name: 'name', type: 'string' },
+   *       { name: 'wallet', type: 'address' },
+   *     ],
+   *     Mail: [
+   *       { name: 'from', type: 'Person' },
+   *       { name: 'to', type: 'Person' },
+   *       { name: 'contents', type: 'string' },
+   *     ],
+   *   },
+   *   primaryType: 'Mail',
+   *   message: {
+   *     from: {
+   *       name: 'Cow',
+   *       wallet: '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826',
+   *     },
+   *     to: {
+   *       name: 'Bob',
+   *       wallet: '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB',
+   *     },
+   *     contents: 'Hello, Bob!',
+   *   },
+   * })
+   *
+   * @example
+   * // Account Hoisting
+   * import { createWalletClient, http } from 'viem'
+   * import { privateKeyToAccount } from 'viem/accounts'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   account: privateKeyToAccount('0x…'),
+   *   chain: mainnet,
+   *   transport: http(),
+   * })
+   * const signature = await client.signTypedData({
+   *   domain: {
+   *     name: 'Ether Mail',
+   *     version: '1',
+   *     chainId: 1,
+   *     verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC',
+   *   },
+   *   types: {
+   *     Person: [
+   *       { name: 'name', type: 'string' },
+   *       { name: 'wallet', type: 'address' },
+   *     ],
+   *     Mail: [
+   *       { name: 'from', type: 'Person' },
+   *       { name: 'to', type: 'Person' },
+   *       { name: 'contents', type: 'string' },
+   *     ],
+   *   },
+   *   primaryType: 'Mail',
+   *   message: {
+   *     from: {
+   *       name: 'Cow',
+   *       wallet: '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826',
+   *     },
+   *     to: {
+   *       name: 'Bob',
+   *       wallet: '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB',
+   *     },
+   *     contents: 'Hello, Bob!',
+   *   },
+   * })
+   */
   signTypedData: <
     TTypedData extends TypedData | { [key: string]: unknown },
     TPrimaryType extends string,
   >(
     args: SignTypedDataParameters<TTypedData, TPrimaryType, TAccount>,
   ) => Promise<SignTypedDataReturnType>
+  /**
+   * Switch the target chain in a wallet.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/switchChain.html
+   * - JSON-RPC Methods: [`eth_switchEthereumChain`](https://eips.ethereum.org/EIPS/eip-3326)
+   *
+   * @param args - {@link SwitchChainParameters}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { mainnet, optimism } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * await client.switchChain({ id: optimism.id })
+   */
   switchChain: (args: SwitchChainParameters) => Promise<void>
+  /**
+   * Adds an EVM chain to the wallet.
+   *
+   * - Docs: https://viem.sh/docs/actions/wallet/watchAsset.html
+   * - JSON-RPC Methods: [`eth_switchEthereumChain`](https://eips.ethereum.org/EIPS/eip-747)
+   *
+   * @param args - {@link WatchAssetParameters}
+   * @returns Boolean indicating if the token was successfully added. {@link WatchAssetReturnType}
+   *
+   * @example
+   * import { createWalletClient, custom } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const success = await client.watchAsset({
+   *   type: 'ERC20',
+   *   options: {
+   *     address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
+   *     decimals: 18,
+   *     symbol: 'WETH',
+   *   },
+   * })
+   */
   watchAsset: (args: WatchAssetParameters) => Promise<WatchAssetReturnType>
+  /**
+   * Executes a write function on a contract.
+   *
+   * - Docs: https://viem.sh/docs/contract/writeContract.html
+   * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/contracts/writing-to-contracts
+   *
+   * A "write" function on a Solidity contract modifies the state of the blockchain. These types of functions require gas to be executed, and hence a [Transaction](https://viem.sh/docs/glossary/terms) is needed to be broadcast in order to change the state.
+   *
+   * Internally, uses a [Wallet Client](https://viem.sh/docs/clients/wallet) to call the [`sendTransaction` action](https://viem.sh/docs/actions/wallet/sendTransaction) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData).
+   *
+   * __Warning: The `write` internally sends a transaction – it does not validate if the contract write will succeed (the contract may throw an error). It is highly recommended to [simulate the contract write with `contract.simulate`](https://viem.sh/docs/contract/writeContract.html#usage) before you execute it.__
+   *
+   * @param args - {@link WriteContractParameters}
+   * @returns A [Transaction Hash](https://viem.sh/docs/glossary/terms#hash). {@link WriteContractReturnType}
+   *
+   * @example
+   * import { createWalletClient, custom, parseAbi } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const hash = await client.writeContract({
+   *   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+   *   abi: parseAbi(['function mint(uint32 tokenId) nonpayable']),
+   *   functionName: 'mint',
+   *   args: [69420],
+   * })
+   *
+   * @example
+   * // With Validation
+   * import { createWalletClient, custom, parseAbi } from 'viem'
+   * import { mainnet } from 'viem/chains'
+   *
+   * const client = createWalletClient({
+   *   chain: mainnet,
+   *   transport: custom(window.ethereum),
+   * })
+   * const { request } = await client.simulateContract({
+   *   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+   *   abi: parseAbi(['function mint(uint32 tokenId) nonpayable']),
+   *   functionName: 'mint',
+   *   args: [69420],
+   * }
+   * const hash = await client.writeContract(request)
+   */
   writeContract: <
     TAbi extends Abi | readonly unknown[],
     TFunctionName extends string,

package/src/errors/version.ts

@@ -1 +1 @@
-export const version = '0.3.1'
+export const version = '0.3.2'

package/src/utils/rpc.ts

@@ -1,5 +1,4 @@
-import WebSocket from 'isomorphic-ws'
-import type { MessageEvent } from 'isomorphic-ws'
+import type { WebSocket, MessageEvent } from 'isomorphic-ws'
 import {
   HttpRequestError,
   RpcRequestError,
@@ -145,6 +144,7 @@ export async function getSocket(url_: string) {
   // If the socket already exists, return it.
   if (socket) return socket
 
+  const { WebSocket } = await import('isomorphic-ws')
   const webSocket = new WebSocket(url)
 
   // Set up a cache for incoming "synchronous" requests.