feat: add new zks_rpc (#42)

Author: dutterbutter

docs/src/overview/index.md

@@ -39,8 +39,10 @@ Supports ETH, Custom Base Token, and ERC-20.
 ### ZKsync RPC Extensions
 
 * **`getBridgehubAddress`** (`zks_getBridgehubContract`) — resolve the canonical Bridgehub contract address.
+* **`getBytecodeSupplierAddress`** (`zks_getBytecodeSupplierContract`) — resolve the Bytecode Supplier contract address.
 * **`getL2ToL1LogProof`** (`zks_getL2ToL1LogProof`) — retrieve the log proof for an L2 → L1 transaction.
 * **`getReceiptWithL2ToL1`** — returns a standard Ethereum `TransactionReceipt` **augmented** with `l2ToL1Logs`.
+* **`getBlockMetadataByNumber`** (`zks_getBlockMetadataByNumber`) — fetch block metadata (pubdata price, native price, execution version).
 * **`getGenesis`** (`zks_getGenesis`) - returns Genesis json.
 
 ## What You’ll Find Here

docs/src/sdk-reference/core/rpc.md

@@ -1,6 +1,6 @@
 # zks_ RPC
 
-Public ZKsync `zks_*` RPC methods exposed on the adapters via `client.zks` (Bridgehub address, L2→L1 log proofs, receipts with `l2ToL1Logs`).
+Public ZKsync `zks_*` RPC methods exposed on the adapters via `client.zks` (Bridgehub address, Bytecode Supplier address, block metadata, L2→L1 log proofs, receipts with `l2ToL1Logs`).
 
 ## Standard Ethereum RPC (`eth_*`)
 
@@ -13,9 +13,11 @@ For standard Ethereum JSON-RPC (e.g., `eth_call`, `eth_getLogs`, `eth_getBalance
 ```ts
 interface ZksRpc {
   getBridgehubAddress(): Promise<Address>;
+  getBytecodeSupplierAddress(): Promise<Address>;
   getL2ToL1LogProof(txHash: Hex, index: number): Promise<ProofNormalized>;
   getReceiptWithL2ToL1(txHash: Hex): Promise<ReceiptWithL2ToL1 | null>;
-  getGenesis(): Promise<GenesisInfo>;
+  getBlockMetadataByNumber(blockNumber: number): Promise<BlockMetadata | null>;
+  getGenesis(): Promise<GenesisInput>;
 }
 ```
 
@@ -33,6 +35,16 @@ const addr = await client.zks.getBridgehubAddress();
 
 ---
 
+### `getBytecodeSupplierAddress() → Promise<Address>`
+
+Fetch the on-chain **Bytecode Supplier** contract address.
+
+```ts
+const addr = await client.zks.getBytecodeSupplierAddress();
+```
+
+---
+
 ### `getL2ToL1LogProof(txHash: Hex, index: number) → Promise<ProofNormalized>`
 
 Return a normalized proof for the **L2→L1 log** at `index` in `txHash`.
@@ -72,6 +84,34 @@ console.log(rcpt?.l2ToL1Logs); // always an array
 
 ---
 
+### `getBlockMetadataByNumber(blockNumber: number)`
+
+**What it does**
+Fetches per-block metadata used by the node (pubdata price, native price, execution version).
+Returns `null` if the block metadata is unavailable.
+Price fields are returned as `bigint`.
+
+**Example**
+
+```ts
+const meta = await client.zks.getBlockMetadataByNumber(123_456);
+if (meta) {
+  console.log(meta.pubdataPricePerByte, meta.nativePrice, meta.executionVersion);
+}
+```
+
+**Returns**
+
+```ts
+type BlockMetadata = {
+  pubdataPricePerByte: bigint;
+  nativePrice: bigint;
+  executionVersion: number;
+};
+```
+
+---
+
 ## Types (overview)
 
 ```ts
@@ -85,6 +125,12 @@ type ReceiptWithL2ToL1 = {
   // …standard receipt fields…
   l2ToL1Logs: unknown[];
 };
+
+type BlockMetadata = {
+  pubdataPricePerByte: bigint;
+  nativePrice: bigint;
+  executionVersion: number;
+};
 ```
 
 ---

docs/src/sdk-reference/index.md

@@ -92,7 +92,7 @@ const bridgehub = await client.zks.getBridgehubAddress();
 | [**Viem · Contracts**](./viem/contracts.md)         | Resolved addresses and connected core contracts.                                               |
 | [**Viem · Deposits**](./viem/deposits.md)           | L1 → L2 flow with quote, prepare, create, status, and wait.                                   |
 | [**Viem · Withdrawals**](./viem/withdrawals.md)     | L2 → L1 flow with quote, prepare, create, status, wait, and finalize.                         |
-| [**Core · ZK RPC**](./core/rpc.md)                  | ZKsync-specific RPC: `getBridgehubAddress`, `getL2ToL1LogProof`, enhanced receipts.           |
+| [**Core · ZK RPC**](./core/rpc.md)                  | ZKsync-specific RPC: `getBridgehubAddress`, `getBytecodeSupplierAddress`, `getBlockMetadataByNumber`, `getL2ToL1LogProof`. |
 | [**Core · Error model**](./core/errors.md)          | Typed `ZKsyncError` envelope and `try*` result helpers.                                       |
 
 ---
@@ -101,7 +101,7 @@ const bridgehub = await client.zks.getBridgehubAddress();
 
 > [!NOTE]
 > **Standard `eth_*` RPC** should always be performed through your chosen base library (**ethers** or **viem**).
-> The SDK only adds **ZKsync-specific** RPC methods via `client.zks.*` (e.g. `getBridgehubAddress`, `getL2ToL1LogProof`, `getGenesis`).
+> The SDK only adds **ZKsync-specific** RPC methods via `client.zks.*` (e.g. `getBridgehubAddress`, `getBytecodeSupplierAddress`, `getBlockMetadataByNumber`, `getGenesis`).
 
 * 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, structured envelope (see [Error model](./core/errors.md)).

src/core/rpc/__tests__/zks.test.ts

@@ -3,7 +3,7 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { describe, it, expect } from 'bun:test';
-import { createZksRpc, normalizeProof, normalizeGenesis } from '../zks';
+import { createZksRpc, normalizeProof, normalizeGenesis, normalizeBlockMetadata } from '../zks';
 import type { RpcTransport } from '../types';
 import { isZKsyncError } from '../../types/errors';
 
@@ -101,6 +101,33 @@ describe('rpc/zks.normalizeGenesis', () => {
   });
 });
 
+describe('rpc/zks.normalizeBlockMetadata', () => {
+  const sample = {
+    pubdata_price_per_byte: '0x7ea8ed4bb',
+    native_price: '0xf4240',
+    execution_version: 1,
+  };
+
+  it('normalizes snake-cased fields', () => {
+    const normalized = normalizeBlockMetadata(sample);
+    expect(normalized).toEqual({
+      pubdataPricePerByte: 0x7ea8ed4bbn,
+      nativePrice: 0xf4240n,
+      executionVersion: 1,
+    });
+  });
+
+  it('throws ZKsyncError on malformed response', () => {
+    try {
+      normalizeBlockMetadata(null);
+      throw new Error('expected to throw');
+    } catch (e) {
+      expect(isZKsyncError(e)).toBe(true);
+      expect(String(e)).toContain('Malformed block metadata response');
+    }
+  });
+});
+
 describe('rpc/zks.getBridgehubAddress', () => {
   it('returns a hex address when RPC responds with a 0x-prefixed string', async () => {
     const rpc = createZksRpc(
@@ -118,6 +145,25 @@ describe('rpc/zks.getBridgehubAddress', () => {
   });
 });
 
+describe('rpc/zks.getBytecodeSupplierAddress', () => {
+  it('returns a hex address when RPC responds with a 0x-prefixed string', async () => {
+    const rpc = createZksRpc(
+      fakeTransport({
+        zks_getBytecodeSupplierContract: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+      }),
+    );
+    const addr = await rpc.getBytecodeSupplierAddress();
+    expect(addr).toBe('0xabcdefabcdefabcdefabcdefabcdefabcdefabcd');
+  });
+
+  it('wraps unexpected response shape into ZKsyncError', () => {
+    const rpc = createZksRpc(fakeTransport({ zks_getBytecodeSupplierContract: 123 }));
+    return expect(rpc.getBytecodeSupplierAddress()).rejects.toThrow(
+      /Unexpected Bytecode Supplier address response/,
+    );
+  });
+});
+
 describe('rpc/zks.getL2ToL1LogProof', () => {
   it('returns normalized proof on success', async () => {
     const proof = {
@@ -197,3 +243,26 @@ describe('rpc/zks.getGenesis', () => {
     });
   });
 });
+
+describe('rpc/zks.getBlockMetadataByNumber', () => {
+  it('returns null when RPC returns null', async () => {
+    const rpc = createZksRpc(fakeTransport({ zks_getBlockMetadataByNumber: null }));
+    const out = await rpc.getBlockMetadataByNumber(123);
+    expect(out).toBeNull();
+  });
+
+  it('returns normalized block metadata', async () => {
+    const raw = {
+      pubdata_price_per_byte: '0x2a',
+      native_price: '0x2b',
+      execution_version: 3,
+    };
+    const rpc = createZksRpc(fakeTransport({ zks_getBlockMetadataByNumber: raw }));
+    const out = await rpc.getBlockMetadataByNumber(456);
+    expect(out).toEqual({
+      pubdataPricePerByte: 0x2an,
+      nativePrice: 0x2bn,
+      executionVersion: 3,
+    });
+  });
+});

src/core/rpc/types.ts

@@ -45,5 +45,11 @@ export type GenesisInput = {
   genesisRoot: Hex;
 };
 
+export type BlockMetadata = {
+  pubdataPricePerByte: bigint;
+  nativePrice: bigint;
+  executionVersion: number;
+};
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type RpcTransport = (method: string, params?: unknown[]) => Promise<any>;