diff --git a/AGENTS.md b/AGENTS.md index 5d5c88d7e..21280200f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,38 +1,52 @@ -# Tangle dApp monorepo (Nx + Yarn) - -## Quick commands -- Install: `yarn install` (Node `>=18.18.x`, Yarn `4.x`) -- Run dApp: `yarn nx serve tangle-dapp` (default `http://localhost:4200`) -- Lint/test/build: `yarn lint`, `yarn test`, `yarn build` - -## Env -- Start from `.env.example` (Vite vars are `VITE_*`) -- Set `VITE_GRAPHQL_ENDPOINT` to your Envio/Hasura GraphQL (local indexer or mainnet) -- Optional: `VITE_WALLETCONNECT_PROJECT_ID` for WalletConnect -- Migration claim flow (`/claim/migration`) requires: - - `VITE_MIGRATION_PROOFS_URL` (proof data JSON) - - `VITE_MIGRATION_RPC_URL` (RPC for migration reads) - - Optional `VITE_TANGLE_MIGRATION_ADDRESS` override (must be non-zero) - - Optional `VITE_CLAIM_RELAYER_URL` (otherwise wallet mode is used) - - Optional `VITE_SP1_PROVER_API_URL` and `VITE_MOCK_PROOF` for proof generation/testing - -## Local protocol repo -- `../tnt-core/` (sibling repo): protocol + claims migration contracts, gas relayer, indexer, etc. -- When running locally, ensure: - - the chain you connect the UI to matches your `tnt-core` deployments - - `VITE_GRAPHQL_ENDPOINT` points at the indexer for that chain - -## Key code locations -- App: `apps/tangle-dapp/` (Vite + React Router) -- Staking (EVM v2): - - GraphQL hooks: `libs/tangle-shared-ui/src/data/graphql/` - - Tx hooks: `libs/tangle-shared-ui/src/data/tx/` - - Write executor: `libs/tangle-shared-ui/src/hooks/useContractWrite.ts` -- Seed scripts (Substrate dev): - - `yarn script:setupServices` (create blueprints) - - `yarn script:setupStaking` (LST/vault/operator staking fixtures) - -## Harness runbook -- Operating spec: `docs/harness-engineering-spec.md` -- Execution checklist: `docs/harness-engineering-checklist.md` -- Wallet flow suite usage: `docs/wallet-flow-suite.md` +# Tangle dApp + +This Nx workspace contains Tangle applications and shared libraries for the TNT EVM protocol stack. +Shared repository guidance lives here; `CLAUDE.md` imports this file. + +## Find the owning source + +Use root `package.json`, project configuration, and Nx targets for current setup, commands, runtime, and test tools. +Read the relevant application's source and shared library before adding a parallel implementation. +Keep application-specific changes local; put reusable Tangle behavior in `tangle-shared-ui` and generic components in `ui-components`. + +Start environment configuration from [.env.example](.env.example). +For local protocol setup, read [scripts/local-env/start-local-env.sh](scripts/local-env/start-local-env.sh) and the matching `tnt-core` checkout. +The dApp, indexer, wallet, and deployed contracts must use the same chain. +Check current deployment configuration and live endpoints before relying on a remembered host, port, or chain identifier. + +Use `bigint` and `viem` for chain values rather than introducing new `BN` usage. +Use the EVM provider for EVM interactions; retain Polkadot compatibility where migration claims require it. +Verify migration proof, RPC, contract, and optional relayer configuration against the selected chain before exercising a claim. + +## Wallet and launch verification + +For launch-impacting changes, read [harness-engineering-spec.md](docs/harness-engineering-spec.md) and complete the applicable [checklist](docs/harness-engineering-checklist.md). +Use [wallet-flow-suite.md](docs/wallet-flow-suite.md) for execution and the [launch readiness board](docs/launch-readiness-board.csv) for flow coverage. +Run the applicable wallet suite and release check from package scripts, then inspect its report and release matrix. +Include the requested verification results in the PR's existing template. +Required flows and exceptions belong in those maintained records, not a second list here. + +Verify the chain, indexer, dApp, wallet provider, and funded test account before interpreting wallet-flow results. +Resolve local port conflicts through supported environment configuration. +Provider absence, connector timeouts, or chain mismatches block strict launch validation. +Exploratory continuation must remain identified as exploratory. +A result with zero agent turns does not prove the agent executed the flow; fix the runtime or model failure first. +Preserve the wallet suite's seeded profile, prompt handling, and funding checks. + +## Code conventions + +Follow the repository's configured formatting, lint, type, test, and build targets. +Use arrow functions, braces for control flow, descriptive names, and typed component props. +Avoid `any` and unnecessary type assertions. +Use memoization only when the component's behavior warrants it. +Keep business logic, data hooks, and generic UI responsibilities distinct without splitting code solely to meet a file quota. +Treat existing Storybook surfaces as legacy; do not add or modify them for ordinary application work. + +## Branches and release + +Feature, fix, and chore PRs target `develop`. +Production uses `master`; read [auto-sync-master-with-develop.yml](.github/workflows/auto-sync-master-with-develop.yml) and the release workflows before a release. +The automation promotes a develop push containing a `[RELEASE]` marker in a commit message. +Use that marker only for an intended release; ordinary maintenance must not trigger promotion. +Follow the workflow's current merge behavior rather than assuming it is a fast-forward. +Use deployment configuration and the live release result to determine which applications were published. diff --git a/CLAUDE.md b/CLAUDE.md index d1e2c39b3..43c994c2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,177 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -This is the Tangle dApp monorepo - a collection of decentralized applications for the Tangle Operator Layer for AI services, built on the TNT EVM protocol stack (`tnt-core`). - -The monorepo uses Nx for fast, extensible building with `apps/` containing interfaces and `libs/` containing shared code. - -## Common Development Commands - -```bash -# Install dependencies -yarn install - -# Development -yarn start # Start all apps -yarn start:tangle-dapp # Start main Tangle dApp -yarn start:tangle-cloud # Start Tangle Cloud -yarn start:leaderboard # Start leaderboard app -yarn start:storybook # Start Storybook for ui-components - -# Building -yarn build # Build all projects -yarn build:tangle-dapp # Build specific app -yarn build:tangle-cloud -yarn build:leaderboard - -# Code Quality -yarn lint # Lint all projects -yarn format # Format code with Prettier -yarn format:check # Check formatting -yarn typecheck # Type check all projects -yarn pr:check # Full pre-PR check (format + lint + build) - -# Testing -yarn test # Run all tests -yarn test # Run tests for specific project - -# Release (maintainers only) -yarn generate:release # Review version bumps and changelog -``` - -## Architecture & Key Concepts - -### Applications (apps/) - -- **tangle-dapp**: Main dApp for staking, delegation, rewards, migration claims, and wallet flows -- **tangle-cloud**: Operator/developer interface for blueprint and service lifecycle management -- **leaderboard**: Points and participation leaderboard - -### Libraries (libs/) - -- **abstract-api-provider**: Base classes unifying API across providers -- **api-provider-environment**: React contexts, app events, error handling -- **browser-utils**: Browser utilities (fetch, download, logger, storage) -- **dapp-config**: Chain/wallet configurations for dApps -- **dapp-types**: Shared TypeScript types and interfaces -- **icons**: Shared icon components -- **polkadot-api-provider**: Legacy chain provider used only by migration-claim flows -- **solana-api-provider**: Solana blockchain provider -- **tangle-shared-ui**: Tangle-specific logic, hooks, utilities (shared between dApps) -- **ui-components**: Generic reusable UI components -- **web3-api-provider**: EVM provider for blockchain interaction - -### Tech Stack - -- **Frontend**: Vite, TypeScript, React, TailwindCSS -- **Blockchain**: EVM-first (`viem`/`wagmi`) with limited PolkadotJS usage for migration-claim interoperability -- **Build System**: Nx monorepo -- **Styling**: TailwindCSS with custom preset - -## Development Guidelines - -### Execution Posture (Senior IC / Tech Lead) - -- Default to ownership and execution. When a goal is clear, proceed immediately without asking permission to continue. -- Prefer decisive action over proposal loops. Bring work to completion end-to-end (implementation, verification, reporting). -- Escalate only for true external blockers (missing credentials, unavailable infrastructure, irreversible risk), and name the exact blocker. -- Report status with concrete evidence (commands run, pass/fail, remaining gaps), not vague progress language. -- For release-readiness tasks, drive to production-grade confidence: strict validation, explicit failure reasons, and concrete remediation steps. -- Avoid “do you want me to…” phrasing when the expected next step is obvious from context. -- For launch-flow-impacting changes, follow `docs/harness-engineering-spec.md` and complete `docs/harness-engineering-checklist.md` before requesting merge. - -### Harness Release Process (Succinct) - -- Scope launch-impacting work to explicit flow IDs in `docs/launch-readiness-board.csv`. -- Run harness suite: `yarn test:wallet-flows` and inspect `suite/report.json` + `suite/release-matrix.md`. -- Enforce gate: `yarn test:wallet-flows:gate` (or `:strict` when required). -- Critical flows (`FLOW-001,002,005,010,011,013,014,018,019`) must be `happy-path-pass` unless exception owner/ETA is documented. -- Include matrix summary and gate output in PR using the harness section in `.github/PULL_REQUEST_TEMPLATE.md`. - -### Wallet Flow Reliability (agent-browser-driver) - -- Treat wallet E2E as environment-first: do not trust flow results until local chain + indexer + dApp are confirmed on the same network. -- Minimum readiness gate before running wallet flows: - - `http://127.0.0.1:8545` responds to `eth_chainId` with `0x7a69` (31337) - - Hasura GraphQL endpoint is reachable (typically `http://localhost:8080/v1/graphql`) - - dApp is started with local indexer env (`VITE_ENVIO_MAINNET_ENDPOINT` and `VITE_ENVIO_TESTNET_ENDPOINT` pointing to local Hasura) -- Use `scripts/local-env/start-local-env.sh` for deterministic local protocol state; if Docker ports are occupied (commonly `5433`), resolve port collisions first or set alternate `ENVIO_PG_PORT` / `HASURA_EXTERNAL_PORT`. -- Wallet preflight failures (`no-provider`, connector timeout, chain mismatch) must be treated as blockers for strict launch validation; only allow non-strict continuation for exploratory debugging. -- A suite result with `turns=0` is not valid evidence of agentic flow execution; treat it as runtime/LLM execution failure and fix provider/runtime conditions first. -- For local wallet runs, prefer persistent seeded profile + automated prompt settling, and ensure funding checks are active for connected local accounts. - -### Code Style - -- Use `const ... => {}` over `function ... () {}` -- React components: `const Component: FC = ({ prop1, prop2 }) => { ... }` -- Use `useMemo`/`useCallback` when appropriate (skip for simple calculations) -- Always use braces: `if (condition) { ... }` -- Add empty lines between sibling JSX components -- Avoid comments unless logic is complex -- Use descriptive variable names, avoid acronyms -- Avoid `as` type casting and `any` type - -### Folder Structure (within apps) - -- `utils/`: Utility functions (one function per file, same filename as function name) -- `components/`: Reusable "dumb" components specific to the app -- `containers/`: "Smart" components with business logic -- `hooks/`: React hooks for infrastructure logic -- `data/`: Data fetching hooks organized by domain (staking, liquid staking, etc.) -- `pages/`: Route pages for react-router-dom -- `abi/`: EVM ABI definitions for precompiles/contracts - -### Important Notes - -- **Localize changes**: Keep changes isolated to relevant projects unless shared libraries are involved -- **Package dependencies**: Don't assume packages exist - check imports or root `package.json` first -- **Number handling**: Prefer `bigint`/`viem` primitives for chain values; avoid introducing new `BN` usage. -- **Monorepo scope**: Avoid cross-project changes unless working with shared libs -- **Storybook**: Considered legacy, avoid creating/modifying storybook files -- **Testing**: No testing libraries currently used or planned - -### Branch Strategy - -Two-branch model (the previous `staging` branch was retired May 2026): - -- **`develop`** — main development branch. All feature, fix, and chore PRs target it. -- **`master`** — production. Promoted from `develop` automatically by the `auto-sync-master-with-develop.yml` workflow: any commit in a `develop` push whose subject starts with `[RELEASE]` triggers a fast-forward of `master` to the push's HEAD. No manual cherry-pick, no separate release branch. -- **Tag at least one commit per release PR with `[RELEASE]`** so auto-sync fires. Either: (a) squash-merge with a `[RELEASE] type(scope): …` subject — simplest, OR (b) ensure the PR's own commit subject starts with `[RELEASE]` and use a normal merge (the workflow scans every commit in the push, not just the merge subject). -- Hotfixes follow the same flow: PR into `develop`, tag the squash subject or branch commit with `[RELEASE]`. - -**Deploy environments** (each Netlify site is pinned to one branch via `allowed_branches`, so there is no overlap): - -| Env | Branch | URL | Netlify site | -|---|---|---|---| -| Production (cloud) | `master` | https://cloud.tangle.tools | `tangle-cloud` | -| Production (dapp) | `master` | https://app.tangle.tools | `tangle-dapp` | -| Production (leaderboard) | `master` | https://leaderboard.tangle.tools | `tangle-leaderboard` | -| Staging (cloud) | `develop` | https://develop.cloud.tangle.tools | `staging-tangle-cloud` | -| Staging (dapp) | `develop` | `develop.app.tangle.tools` | `staging-tangle-dapp` | -| Staging (leaderboard) | `develop` | https://develop.leaderboard.tangle.tools | `staging-tangle-leaderboard` | - -PR deploy previews are produced by the staging sites and surface in the GitHub PR check `Deploy Preview – staging-`. - -### Prerequisites - -- Node.js v18.18.x or later -- Yarn package manager (v4.7.0) - -## Working with Specific Libraries - -### tangle-shared-ui - -Contains Tangle-specific logic shared between dApps. Use this for functionality tied to Tangle Network context. - -### ui-components - -Generic, reusable components not tied to any specific context. Should be usable across different dApps. - -### API Providers - -- Use `polkadot-api-provider` only where migration-claim compatibility requires it -- Use `web3-api-provider` for EVM interactions -- Use `abstract-api-provider` base classes when creating new providers +@AGENTS.md