Quickstart ·
User Book ·
Contributing

✨ Features

- Adapters for both worlds – choose viem or ethers
- Deposits (L1 → L2) – ETH and ERC-20 transfers
- Withdrawals (L2 → L1) – full two-step flows with status tracking + finalization
- zks\_ RPC methods – typed helpers for logProofs, receipts, and bridgehub access
- Helper methods – helpers for l1-l2 token address mapping, contract address fetching
- Try-methods – no-throw style (tryCreate, tryWait) for UI / services

📦 Installation

Install the adapter you need:

⚡️ Quick-start

For exhaustive examples please refer to ./examples directory.

ETH deposit (ethers)

`ts
import { JsonRpcProvider, Wallet, parseEther } from 'ethers';
import { createEthersClient, createEthersSdk } from '@matterlabs/zksync-js/ethers';
import { ETH_ADDRESS } from '@matterlabs/zksync-js/core';

const l1Provider = new JsonRpcProvider('https://sepolia.infura.io/v3/...');
const l2Provider = new JsonRpcProvider('https://zksync-testnet.rpc');
const signer = new Wallet(process.env.PRIVATE_KEY!, l1Provider);

const client = await createEthersClient({ l1Provider, l2Provider, signer });
const sdk = createEthersSdk(client);

const deposit = await sdk.deposits.create({
token: ETH_ADDRESS,
amount: parseEther('0.01'),
to: signer.address,
});

await sdk.deposits.wait(handle, { for: 'l2' });
console.log('Deposit complete ✅');
`

ETH deposit (viem)

`ts
import { createPublicClient, createWalletClient, http, parseEther } from 'viem';
import { createViemClient, createViemSdk } from '@matterlabs/zksync-js/viem';
import { ETH_ADDRESS } from '@matterlabs/zksync-js/core';

const l1 = createPublicClient({ transport: http('https://sepolia.infura.io/v3/...') });
const l2 = createPublicClient({ transport: http('https://zksync-testnet.rpc') });
const l1Wallet = createWalletClient({
account,
transport: http('https://sepolia.infura.io/v3/...'),
});
const client = createViemClient({ l1, l2, l1Wallet });
const sdk = createViemSdk(client);

const handle = await sdk.deposits.create({
token: ETH_ADDRESS,
amount: parseEther('0.01'),
to: account.address,
});

await sdk.deposits.wait(handle, { for: 'l2' });
console.log('Deposit complete ✅');
``

> See Quickstart docs for full examples.

📚 Documentation

- User Book – guides, concepts, API docs
- How-to Guides – deposits, withdrawals, RPC helpers
- Mental Model – mental model, status vs wait, finalization

🤝 Contributing

Bug reports, fixes, and new features are welcome! Please read the contributing guide to get started.

📜 License

This project is licensed under the terms of the MIT License – see the LICENSE file for details.