From 7c18d94c9392f01f343507507c60809b20337baf Mon Sep 17 00:00:00 2001
From: Beebs <47253537+jahabeebs@users.noreply.github.com>
Date: Tue, 29 Oct 2024 17:37:45 -0500
Subject: [PATCH] chore: write blocknumber package readme (#77)

---
 apps/agent/README.md           |  2 +-
 packages/blocknumber/README.md | 54 ++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocknumber/README.md

diff --git a/apps/agent/README.md b/apps/agent/README.md
index 0c01385..450aa4d 100644
--- a/apps/agent/README.md
+++ b/apps/agent/README.md
@@ -97,6 +97,6 @@ pnpm run test:cov
 
 ### End-to-End Testing
 
-The e2e tests simulate scenarios starting at the contract level and extending to the agent, like processing requests and handling disputes. For detailed test scenarios, refer to the files in `test/e2e/scenarios`.
+The e2e tests simulate scenarios starting at the contract level and extending to the agent, like processing requests and handling disputes. For detailed test scenarios, refer to the files in [test/e2e/scenarios](./test/e2e/scenarios).
 
 TODO: Add instructions on running e2e tests
diff --git a/packages/blocknumber/README.md b/packages/blocknumber/README.md
new file mode 100644
index 0000000..cb69c6d
--- /dev/null
+++ b/packages/blocknumber/README.md
@@ -0,0 +1,54 @@
+# ebo-agent: blocknumber package
+
+The `blocknumber` package in `ebo-agent` provides services for retrieving block numbers based on timestamps across different blockchains. This package includes two main providers for accurate, efficient block number resolution:
+
+1. **EVM Block Number Provider**: Uses a binary search approach optimized to interact with EVM-compatible chains through direct RPC calls.
+2. **Blockmeta JSON Block Number Provider**: Utilizes The Graph's Blockmeta service to retrieve block numbers with precision for specific timestamps, using HTTP requests instead of classic RPC calls.
+
+## Available Scripts
+
+Available scripts that can be run using `pnpm`:
+
+| Script       | Description                                             |
+| ------------ | ------------------------------------------------------- |
+| `build`      | Build the library                                       |
+| `lint`       | Run ESLint to check for coding standards                |
+| `lint:fix`   | Run linter and automatically fix code formatting issues |
+| `format`     | Check code formatting and style using Prettier          |
+| `format:fix` | Run formatter and automatically fix issues              |
+| `test`       | Run unit tests using Vitest                             |
+| `coverage`   | Run tests with coverage report                          |
+
+## API
+
+The primary services available within the `blocknumber` package are the following:
+
+### [BlockNumberService](./src/services/blockNumberService.ts)
+
+Handles the interactions with chains specified in the configuration, using the appropriate block number provider based on the chain type (EVM or Blockmeta).
+
+#### Available Methods
+
+-   **getEpochBlockNumber**(timestamp: UnixTimestamp, chainId: Caip2ChainId): Promise<bigint>
+    -   Retrieves the block number corresponding to a given timestamp for a specified chain.
+-   **getEpochBlockNumbers**(timestamp: UnixTimestamp, chains: Caip2ChainId[]): Promise<Map<Caip2ChainId, bigint>>
+    -   Retrieves the block numbers for a list of chains based on a single timestamp.
+
+### [EvmBlockNumberProvider](./src/providers/evmBlockNumberProvider.ts)
+
+Uses a binary search algorithm on EVM-compatible chains to find the block corresponding to a timestamp.
+
+#### Highlights
+
+-   **Optimized binary search**: Reduces search space with estimated bounds.
+-   **Direct RPC calls**: Interacts directly with chain nodes to fetch data.
+-   **Configuration**: Includes customizable settings for blocks lookback and delta multipliers for efficient block time estimation.
+
+### [BlockmetaJsonBlockNumberProvider](./src/providers/blockmetaJsonBlockNumberProvider.ts)
+
+Fetches blocks based on timestamps using the Blockmeta service from The Graph, by passing the timestamp to the service via HTTP requests.
+
+#### Highlights
+
+-   **HTTP integration with Blockmeta**: Queries Blockmeta endpoints for timestamp-based block resolution.
+-   **Bearer token validation**: Ensures token validity with expiration checks and logging for token refresh reminders.