From 090a20fcd183d68d8292265f4f3e5798cba5b222 Mon Sep 17 00:00:00 2001 From: Augusto Lemble Date: Thu, 19 Mar 2026 15:52:22 -0300 Subject: [PATCH] docs(claude): update rules to reflect current architecture and workflow - workflow: add dual strategy (patch PRs to dev, release branches for minor/major) - architecture: update to NetworkAdapter/AdapterFactory pattern, add Bitcoin and Hardhat - patterns: fix paths, update "add network" steps to new adapter structure - i18n: add 5 supported languages, tooltips namespace, update checklists - code-style: reference all 5 locales in i18n verification --- .claude/rules/architecture.md | 55 ++++++++--------- .claude/rules/code-style.md | 2 +- .claude/rules/i18n.md | 13 +++-- .claude/rules/patterns.md | 17 +++--- .claude/rules/workflow.md | 107 ++++++++++++++++++++++------------ 5 files changed, 114 insertions(+), 80 deletions(-) diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md index cf1ade9f..ec5e538a 100644 --- a/.claude/rules/architecture.md +++ b/.claude/rules/architecture.md @@ -4,48 +4,49 @@ OpenScan follows a layered architecture with clear separation between data fetching, transformation, and presentation: -### 1. RPC Layer (`RPCClient.ts`) -Handles JSON-RPC communication with blockchain nodes: -- Supports two strategies: `fallback` (sequential with automatic failover) and `parallel` (query all providers simultaneously) -- Strategy is configurable via user settings (`useDataService` hook applies strategy) -- Parallel mode enables provider comparison and inconsistency detection - -### 2. Fetcher Layer (`services/EVM/*/fetchers/`) -Makes raw RPC calls for specific data types: -- Network-specific implementations: `L1/`, `Arbitrum/`, `Optimism/` -- Each fetcher handles one domain (blocks, transactions, addresses, network stats) - -### 3. Adapter Layer (`services/EVM/*/adapters/`) -Transforms raw RPC responses into typed domain objects: -- Normalizes network-specific fields (e.g., Arbitrum's `l1BlockNumber`, Optimism's L1 fee data) -- Ensures consistent type structure across networks - -### 4. Service Layer (`DataService.ts`) +### 1. Client Layer (`@openscan/network-connectors`) +Typed RPC clients for blockchain communication: +- `EthereumClient` - Standard JSON-RPC for EVM chains +- `HardhatClient` - Extended client with Hardhat-specific methods (`hardhat_*`, `evm_*`, `debug_*`) +- `BitcoinClient` - Bitcoin JSON-RPC (`getblock`, `getrawtransaction`, etc.) +- Supports `fallback`, `parallel`, and `race` strategies + +### 2. Adapter Layer (`services/adapters/`) +Abstract `NetworkAdapter` base class with chain-specific implementations: +- `EVMAdapter` - Default EVM adapter (Ethereum, BSC, Polygon, Sepolia) +- `ArbitrumAdapter` - Adds `l1BlockNumber`, `sendCount`, `sendRoot` +- `OptimismAdapter` / `BaseAdapter` - Adds L1 fee breakdown (`l1Fee`, `l1GasPrice`, `l1GasUsed`) +- `HardhatAdapter` - Localhost (31337) with trace support via struct log conversion +- `BitcoinAdapter` - Bitcoin networks with UTXO model, mempool, and block explorer +- Each adapter implements: `getBlock`, `getTransaction`, `getAddress`, `getNetworkStats`, trace methods +- `AdapterFactory` routes chain ID to the correct adapter + +### 3. Service Layer (`DataService.ts`) Orchestrates data fetching with caching and metadata: -- Instantiates network-specific fetchers/adapters based on chain ID +- Instantiates the correct adapter via `AdapterFactory` based on chain ID - Returns `DataWithMetadata` when using parallel strategy - 30-second in-memory cache keyed by `networkId:type:identifier` -- Supports trace operations for localhost networks only -### 5. Hook Layer (`hooks/`) +### 4. Hook Layer (`hooks/`) React integration: - `useDataService(networkId)`: Creates DataService instance with strategy from settings - `useProviderSelection`: Manages user's selected RPC provider in parallel mode - `useSelectedData`: Extracts data from specific provider based on user selection -### 6. Context Layer (`context/`) +### 5. Context Layer (`context/`) Global state management: - `AppContext`: RPC URLs configuration -- `SettingsContext`: User settings including `rpcStrategy` ('fallback' | 'parallel') +- `SettingsContext`: User settings including `rpcStrategy` ('fallback' | 'parallel' | 'race') ## Network-Specific Handling -Chain ID detection in `DataService` constructor determines which adapters/fetchers to use: +Chain ID detection in `AdapterFactory` determines which adapter to instantiate: -- **Arbitrum** (42161): `BlockFetcherArbitrum`, `BlockArbitrumAdapter` - adds `l1BlockNumber`, `sendCount`, `requestId` -- **OP Stack** (10, 8453): Optimism (10), Base (8453) - adds L1 fee breakdown (`l1Fee`, `l1GasPrice`, `l1GasUsed`) -- **Localhost** (31337): All networks + trace support (`debug_traceTransaction`, `trace_block`, etc.) -- **Default**: L1 fetchers/adapters for Ethereum (1), BSC (56, 97), Polygon (137), Sepolia (11155111) +- **Arbitrum** (42161): `ArbitrumAdapter` - adds `l1BlockNumber`, `sendCount`, `sendRoot` +- **OP Stack** (10, 8453): `OptimismAdapter`, `BaseAdapter` - adds L1 fee breakdown +- **Hardhat** (31337): `HardhatAdapter` - trace support via struct log conversion (`buildCallTreeFromStructLogs`, `buildPrestateFromStructLogs`) +- **Bitcoin** (bip122:*): `BitcoinAdapter` - UTXO model, mempool transactions, block rewards +- **Default**: `EVMAdapter` for Ethereum (1), BSC (56, 97), Polygon (137), Sepolia (11155111), BNB (56) ## Key Type Definitions diff --git a/.claude/rules/code-style.md b/.claude/rules/code-style.md index 33dfdabb..70a5a412 100644 --- a/.claude/rules/code-style.md +++ b/.claude/rules/code-style.md @@ -61,7 +61,7 @@ npm run typecheck # 4. Verify i18n compliance # - Ensure no hardcoded user-facing strings -# - Test in both English and Spanish if you added translations +# - Test in multiple languages if you added translations (en, es, ja, pt-BR, zh) # 5. Run tests (if applicable) npm run test:run diff --git a/.claude/rules/i18n.md b/.claude/rules/i18n.md index 66948ff5..99a68268 100644 --- a/.claude/rules/i18n.md +++ b/.claude/rules/i18n.md @@ -9,7 +9,7 @@ - **Library**: react-i18next (v16.5.4) with i18next (v25.8.0) - **Configuration**: `src/i18n.ts` - **Type Definitions**: `src/i18next.d.ts` (provides TypeScript autocomplete) -- **Supported Languages**: English (en), Spanish (es) +- **Supported Languages**: English (en), Spanish (es), Japanese (ja), Portuguese-BR (pt-BR), Chinese (zh) - **Language Detection**: Auto-detects from browser or localStorage (`openScan_language`) ## When to Use i18n @@ -49,6 +49,7 @@ Choose the appropriate namespace based on the component location: 8. **devtools** - Developer tools page 9. **errors** - Error messages (if not in common) 10. **tokenDetails** - Token detail pages (ERC20, ERC721, ERC1155) +11. **tooltips** - Helper tooltip content for blockchain data fields (used by FieldLabel/HelperTooltip) ## Basic Usage @@ -153,9 +154,9 @@ const currentLang = i18n.language; // "en" or "es" 1. **Identify the appropriate namespace** based on component location 2. **Add key to English file** (`src/locales/en/{namespace}.json`) -3. **Add same key to Spanish file** (`src/locales/es/{namespace}.json`) +3. **Add same key to all other locale files** (`src/locales/{es,ja,pt-BR,zh}/{namespace}.json`) 4. **Use TypeScript autocomplete** to verify the key exists -5. **Test in both languages** by switching in Settings +5. **Test in multiple languages** by switching in Settings ### Example @@ -325,9 +326,9 @@ When adding or modifying components, ensure: - [ ] No hardcoded user-facing strings remain - [ ] All text uses `t()` function from useTranslation -- [ ] Translation keys exist in **both** en/ and es/ directories +- [ ] Translation keys exist in **all** locale directories (en, es, ja, pt-BR, zh) - [ ] TypeScript compilation passes (`npm run typecheck`) -- [ ] Tested in both English and Spanish (switch in Settings) +- [ ] Tested in multiple languages (switch in Settings) ## Checklist for Code Review @@ -337,5 +338,5 @@ When reviewing code, verify: - [ ] Appropriate namespace is selected - [ ] Translation keys follow existing naming patterns - [ ] Interpolation variables are properly typed -- [ ] Translations exist in all supported languages +- [ ] Translations exist in all 5 supported languages (en, es, ja, pt-BR, zh) - [ ] No typos in translation keys (TypeScript should catch these) diff --git a/.claude/rules/patterns.md b/.claude/rules/patterns.md index 8d9e0d11..8b71e764 100644 --- a/.claude/rules/patterns.md +++ b/.claude/rules/patterns.md @@ -2,17 +2,18 @@ ## When Modifying Data Fetching -- Always maintain the adapter pattern: Fetcher → Adapter → Service +- Always maintain the adapter pattern: Client → Adapter → Service +- All adapters extend the abstract `NetworkAdapter` class (`services/adapters/NetworkAdapter.ts`) - If adding parallel strategy support, ensure complete objects are built for each provider -- Test both `fallback` and `parallel` strategies +- Test `fallback`, `parallel`, and `race` strategies - Update TypeScript types in `src/types/index.ts` if adding new fields ## When Adding L2-Specific Features - Check if network is OP Stack-based (Optimism, Base) or Arbitrum - Add network-specific types (e.g., `TransactionOptimism extends Transaction`) -- Create adapters that inherit base behavior and add L2 fields -- Update `DataService` conditional logic in constructor and relevant methods +- Create a new adapter extending `NetworkAdapter` in `services/adapters/[Network]/` +- Register the adapter in `AdapterFactory` (`services/adapters/adaptersFactory.ts`) ## When Working with Cache @@ -32,9 +33,9 @@ 1. Add chain ID to `src/types/index.ts` if creating new domain types 2. Add default RPC endpoints to `src/config/rpcConfig.ts` -3. Determine if network needs custom fetchers/adapters (L1, Arbitrum-like, OP Stack-like) -4. If custom: create `src/services/EVM/[Network]/fetchers/` and `adapters/` -5. Update `DataService` constructor to detect chain ID and instantiate correct fetchers/adapters +3. Determine if network needs a custom adapter (L1, Arbitrum-like, OP Stack-like, Bitcoin) +4. If custom: create `src/services/adapters/[Network]/[Network]Adapter.ts` extending `NetworkAdapter` +5. Register the adapter in `AdapterFactory` (`src/services/adapters/adaptersFactory.ts`) 6. Add network config to `ALL_NETWORKS` in `src/config/networks.ts` 7. Add network logo to `public/` and update `logoType` in network config @@ -50,7 +51,7 @@ OpenScan includes special support for localhost development: ### Address Page Components - Use display components for different address types: `AccountDisplay`, `ContractDisplay`, `ERC20Display`, `ERC721Display`, `ERC1155Display` -- Shared components in `src/components/pages/address/shared/` +- Shared components in `src/components/pages/evm/address/shared/` - Card-based layout with Overview and More Info sections ### Theming diff --git a/.claude/rules/workflow.md b/.claude/rules/workflow.md index 579f2a94..1ccfe130 100644 --- a/.claude/rules/workflow.md +++ b/.claude/rules/workflow.md @@ -2,76 +2,107 @@ ## Branch Strategy -The project follows a structured branching workflow: +The project uses two workflows depending on the scope of changes: + +### Patch Releases (default workflow) + +For incremental work (bug fixes, small features, improvements) that goes into the next patch version: ``` -feature/fix/refactor branches → release branch (vX.Y.Z) → dev (staging/QA) → main (production) +feature/fix/refactor branches → dev (release candidate) → main (production) ``` -### Branch Types +1. **Dev Branch**: Always holds the next release candidate (patch increment) + - Feature/fix PRs are created directly against `dev` + - Used for QA/staging before production + - Always represents the next patch version (e.g., if main is v1.2.0, dev is the v1.2.1 candidate) -1. **Feature/Fix/Refactor Branches**: Created from the **release branch** for specific changes +2. **Feature/Fix/Refactor Branches**: Created from `dev` - Naming: `feat/`, `fix/`, `refactor/` - - Example: `feat/token-holdings`, `fix/light-theme-colors`, `refactor/address-layout` - - PRs are created against the release branch - -2. **Release Branches**: Created for each release cycle - - Naming: `release/vX.Y.Z` (e.g., `release/v1.1.1`) - - All feature branches are merged here - - When features are complete, merged to `dev` for QA/staging + - PRs are created against `dev` -3. **Dev Branch**: Staging/QA environment - - Receives merges from release branches - - Used for QA testing before production - - If fixes are needed during QA, PRs can be created directly against `dev` - -4. **Main Branch**: Production-ready code +3. **Main Branch**: Production-ready code - Only receives merges from `dev` after QA approval - - Always stable and deployable + - Tagged with the version on merge -### Workflow Steps +#### Patch Workflow Steps -1. Create or checkout the release branch: +1. Create feature branch from `dev`: ```bash - git checkout release/v1.1.1 - git pull origin release/v1.1.1 + git checkout dev + git pull origin dev + git checkout -b feat/my-feature ``` -2. Create feature branch from the release branch: +2. Work on feature, commit changes following conventional commits + +3. Push and create PR to `dev`: ```bash - git checkout -b feat/my-feature + git push -u origin feat/my-feature + gh pr create --base dev ``` -3. Work on feature, commit changes following conventional commits +4. After PR approval and merge to `dev`, delete feature branch -4. Push and create PR to the **release branch**: +5. After QA approval, merge `dev` to `main`: ```bash - git push -u origin feat/my-feature - gh pr create --base release/v1.1.1 + git checkout main + git merge dev + git tag v1.2.1 + git push origin main --tags ``` -5. After PR approval and merge to release branch, delete feature branch +### Minor/Major Releases (release branch workflow) + +For larger milestones with multiple coordinated changes (new features, breaking changes): -6. When release is ready for QA, merge release branch to `dev`: +``` +feature/fix/refactor branches → release branch (vX.Y.Z) → dev → main +``` + +1. **Release Branches**: Created from `dev` for each release cycle + - Naming: `release/vX.Y.Z` (e.g., `release/v1.3.0`) + - Feature branches are created from and merged into the release branch + - When features are complete, merged to `dev` for QA/staging + +2. **Feature Branches**: Created from the **release branch** + - PRs are created against the release branch + +#### Release Branch Workflow Steps + +1. Create the release branch from `dev`: ```bash git checkout dev - git merge release/v1.1.1 - git push origin dev + git checkout -b release/v1.3.0 + git push -u origin release/v1.3.0 + ``` + +2. Create feature branches from the release branch: + ```bash + git checkout release/v1.3.0 + git checkout -b feat/my-feature ``` -7. **QA/Staging fixes**: If issues are found during QA, create PRs directly against `dev`: +3. Push and create PR to the **release branch**: + ```bash + git push -u origin feat/my-feature + gh pr create --base release/v1.3.0 + ``` + +4. When all features are merged, merge release branch to `dev` for QA: ```bash git checkout dev - git checkout -b fix/qa-issue - # ... fix the issue ... - gh pr create --base dev + git merge release/v1.3.0 + git push origin dev ``` -8. After QA approval, merge `dev` to `main`: +5. QA fixes go directly against `dev` + +6. After QA approval, merge `dev` to `main`: ```bash git checkout main git merge dev - git tag v1.1.1 + git tag v1.3.0 git push origin main --tags ```