diff --git a/AGENTS.md b/AGENTS.md index 29bb7c3..7fef159 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ - + # Agent Brief: Harb Stack ## What is KRAIKEN? @@ -32,6 +32,10 @@ KRAIKEN couples Harberger-tax staking with a dominant Uniswap V3 liquidity manag ``` See [docs/dev-environment.md](docs/dev-environment.md) for restart modes, ports, Docker topology, and common pitfalls. +## Docker / LXD Notes +- Containers require `security_opt: apparmor=unconfined` when running inside LXD to avoid permission denied errors on Unix socket creation (Anvil, Postgres). +- Umami analytics runs on **port 3001** (moved from 3000 to avoid conflict with Forgejo when running alongside the disinto factory stack). + ## Red-team Agent Context The red-team agent (`scripts/harb-evaluator/red-team.sh`) injects the following Solidity sources into the agent prompt so it can reason from exact contract logic: - `LiquidityManager.sol` — three-position manager, recenter, floor formula @@ -48,6 +52,7 @@ The red-team agent (`scripts/harb-evaluator/red-team.sh`) injects the following - **LiquidityManager funding**: Fund with Base WETH (`0x4200...0006`) before expecting `recenter()` to succeed. - **Ponder state**: Stored in `.ponder/`; drop the directory if schema changes break migrations. - **Harberger staking** supplies the sentiment oracle that drives Optimizer parameters, which in turn tune liquidity placement and supply expansion. +- **viem v2 slot0**: `slot0()` returns an array, not a record. `tick` is at index 1 (e.g. `slot0Response[1]`), not `slot0Response.tick`. ## Engineering Principles These apply to infrastructure (Docker, scripts, startup/teardown) and test/scenario execution — NOT to frontend polling of HTTP APIs where caching is the correct solution. diff --git a/containers/bootstrap.sh b/containers/bootstrap.sh index 1952593..299bf4e 100755 --- a/containers/bootstrap.sh +++ b/containers/bootstrap.sh @@ -104,6 +104,9 @@ write_ponder_env() { PONDER_NETWORK=$NETWORK_NAME KRAIKEN_ADDRESS=$KRAIKEN STAKE_ADDRESS=$STAKE +LM_ADDRESS=$LIQUIDITY_MANAGER +POOL_ADDRESS=$POOL_ADDRESS +MINIMUM_BLOCKS_FOR_RINGBUFFER=0 START_BLOCK=$DEPLOY_BLOCK PONDER_RPC_URL_${NETWORK_NAME}=$ANVIL_RPC DATABASE_URL=postgresql://ponder:ponder_local@postgres:5432/ponder_local diff --git a/formulas/AGENTS.md b/formulas/AGENTS.md index 230ae78..90ce8fc 100644 --- a/formulas/AGENTS.md +++ b/formulas/AGENTS.md @@ -1,4 +1,4 @@ - + # Agent Brief: Formulas Formulas are TOML files that declare automated pipeline jobs for the harb evaluator. diff --git a/gardener/pending-actions.json b/gardener/pending-actions.json index 04530a0..11bf8f8 100644 --- a/gardener/pending-actions.json +++ b/gardener/pending-actions.json @@ -1,22 +1,7 @@ [ { - "action": "comment", - "issue": 1179, - "body": "Closing: action complete. Post-fix user-test run (`evidence/user-test/2026-03-27-post-stake-fix.json`) verified the /stakestake navigation bug (PR #1171) is fixed — all 3 personas that reached /stake navigated correctly with no invalid route. The prediction concern is resolved. New ponder 504 issue and chain-revert state corruption were discovered as separate items." - }, - { - "action": "close", - "issue": 1179, - "reason": "actioned and verified — /stakestake fix confirmed working in post-fix user-test 2026-03-27" - }, - { - "action": "comment", - "issue": 1177, - "body": "Closing: action complete. A fresh red-team session was run on 2026-03-27 (`evidence/red-team/2026-03-27.json`): 7 real attacks with full per-attack data, floor_held: true, verdict: floor_held. The ghost run concern is addressed — the new run provides the real evidence the 2026-03-26 ghost run lacked." - }, - { - "action": "close", - "issue": 1177, - "reason": "actioned and verified — fresh red-team run 2026-03-27 completed with 7 real attacks" + "action": "add_label", + "issue": 13, + "label": "bug-report" } ] diff --git a/kraiken-lib/AGENTS.md b/kraiken-lib/AGENTS.md index 4894c19..d63542a 100644 --- a/kraiken-lib/AGENTS.md +++ b/kraiken-lib/AGENTS.md @@ -1,4 +1,4 @@ - + # Kraiken Library - Agent Guide Shared TypeScript helpers used by the landing app, txnBot, and other services to talk to KRAIKEN contracts and the Ponder GraphQL API. diff --git a/landing/AGENTS.md b/landing/AGENTS.md index 0c92ebc..8dc27ea 100644 --- a/landing/AGENTS.md +++ b/landing/AGENTS.md @@ -1,4 +1,4 @@ - + # Landing Interface - Agent Guide Vue 3 + Vite application that delivers the public marketing site and forthcoming staking UI. diff --git a/onchain/AGENTS.md b/onchain/AGENTS.md index f10e36a..bb73f00 100644 --- a/onchain/AGENTS.md +++ b/onchain/AGENTS.md @@ -1,4 +1,4 @@ - + # Agent Brief: Kraiken Protocol ## Protocol Philosophy & Business Logic diff --git a/scripts/bootstrap-common.sh b/scripts/bootstrap-common.sh index 2c6182b..763d714 100755 --- a/scripts/bootstrap-common.sh +++ b/scripts/bootstrap-common.sh @@ -102,6 +102,19 @@ extract_addresses() { bootstrap_log "LiquidityManager address missing" exit 1 fi + + # Discover Uniswap pool address from factory + POOL_ADDRESS="" + detect_swap_router + local factory + factory=$(cast call --rpc-url "$ANVIL_RPC" "$SWAP_ROUTER" "factory()(address)" 2>/dev/null) || factory="" + if [[ -n "$factory" && "$factory" != "0x" ]]; then + POOL_ADDRESS=$(cast call --rpc-url "$ANVIL_RPC" "$factory" "getPool(address,address,uint24)(address)" "$WETH" "$KRAIKEN" 10000 2>/dev/null) || POOL_ADDRESS="" + fi + if [[ -z "$POOL_ADDRESS" || "$POOL_ADDRESS" == "0x0000000000000000000000000000000000000000" ]]; then + bootstrap_log "Warning: could not discover pool address" + POOL_ADDRESS="" + fi } write_contracts_env() { diff --git a/scripts/harb-evaluator/AGENTS.md b/scripts/harb-evaluator/AGENTS.md index 081ade4..a51de44 100644 --- a/scripts/harb-evaluator/AGENTS.md +++ b/scripts/harb-evaluator/AGENTS.md @@ -1,4 +1,4 @@ - + # Agent Brief: harb-evaluator The evaluator runtime executes formula-defined pipelines. Scripts in this diff --git a/services/ponder/AGENTS.md b/services/ponder/AGENTS.md index c99fc0a..45384e3 100644 --- a/services/ponder/AGENTS.md +++ b/services/ponder/AGENTS.md @@ -1,4 +1,4 @@ - + # Ponder Indexer - Agent Guide Ponder-based indexer that records Kraiken protocol activity and exposes the GraphQL API consumed by the app and automation bot. @@ -13,8 +13,15 @@ Ponder-based indexer that records Kraiken protocol activity and exposes the Grap - `ponder.config.ts` - Network selection and contract bindings (update addresses after deployments). - `ponder.schema.ts` - Stats, hourly data, and position tables. - `src/kraiken.ts` / `src/stake.ts` - Event handlers; rely on Ponder v0.13 helpers for on-chain reads during sync. +- `src/helpers/stats.ts` - Ring buffer logic; `MINIMUM_BLOCKS_FOR_RINGBUFFER` is configurable via env var (see below). - `.ponder/` - Local SQLite/state cache (safe to delete when schemas change). +## Environment Variables +- `LM_ADDRESS` — LiquidityManager contract address; must be set in `.env.local` for correct contract binding. Bootstrap (`containers/bootstrap.sh`) writes this automatically. +- `POOL_ADDRESS` — Uniswap V3 pool address; discovered from the Uniswap factory during bootstrap and written to `.env.local`. Ponder uses this for pool event indexing. +- `MINIMUM_BLOCKS_FOR_RINGBUFFER` — Override the minimum block count before ring buffer data is populated (default: 100). Set to `0` for local dev so early events populate the ring buffer from genesis. +- `START_BLOCK` — Deploy block number; written by bootstrap; used as the Ponder `startBlock` for all contract event sources. + ## Development Workflow - Primary path: `nohup ./scripts/dev.sh start &` boots Anvil, deploys contracts, and launches Ponder in watch mode. - Docker stack: `docker-compose up -d` starts all services including PostgreSQL; bootstrap creates `.env.local` automatically. @@ -25,6 +32,7 @@ Ponder-based indexer that records Kraiken protocol activity and exposes the Grap - Confirm handler timestamps are monotonic; large gaps (>168 hours) reset the ring buffer by design. - Regenerate typings after schema edits by restarting Ponder; generated artifacts live in `generated/`. - If the stack script fails during boot, check `.ponder/logs` and RPC quota usage before rerunning. +- If protocol activity statistics show all zeros, verify `LM_ADDRESS` and `POOL_ADDRESS` are present in `.env.local` — the indexer silently watches the wrong (zero) address if they are missing. ## Containerized Environment (Podman/Docker) - **Environment Loading**: `.env.local` must be explicitly sourced in the entrypoint script before `npm run dev`. Ponder's built-in env loader may not find it in containerized environments. diff --git a/services/ponder/src/helpers/stats.ts b/services/ponder/src/helpers/stats.ts index 7d9bff9..b226a0d 100644 --- a/services/ponder/src/helpers/stats.ts +++ b/services/ponder/src/helpers/stats.ts @@ -7,7 +7,7 @@ export type StatsContext = HandlerArgs extends { context: infer C } ? C : never; type StatsEvent = HandlerArgs extends { event: infer E } ? E : never; export const RING_BUFFER_SEGMENTS = 4; // ethReserve, minted, burned, holderCount -export const MINIMUM_BLOCKS_FOR_RINGBUFFER = 100; +export const MINIMUM_BLOCKS_FOR_RINGBUFFER = parseInt(process.env.MINIMUM_BLOCKS_FOR_RINGBUFFER || '100'); // Get deploy block from environment (set by bootstrap) const DEPLOY_BLOCK = BigInt(process.env.START_BLOCK || '0'); diff --git a/services/txnBot/AGENTS.md b/services/txnBot/AGENTS.md index 07b2d27..1eb6710 100644 --- a/services/txnBot/AGENTS.md +++ b/services/txnBot/AGENTS.md @@ -1,4 +1,4 @@ - + # Transaction Bot - Agent Guide Automation service that maintains liquidity alignment and tax enforcement for the KRAIKEN protocol. diff --git a/web-app/AGENTS.md b/web-app/AGENTS.md index 6f7c5c8..b5b4fe6 100644 --- a/web-app/AGENTS.md +++ b/web-app/AGENTS.md @@ -1,4 +1,4 @@ - + # Web App - Agent Guide Vue 3 + TypeScript staking interface for KRAIKEN, enabling users to stake tokens, manage positions, and interact with Harberger-tax mechanics. @@ -34,6 +34,10 @@ Vue 3 + TypeScript staking interface for KRAIKEN, enabling users to stake tokens - `ChartComplete.vue` — Position visualization - `CollapseActive.vue` — Expandable position card with actions +## viem v2 Contract Call Patterns +- **`slot0()` returns an array, not a record.** `tick` is at index 1: `slot0Response[1]`. Do not access `slot0Response.tick` — that was viem v1 behaviour. `CheatsView.vue` handles both formats for backward compat. +- When adding new contract reads, check whether viem v2 returns an array or named tuple before indexing into the result. + ## Development Workflow - Boot full stack: `./scripts/dev.sh start` (see root AGENTS.md) - Targeted: `npm run dev` (assumes Ponder/Anvil already running) diff --git a/web-app/src/components/collapse/CollapseHistory.vue b/web-app/src/components/collapse/CollapseHistory.vue index 1dca3e9..95f8039 100644 --- a/web-app/src/components/collapse/CollapseHistory.vue +++ b/web-app/src/components/collapse/CollapseHistory.vue @@ -83,6 +83,7 @@ const relativeClosedAt = computed(() => { @use 'collapse' .f-collapse &.f-collapse-history + background-color: #07111B .collapse-header, .collapsableDiv margin-right: 32px .collapse-header diff --git a/web-app/src/views/CheatsView.vue b/web-app/src/views/CheatsView.vue index c1b6328..c83ee59 100644 --- a/web-app/src/views/CheatsView.vue +++ b/web-app/src/views/CheatsView.vue @@ -556,7 +556,9 @@ async function loadLiquidityStats({ notify = false }: { notify?: boolean } = {}) }); let currentTick: number | null = null; - if (isRecord(slot0Response) && typeof slot0Response.tick === 'number') { + if (Array.isArray(slot0Response) && typeof slot0Response[1] === 'number') { + currentTick = slot0Response[1]; + } else if (isRecord(slot0Response) && typeof slot0Response.tick === 'number') { currentTick = slot0Response.tick; }