Skip to content

Commit

Permalink
feat: create api docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@itsacoyote
itsacoyote committed Mar 28, 2024
1 parent d3206fc commit fa9935c
Show file tree
Hide file tree
Showing 6 changed files with 518 additions and 0 deletions.
31 changes: 31 additions & 0 deletions content/20.api-reference/10.index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
title: Endpoint URLs
description:
---

zkSync Era seamlessly integrates with the Ethereum ecosystem. To achieve this integration,
we support not only the standard <a href="https://ethereum.org/en/developers/docs/apis/json-rpc/" target="_blank">Ethereum JSON-RPC API</a>
but also introduce L2-specific features that enhance functionality.

::callout
To ensure a seamless experience, we impose rate limits on both HTTPS and WebSocket APIs.
Generally, these limits are ample, ranging from 10 to 100 requests per second (RPS) per client.
::

## Mainnet

- **Network Name**: zkSync Era Mainnet
- **RPC URL**: https://mainnet.era.zksync.io
- **WebSocket URL**: wss://mainnet.era.zksync.io/ws
- **Chain ID**: 324
- **Currency Symbol**: ETH
- **Block Explorer URL**: https://explorer.zksync.io/

## Testnet

- **Network Name**: zkSync Era Testnet
- **RPC URL**: https://testnet.era.zksync.dev
- **WebSocket URL**: wss://testnet.era.zksync.dev/ws
- **Chain ID**: 280
- **Currency Symbol**: ETH
- **Block Explorer URL**: https://sepolia.explorer.zksync.io/
183 changes: 183 additions & 0 deletions content/20.api-reference/20.zks.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
---
title: ZKs JSON-RPC API
description:
github: https://github.com/matter-labs/zksync-era/blob/main/core/lib/web3_decl/src/namespaces/zks.rs
---

### `zks_estimateFee`

Estimates the fee for a given call request.

| **Parameter** | **Type** | **Description** |
|---------------|------------------|------------------------------------|
| `req` | `CallRequest` | The call request for fee estimation. |


### `zks_estimateGasL1ToL2`

Estimates the gas required for an L1 to L2 transaction.

| **Parameter** | **Type** | **Description** |
|---------------|------------------|-------------------------------------------|
| `req` | `CallRequest` | The call request for gas estimation. |

### `zks_getBridgehubContract`

Retrieves the bridge hub contract address.

### `zks_getMainContract`

Retrieves the main contract address.

### `zks_getTestnetPaymaster`

Retrieves the testnet paymaster address.

### `zks_getBridgeContracts`

Retrieves the addresses of bridge contracts.

### `zks_L1ChainId`

Retrieves the L1 chain ID.

### `zks_getConfirmedTokens`

Lists confirmed tokens. **Confirmed** in the method name means any token bridged to zkSync Era via the official bridge.

The tokens are returned in alphabetical order by their symbol. This means the token id is its
position in an alphabetically sorted array of tokens.

| **Parameter** | **Type** | **Description** |
|---------------|------------------|-------------------------------------|
| `from` | `uint32` | The token id from which to start. |
| `limit` | `uint8` | The maximum number of tokens to list. |

### `zks_getAllAccountBalances`

Gets all account balances for a given address.

| **Parameter** | **Type** | **Description** |
|---------------|------------------|-------------------------------------|
| `address` | `Address` | The account address. |

### `zks_getL2ToL1MsgProof`

Retrieves the proof for an L2 to L1 message.

| **Parameter** | **Type** | **Description** |
|---------------|------------------------|------------------------------------|
| `block` | `uint32` | The block number. |
| `sender` | `Address` | The sender's address. |
| `msg` | `bytes32` | The message hash. |
| `l2_log_position` | `number` | Optional. The log position in L2. |

### `zks_getL2ToL1LogProof`

Retrieves the log proof for an L2 to L1 transaction.

| **Parameter** | **Type** | **Description** |
|---------------|------------------------|------------------------------------|
| `tx_hash` | `bytes32` | The transaction hash. |
| `index` | `number` | Optional. Index of the log. |

### `zks_L1BatchNumber`

Retrieves the current L1 batch number.

### `zks_getBlockDetails`

Retrieves details for a given block.

- `committed`: The batch is closed and the state transition it creates exists on layer 1.

- `proven`: The batch proof has been created, submitted, and accepted on layer 1.

- `executed`: The batch state transition has been executed on L1; meaning the root state has been updated.

| **Parameter** | **Type** | **Description** |
|---------------|----------------------|-----------------------------------|
| `block_number`| `uint32` | The number of the block. |

### `zks_getTransactionDetails`

Retrieves details for a given transaction.

| **Parameter** | **Type** | **Description** |
|---------------|------------------|------------------------------------|
| `hash` | `bytes32` | The hash of the transaction. |

### `zks_getRawBlockTransactions`

Lists transactions in a block without processing them.

| **Parameter** | **Type** | **Description** |
|---------------|----------------------|-----------------------------------|
| `block_number`| `uint32` | The number of the block. |

### `zks_getL1BatchDetails`

Retrieves details for a given L1 batch.

| **Parameter** | **Type** | **Description** |
|---------------|------------------|------------------------------------|
| `batch` | `L1BatchNumber` | The L1 batch number. |

### `zks_getBytecodeByHash`

Retrieves the bytecode of a transaction by its hash.

| **Parameter** | **Type** | **Description** |
|---------------|------------------|------------------------------------|
| `hash` | `bytes32` | The hash of the transaction. |

### `zks_getL1GasPrice`

Retrieves the current L1 gas price.

### `zks_getFeeParams`

Retrieves the current fee parameters.

### `zks_getProtocolVersion`

Gets the protocol version.

| **Parameter** | **Type** | **Description** |
|---------------|------------------------|--------------------------------------|
| `version_id` | `u16` | Optional. Specific version ID. |

### `zks_getProof`

This method generates Merkle proofs for one or more storage values associated with a specific account,
accompanied by a proof of their authenticity. It verifies that these values remain unaltered.

Similar to Ethereum's `eth_getProof`, this method provides verification means under zkSync Era's distinct
Merkle tree architecture, noting several key differences:

- The retrieval of values and their respective proofs is determined by an L1 batch number instead of a block number.
- zkSync Era employs a different Merkle tree structure, necessitating a unique approach to proof verification.
Unlike Ethereum's two-level hexadecimal trie—where the top level maps to accounts and the bottom to
account storage slots—Era uses a single-level, full binary tree with 256-bit keys.
- In Ethereum, account-level values are mapped using specific combinations of account and storage keys. For example, to
store the code hash for account address A, it uses account `0x0000000000000000000000000000000000008002`
and a storage key generated by padding A's address. Conversely, zkSync Era's Merkle tree specifics are as follows:

**zkSync Era Merkle Tree Details:**

- The tree is a one-level, full binary tree, supporting 256-bit keys and 40-byte values.
- Keys are derived by reversing the output of `reversed(blake2s256([0_u8; 12] ++ account_address ++ storage_key))`,
where `account_address` is the 20-byte address, and `storage_key` is a 32-byte key from the account's storage.
The `++` operator denotes byte concatenation, and `reversed` inverts the byte sequence order.
- Values are structured as `big_endian(leaf_index) ++ storage_value`, with `leaf_index` marking
the 1-based index in entry order, and `storage_value` representing the 32-byte slot value.
- Empty tree entries are marked with 40 zero bytes (`[0_u8; 40]`).
- Leaf hashing utilizes `blake2s256` without tags, treating vacant leaves as `blake2s256([0_u8; 40])`.
- Internal node hashes are computed by concatenating the hashes of their child nodes, again using `blake2s256`
without tags: `blake2s256(left_child_hash ++ right_child_hash)`

| **Parameter** | **Type** | **Description** |
|---------------|------------------------|---------------------------------------|
| `address` | `Address` | The account to fetch storage values and proofs for.|
| `keys` | `bytes32[]` | The keys in the account. |
| `l1BatchNumber` | `number` | Number of the L1 batch specifying the point in time at which the requested values are returned. |
43 changes: 43 additions & 0 deletions content/20.api-reference/30.debug.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: Debug JSON-RPC API
description:
github: https://github.com/matter-labs/zksync-era/blob/main/core/lib/web3_decl/src/namespaces/debug.rs
---

### `debug_traceBlockByHash`

Traces all calls made from a specific block by its L2 hash.

| **Parameter** | **Type** | **Description** |
|---------------|------------------------|----------------------------------|
| `hash` | `H256` | The 32 byte hash defining the L2 block. |
| `options` | `TracerConfig` | Optional. See the <a href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig" target="_blank">TraceConfig documentation</a> for details. |

### `debug_traceBlockByNumber`

Traces all calls made from a specific block by its L2 block number.

| **Parameter** | **Type** | **Description** |
|---------------|------------------------|-----------------------------------|
| `block` | `BlockNumber` | The number of the block to trace. |
| `options` | `TracerConfig` | Optional. See the <a href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig" target="_blank">TraceConfig documentation</a> for details. |

### `debug_traceCall`

Traces a call made at a specific block, by block number or hash.

| **Parameter** | **Type** | **Description** |
|---------------|------------------------|----------------------------------------------|
| `request` | `CallRequest` | The call request to trace. |
| `block` | `BlockId` | Optional. The block identifier, by number or hash. |
| `options` | `TracerConfig` | Optional. See the <a href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig" target="_blank">TraceConfig documentation</a> for details. |

### `debug_traceTransaction`

Uses the <a href="https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#call-tracer" target="_block">EVM's `callTracer`</a>
to return a debug trace of a specific transaction given by its transaction hash.

| **Parameter** | **Type** | **Description** |
|---------------|------------------------|---------------------------------------|
| `tx_hash` | `H256` | The 32 byte hash of the transaction to trace. |
| `options` | `TracerConfig` | Optional. See the <a href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig" target="_blank">TraceConfig documentation</a> for details. |
Loading

0 comments on commit fa9935c

Please sign in to comment.