johba/harb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request 'docs: add engineering principles to AGENTS.md' (#441) from docs/engineering-principles into master

Browse source
This commit is contained in:
johba 2026-03-05 06:47:52 +01:00
commit 0f4d07a4b7
1 changed files with 2 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

4
AGENTS.md
View file

@ -40,9 +40,9 @@ See [docs/dev-environment.md](docs/dev-environment.md) for restart modes, ports,
## Engineering Principles
These apply to ALL code in this repo — contracts, tests, scripts, indexers, frontend.
1. **Never use fixed delays or `waitForTimeout`** — subscribe to events instead. Use `eth_newFilter`/`eth_subscribe` for on-chain events, DOM mutation observers for UI changes, callback patterns for async flows. Even if event-driven code takes more effort, it is always the right answer.
1. **Never use fixed delays or `waitForTimeout`** — react to actual events instead. Use `eth_subscribe` (WebSocket) for on-chain push notifications, `eth_newFilter` + `eth_getFilterChanges` for on-chain polling, DOM mutation observers or Playwright's `waitForSelector`/`waitForURL` for UI changes, callback patterns for async flows. Even if event-driven code takes more effort, it is always the right answer.
2. **Never use hardcoded expectations** — dynamic systems change. React to actual state, not assumed state. Don't assert a specific block number, token amount, or address unless it's a protocol constant.
3. **Event subscription > polling > fixed delay** — if there is truly no way to subscribe to an event, polling with a timeout is acceptable. A fixed `sleep`/`wait` is never acceptable.
3. **Event subscription > polling with timeout > fixed delay** — prefer true push subscriptions (`eth_subscribe`, WebSocket, observers). When push is unavailable (e.g. HTTP-only RPC), polling with a timeout and clear error is acceptable. A fixed `sleep`/`wait`/`waitForTimeout` is never acceptable. Existing violations should be replaced when touched.
## Before Opening a PR
1. `forge build && forge test` in `onchain/` — contracts must compile and pass.