chore: write blocknumber package readme (#77)

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

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.