de3c8eef94
- Rewrite root README.md with proper project overview, tech stack, and repo structure - Remove duplicate CLAUDE.md files (root, onchain, ponder) — AGENTS.md is the standard - Update HARBERG.md to reflect Stage 1 completion and Stage 2 evolution - Delete stale onchain/testing_todos.md (all high-priority items completed) - Update VERSION_VALIDATION.md for VERSION=2 - Trim root AGENTS.md: replace Docker duplication with docs/docker.md reference - Trim onchain/AGENTS.md (129→71 lines): reference TECHNICAL_APPENDIX for formulas - Trim web-app/AGENTS.md (278→55 lines): remove internal API docs, keep architecture - Rewrite onchain/README.md: add contract table, deployment addresses, analysis links - Trim services/ponder/README.md: remove stale subgraph comparison - Add otterscan to docs/docker.md service topology - Update TECHNICAL_APPENDIX.md references Net: -388 lines across documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
# Web App - Agent Guide
|
|
|
|
Vue 3 + TypeScript staking interface for KRAIKEN, enabling users to stake tokens, manage positions, and interact with Harberger-tax mechanics.
|
|
|
|
## Technology Snapshot
|
|
- Vue 3 (Composition API) with TypeScript and Vite toolchain
|
|
- Wagmi/Viem for wallet connection and blockchain interaction
|
|
- Vue Router for navigation
|
|
- Axios for GraphQL queries to Ponder indexer
|
|
- Sass-based component styling
|
|
|
|
## Architecture
|
|
|
|
### Chain Configuration
|
|
`src/services/chainConfig.ts` centralizes endpoint resolution. All composables accept `chainId` as a parameter and resolve endpoints via `chainConfigService.getEndpoint(chainId, type)`. Supported chains: 31337 (Anvil), 84532 (Base Sepolia), 8453 (Base Mainnet).
|
|
|
|
### Wagmi Integration
|
|
`src/wagmi.ts` manages wallet connection. Wagmi is the source of truth for which chain the wallet is on. Composables don't import wallet state directly — they accept `chainId` for testability.
|
|
|
|
### Key Composables
|
|
- `useWallet()` — Wallet connection, balance, account state
|
|
- `usePositions(chainId)` — Loads staking positions from Ponder GraphQL
|
|
- `useStatCollection(chainId)` — Protocol-wide statistics
|
|
- `useSnatchSelection(demo, taxRateIndex, chainId)` — Calculates snatchable positions
|
|
- `useStake()` — Executes staking transactions
|
|
- `useAdjustTaxRate()` — Tax rate adjustment
|
|
- `useUnstake()` — Position exit transactions
|
|
|
|
### Key Components
|
|
- `StakeView.vue` — Main staking dashboard (route: `/dashboard`)
|
|
- `StakeHolder.vue` — Staking form with accessibility-focused UI
|
|
- `ConnectWallet.vue` — Wallet connection modal
|
|
- `ChartComplete.vue` — Position visualization
|
|
- `CollapseActive.vue` — Expandable position card with actions
|
|
|
|
## Development Workflow
|
|
- Boot full stack: `./scripts/dev.sh start` (see root AGENTS.md)
|
|
- Targeted: `npm run dev` (assumes Ponder/Anvil already running)
|
|
- Build: `npm run build`
|
|
- E2E tests: `npm run test:e2e` from repo root (Playwright)
|
|
|
|
## Testing
|
|
- E2E tests in `tests/e2e/` (repo root) cover complete user journeys
|
|
- Uses mocked wallet provider with Anvil accounts
|
|
- Relies on semantic HTML and ARIA attributes for selectors
|
|
- StakeHolder test hooks: `page.getByRole('slider', { name: 'Token Amount' })`, `page.getByLabel('Tax')`
|
|
|
|
## Quality Guidelines
|
|
- Composables accept `chainId` parameter instead of importing wallet state directly
|
|
- Each composable maintains its own `watchChainId()` listener for independence
|
|
- Always expose `xxxError` and `loading` refs for UI feedback
|
|
- Use strongly typed interfaces for Position, StatsRecord, etc.
|
|
- Use semantic HTML, ARIA attributes, and keyboard navigation
|
|
- Clear watchers and retry timers in `onUnmounted()`
|