+
+
+
+
+
+
+#### Videos
+
+Use the HTML video element for self-hosted video content:
+
+
+
+Embed YouTube videos using iframe elements:
+
+
+
+#### Tooltips
+
+Example of tooltip usage:
+
+try* variants when you want to avoid exceptions and branch on
+ success/failure.
+err.message for logic. Use the typed fields on{' '}
+ err.envelope instead.
+client.zks (Bridgehub address, L2→L1 log proofs, receipts with l2ToL1Logs).
+group: API Reference / Core
+---
+
+### Standard Ethereum RPC (`eth_*`)
+
+Use your base library for all `eth_*` methods.
+The client.zks
+surface only covers ZKsync-specific RPC (zks\_\*).
+For standard Ethereum JSON-RPC (e.g., eth_call, eth_getLogs, eth_getBalance),
+call them through your chosen library (`ethers` or `viem`).
+
+## zks\_ Interface
+
+```ts
+interface ZksRpc {
+ getBridgehubAddress(): Promise;
+ getL2ToL1LogProof(txHash: Hex, index: number): PromiseSTATE error. Poll based on
+ your app’s cadence.
+args.l1, it will be connected.
+l1 for sends).
+l2.
+try* variants and branch on ok.
+0x…00 for ETH).
+approvalsNeeded is non-empty (ERC-20), create will include those
+ steps automatically.
+create throws a typed error. Prefer tryCreate to
+ avoid exceptions.
+try* variants if you want to avoid exceptions and work with result
+ objects.
+`createEthersClient({(l1, l2, signer)})`.
+deposits, withdrawals, and
+ convenience helpers.
+try\* variants on resources for result objects.
diff --git a/docs/api-reference/ethers/withdrawals.mdx b/docs/api-reference/ethers/withdrawals.mdx
new file mode 100644
index 0000000..80416a4
--- /dev/null
+++ b/docs/api-reference/ethers/withdrawals.mdx
@@ -0,0 +1,265 @@
+---
+title: Withdrawals
+description: L2 → L1 withdrawals for ETH and ERC-20 with quote, prepare, create, status, wait, and finalize helpers.
+group: SDK Reference / Ethers
+---
+
+## At a glance
+
+- **Resource:** `sdk.withdrawals`
+- **Typical flow:** `quote → create → wait({ for: 'l2' }) → wait({ for: 'ready' }) → finalize`
+- **Auto-routing:** ETH vs ERC-20 and base-token vs non-base handled internally
+- **Error style:** Throwing methods (`quote`, `prepare`, `create`, `status`, `wait`, `finalize`) + result variants (`tryQuote`, `tryPrepare`, `tryCreate`, `tryWait`, `tryFinalize`)
+
+## Import
+
+```ts
+import { JsonRpcProvider, Wallet, parseEther } from 'ethers';
+import { createEthersClient, createEthersSdk } 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 });
+const sdk = createEthersSdk(client);
+// sdk.withdrawals → WithdrawalsResource
+```
+
+## Quick start
+
+Withdraw **0.1 ETH** from L2 → L1 and finalize on L1:
+
+```ts
+const handle = await sdk.withdrawals.create({
+ token: ETH_ADDRESS, // ETH sentinel supported
+ amount: parseEther('0.1'),
+ to: await signer.getAddress(), // L1 recipient
+});
+
+// 1) L2 inclusion (adds l2ToL1Logs if available)
+await sdk.withdrawals.wait(handle, { for: 'l2' });
+
+// 2) Wait until finalizable (no side effects)
+await sdk.withdrawals.wait(handle, { for: 'ready', pollMs: 6000 });
+
+// 3) Finalize on L1 (no-op if already finalized)
+const { status, receipt: l1Receipt } = await sdk.withdrawals.finalize(handle.l2TxHash);
+```
+
+finalize directly; it will throw if not yet ready. Prefer `wait(..., { for: 'ready' })` to avoid that.
+create throws a typed error. Prefer tryCreate{' '}
+ for a result object.
+timeoutMs for long windows.
+finalize throws a typed STATE error. Use status(...) or `wait(..., { for: 'ready' })` first to avoid throws.
+`wait({ for: 'ready' })` then finalize; it avoids premature finalize calls.
+- **Approvals:** if withdrawing ERC-20 requires approvals, `create` will include those steps automatically.
diff --git a/docs/api-reference/introduction.mdx b/docs/api-reference/introduction.mdx
new file mode 100644
index 0000000..55495ab
--- /dev/null
+++ b/docs/api-reference/introduction.mdx
@@ -0,0 +1,127 @@
+---
+title: Introduction
+description: Public, typed API surface for the ZKsyncOS SDK — Incorruptible Financial Infrastructure.
+group: API Reference / Overview
+---
+
+## What is this?
+
+The **ZKsyncOS SDK** provides lightweight adapters for **ethers** and **viem** to build L1 ↔ L2 flows—**deposits** and **withdrawals**—with a small, focused API. You’ll work with:
+
+- Adapter-level **Clients** (providers/wallets, resolved addresses, convenience contracts)
+- High-level **SDKs** (resources for deposits & withdrawals + helpers)
+- ZKsync-specific **RPC** helpers (`client.zks.*`)
+- A consistent, typed **Error model** (`ZKsyncError`, `try*` results)
+
+## Quick start
+
+getBridgehubAddress, getL2ToL1LogProof, enhanced receipts.
+ ZKsyncError envelope and try* result helpers.
+ eth\_\* RPC** should be performed through your chosen base library (**ethers** / **viem**).
+ The SDK only adds ZKsync-specific RPC via client.zks.\* (e.g., getBridgehubAddress, getL2ToL1LogProof, enhanced receipts).
+
+- Every resource method has a try\* variant (e.g., tryCreate) that returns a result object instead of throwing.
+ When errors occur, the SDK throws ZKsyncError with a stable envelope (see Error model).
+
+- Address resolution comes from on-chain lookups and well-known constants. You can override addresses in the client constructor for forks/tests.
diff --git a/docs/api-reference/viem/client.mdx b/docs/api-reference/viem/client.mdx
new file mode 100644
index 0000000..8b809ba
--- /dev/null
+++ b/docs/api-reference/viem/client.mdx
@@ -0,0 +1,169 @@
+---
+title: ViemClient
+description: Low-level client for the Viem adapter. Carries viem public/wallet clients, resolves core contract addresses, and exposes typed contract instances.
+group: SDK Reference / Viem
+---
+
+## At a glance
+
+- **Factory:** `createViemClient({ l1, l2, l1Wallet, l2Wallet?, overrides? }) → ViemClient`
+- **What it provides:** cached core **addresses**, typed **contracts**, convenience **wallet access** (L2 wallet derivation), and ZKsync **RPC** bound to `l2`.
+- **When to use:** create this first; then pass into `createViemSdk(client)`.
+
+## Import
+
+```ts
+import { createViemClient } from '@dutterbutter/zksync-sdk/viem';
+```
+
+## Quick start
+
+```ts
+import { createPublicClient, createWalletClient, http } from "viem";
+
+// Public clients (reads)
+const l1 = createPublicClient({ transport: http(process.env.ETH_RPC!) });
+const l2 = createPublicClient({ transport: http(process.env.ZKSYNC_RPC!) });
+
+// Wallet clients (writes)
+const l1Wallet = createWalletClient({
+ account: /* your L1 Account */,
+ transport: http(process.env.ETH_RPC!),
+});
+
+// Optional dedicated L2 wallet. Required for L2 sends (withdrawals).
+const l2Wallet = createWalletClient({
+ account: /* can be same key as L1 */,
+ transport: http(process.env.ZKSYNC_RPC!),
+});
+
+const client = createViemClient({ l1, l2, l1Wallet, l2Wallet });
+
+// Resolve core addresses (cached)
+const addrs = await client.ensureAddresses();
+
+// Typed contracts (viem getContract)
+const { bridgehub, l1AssetRouter } = await client.contracts();
+```
+
+l1Wallet.account is required. If you omit l2Wallet, use{' '}
+ client.getL2Wallet(); it lazily reuses the L1 account over the L2 transport.
+account) used for L1 sends.
+getL2Wallet().
+account).
+l1Wallet).
+l2.
+try* variants and branch on ok.
+0x…00 for ETH).
+approvalsNeeded is non-empty (ERC-20), create will include those
+ steps automatically.
+create throws a typed error. Prefer tryCreate to
+ avoid exceptions.
+try* variants if you want to avoid exceptions and work with result
+ objects.
+l2Wallet to create withdrawals; add l1Wallet when you plan to finalize).
+`createViemClient({ l1, l2, l1Wallet?, l2Wallet? })`.
+deposits, withdrawals, and
+ convenience helpers.
+try\* variants on resources for result objects.
diff --git a/docs/api-reference/viem/withdrawals.mdx b/docs/api-reference/viem/withdrawals.mdx
new file mode 100644
index 0000000..74cad4b
--- /dev/null
+++ b/docs/api-reference/viem/withdrawals.mdx
@@ -0,0 +1,280 @@
+---
+title: Withdrawals
+description: L2 → L1 withdrawals for ETH and ERC-20 with quote, prepare, create, status, wait, and finalize helpers (Viem adapter).
+group: API Reference / Viem
+---
+
+## At a glance
+
+- **Resource:** `sdk.withdrawals`
+- **Typical flow:** `quote → create → wait({ for: 'l2' }) → wait({ for: 'ready' }) → finalize`
+- **Auto-routing:** ETH vs ERC-20 and base-token vs non-base handled internally
+- **Error style:** Throwing methods (`quote`, `prepare`, `create`, `status`, `wait`, `finalize`) + result variants (`tryQuote`, `tryPrepare`, `tryCreate`, `tryWait`, `tryFinalize`)
+
+## Import
+
+```ts
+import {
+ createPublicClient,
+ createWalletClient,
+ http,
+ parseEther,
+ type Account,
+ type Chain,
+ type Transport,
+ type WalletClient,
+} from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { createViemClient, createViemSdk } from '@dutterbutter/zksync-sdk/viem';
+
+const account = privateKeyToAccount(PRIVATE_KEY as `0x${string}`);
+const l1 = createPublicClient({ transport: http(L1_RPC) });
+const l2 = createPublicClient({ transport: http(L2_RPC) });
+const l1Wallet: WalletClientfinalize directly; it will throw if not yet ready. Prefer `wait(..., { for: 'ready' })` to avoid that.
+create throws a typed error. Prefer tryCreate{' '}
+ for a result object.
+timeoutMs for long windows.
+finalize throws a typed STATE error. Use status(...) or `wait(..., { for: 'ready' })` first to avoid throws.
+`wait({ for: 'ready' })` then finalize; it avoids premature finalize calls.
+- **Approvals:** if withdrawing ERC-20 requires approvals, `create` will include those steps automatically.
diff --git a/docs/book.toml b/docs/book.toml
deleted file mode 100644
index 1e197e4..0000000
--- a/docs/book.toml
+++ /dev/null
@@ -1,18 +0,0 @@
-[book]
-title = "ZKsync SDK"
-author = "Matter Labs"
-language = "en"
-multilingual = false
-src = "src"
-
-[build]
-build-dir = "book" # output folder (docs/book)
-
-[preprocessor.admonish]
-command = "mdbook-admonish"
-assets_version = "3.0.3" # do not edit: managed by `mdbook-admonish install`
-
-[output.html]
-additional-css = ["./mdbook-admonish.css"]
-default-theme = "light"
-preferred-dark-theme = "navy"
diff --git a/docs/changelog.mdx b/docs/changelog.mdx
new file mode 100644
index 0000000..a5975f3
--- /dev/null
+++ b/docs/changelog.mdx
@@ -0,0 +1,95 @@
+---
+title: Changelog
+description: New releases and improvements for the ZKsyncOS SDK.
+rss: true
+---
+
+
+ Extend viem and ethers with optimized L1↔L2 flows:
+ deposits, withdrawals, and clean status/wait helpers—tuned for the
+ Elastic Network and great DX.
+
npm i or pnpm add.
+ getBridgehubAddress, getL2ToL1LogProof.
+