johba/harb
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
harb/web-app/AGENTS.md
openhands de3c8eef94 docs: consolidate and update all documentation for launch readiness 
- 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>
2026-02-13 19:22:34 +00:00

2.6 KiB
Raw Blame History

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()