chore: Write agent app README

apps/agent/.env.example

@@ -1,3 +1,23 @@
+# Private key for the Protocol Provider
 PROTOCOL_PROVIDER_PRIVATE_KEY=afdfd9c3d2095ef696594f6cedcae59e72dcd697e2a7521b1578140422a4f890
+
+# URLs for RPC endpoints for Layer 1 networks, comma-separated
+PROTOCOL_PROVIDER_L1_RPC_URLS=url1,url2,url3
+
+# URLs for RPC endpoints for Layer 2 networks, comma-separated
+PROTOCOL_PROVIDER_L2_RPC_URLS=url4,url5,url6
+
+# JSON map of chain IDs to their respective RPC URLs
+BLOCK_NUMBER_RPC_URLS_MAP='{"chain:id":["url7"]}'
+
+# Blockmeta BlockNumberService bearer token
 BLOCK_NUMBER_BLOCKMETA_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuaWNlIjoidHJ5Iiwibm90aGluZyI6InRvIiwic2VlIjoiaGVyZSJ9.gsWpvMzpzd5_7IN_GU0PhNLH7wuKHl29FHkL5-i18b4
-EBO_AGENT_CONFIG_FILE_PATH="./config.example.yml"
+
+# Path to the agent YAML configuration file
+EBO_AGENT_CONFIG_FILE_PATH="./config.example.yml"
+
+# Discord bot token for notifications
+DISCORD_BOT_TOKEN=YOUR_DISCORD_BOT_TOKEN
+
+# Discord channel ID for notifications
+DISCORD_CHANNEL_ID=YOUR_DISCORD_CHANNEL_ID

apps/agent/README.md

@@ -0,0 +1,102 @@
+# Agent Monorepo
+
+The `agent` package is designed as a service that drives the EBO agent's main workflow. It initializes the relevant
+services in the `packages` directory that are necessary to run the agent, like `BlockNumberService` and `ProtocolProvider`.
+The agent interacts with the EBO smart contracts deployed on the chains specified in the `config.yml` file
+that you'll create during this setup process.
+
+## Setup
+
+To set up the EBO agent, follow these steps:
+
+1. **Install Dependencies**: Ensure you have `pnpm` installed, and run:
+
+```bash
+pnpm install
+```
+
+2. **Configure Environment Variables**:
+
+You can configure environment variables in one of two ways:
+
+-   **Using a `.env` file**: Create a `.env` file in the root of the `agent` package. Refer to `.env.example` for the required environment variables, and copy it to `.env`:
+
+```bash
+cp .env.example .env
+```
+
+-   **Setting environment variables directly**: Alternatively, you may set the environment variables directly in your shell or deployment environment without using a `.env` file.
+
+**Environment Variables**:
+
+| Variable                        | Description                                                               | Required |
+| ------------------------------- | ------------------------------------------------------------------------- | -------- |
+| `PROTOCOL_PROVIDER_PRIVATE_KEY` | Private key for the Protocol Provider                                     | Yes      |
+| `PROTOCOL_PROVIDER_L1_RPC_URLS` | Comma-separated URLs for Layer 1 RPC endpoints                            | Yes      |
+| `PROTOCOL_PROVIDER_L2_RPC_URLS` | Comma-separated URLs for Layer 2 RPC endpoints                            | Yes      |
+| `BLOCK_NUMBER_RPC_URLS_MAP`     | JSON map of chain IDs to arrays of RPC URLs for Block Number calculations | Yes      |
+| `BLOCK_NUMBER_BLOCKMETA_TOKEN`  | Bearer token for the Blockmeta service (see notes below on how to obtain) | Yes      |
+| `EBO_AGENT_CONFIG_FILE_PATH`    | Path to the agent YAML configuration file                                 | Yes      |
+| `DISCORD_BOT_TOKEN`             | Your Discord bot’s token                                                  | Yes      |
+| `DISCORD_CHANNEL_ID`            | Discord channel ID for notifications                                      | Yes      |
+
+**Notes:**
+
+-   For information on generating the `BLOCK_NUMBER_BLOCKMETA_TOKEN`, refer to [Substreams Authentication Documentation](https://docs.substreams.dev/documentation/consume/authentication) for guidance on obtaining and using an authentication token.
+-   To explore the available Substreams providers and URLs, check out [The Graph’s Marketplace](https://thegraph.market/), which lists supported substreams.
+
+3. **Configuration File**:
+
+-   The agent requires a YAML configuration file. The path to this file must be specified in the `.env` file via `EBO_AGENT_CONFIG_FILE_PATH`.
+-   To set up the configuration, copy `config.example.yml` to `config.yml`:
+
+```bash
+cp config.example.yml config.yml
+```
+
+-   Update the `config.yml` file with your specific settings. Comments have been added in `config.example.yml` to explain each property.
+
+## Available Scripts
+
+Here are the scripts you can run using `pnpm`:
+
+| Script        | Description                                    |
+| ------------- | ---------------------------------------------- |
+| `build`       | Build the agent                                |
+| `check-types` | Check for type issues using TypeScript         |
+| `clean`       | Remove `dist` folder                           |
+| `format`      | Check code formatting using Prettier           |
+| `format:fix`  | Automatically fix code formatting issues       |
+| `lint`        | Run ESLint to check for code quality and style |
+| `lint:fix`    | Automatically fix ESLint errors                |
+| `start`       | Start the EBO Agent                            |
+| `test`        | Run tests using Vitest                         |
+| `test:cov`    | Run tests with a coverage report               |
+
+### Running the Agent
+
+To start the EBO Agent, run:
+
+```bash
+pnpm run start
+```
+
+## Running Tests
+
+The `agent` package includes a suite of Vitest and end-to-end (e2e) tests to verify the correct functioning of the agent's processes. To run the Vitest tests, execute:
+
+```bash
+pnpm run test
+```
+
+For a coverage report, run:
+
+```bash
+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`.
+
+TODO: Add instructions on running e2e tests

apps/agent/config.example.yml

@@ -1,33 +1,33 @@
 protocolProvider:
     rpcsConfig:
         l1:
-            chainId: eip155:11155111
-            transactionReceiptConfirmations: 1
-            timeout: 10000
-            retryInterval: 150
+            chainId: eip155:11155111 # Chain ID for Layer 1 network
+            transactionReceiptConfirmations: 1 # Confirmations needed for transactions on L1
+            timeout: 10000 # Timeout for RPC calls (ms)
+            retryInterval: 150 # Retry interval for RPC calls (ms)
         l2:
-            chainId: eip155:42161
+            chainId: eip155:42161 # Chain ID for Layer 2 network
             transactionReceiptConfirmations: 1
             timeout: 10000
             retryInterval: 150
     contracts:
-        oracle: "0x1234567890123456789012345678901234567890"
-        epochManager: "0x1234567890123456789012345678901234567890"
-        eboRequestCreator: "0x1234567890123456789012345678901234567890"
-        bondEscalationModule: "0x1234567890123456789012345678901234567890"
-        horizonAccountingExtension: "0x1234567890123456789012345678901234567890"
+        oracle: "0x1234567890123456789012345678901234567890" # Oracle contract address
+        epochManager: "0x1234567890123456789012345678901234567890" # Epoch Manager contract address
+        eboRequestCreator: "0x1234567890123456789012345678901234567890" # EBO Request Creator contract
+        bondEscalationModule: "0x1234567890123456789012345678901234567890" # Bond Escalation Module contract
+        horizonAccountingExtension: "0x1234567890123456789012345678901234567890" # Accounting extension contract
 
 blockNumberService:
     blockmetaConfig:
-        baseUrl: "localhost:443"
+        baseUrl: "localhost:443" # Base URL for Blockmeta service
         servicePaths:
-            blockByTime: /sf.blockmeta.v2.BlockByTime
-            block: /sf.blockmeta.v2.Block
-        bearerTokenExpirationWindow: 31536000000
+            blockByTime: /sf.blockmeta.v2.BlockByTime # Substream's endpoint for "block by time" service
+            block: /sf.blockmeta.v2.Block # Substream's endpoint for "block" service
+        bearerTokenExpirationWindow: 31536000000 # Expiration window for bearer token (ms)
 
 processor:
-    msBetweenChecks: 1000
+    msBetweenChecks: 1000 # Interval between periodic checks (ms)
     accountingModules:
-        requestModule: "0x1234567890123456789012345678901234567890"
-        responseModule: "0x1234567890123456789012345678901234567890"
-        escalationModule: "0x1234567890123456789012345678901234567890"
+        requestModule: "0x1234567890123456789012345678901234567890" # Address of the Request module
+        responseModule: "0x1234567890123456789012345678901234567890" # Address of the Response module
+        escalationModule: "0x1234567890123456789012345678901234567890" # Address of the Escalation module

apps/scripts/README.md

@@ -1,6 +1,6 @@
-# EBO Agent Monorepo
+# Scripts Monorepo
 
-This monorepo contains the EBO Agent scripts and packages.
+This monorepo contains scripts relevant to running the EBO agent, such as approving its required modules
 
 ## Setup