Smart Contract Wallets: Architecture, UserOperations, and a Reproducible Test Workflow

What a smart contract wallet actually is

A smart contract wallet, often called a smart account, is an on-chain account whose control logic is implemented as deployed bytecode. Funds sit at the contract address, and the contract decides whether a given action is authorized: it may check one signature, several signatures, a passkey, a session key with an expiry, or an arbitrary policy encoded by the developer. This is the core difference from an externally owned account, where possession of a private key is the only authorization primitive the protocol understands.

The practical consequence is that wallet behavior becomes upgradeable and programmable at the account level. Multisig approval thresholds, social recovery guardians, spending limits, and batched calls are all contract logic rather than protocol features. The tradeoff is that every one of those features is now attack surface: a bug in the account implementation, a misconfigured module, or an unsafe upgrade path can compromise funds even when the user's key is never exposed.

This article focuses on EVM smart accounts using ERC-4337, because that is the model most tooling and infrastructure providers target. Account abstraction on other runtimes, such as native account contracts on Starknet, follows the same mental model but replaces the bundler and EntryPoint machinery with runtime-level account semantics.

• Funds are held by contract code, not by a key-controlled address.
• Authorization is a contract decision, so it can be multi-party, time-bound, or policy-driven.
• Upgradeability and module systems add power and add risk at the same time.

Assumptions and prerequisites for the workflow

The procedure below assumes you have an EVM-compatible RPC endpoint for the target network, an account implementation address you want to inspect, and basic familiarity with JSON-RPC. You do not need a funded key to run the read-only verification steps; you do need one only if you intend to submit a real UserOperation.

Use a placeholder endpoint such as RPC_URL throughout and substitute your own provider URL. If you are still choosing infrastructure, the multi-chain RPC endpoints guide covers how endpoint behavior differs across networks, and OnFinality's API service describes managed access. For production workloads where bundler and node latency matter, review dedicated node options before committing to a shared endpoint.

The ERC-4337 mental model: UserOperations and the EntryPoint

ERC-4337 avoids changing the base protocol by introducing a higher-level transaction object called a UserOperation. A user or application signs a UserOperation describing the intended call, and a bundler packages one or more of them into an ordinary transaction sent to a singleton EntryPoint contract. The EntryPoint then calls the smart account's validation function, optionally calls a paymaster to cover gas, and finally executes the requested call.

This layering is what makes gas sponsorship and batching possible without protocol changes. It also means there are three distinct parties whose behavior you must reason about: the account contract that validates, the paymaster that agrees to pay, and the bundler that decides whether to include the operation. A failure at any layer surfaces as a rejected or dropped UserOperation, and the error text usually tells you which layer refused.

The account's nonce is managed by the EntryPoint rather than by the network, which is a frequent source of confusion. Two UserOperations from the same account can be valid with different EntryPoint nonces even though the underlying EOA nonce has not changed, and a stuck operation can block later ones until it is replaced or invalidated.

• Account contract: validates signatures and executes calls.
• Paymaster: optionally sponsors gas, subject to its own policy checks.
• Bundler: simulates, batches, and submits to the EntryPoint.
• EntryPoint: the singleton that orchestrates validation and execution.

Inspecting a smart account with curl

Before trusting any wallet integration, confirm that the address you are treating as a smart account actually has code and exposes the expected interface. The following read-only calls work against any standard EVM JSON-RPC endpoint. Replace RPC_URL and ACCOUNT_ADDRESS with your own values.

The first call returns bytecode if the address is a contract and 0x if it is an EOA. The second reads the account's EntryPoint reference if the implementation exposes a public getter; not every implementation does, so treat an empty result as inconclusive rather than as proof of misconfiguration.

curl -s RPC_URL \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getCode","params":["ACCOUNT_ADDRESS","latest"]}'

curl -s RPC_URL \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_call","params":[{"to":"ACCOUNT_ADDRESS","data":"0xENTRYPOINT_GETTER_SELECTOR"},"latest"]}'

Verifying a deployment with a scripted check

A single curl call is useful for spot checks, but a repeatable verification script is better for CI and for comparing behavior across endpoints. The Python example below checks that the address has code, reads its balance, and confirms the chain ID so you know which network you are actually talking to. It uses only the standard library and a placeholder endpoint.

Run this against each endpoint you plan to use in production. If two endpoints disagree on chain ID or return different bytecode for the same address at the same block, stop and investigate before deploying anything that depends on them.

import json, urllib.request

RPC_URL = "RPC_URL"
ACCOUNT = "ACCOUNT_ADDRESS"

def rpc(method, params):
    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}).encode()
    req = urllib.request.Request(RPC_URL, data=body, headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=10) as resp:
        payload = json.loads(resp.read())
    if "error" in payload:
        raise RuntimeError(payload["error"])
    return payload["result"]

chain_id = int(rpc("eth_chainId", []), 16)
code = rpc("eth_getCode", [ACCOUNT, "latest"])
balance = int(rpc("eth_getBalance", [ACCOUNT, "latest"]), 16)

print("chain_id:", chain_id)
print("is_contract:", code not in ("0x", "0x0"))
print("code_bytes:", (len(code) - 2) // 2)
print("balance_wei:", balance)

Expected verification result and how to read it

A correctly configured smart account should return a chain ID matching the network you intended, a non-empty bytecode string, and a balance consistent with your records. Record the code byte length and the block number at which you read it, because proxy implementations can change bytecode after an upgrade and a later mismatch is often the first sign that an account was upgraded unexpectedly.

When you run the same check across several endpoints, capture the results in a table so differences are visible rather than remembered. A template like the one below is enough; fill in your own measured values rather than relying on any published figure.

Latency in that table should be measured by your own client over several requests, not copied from a provider's marketing page. The point of the table is consistency: if one endpoint lags the others by many blocks, UserOperation simulation results will differ depending on which endpoint your bundler uses.

Simulating a UserOperation before you submit it

Most bundlers expose an RPC method to simulate a UserOperation, commonly eth_estimateUserOperationGas or a vendor-specific equivalent. Simulation catches signature failures, paymaster rejections, and out-of-gas conditions before you spend anything. The exact request shape depends on your bundler, so consult its documentation for field names; the structure below illustrates the pattern with placeholders.

Treat simulation as a required gate in your deployment pipeline. A UserOperation that fails simulation will almost certainly fail on-chain, and the error message from simulation is usually more specific than the on-chain revert reason.

curl -s BUNDLER_URL \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_estimateUserOperationGas",
    "params": [
      {
        "sender": "ACCOUNT_ADDRESS",
        "nonce": "0x0",
        "callData": "0xCALLDATA",
        "callGasLimit": "0x0",
        "verificationGasLimit": "0x0",
        "preVerificationGas": "0x0",
        "maxFeePerGas": "0x0",
        "maxPriorityFeePerGas": "0x0",
        "signature": "0xSIGNATURE"
      },
      "ENTRYPOINT_ADDRESS"
    ]
  }'

Troubleshooting common smart account failures

Failures cluster around a small number of causes. Signature validation errors usually mean the account expects a different signing scheme than the one your client used, or the UserOperation hash was computed over different fields than the account reconstructs. Paymaster rejections mean the sponsorship policy declined the operation, often because the target contract or selector is not on an allowlist, or because the account has exceeded a rate limit.

Nonce conflicts appear when a previous UserOperation is still pending in the bundler's mempool. Because the EntryPoint tracks nonces separately from the network, you must query the EntryPoint for the account's current nonce rather than reading eth_getTransactionCount on the EOA. If an operation is stuck, replace it with one that uses the same nonce and a higher fee, or wait for it to be dropped.

Gas estimation failures are frequently caused by state that changes between simulation and execution. A paymaster balance that is sufficient during simulation can be depleted by the time the bundle lands, and a token approval that exists at simulation can be revoked before inclusion. Build retries that re-simulate rather than blindly resubmitting.

• Signature error: confirm the signing scheme and the exact UserOperation hash fields.
• Paymaster error: check sponsorship policy, allowlists, and paymaster deposit.
• Nonce error: query the EntryPoint, not the EOA, for the current nonce.
• Gas error: re-simulate immediately before submission and handle state drift.

Limitations and tradeoffs of smart contract wallets

Smart accounts add a dependency layer that EOAs do not have. Your users depend on the account implementation's correctness, on the EntryPoint's continued availability, and on bundlers continuing to include their operations. An upgradeable account introduces an admin key or governance process that can change the rules after funds are deposited, which is a meaningful trust assumption even when the upgrade path is timelocked.

Gas costs are also different. Validation is more expensive than a plain signature check, and paymaster sponsorship shifts cost to whoever funds the paymaster rather than eliminating it. Batching can reduce per-call overhead, but the savings depend on how many calls you actually batch and on the calldata size of each.

Finally, portability is not automatic. A UserOperation signed for one chain is not valid on another unless the account and EntryPoint are deployed there and the signature scheme accounts for chain ID. Cross-chain replay protection is a property of the account implementation, not of ERC-4337 itself.

Next steps for building and operating smart accounts

Start by pinning the account implementation and EntryPoint addresses you intend to support, then run the verification script against every endpoint in your stack and record the results. From there, add simulation to your submission path, instrument bundler responses so failures are attributable to a specific layer, and monitor paymaster balances and deposit levels as first-class operational metrics.

If you are selecting infrastructure for the bundler and node layer, the RPC endpoints guide explains what to evaluate, and RPC pricing helps you model cost against expected UserOperation volume. For network-specific deployment details, browse the supported networks list before assuming a given chain supports the account implementation you have chosen. Concrete endpoint and provider recommendations are handled separately by RPC Assistant, so use this article for the methodology and that resource for the specific choice.