Skip to content

docs(instructions): unify dApp maintenance guidance #3325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
drewstone merged 1 commit into from
Sep 6, 2026
Merged

docs(instructions): unify dApp maintenance guidance #3325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 52 additions & 38 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
178 changes: 1 addition & 177 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <project-name> # 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<Props> = ({ 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-<app>`.

### 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
Loading