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

fix agent

Browse source
This commit is contained in:
johba 2025-09-24 09:57:20 +02:00
parent cbf5ce0733
commit f3fb0f142a
9 changed files with 173 additions and 432 deletions
Download patch file Download diff file Expand all files Collapse all files

109
AGENTS.md
View file

@ -1,84 +1,47 @@
# Agent Brief: Harb Stack
## System Map
- `onchain/`: Foundry workspace for Kraiken token, Harberger staking, Optimizer, and LiquidityManager logic. Deployment scripts live in `script/`, tests in `test/`, fuzzing toolchain in `analysis/`. Use `.secret.local` mnemonic for local scripts.
- `services/ponder/`: New indexer replacing The Graph. `ponder.config.ts` selects network/contracts, `src/` holds TypeScript event handlers, `ponder.schema.ts` defines tables, `README.md` documents usage. Generated artifacts in `generated/` are auto-created by Ponder.
- `subgraph/base_sepolia/`: Legacy AssemblyScript implementation kept for reference during migration. Do not modify unless syncing schema changes between stacks.
- `landing/`: Vue 3 app (Vite + TypeScript) for the public launch site and forthcoming staking UI. See `src/views/` for pages, `env.d.ts` for injected globals.
- `services/txnBot/`: Node service that consumes the Ponder GraphQL API to trigger `recenter()` and `payTax()` on-chain when profitable.
- `kraiken-lib/`: Shared TypeScript helpers (e.g., `bytesToUint256`) consumed by the landing app + bots.
## Core Concepts
- KRAIKEN couples Harberger-tax staking with a dominant Uniswap V3 liquidity manager to create asymmetric slippage, sentiment-driven pricing, and VWAP "price memory" safeguards.
- Liquidity dominance is mission-critical; treat any regression that weakens the LiquidityManager's control as a priority incident.
- Harberger staking supplies the sentiment oracle that drives Optimizer parameters, which in turn tune liquidity placement and supply expansion.
## Environment Profiles
- `BASE_SEPOLIA_LOCAL_FORK`: Anvil fork bootstrapped by `scripts/local_env.sh`
- `BASE_SEPOLIA`: Public Base Sepolia testnet
- `BASE`: Base mainnet
## User Journey
1. **Buy** - Acquire KRAIKEN on Uniswap.
2. **Stake** - Declare a tax rate on kraiken.org to earn from protocol growth.
3. **Compete** - Snatch undervalued positions to optimise returns.
> **Local dev**: Always start the stack via `nohup ./scripts/local_env.sh start &` (never run services individually); stop with `./scripts/local_env.sh stop`.
## Operating the Stack
- Start everything with `nohup ./scripts/local_env.sh start &` and stop via `./scripts/local_env.sh stop`. Do not launch services individually.
- Supported environments: `BASE_SEPOLIA_LOCAL_FORK` (default Anvil fork), `BASE_SEPOLIA`, and `BASE`. Match contract addresses and RPCs accordingly.
- The stack boots Anvil, deploys contracts, seeds liquidity, starts Ponder, launches the landing site, and runs the txnBot. Wait for logs to settle before manual testing.
## Execution Workflow
1. **Contracts**
- Build/test via `forge build` and `forge test` inside `onchain/`.
- Local deployment: run Anvil fork, execute `forge script script/DeployLocal.sol --fork-url http://127.0.0.1:8545 --broadcast` with `.secret.local` mnemonic. Script attaches to Base Uniswap V3 factory, creates pool if absent, deploys Optimizer proxy + LiquidityManager, configures Kraiken/Stake links.
- Post-deploy: fund LiquidityManager (`cast send <LM> --value 0.1ether`) and call `recenter()`.
## Component Guides
- `onchain/` - Solidity + Foundry contracts, deploy scripts, and fuzzing helpers ([details](onchain/AGENTS.md)).
- `services/ponder/` - Ponder indexer powering the GraphQL API ([details](services/ponder/AGENTS.md)).
- `landing/` - Vue 3 marketing + staking interface ([details](landing/AGENTS.md)).
- `kraiken-lib/` - Shared TypeScript helpers for clients and bots ([details](kraiken-lib/AGENTS.md)).
- `services/txnBot/` - Automation bot for `recenter()` and `payTax()` upkeep ([details](services/txnBot/AGENTS.md)).
2. **Indexer (Ponder)**
- Install deps (`npm install`).
- Configure environment via `PONDER_NETWORK` (`BASE_SEPOLIA_LOCAL_FORK`, `BASE_SEPOLIA`, or `BASE`). Update `ponder.config.ts` addresses if deployments change.
- Run dev mode with `npm run dev`; GraphQL served at `http://localhost:42069/graphql`.
- Handlers in `src/kraiken.ts` and `src/stake.ts` maintain rolling supply stats, ring-buffered hourly metrics, and position state.
## Testing & Tooling
- Contracts: run `forge build`, `forge test`, and `forge snapshot` inside `onchain/`.
- Fuzzing: scripts under `onchain/analysis/` (e.g., `./analysis/run-fuzzing.sh [optimizer] debugCSV`) generate replayable scenarios.
- Integration: after the stack boots, inspect Anvil logs, hit `http://localhost:42069/graphql` for Ponder, and poll `http://127.0.0.1:43069/status` for txnBot health.
3. **Frontend**
- `npm install` then `npm run dev` in `landing/`. Currently static marketing copy with placeholders for wallet/staking flows.
- Configure GraphQL endpoints via `VITE_PONDER_BASE_SEPOLIA`, `VITE_PONDER_BASE`, and optionally override `VITE_PONDER_BASE_SEPOLIA_LOCAL_FORK` (defaults to `http://127.0.0.1:42069/graphql`).
## Guardrails & Tips
- `token0isWeth` flips amount semantics; confirm ordering before seeding or interpreting liquidity.
- VWAP, `ethScarcity`, and Optimizer outputs operate on price^2 (X96). Avoid "normalising" to sqrt inadvertently.
- Fund the LiquidityManager with Base WETH (`0x4200...0006`) before expecting `recenter()` to succeed.
- Ponder stores data in `.ponder/`; drop the directory if schema changes break migrations.
- Keep git clean before committing; never leave commented-out code or untested changes.
4. **Automation Bot**
- Requires `.env` with RPC + key. Queries the Ponder GraphQL endpoint to decide when to pay tax or recenter liquidity.
- `scripts/local_env.sh start` provisions and launches the bot automatically when running against the local fork.
## Migration Notes (Subgraph → Ponder)
- Schema parity: ensure any entity changes land in both `ponder.schema.ts` and legacy Graph `schema.graphql` until cutover.
- Event coverage: `Stake` events (`PositionCreated/Removed/Shrunk/TaxPaid/RateHiked`) mirrored from AssemblyScript handlers. Kraiken `Transfer` powers mint/burn/tax/UBI tracking.
- Ring buffer logic in `kraiken.ts` depends on block timestamps being monotonic; gaps >168 hours zero out the buffer. Verify `startBlock` in `ponder.config.ts` to avoid reprocessing genesis noise.
- Local deployment requires updating `ponder.config.ts` local contract addresses after each run or injecting via env overrides. The `BASE_SEPOLIA_LOCAL_FORK` profile assumes addresses generated by `DeployLocal.sol`.
- Ponder v0.13 exposes helpers via `context.client` / `context.contracts`; use these to seed stats from on-chain `totalSupply` and refresh `outstandingStake` straight from the `Stake` contract. All hourly projections now run off a JSON ring buffer on the `stats` row.
- Subgraph naming differs from the new schema (`stats_collection`, decimal shares). The web-app and txn bot now target the Ponder schema directly; keep legacy Graph compatibility only until the AssemblyScript stack is fully retired.
- Tax accounting must listen to `PositionTaxPaid` instead of guessing via hard-coded addresses. The old subgraph missed this; Ponder now increments the ring buffer segment on each tax payment.
- Liquidity bootstrap still depends on the Uniswap pool stepping through `recenter()`. On current Base-Sepolia forks the LM reverts with `LOK`. Investigate before relying on `scripts/local_env.sh start` for an unattended setup.
## Testing Playbook
- **Unit/Fuzz**: `forge test` and scripts under `onchain/analysis/` to stress liquidity + staking edge cases.
- **Integration (local fork)**:
1. `anvil --fork-url https://sepolia.base.org` (or base mainnet RPC) in terminal 1.
2. From `onchain/`, deploy with `forge script script/DeployLocal.sol --fork-url http://127.0.0.1:8545 --broadcast`.
3. Fund LiquidityManager, call `recenter()`, and execute sample trades (KRK buy, stake, unstake) using `cast` or Foundry scripts.
4. Start Ponder (`PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK npm run dev`) and watch logs for handler errors.
5. Query GraphQL (`stats`, `positions`) to confirm indexed state.
## Gotchas & Tips
- `token0isWeth` toggles amount0/amount1 semantics—check pool ordering before seeding liquidity.
- VWAP/ethScarcity logic expects squared price format; do not convert to sqrt unintentionally.
- LiquidityManager `recenter()` reverts unless funded with WETH (Base WETH address `0x4200...006`). Use `cast send` with sufficient ETH when testing locally.
- Ponder’s SQLite store lives in `.ponder/` (gitignored). Delete between runs if schema changes.
- Legacy subgraph is maintained for reference only; all active services now read from Ponder.
- `web-app/` reads from Ponder by default (see `src/config.ts`). Update the environment specific GraphQL URLs when deployments move.
## Useful Commands
- `foundryup` / `forge clean` / `forge snapshot`
- `anvil --fork-url https://sepolia.base.org`
- `cast call <POOL> "slot0()"`
- `PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK npm run dev`
## Handy Commands
- `foundryup` - update Foundry toolchain.
- `anvil --fork-url https://sepolia.base.org` - manual fork when diagnosing outside the helper script.
- `cast call <POOL> "slot0()"` - inspect pool state.
- `PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK npm run dev` (inside `services/ponder/`) - focused indexer debugging when the full stack is already running.
- `curl -X POST http://localhost:42069/graphql -d '{"query":"{ stats(id:\"0x01\"){kraikenTotalSupply}}"}'`
- `curl http://127.0.0.1:43069/status`
- `nohup ./scripts/local_env.sh start &` boots Anvil+contracts+ponder+frontend+txnBot; stop with Ctrl+C or `./scripts/local_env.sh stop` when you want to tear it down.
## Refactor Backlog
- Replace the temporary `any` shims in `services/ponder/src/kraiken.ts` and `services/ponder/src/stake.ts` by importing the official 0.13 handler types instead of stubbing `ponder-env.d.ts`.
- Drop the custom `ponder:api` / `ponder:registry` module declarations once the generator emits them; if it cannot, declare precise interfaces rather than `any` to keep autocomplete and future upgrades safe.
- Convert the JSON ABI imports in `services/ponder/ponder.config.ts` to typed loaders (e.g., `satisfies Abi`) so config drift is caught at compile time instead of via `as Abi` casts.
- Move the snatch-selection logic out of `web-app/src/components/StakeHolder.vue` into a dedicated composable that both the stake form and charts can reuse, and memoise the `assetsToShares` conversions there.
- Split `kraiken-lib/src/helpers.ts` into focused modules (ids, tax rates, snatch selection) so consumers can tree-shake and each helper stays small and testable.
## Contacts & Artifacts
- Deployment addresses recorded in `onchain/deployments-local.json` (local) and broadcast traces under `onchain/broadcast/`.
- Technical deep dive: `TECHNICAL_APPENDIX.md` & `HARBERG.md`.
- Liquidity math references: `onchain/UNISWAP_V3_MATH.md`.
## References
- Deployment history: `onchain/deployments-local.json`, `onchain/broadcast/`.
- Deep dives: `TECHNICAL_APPENDIX.md`, `HARBERG.md`, and `onchain/UNISWAP_V3_MATH.md`.