Wallets

Wallets (Pro) support suites that send transactions, deploy contracts, or require on-chain state mutation.

Wallet pool model

Wallets are configured per chain and scoped to test usage.

Wallet types

OnchainProbe supports three wallet types for different key management strategies:

managed: keys generated and stored by OnchainProbe (currently the only type available)
imported: user-provided private keys stored encrypted
external_signer: delegated signing via external service

Wallets are currently created automatically when a suite requires them. Manual wallet creation from the dashboard is not yet available.

Wallet roles

System-level wallet roles (the WalletRole enum):

faucet: source of funds for auto-funding test wallets
test: general-purpose wallet for transaction execution

Suite templates may define named roles (e.g. “deployer”) that map to wallets with these system roles at runtime.

Claim and release mechanics

Before a suite run, the worker claims wallets from the pool. After the run completes, wallets are released back. Pool statuses:

available: wallet is idle and can be claimed
claimed: wallet is in use by an active run
funding: wallet is being topped up by the faucet

This prevents nonce collisions between concurrent runs.

Why scoped pools matter

Using dedicated test wallets prevents:

cross-suite nonce collisions
accidental spend from operational wallets
hard-to-debug shared-state interference

Funding your faucet wallet

The faucet wallet is the source of funds for all test wallets. Before running transaction-based suites, you need to send native tokens to the faucet address.

How to fund

Open Wallets (/chains/:chainId/wallets) for your chain.
Copy the faucet wallet address (displayed at the top of the page).
Send native tokens from an external wallet (MetaMask, hardware wallet, exchange, etc.) to that address.
Wait for the transaction to confirm on-chain.
Click the refresh button on the faucet card to update the displayed balance.

How much to fund

Start with a small amount. A reasonable starting balance depends on the chain’s gas costs:

Testnets with free faucets: 1-5 native tokens is plenty.
Low-gas L2s (Arbitrum, Base, Optimism): 0.01-0.1 ETH covers many test runs.
Mainnet Ethereum: keep it minimal. Even 0.005 ETH goes a long way for read-heavy suites.

The faucet auto-funds test wallets when their balance drops below the configured threshold, so keep the faucet balance above the sum of all test wallet funding targets.

Auto-funding behavior

If configured, wallet balances can be topped up when they drop below threshold.

Typical flow:

Suite run starts.
Wallet health/balance check runs.
If below threshold, faucet transfer is initiated.
Suite continues once funded.

Operational recommendations

Keep wallet infrastructure healthy with these practices:

separate wallet pools by environment (staging, prod-sim)
rotate test wallets on regular cadence
keep on-chain permissions minimal
sweep residual balances periodically

Failure patterns

Watch for these common wallet-related failures:

insufficient faucet balance
nonce gaps from out-of-band transactions
gas price spikes causing budget errors
unexpected chain congestion affecting timing assertions

Wallet setup checklist

Define per-suite wallet role requirements.
Provision wallets on the target chain.
Assign minimum balance thresholds.
Configure faucet source and refill policy.
Run a manual suite execution to validate funding path.

Balance policy guidance

Set funding thresholds that prevent mid-run failures:

Keep faucet wallets well-funded above operational floor.
Use smaller thresholds on high-frequency suites.
Alert when faucet wallet falls below operational floor.

Isolation strategy

Separate wallet pools by workload to prevent interference:

one pool for upgrade tests
one pool for continuous smoke checks
separate pools across staging and production-like environments

This reduces unexpected nonce and balance interactions across workflows.

Sweep strategy

Use sweep operations during maintenance windows:

disable impacted suites
sweep residual balances to treasury wallet
re-fund and re-enable suites

Security practices

avoid reusing operational treasury keys
rotate wallet credentials if exposure is suspected
use least-privilege key access for automation
log all funding and sweep actions in your change process