From 19f94c0c36e53701352cc264a04c16c1286111d8 Mon Sep 17 00:00:00 2001
From: zaidarain1 <zaid.arain@immutable.com>
Date: Mon, 17 Jun 2024 15:34:08 +1000
Subject: [PATCH] Docs: [DX-2930] Update README of "orderbook" package (#1903)

---
 packages/orderbook/README.md    | 124 ++++++++++++++++++++++++++------
 packages/orderbook/package.json |   1 +
 2 files changed, 105 insertions(+), 20 deletions(-)

diff --git a/packages/orderbook/README.md b/packages/orderbook/README.md
index 77b65fc6de..e10b613a1b 100644
--- a/packages/orderbook/README.md
+++ b/packages/orderbook/README.md
@@ -1,30 +1,107 @@
 # Order Book
 
-The SDK for the zkEVM Order Book
+## Table of Contents
 
-## Getting Started
+- [Pre-requisites](#pre-requisites)
+- [Quick Start Guide](#quick-start-guide)
+- [Demo Scripts](#demo-scripts)
+- [About](#about)
 
-### Configuration
+### Pre-requisites
 
-Initializing the SDK can be achieved by specifying the target environment in the constructor:
+Install dependencies for the workspace
 
+```bash
+yarn install
 ```
-new Orderbook({
-  baseConfig: {
-    environment: Environment.SANDBOX,
-  },
-})
+
+### Quick Start Guide
+
+All commands below need to be run in the context of the `orderbook` package where this README is located. Read more about context [here](../../README.md#context).
+
+Running in `dev` mode:
+
+```bash
+yarn dev
 ```
 
-### Usage
+Building to `./dist` directory with javascript output:
 
-The `*.demo.ts` and `*.e2e.ts` files in the `./test` folder have a number of practical examples of how the SDK is used for placing, fulfilling and cancelling listings.
+```bash
+yarn build
+```
 
-### Demo Scripts
+Running all orderbook demos (these rely on the `.env` file explained in the [demo script section](#demo-scripts)):
+
+```bash
+yarn run:demo
+```
 
-There are a number a demo scripts. Check the package.json for entries that following this pattern: `yarn run:demo*`. These scripts rely on an `.env` file that specifies the following properties:
+Running the orderbook expiry demo (this relies on the `.env` file explained in the [demo script section](#demo-scripts)):
 
+```bash
+yarn run:demo-expiry
 ```
+
+Running the orderbook order fulfillment demo (this relies on the `.env` file explained in the [demo script section](#demo-scripts)):
+
+```bash
+yarn run:demo-fulfill
+```
+
+Running the orderbook bulk orders fulfillment demo (this relies on the `.env` file explained in the [demo script section](#demo-scripts)):
+
+```bash
+yarn run:demo-fulfill-bulk
+```
+
+Running all tests:
+
+```bash
+yarn test
+```
+
+Running changed tests in watch mode:
+
+```bash
+yarn test:watch
+```
+
+Running E2E tests (these rely on the `.env` file explained in the [demo script section](#demo-scripts)):
+
+```bash
+yarn test:e2e
+```
+
+Linting:
+
+```bash
+yarn lint
+```
+
+Linting and attempting to auto-fix issues:
+
+```bash
+yarn lint:fix
+```
+
+Typechecking:
+
+```bash
+yarn typecheck
+```
+
+Generating types from the `./abi/*.json` files to `./src/typechain/types`:
+
+```bash
+yarn generate-types
+```
+
+### Demo Scripts
+
+The demo scripts and e2e test scripts mentioned above rely on an `.env` file that specifies the following properties:
+
+```bash
 ACCOUNT_1=
 ACCOUNT_2=
 RPC_ENDPOINT=
@@ -38,17 +115,24 @@ ZONE_CONTRACT_ADDRESS=
 * ORDERBOOK_MR_API_URL is the exposed URL for the API
 * SEAPORT_CONTRACT_ADDRESS and ZONE_CONTRACT_ADDRESS depend on the address of the deployed contracts
 
-### Testing
-#### Unit Tests
+An example `.env.example` file is provided in the root of the `orderbook` package, where this README is located, that can be used as a baseline for creating the `.env` file.
 
-`yarn test`
+### About
 
-#### E2E Tests
+This package contains the Typescript SDK for the zkEVM Order Book. It is used to interact with the zkEVM Order Book API and provides a number of methods for placing, fulfilling and cancelling listings. The SDK is initialized with a configuration object that specifies the target environment and other necessary parameters.
 
-`yarn test:e2e`
+Initializing the SDK can be achieved by specifying the target environment in the constructor:
 
-The E2E tests rely on the `.env` explained in the demo script section above.
+```typescript
+new Orderbook({
+  baseConfig: {
+    environment: Environment.SANDBOX,
+  },
+})
+```
 
-## OpenAPI SDK
+The `*.demo.ts` and `*.e2e.ts` files in the `./test` folder have a number of practical examples of how the SDK is used for placing, fulfilling and cancelling listings and can be used as a point of reference. 
 
 All content in src/openapi/sdk is auto-generated.
+
+[Read more about the orderbook package here](../../README.md#orderbook)
diff --git a/packages/orderbook/package.json b/packages/orderbook/package.json
index e41ac25284..37e4ef2583 100644
--- a/packages/orderbook/package.json
+++ b/packages/orderbook/package.json
@@ -41,6 +41,7 @@
     "run:demo-fulfill-bulk": "jest --runInBand --testMatch \"**/(fulfillBulk.demo).[jt]s?(x)\"",
     "test": "jest",
     "test:e2e": "jest --runInBand --testMatch \"**/?(*.)+(e2e).[jt]s?(x)\"",
+    "test:watch": "jest --watch",
     "typecheck": "tsc --noEmit --jsx preserve"
   },
   "type": "module",