> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://v3.viem.sh/api/mcp` to find what you need.

# Frequently Asked Questions

## Why Does Viem Use Module Namespaces?

Module namespaces keep runtime functions, types, and errors beside the concept that owns them. For
example, [`Actions.transaction`](/docs/actions) groups transaction Actions and their related errors.

The namespace includes Actions for estimating, preparing, signing, sending, retrieving, and
watching transactions.

```ts twoslash
// @noErrors
import { Actions } from 'viem'

Actions.transaction.
//                  ^|
```

The same pattern applies to [Accounts](/docs/accounts), [Clients](/docs/clients), and the Ox-backed
utilities exported from `viem/utils`.

This structure avoids collisions between similarly named APIs and supports discovery through editor
autocomplete.

## Should I Use Standalone Actions or Decorators?

Prefer standalone [Actions](/docs/actions) when you want dependencies to remain explicit, especially
in shared functions and libraries. Pass the Client as the first argument:

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })

const blockNumber = await Actions.block.getNumber(client)
// @log: 19868020n
```

Use a decorator when an application repeatedly uses the same group of Actions and benefits from
shorter method calls:

```ts twoslash
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({
  chain: mainnet,
  transport: http(),
}).extend(publicActions())

const blockNumber = await client.block.getNumber()
// @log: 19868020n
```

[`publicActions`](/docs/actions/public) and the other decorators bind the same Action
implementations and preserve the Client's chain, Account, and transport types.

## What Are Wallets, Accounts, and Signers?

A **wallet** is software or hardware that manages Accounts and often exposes a JSON-RPC provider.
An [Account](/docs/accounts) represents the Ethereum identity used by signing Actions.

A Local Account signs in your process. A JSON-RPC Account delegates signing to a provider, such as
a browser wallet.

**Signer** is a common ecosystem term, not a separate Viem abstraction. Represent signing authority
as an Account, then pass it to a Client or directly to an Action.

```ts twoslash
import { Account } from 'viem'

const localAccount = Account.fromPrivateKey('0x...')
const jsonRpcAccount = Account.from(
  '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
)
```

See [Local Accounts](/docs/accounts/local/private-key),
[JSON-RPC Accounts](/docs/accounts/json-rpc), and [Wallet Actions](/docs/actions/wallet) for the
corresponding setup patterns.

## Why Are Multiple Return Values Arrays?

Set `as` to `'Array'` to return multiple top-level contract outputs as an inferred tuple. The
values follow ABI order even when the outputs are named, so destructure them by position:

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abi } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const abi = Abi.from([
  'function reserves() view returns (uint256 reserve0, uint256 reserve1)',
])

const reserves = await Actions.contract.read(client, {
  abi,
  address: '0x0000000000000000000000000000000000000001',
  as: 'Array',
  functionName: 'reserves',
})
// @log: [1000000n, 2000000n]

const [reserve0, reserve1] = reserves
```

Single return values are returned directly rather than wrapped in a one-element array.

## How Do I Migrate from v2?

Follow the [v2 Migration Guide](/docs/v2-migration) for package entrypoints and migration examples.

Start with Client construction, Actions, decorators, Accounts, and Ox-backed utility namespaces.
Then use TypeScript errors to find application-specific call-shape changes.