⚡️ zksync-js ⚡️

TypeScript SDK for deposits, withdrawals, and RPC access across the Elastic Network

Note: This repository is a successor to the original ZKsync SDK, which can be found at dutterbutter/zksync-sdk.

✨ 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:

npm install @matter-labs/zksync-js viem

npm install @matter-labs/zksync-js ethers

⚡️ Quick-start

For exhaustive examples please refer to ./examples directory.

ETH deposit (ethers)

import { JsonRpcProvider, Wallet, parseEther } from 'ethers';
import { createEthersClient, createEthersSdk } from '@matter-labs/zksync-js/ethers';
import { ETH_ADDRESS } from '@matter-labs/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)

import { createPublicClient, createWalletClient, http, parseEther } from 'viem';
import { createViemClient, createViemSdk } from '@matter-labs/zksync-js/viem';
import { ETH_ADDRESS } from '@matter-labs/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
• Concepts – 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.