⚡️ zksync-js ⚡️

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

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:

viem adapter

npm install @matterlabs/zksync-js viem

ethers adapter

npm install @matterlabs/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 '@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)

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.

🤖 AI Instruction Map

For AI-assisted contribution workflows:

Path	Purpose
AGENTS.md	Repo-wide policy, boundaries, and required verification rules.
llm/	Canonical contributor contracts (architecture, API gate, testing, release, style).
.codex/config.toml	Codex multi-agent registry and role wiring.
.codex/agents/	Canonical role behavior (.toml) for explorer/planner/implementer/reviewer/tester/docs/release/api-sentinel.
agents/	Human-readable role summaries that mirror .codex/agents behavior.
.agents/skills/	Repo-scoped reusable skills for focused workflows (for example API gate, adapter parity, contract interaction patterns).

📜 License

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