docs: document the onchain CLOB and how to run it on Monad

[jarrodwatts]

Summary

The README shipped the stock Scaffold-ETH 2 boilerplate and said nothing about the order book. This replaces it with documentation written from packages/foundry/contracts/CLOB.sol, the tests, and the deploy script.

What the new README covers:

• What the contract is: a from-scratch onchain central limit order book, one contract, two price-sorted singly linked lists (bidHead / askHead), immediate ERC20 settlement per fill. Framed as a workshop/reference implementation, not an audited DEX.
• How orders rest, match, and cancel: placeOrder pulls the locked token, walks the opposite list while the price crosses, fills at the resting order's price, unlinks fully filled orders, and rests the remainder via _insertOrder (price-time priority). cancelOrder walks the list, unlinks, refunds the stored remainder.
• Public functions, events, and custom errors (with selectors) in tables.
• A limitations section that states what the code actually does today, including the bid-accounting unit mismatch that testSellMatchBid pins (10 token0 bid at price 2, 3 token1 ask: seller gets 6 token0, bid remainder reads 7), OrderMatched emitting 0 for both order ids, linear list walks, rounding, the open mint() on the mock tokens, and the hardcoded mint recipient in the deploy script.
• Foundry build/test/deploy steps, cast examples, and Monad network details (mainnet chain id 143, https://rpc.monad.xyz; testnet 10143, https://testnet-rpc.monad.xyz). Mainnet is not in foundry.toml yet, so the README says to add it; this PR does not touch config.

Verification

• forge build and forge test on this branch: 5 tests pass.
• yarn deploy --network / --keystore flags and the live-network default-key guard checked against scripts-js/parseArgs.js.
• Frontend convention (buy form approves BTC = token0) checked against components/trade/TradeForm.tsx.

🤖 Generated with Claude Code

Greptile Summary

The PR replaces the Scaffold-ETH boilerplate README with detailed CLOB architecture, limitations, setup, and Monad deployment documentation. The follow-up corrects the environment-variable guidance, but the replacement keystore command remains inconsistent with the live deployment wrapper.

• Documents order placement, matching, cancellation, storage, events, errors, and known contract limitations.
• Adds local and Monad build, deployment, frontend, and cast workflows.
• Replaces ETH_KEYSTORE_ACCOUNT guidance with explicit --keystore usage.

Confidence Score: 4/5

The PR is not yet safe to merge because its documented live deployment command may ignore the funded keystore and use a different Forge sender or fail.

The README directs users to select a live deployment account with --keystore, but the wrapper only stores that selection in an environment variable and invokes Forge without an account argument, so the documented deployment path does not reliably use the selected signer.

Files Needing Attention: README.md and packages/foundry/Makefile

Important Files Changed

Filename	Overview
README.md	Replaces the boilerplate with comprehensive CLOB and Monad documentation, but the revised live-deployment instructions claim the selected keystore is used even though the wrapper does not forward it to Forge.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["yarn deploy --network monad --keystore name"] --> B["parseArgs validates name"]
  B --> C["Sets ETH_KEYSTORE_ACCOUNT"]
  C --> D["Makefile invokes forge script"]
  D --> E["Forge selects broadcaster without --account"]
  E --> F["Deployment may use the wrong sender or fail"]

Loading

Prompt To Fix All With AI

### Issue 1
README.md:223
**Named keystore is not forwarded**

When a developer runs `yarn deploy --network monad --keystore <name>`, the wrapper validates the name but invokes Forge without an account or signing argument. Forge therefore selects its broadcaster independently, causing the deployment to use a different sender or abort because that sender lacks the funds assigned to the documented keystore.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (2): Last reviewed commit: "docs: correct keystore selection instruc..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.