docs: update docs and readme (#62)

README.md

@@ -12,6 +12,7 @@ This repository is a monorepo consisting of 4 packages and 1 app:
 -   [`@zkchainhub/shared`](./packages/shared): A library for shared configurations, constants, types, etc.
 -   [`@zkchainhub/chain-providers`](./packages/chain-providers): A library that provides abstracted services over Viem providers to query blockchain data
 -   [`@zkchainhub/pricing`](./packages/pricing): An extensible library that provides Pricing services to fetch token prices. Currently, only Coingecko provider is developed
+-   [`@zkchainhub/metadata`](./packages/metadata): A library that exposes different providers for fetching chains and tokens metadata.
 -   [`@zkchainhub/metrics`](./packages/metrics): A library that provides different aggregated metrics from the ZKsync ecosystem and ZK chains.
 -   [`@zkchainhub/api`](./apps/api): An Express server that exposes an API where you can fetch information about ZKsync ecosystem and their chains, using the before mentioned libraries
 
@@ -48,16 +49,7 @@ $ pnpm build
 
 ## ⚙️ Setting up env variables
 
--   Inside `apps/api` folder, create `.env` file and copy paste `.env.example` content in there.
-
-```
-$ cd apps/api && cp .env.example .env
-```
-
--   Set up `L1_RPC_URLS` as CSV list of RPC URLs. For example, `https://eth.llamarpc.com,https://rpc.flashbots.net/fast`. You can check [Chainlist](https://chainlist.org/) for a list of public RPCs
--   Set up `L2_RPC_URLS` as CSV list of RPC URLs. For example, `https://mainnet.era.zksync.io`. You can check [Chainlist](https://chainlist.org/) for a list of public RPCs
--   Set `COINGECKO_API_KEY`, `COINGECKO_BASE_URL` and `COINGECKO_API_KEY` depending on your API plan. You can get an API Key creating an account on [Coingecko's site](https://www.coingecko.com/en/api)
--   (Optionally) Set `PORT` on which API is made available. By default is port 3000
+-   Follow the instructions for `apps/api` on [API's README](./apps/api/README.md)
 
 ## Running the app
 
@@ -116,3 +108,7 @@ ZKchainHub was built with ❤️ by [Wonderland](https://defi.sucks).
 Wonderland is a team of top Web3 researchers, developers, and operators who believe that the future needs to be open-source, permissionless, and decentralized.
 
 [DeFi sucks](https://defi.sucks), but Wonderland is here to make it better.
+
+## License
+
+This project is licensed under the MIT License. See the [`LICENSE`](./LICENSE) file for details.

apps/api/README.md

@@ -0,0 +1,85 @@
+# ZKchainHub API
+
+## Overview
+
+The `@zkchainhub/api` app is an Express server that exposes an API where you can fetch information about ZKsync ecosystem and their chains.
+
+## 📋 Prerequisites
+
+-   Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed.
+
+## Installation
+
+```bash
+$ pnpm install
+```
+
+## Building
+
+To build the monorepo packages, run:
+
+```bash
+$ pnpm build
+```
+
+## ⚙️ Setting up env variables
+
+-   Create `.env` file and copy paste `.env.example` content in there.
+
+```
+$ cp .env.example .env
+```
+
+Available options:
+| Name | Description | Default | Required | Notes |
+|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------|-----------|----------------------------------|-----------------------------------------------------------------|
+| `PORT` | Port on which API is made available | 3000 | No | |
+| `ENVIRONMENT` | Environment we are using (`'mainnet'`, `'testnet'`, `'local'`) | 'mainnet' | No | |
+| `BRIDGE_HUB_ADDRESS` | Bridge Hub address | N/A | Yes | |
+| `SHARED_BRIDGE_ADDRESS` | Shared Bridge address | N/A | Yes | |
+| `STATE_MANAGER_ADDRESSES` | CSV list of State manager addresses | N/A | Yes | |
+| `L1_RPC_URLS` | CSV list of RPC URLs. For example, `https://eth.llamarpc.com,https://rpc.flashbots.net/fast` | N/A | Yes | You can check [Chainlist](https://chainlist.org/) for a list of public RPCs |
+| `PRICING_SOURCE` | Pricing source to use (`'dummy'`, `'coingecko'`) | 'dummy' | No | |
+| `DUMMY_PRICE` | Price for dummy pricing source | undefined | No | Only applicable if `PRICING_SOURCE` is `'dummy'` |
+| `COINGECKO_API_KEY` | API key for CoinGecko | N/A | If `'coingecko'` is selected | You can get an API key by creating an account on [CoinGecko's site](https://www.coingecko.com/en/api) |
+| `COINGECKO_BASE_URL` | Base URL for CoinGecko | N/A | If `'coingecko'` is selected | |
+| `COINGECKO_API_TYPE` | CoinGecko API Type (`'demo'` or `'pro'`) | N/A | If `'coingecko'` is selected | |
+| `METADATA_SOURCE` | Metadata source to use (`'github'`, `'local'`, `'static'`) | N/A | Yes | |
+| `METADATA_TOKEN_URL` | Metadata tokens URL | N/A | If `METADATA_SOURCE` is `'github'` | |
+| `METADATA_CHAIN_URL` | Metadata chains URL | N/A | If `METADATA_SOURCE` is `'github'` | |
+| `METADATA_TOKEN_JSON_PATH` | Metadata tokens JSON file path | N/A | If `METADATA_SOURCE` is `'local'` | See examples in `packages/metadata` |
+| `METADATA_CHAIN_JSON_PATH` | Metadata chain JSON file path | N/A | If `METADATA_SOURCE` is `'local'` | See examples in `packages/metadata` |
+
+## Running the app
+
+```bash
+# development watch mode
+$ pnpm run dev
+
+# production mode
+$ pnpm run start
+
+```
+
+Verify that ZKchainHub API is running on http://localhost:3000 (or the port specified)
+
+## Test
+
+```bash
+# unit tests
+$ pnpm run test
+
+# test coverage
+$ pnpm run test:cov
+```
+
+## API
+
+### Metrics routes
+
+-   `GET /metrics/ecosystem`: Retrieves overall ecosystem metrics
+-   `GET /metrics/zkchain/:chainId`: Retrieves chain specific metrics
+
+## Docs
+
+Locally Swagger docs are available at http://localhost:3000/docs

packages/chain-providers/README.md

@@ -0,0 +1,90 @@
+# ZKchainHub Chain Providers package
+
+## Overview
+
+The `@zkchainhub/chain-providers` package provides wrappers of the `Viem` library to interact with EVM-based blockchains and ZK chains of the ZKsync ecosystem.
+
+## 📋 Prerequisites
+
+-   Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed.
+
+## Installation
+
+```bash
+$ pnpm install
+```
+
+## Building
+
+To build the monorepo packages, run:
+
+```bash
+$ pnpm build
+```
+
+## Test
+
+```bash
+# unit tests
+$ pnpm run test
+
+# test coverage
+$ pnpm run test:cov
+```
+
+## Usage
+
+### Importing the Package
+
+You can import the package in your TypeScript or JavaScript files as follows:
+
+```typescript
+import { EvmProvider } from "@zkchainhub/chain-providers";
+```
+
+### Example
+
+```typescript
+// EVM-provider
+const rpcUrls = [...]; //non-empty
+const chain = mainnet; // from viem/chains
+
+const evmProvider = new EvmProvider(rpcUrls, chain, logger);
+
+const gasPrice = await evmProvider.getGasPrice();
+
+const result = await evmProvider.readContract(address, abi, "myfunction", [arg1, arg2]);
+
+// ZK-chain provider
+const zkChainProvider = new ZKChainProvider(rpcUrls, chain, logger);
+
+const l2Tps = await zkChainProvider.tps();
+```
+
+## API
+
+### [EvmProvider](./src/providers/evmProvider.service.ts)
+
+Available methods
+
+-   `getMulticall3Address()`
+-   `getBalance(address: Address)`
+-   `getBlockNumber()`
+-   `getBlockByNumber(blockNumber: number)`
+-   `getGasPrice()`
+-   `estimateGas(args: EstimateGasParameters<typeof this.chain>)`
+-   `getStorageAt(address: Address, slot: number | Hex)`
+-   `readContract(contractAddress: Address, abi: TAbi functionName: TFunctionName, args?: TArgs)`
+-   `batchRequest(abi: AbiWithConstructor,bytecode: Hex, args: ContractConstructorArgs<typeof abi>, constructorReturnParams: ReturnType)`
+-   `multicall(args: MulticallParameters<contracts, allowFailure>)`
+
+### [ZKChainProvider](./src/providers/zkChainProvider.service.ts)
+
+Available methods
+
+-   `getL1BatchDetails(batchNumber: number)`
+-   `getL1BatchNumber()`
+-   `avgBlockTime(range: number = 1000)`
+-   `tps()`
+
+For more details on both providers, refer to their implementations.

packages/metadata/README.md

@@ -87,6 +87,43 @@ $ pnpm run test
 $ pnpm run test:cov
 ```
 
+## Usage
+
+### Importing the Package
+
+You can import the package in your TypeScript or JavaScript files as follows:
+
+```typescript
+import { MetadataProviderFactory } from "@zkchainhub/metadata";
+```
+
+### Example
+
+You can manually instantiate any of the available providers or use the factory
+
+```typescript
+// manual
+const metadataProvider = new LocalFileMetadataProvider(tokenJson, chainsJson, logger);
+
+// factory
+const metadataFromFactory = MetadataProviderFactory.create(providerOptions, additionalDependencies);
+
+const chainsMap = await metadataProvider.getChainsMetadata();
+const tokensArray = await metadataProvider.getTokensMetadata();
+```
+
+## API
+
+### IMetadataProvider
+
+#### `getChainsMetadata(): Promise<ZKChainMetadata>`
+
+Retrieves the metadata for ZK chains of the ecosystem
+
+#### `getTokensMetadata(): Promise<Token<TokenType>[]>`
+
+Retrieves metadata for tokens of the ecosystem
+
 ## Contributing
 
 To create a new provider, create it inside [`providers`](./src/providers/) folder and implement the [`IMetadataProvider`](./src/interfaces/metadata.interface.ts) interface.

packages/metrics/README.md

@@ -0,0 +1,84 @@
+# ZKchainHub Metrics package
+
+## Overview
+
+The `@zkchainhub/metrics` package exposes services with different aggregated metrics from the ZKsync ecosystem and ZK chains.
+
+## 📋 Prerequisites
+
+-   Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed.
+
+## Installation
+
+```bash
+$ pnpm install
+```
+
+## Building
+
+To build the monorepo packages, run:
+
+```bash
+$ pnpm build
+```
+
+## Test
+
+```bash
+# unit tests
+$ pnpm run test
+
+# test coverage
+$ pnpm run test:cov
+```
+
+## Usage
+
+### Importing the Package
+
+You can import the package in your TypeScript or JavaScript files as follows:
+
+```typescript
+import { L1MetricsService } from "@zkchainhub/metrics";
+```
+
+### Example
+
+This packages requires that user injects instances of:
+
+-   EvmProvider
+-   IPricingProvider
+-   IMetadataProvider
+
+```typescript
+// ... define needed dependencies
+
+const l1MetricsService = new L1MetricsService(
+    bridgeHubAddress,
+    sharedBridgeAddress,
+    stateTransitionManagerAddresses,
+    evmProvider,
+    pricingProvider,
+    metadataProvider,
+    logger,
+);
+
+await l1MetricsService.l1Tvl();
+```
+
+## API
+
+### [L1MetricsService](./src/l1/l1MetricsService.ts)
+
+Available methods
+
+-   `l1Tvl()`
+-   `getBatchesInfo(chainId: ChainId)`
+-   `tvl(chainId: ChainId)`
+-   `chainType(chainId: ChainId)`
+-   `ethGasInfo()`
+-   `getChainIds()`
+-   `getBaseTokens(chainIds: ChainId[])`
+-   `feeParams(chainId: ChainId)`
+
+For more details on services, refer to their implementations.