code/yieldomega
Watch
4
0
Fork
You've already forked yieldomega
 0
Code Issues 1 Pull requests 1 Projects Releases Packages Wiki Activity

QA setup checklist: local full stack (prerequisites, quick start, reference) #162

New issue
Closed
opened 2026-05-05 13:57:30 +00:00 by PlasticDigits · 7 comments
PlasticDigits commented 2026-05-05 13:57:30 +00:00 (Migrated from gitlab.com)

Prerequisites

Git, Docker, Foundry (anvil, forge, cast), jq, curl, Rust, Node/npm. One-time per clone: (cd frontend && npm ci) and a bots/timecurve venv with pip install -e ".[dev]" so python3 -c "import web3" works (see bots/timecurve/README.md).

Quick start

Repo root — installs frontend deps if needed, then full stack (Postgres, Anvil, deploy, indexer, swarm, Vite; live sale + short buy cooldown for usable bot traffic):

(cd frontend && npm ci) && YIELDOMEGA_DEPLOY_NO_COOLDOWN=1 bash scripts/start-qa-local-full-stack.sh --live-sale

Open http://127.0.0.1:5173 (or the port printed in the summary).

Reference: QA setup, options, and terms

If frontend/node_modules is already present and the bot venv can import web3, you can run only YIELDOMEGA_DEPLOY_NO_COOLDOWN=1 bash scripts/start-qa-local-full-stack.sh --live-sale.

What the orchestrator does

scripts/start-qa-local-full-stack.sh is a thin wrapper: it only calls scripts/start-local-anvil-stack.sh, then optionally starts the Vite dev server. All deploy, DB reset, registry, and indexer logic lives in the stack script (GitLab #104).

Authoritative doc: docs/testing/qa-local-full-stack.md.

Terms

Term Meaning
Anvil Local EVM node (chain 31337 by default).
DeployDev Foundry script that deploys the dev protocol stack used for local QA.
Rich state Runs contracts/script/anvil_rich_state.sh after deploy: warps/simulates a post–sale-end narrative (prizes, vesting hooks, etc.). Swarm defaults off so bots do not fight that scripted state.
Live sale SKIP_ANVIL_RICH_STATE=1: skips rich state; TimeCurve stays in a live sale window suitable for UI + indexer demos. Swarm defaults on unless you disable it.
Indexer Rust service reading chain logs into Postgres; HTTP API consumed by the frontend (VITE_INDEXER_URL in frontend/.env.local).
Bot swarm Python workers under bots/timecurve/ issuing scripted txs (requires web3). Not onchain authority—QA traffic only.
Kumbaya path Optional DeployKumbayaAnvilFixtures + TimeCurveBuyRouter registry entries and matching VITE_* lines for single-tx / router QA.

CLI flags (start-qa-local-full-stack.sh)

Flag Effect
--no-frontend Stack + indexer only; no background npm run dev.
--no-swarm Sets START_BOT_SWARM=0 before the stack.
--kumbaya Sets YIELDOMEGA_DEPLOY_KUMBAYA=1 (fixtures + router in registry + local VITE_* merge).
--rich-state Unsets SKIP_ANVIL_RICH_STATE so rich state runs when your shell had previously exported SKIP_ANVIL_RICH_STATE=1.
--live-sale Sets SKIP_ANVIL_RICH_STATE=1 (live sale path; swarm on by default).

Any env var documented for start-local-anvil-stack.sh can be exported in the same shell before the orchestrator; it is forwarded unchanged.

Decision hints

  1. Post-end / prizes / vesting flows: use default (omit --live-sale) so rich state runs; keep swarm off unless you know you need it (START_BOT_SWARM=1).
  2. Live sale + indexer “live buys” + swarm: --live-sale (quick start above). Prefer YIELDOMEGA_DEPLOY_NO_COOLDOWN=1 and/or YIELDOMEGA_ANVIL_BUY_COOLDOWN_SEC for dense traffic; default 300 s per-wallet cooldown stalls naive swarm + automine timing (GitLab #88, GitLab #99).
  3. BuyViaKumbaya / router QA: add --kumbaya or YIELDOMEGA_DEPLOY_KUMBAYA=1; ensure indexer restarts if you merge registry rows after the fact (GitLab #78, GitLab #84).
  4. Headless / API-only: --no-frontend.

Env matrix (representative)

Area Variables
Stack / Anvil ANVIL_PORT, RPC_URL, SKIP_ANVIL_RICH_STATE, START_BOT_SWARM, YIELDOMEGA_ANVIL_BLOCK_TIME_SEC, YIELDOMEGA_ANVIL_GAS_LIMIT, YIELDOMEGA_DEV_SALE_START_DELAY_SEC, YIELDOMEGA_DEPLOY_NO_COOLDOWN, YIELDOMEGA_ANVIL_BUY_COOLDOWN_SEC, YIELDOMEGA_DEPLOY_KUMBAYA, DEPLOYER_PK, FOUNDRY_OUT
Postgres / indexer PG_HOST_PORT, INDEXER_PORT, QA_USE_FIXED_INDEXER_PORT, DOCKER_PG
Frontend FRONTEND_DEV_PORT; LAUNCH_OFFSET_SEC → VITE_LAUNCH_TIMESTAMP in .env.local
Swarm YIELDOMEGA_SWARM_REFERRALS, YIELDOMEGA_ANVIL_EXTRA_FUNDED_ADDRESSES (GitLab #102)

Production indexer knobs (INDEXER_PRODUCTION=1, strict DATABASE_URL / ADDRESS_REGISTRY) apply to real deploys, not this local orchestrator path—see indexer/README.md.

Addresses and proxies

Use ERC-1967 proxy addresses from the stack / local-anvil-registry.json, not the implementation row in run-latest.json, for wallet calls and bot config (GitLab #61).

Smoke checks (after stack is up)

Use RPC_URL and indexer base from stack output or frontend/.env.local (VITE_RPC_URL, VITE_INDEXER_URL):

cast block-number --rpc-url "$RPC_URL"
curl -sf "${INDEXER_URL}/v1/status"
curl -s "${INDEXER_URL}/v1/timecurve/buys?limit=5" | jq .

Stopping / logs

PIDs and logs under /tmp/ (yieldomega_anvil_stack, yieldomega_indexer_stack, yieldomega_frontend_qa, yieldomega_bot_swarm, swarm logs). Postgres: docker stop yieldomega-pg (override name with DOCKER_PG). Details: qa-local-full-stack.md § Stopping.

Not covered here

Automated Playwright E2E: scripts/e2e-anvil.sh and docs/testing/e2e-anvil.md.

Issue-tagged manual QA checklists for contributors: docs/testing/manual-qa-checklists.md.

## Prerequisites Git, Docker, Foundry (`anvil`, `forge`, `cast`), `jq`, `curl`, Rust, Node/npm. One-time per clone: `(cd frontend && npm ci)` and a `bots/timecurve` venv with `pip install -e ".[dev]"` so `python3 -c "import web3"` works (see [`bots/timecurve/README.md`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/bots/timecurve/README.md)). --- ## Quick start Repo root — installs frontend deps if needed, then full stack (**Postgres, Anvil, deploy, indexer, swarm, Vite**; live sale + short buy cooldown for usable bot traffic): ```bash (cd frontend && npm ci) && YIELDOMEGA_DEPLOY_NO_COOLDOWN=1 bash scripts/start-qa-local-full-stack.sh --live-sale ``` Open **http://127.0.0.1:5173** (or the port printed in the summary). --- ## Reference: QA setup, options, and terms If `frontend/node_modules` is already present and the bot venv can `import web3`, you can run only `YIELDOMEGA_DEPLOY_NO_COOLDOWN=1 bash scripts/start-qa-local-full-stack.sh --live-sale`. ### What the orchestrator does [`scripts/start-qa-local-full-stack.sh`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/scripts/start-qa-local-full-stack.sh) is a thin wrapper: it **only** calls [`scripts/start-local-anvil-stack.sh`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/scripts/start-local-anvil-stack.sh), then optionally starts the Vite dev server. All deploy, DB reset, registry, and indexer logic lives in the stack script ([GitLab #104](https://gitlab.com/PlasticDigits/yieldomega/-/issues/104)). **Authoritative doc:** [`docs/testing/qa-local-full-stack.md`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/docs/testing/qa-local-full-stack.md). ### Terms | Term | Meaning | |------|--------| | **Anvil** | Local EVM node (chain **31337** by default). | | **DeployDev** | Foundry script that deploys the dev protocol stack used for local QA. | | **Rich state** | Runs `contracts/script/anvil_rich_state.sh` after deploy: warps/simulates a **post–sale-end** narrative (prizes, vesting hooks, etc.). **Swarm defaults off** so bots do not fight that scripted state. | | **Live sale** | `SKIP_ANVIL_RICH_STATE=1`: skips rich state; TimeCurve stays in a **live sale** window suitable for UI + indexer demos. **Swarm defaults on** unless you disable it. | | **Indexer** | Rust service reading chain logs into Postgres; HTTP API consumed by the frontend (`VITE_INDEXER_URL` in `frontend/.env.local`). | | **Bot swarm** | Python workers under `bots/timecurve/` issuing scripted txs (requires `web3`). Not onchain authority—QA traffic only. | | **Kumbaya path** | Optional `DeployKumbayaAnvilFixtures` + `TimeCurveBuyRouter` registry entries and matching `VITE_*` lines for single-tx / router QA. | ### CLI flags (`start-qa-local-full-stack.sh`) | Flag | Effect | |------|--------| | `--no-frontend` | Stack + indexer only; no background `npm run dev`. | | `--no-swarm` | Sets `START_BOT_SWARM=0` before the stack. | | `--kumbaya` | Sets `YIELDOMEGA_DEPLOY_KUMBAYA=1` (fixtures + router in registry + local `VITE_*` merge). | | `--rich-state` | Unsets `SKIP_ANVIL_RICH_STATE` so rich state runs when your shell had previously exported `SKIP_ANVIL_RICH_STATE=1`. | | `--live-sale` | Sets `SKIP_ANVIL_RICH_STATE=1` (live sale path; swarm on by default). | Any env var documented for `start-local-anvil-stack.sh` can be **exported in the same shell** before the orchestrator; it is forwarded unchanged. ### Decision hints 1. **Post-end / prizes / vesting flows:** use **default** (omit `--live-sale`) so rich state runs; keep swarm off unless you know you need it (`START_BOT_SWARM=1`). 2. **Live sale + indexer “live buys” + swarm:** `--live-sale` (quick start above). Prefer **`YIELDOMEGA_DEPLOY_NO_COOLDOWN=1`** and/or **`YIELDOMEGA_ANVIL_BUY_COOLDOWN_SEC`** for dense traffic; default **300 s** per-wallet cooldown stalls naive swarm + automine timing ([GitLab #88](https://gitlab.com/PlasticDigits/yieldomega/-/issues/88), [GitLab #99](https://gitlab.com/PlasticDigits/yieldomega/-/issues/99)). 3. **`BuyViaKumbaya` / router QA:** add `--kumbaya` or `YIELDOMEGA_DEPLOY_KUMBAYA=1`; ensure indexer restarts if you merge registry rows after the fact ([GitLab #78](https://gitlab.com/PlasticDigits/yieldomega/-/issues/78), [GitLab #84](https://gitlab.com/PlasticDigits/yieldomega/-/issues/84)). 4. **Headless / API-only:** `--no-frontend`. ### Env matrix (representative) | Area | Variables | |------|-----------| | Stack / Anvil | `ANVIL_PORT`, `RPC_URL`, `SKIP_ANVIL_RICH_STATE`, `START_BOT_SWARM`, `YIELDOMEGA_ANVIL_BLOCK_TIME_SEC`, `YIELDOMEGA_ANVIL_GAS_LIMIT`, `YIELDOMEGA_DEV_SALE_START_DELAY_SEC`, `YIELDOMEGA_DEPLOY_NO_COOLDOWN`, `YIELDOMEGA_ANVIL_BUY_COOLDOWN_SEC`, `YIELDOMEGA_DEPLOY_KUMBAYA`, `DEPLOYER_PK`, `FOUNDRY_OUT` | | Postgres / indexer | `PG_HOST_PORT`, `INDEXER_PORT`, `QA_USE_FIXED_INDEXER_PORT`, `DOCKER_PG` | | Frontend | `FRONTEND_DEV_PORT`; `LAUNCH_OFFSET_SEC` → `VITE_LAUNCH_TIMESTAMP` in `.env.local` | | Swarm | `YIELDOMEGA_SWARM_REFERRALS`, `YIELDOMEGA_ANVIL_EXTRA_FUNDED_ADDRESSES` ([GitLab #102](https://gitlab.com/PlasticDigits/yieldomega/-/issues/102)) | Production indexer knobs (`INDEXER_PRODUCTION=1`, strict `DATABASE_URL` / `ADDRESS_REGISTRY`) apply to real deploys, not this local orchestrator path—see [`indexer/README.md`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/indexer/README.md). ### Addresses and proxies Use **ERC-1967 proxy** addresses from the stack / `local-anvil-registry.json`, not the **implementation** row in `run-latest.json`, for wallet calls and bot config ([GitLab #61](https://gitlab.com/PlasticDigits/yieldomega/-/issues/61)). ### Smoke checks (after stack is up) Use `RPC_URL` and indexer base from stack output or `frontend/.env.local` (`VITE_RPC_URL`, `VITE_INDEXER_URL`): ```bash cast block-number --rpc-url "$RPC_URL" curl -sf "${INDEXER_URL}/v1/status" curl -s "${INDEXER_URL}/v1/timecurve/buys?limit=5" | jq . ``` ### Stopping / logs PIDs and logs under `/tmp/` (`yieldomega_anvil_stack`, `yieldomega_indexer_stack`, `yieldomega_frontend_qa`, `yieldomega_bot_swarm`, swarm logs). Postgres: `docker stop yieldomega-pg` (override name with `DOCKER_PG`). Details: [`qa-local-full-stack.md` § Stopping](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/docs/testing/qa-local-full-stack.md#stopping-the-stack). ### Not covered here Automated **Playwright** E2E: [`scripts/e2e-anvil.sh`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/scripts/e2e-anvil.sh) and [`docs/testing/e2e-anvil.md`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/docs/testing/e2e-anvil.md). Issue-tagged **manual QA checklists** for contributors: [`docs/testing/manual-qa-checklists.md`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/docs/testing/manual-qa-checklists.md).
PlasticDigits commented 2026-05-05 13:57:30 +00:00 (Migrated from gitlab.com)

assigned to @nullvector_ux

assigned to @nullvector_ux
Brouie commented 2026-05-05 23:51:54 +00:00 (Migrated from gitlab.com)

mentioned in issue #164

mentioned in issue #164
PlasticDigits commented 2026-05-06 09:29:02 +00:00 (Migrated from gitlab.com)

@nullvector_ux Once you start this task, please update here with your status - or any problems you run into document here.

@nullvector_ux Once you start this task, please update here with your status - or any problems you run into document here.
PlasticDigits commented 2026-05-06 12:33:32 +00:00 (Migrated from gitlab.com)

mentioned in issue #147

mentioned in issue #147
PlasticDigits commented 2026-05-06 12:46:33 +00:00 (Migrated from gitlab.com)

Added scripts/bootstrap-dev.sh for post-clone setup: runs git submodule update --init --recursive (Foundry libs under contracts/lib/, including OpenZeppelin for @openzeppelin/contracts imports) then (cd frontend && npm ci).

Run from repo root (idempotent):

bash scripts/bootstrap-dev.sh

Optional next steps (unchanged from prerequisites): bots/timecurve venv and pip install -e ".[dev]" for the swarm — see bots/timecurve/README.md. Contracts reference: contracts/README.md.

This covers fresh clones (including WSL) where the editor or forge reports missing @openzeppelin/contracts/... until submodules are populated.

Added **`scripts/bootstrap-dev.sh`** for post-clone setup: runs **`git submodule update --init --recursive`** (Foundry libs under `contracts/lib/`, including OpenZeppelin for `@openzeppelin/contracts` imports) then **`(cd frontend && npm ci)`**. Run from repo root (idempotent): ```bash bash scripts/bootstrap-dev.sh ``` Optional next steps (unchanged from prerequisites): **`bots/timecurve`** venv and `pip install -e ".[dev]"` for the swarm — see [`bots/timecurve/README.md`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/bots/timecurve/README.md). Contracts reference: [`contracts/README.md`](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/contracts/README.md). This covers fresh clones (including WSL) where the editor or `forge` reports missing `@openzeppelin/contracts/...` until submodules are populated.
PlasticDigits commented 2026-05-06 12:48:39 +00:00 (Migrated from gitlab.com)

mentioned in commit 5bd1e5b354

mentioned in commit 5bd1e5b354bbdeb8bdd479d570440fed92f574e0
PlasticDigits (Migrated from gitlab.com) closed this issue 2026-05-09 09:18:13 +00:00
PlasticDigits commented 2026-05-13 15:13:33 +00:00 (Migrated from gitlab.com)

mentioned in commit fb98ea8364

mentioned in commit fb98ea8364f759bff0d0808897cf7b33146d5da5
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
cac-design-issue-544
renovate/configure
No results found.
Labels
Clear labels   
agent:fix_bugfix

   
agent:fix_conflicts

   
agent:fix_security

   
agent:gap_analysis

   
agent:implement

   
agent:open_issues

   
agents

   
agent:security_audit

   
agent:verify
  
area
timecurve

  
arena

   
arena-v2

   
audit

   
block:feature_review

   
block:security

   
bug

   
contracts

   
design

   
devops

   
docs
Documentation

  
documentation

   
enhancement

   
epic
Epic / umbrella issue

  
feature

   
frontend

   
indexer

   
low priority
Low priority, investigate other issues first

  
megaeth

   
operations

   
ops
Deploy and operations

  
performance

   
QA

   
qa checklist

   
referrals

   
removal
Legacy removal

  
security

   
smart-contracts

   
tech-debt

   
testing

   
time-arena
TimeArena v2 revamp

  
timecurve

   
visual-qa
No labels
agent:fix_bugfix
agent:fix_conflicts
agent:fix_security
agent:gap_analysis
agent:implement
agent:open_issues
agents
agent:security_audit
agent:verify
area
timecurve
arena
arena-v2
audit
block:feature_review
block:security
bug
contracts
design
devops
docs
documentation
enhancement
epic
feature
frontend
indexer
low priority
megaeth
operations
ops
performance
QA
qa checklist
referrals
removal
security
smart-contracts
tech-debt
testing
time-arena
timecurve
visual-qa
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
code/yieldomega#162
No description provided.