EthersClient

Low-level client for the Ethers adapter. Carries providers/signer, resolves core contract addresses, and exposes connected ethers.Contract instances.

At a glance

• Factory: createEthersClient({ l1, l2, signer, overrides? }) → EthersClient
• What it provides: cached core addresses, connected contracts, L2-bound ZKsync RPC (zks), and a signer force-bound to L1.
• When to use: create this first; then pass into createEthersSdk(client).

Import

import { createEthersClient } from '@dutterbutter/zksync-sdk/ethers';

Quick start

import { JsonRpcProvider, Wallet } from 'ethers';
import { createEthersClient } from '@dutterbutter/zksync-sdk/ethers';

const l1 = new JsonRpcProvider(process.env.ETH_RPC!);
const l2 = new JsonRpcProvider(process.env.ZKSYNC_RPC!);
const signer = new Wallet(process.env.PRIVATE_KEY!, l1);

const client = createEthersClient({ l1, l2, signer });

// Resolve core addresses (cached)
const addrs = await client.ensureAddresses();

// Connected contracts
const { bridgehub, l1AssetRouter } = await client.contracts();

The signer is force-bound to the L1 provider to make L1 finalization flows work out of the box.

createEthersClient(args) → EthersClient

Returns: EthersClient

EthersClient interface

kind · 'ethers'

Adapter discriminator.

l1 · ethers.AbstractProvider

Public L1 provider.

l2 · ethers.AbstractProvider

Public L2 (ZKsync) provider.

signer · ethers.Signer

Signer (bound to l1 for sends).

zks · ZksRpc

ZKsync-specific RPC surface bound to l2.

Methods

ensureAddresses() → Promise<ResolvedAddresses>

Resolve and cache core contract addresses from chain state (merges any overrides).

const a = await client.ensureAddresses();
/*
{
  bridgehub, l1AssetRouter, l1Nullifier, l1NativeTokenVault,
  l2AssetRouter, l2NativeTokenVault, l2BaseTokenSystem
}
*/

contracts() → Promise<{ ...contracts }>

Return connected ethers.Contract instances for all core contracts.

const c = await client.contracts();
const bh = c.bridgehub; // call bh.getAddress(), bh.interface, bh.functions.*, etc.

refresh(): void

Clear cached addresses/contracts. Subsequent calls re-resolve.

client.refresh();
await client.ensureAddresses();

baseToken(chainId: bigint) → Promise<Address>

Return the L1 base-token address for a given L2 chain via Bridgehub.baseToken(chainId).

const base = await client.baseToken(324n /* e.g., Era */);

Types

ResolvedAddresses

type ResolvedAddresses = {
  bridgehub: Address;
  l1AssetRouter: Address;
  l1Nullifier: Address;
  l1NativeTokenVault: Address;
  l2AssetRouter: Address;
  l2NativeTokenVault: Address;
  l2BaseTokenSystem: Address;
};

Notes & pitfalls

• Provider roles: l1 is used for L1 lookups and finalization sends; l2 is used for ZKsync reads/RPC via zks.
• Signer binding: The signer is connected to l1 to ensure L1 transactions (e.g., finalize) succeed without extra wiring.
• Caching: ensureAddresses() and contracts() are cached. Call refresh() after network changes or when using new overrides.
• Overrides: For forks or custom deployments, pass overrides at construction; they are merged with on-chain resolution.