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

added web-app and landing

Browse source
This commit is contained in:
johba 2025-09-23 14:18:04 +02:00
parent af031877a5
commit 769fa105b8
198 changed files with 22132 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

67
AGENTS.md Normal file
View file

@ -0,0 +1,67 @@
# 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.
- `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 GraphQL API (`.graphclient`) to trigger `recenter()` and `payTax()` on-chain when profitable.
- `kraiken-lib/`: Shared TypeScript helpers (e.g., `bytesToUint256`) consumed by the landing app + bots.
## 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()`.
2. **Indexer (Ponder)**
- Install deps (`npm install`).
- Configure environment via `PONDER_NETWORK` (`local`, `baseSepolia`, 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.
3. **Frontend**
- `npm install` then `npm run dev` in `landing/`. Currently static marketing copy with placeholders for wallet/staking flows.
4. **Automation Bot**
- Requires `.env` with RPC + key. Queries indexer (Graph or Ponder) to decide when to pay tax or recenter liquidity.
## 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.
- 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). Until the web-app switches to Ponder’s GraphQL endpoint, keep the legacy entity shape in mind. Plan to provide either a compatibility layer or update `web-app/src/composables/useStatCollection.ts` to hit the new schema.
- 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=local 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 still powers `services/txnBot` until cutover—coordinate endpoint switch when Ponder is production-ready.
- `web-app/` currently points at The Graph Studio URLs (see `src/config.ts`). When Ponder replaces the subgraph, update those envs and mirror the expected GraphQL shape (the app queries `stats_collection` with camelCase fields). Consider adding an adapter layer or bumping the frontend to the new schema before deleting `subgraph/`.
## Useful Commands
- `foundryup` / `forge clean` / `forge snapshot`
- `anvil --fork-url https://sepolia.base.org`
- `cast call <POOL> "slot0()"`
- `PONDER_NETWORK=local npm run dev`
- `curl -X POST http://localhost:42069/graphql -d '{"query":"{ stats(id:\"0x01\"){kraikenTotalSupply}}"}'`
- `./scripts/local_env.sh start` boots Anvil+contracts+ponder+frontend; stop with Ctrl+C or `./scripts/local_env.sh stop`.
## 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`.