v1.0.0-alpha

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Description
+A clear and concise description of the bug.
+
+## Steps to Reproduce
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
+
+## Expected Behavior
+What you expected to happen.
+
+## Actual Behavior
+What actually happened.
+
+## Screenshots
+If applicable, add screenshots to help explain your problem.
+
+## Environment
+- **Browser**: [e.g., Chrome 120, Firefox 121]
+- **OS**: [e.g., Windows 11, macOS 14, Ubuntu 22.04]
+- **Network**: [e.g., Ethereum Mainnet, Arbitrum, Localhost]
+
+## Additional Context
+Add any other context about the problem here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+## Description
+
+<!-- Brief description of the changes in this PR -->
+
+## Related Issue
+
+<!-- Link to the related issue (e.g., Closes #123) -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactoring
+- [ ] Performance improvement
+- [ ] Other (please describe):
+
+## Changes Made
+
+<!-- List the main changes made in this PR -->
+
+## Screenshots (if applicable)
+
+<!-- Add screenshots to help explain your changes -->
+
+## Checklist
+
+- [ ] I have run `npm run format:fix` and `npm run lint:fix`
+- [ ] I have run `npm run typecheck` with no errors
+- [ ] I have run tests with `npm run test:run`
+- [ ] I have tested my changes locally
+- [ ] I have updated documentation if needed
+- [ ] My code follows the project's architecture patterns
+
+## Additional Notes
+
+<!-- Any additional information that reviewers should know -->

.github/workflows/deploy-pr-preview.yml

@@ -1,28 +1,29 @@
-name: Deploy PR Preview to Netlify
+name: Build and Deploy PR Preview
 
 on:
-  workflow_dispatch:
-  pull_request:
+  pull_request_target:
     types: [opened, synchronize, reopened]
 
 permissions:
   contents: read
   pull-requests: write
 
 jobs:
-  deploy-preview:
+  build-and-deploy:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
+      - name: Checkout PR head
         uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '22'
           cache: 'npm'
           cache-dependency-path: './package-lock.json'
-      
+
       - name: Update npm to v11
         run: npm install -g npm@11
 
@@ -36,34 +37,34 @@ jobs:
           publish-dir: './dist'
           production-deploy: false
           github-token: ${{ secrets.GITHUB_TOKEN }}
-          deploy-message: "PR Preview - ${{ github.event.pull_request.title || github.ref_name }}"
-          alias: pr-${{ github.event.pull_request.number || github.run_id }}
+          deploy-message: "PR Preview #${{ github.event.pull_request.number }}"
+          alias: pr-${{ github.event.pull_request.number }}
           enable-pull-request-comment: false
           enable-commit-comment: false
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
 
       - name: Comment PR with Preview URL
-        if: github.event_name == 'pull_request'
         uses: actions/github-script@v7
         with:
           script: |
+            const prNumber = ${{ github.event.pull_request.number }};
             const deployUrl = '${{ steps.netlify.outputs.deploy-url }}';
-            const body = `🚀 **Preview:** ${deployUrl}\n📝 **Commit:** \`${{ github.sha }}\``;
-            
+            const body = `🚀 **Preview:** ${deployUrl}\n📝 **Commit:** \`${{ github.event.pull_request.head.sha }}\``;
+
             // Find existing comment
             const { data: comments } = await github.rest.issues.listComments({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              issue_number: context.issue.number,
+              issue_number: prNumber,
             });
-            
-            const botComment = comments.find(comment => 
-              comment.user.type === 'Bot' && 
+
+            const botComment = comments.find(comment =>
+              comment.user.type === 'Bot' &&
               comment.body.includes('Preview:')
             );
-            
+
             if (botComment) {
               await github.rest.issues.updateComment({
                 owner: context.repo.owner,
@@ -75,7 +76,7 @@ jobs:
               await github.rest.issues.createComment({
                 owner: context.repo.owner,
                 repo: context.repo.repo,
-                issue_number: context.issue.number,
+                issue_number: prNumber,
                 body: body
               });
             }

.github/workflows/e2e.yml

@@ -0,0 +1,42 @@
+name: E2E Tests
+
+on:
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Build application
+        run: npm run build
+
+      - name: Run E2E tests
+        run: npm run test:e2e
+        env:
+          CI: true
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7

.github/workflows/lint.yml

@@ -0,0 +1,20 @@
+name: Lint
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - name: Setup Biome
+        uses: biomejs/setup-biome@v2
+      - name: Run Biome
+        run: biome ci .

.gitignore

@@ -52,4 +52,10 @@ ehthumbs.db
 .Trashes
 
 # Dev files
-src/config/dev.json
+src/config/dev.json
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

CLAUDE.md

@@ -12,7 +12,7 @@ OpenScan is a trustless, open-source, standalone web-app and multi-chain blockch
 
 ```bash
 npm start
-# Runs on http://localhost:3000
+# Runs on http://localhost:3030
 ```
 
 ### Build for Production
@@ -28,10 +28,20 @@ npm run build
 npm run typecheck
 ```
 
-### Formatting
+### Formatting and Linting
 
 ```bash
+# Check formatting (dry run)
+npm run format
+
+# Fix formatting issues automatically
 npm run format:fix
+
+# Check linting issues (dry run)
+npm run lint
+
+# Fix linting issues automatically
+npm run lint:fix
 ```
 
 ### Test Environment with Local Node
@@ -79,11 +89,11 @@ OpenScan follows a layered architecture with clear separation between data fetch
    - Returns `DataWithMetadata<T>` when using parallel strategy, containing:
      - `data`: The primary result (from first successful provider)
      - `metadata`: Optional RPCMetadata with all provider responses, hashes, and inconsistency flags
-   - 30-second in-memory cache keyed by `chainId:type:identifier`
+   - 30-second in-memory cache keyed by `networkId:type:identifier`
    - Supports trace operations (debug_traceTransaction, etc.) for localhost networks only
 
 5. **Hook Layer** (`hooks/`) - React integration
-   - `useDataService(chainId)`: Creates DataService instance with strategy from settings
+   - `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
 
@@ -166,8 +176,56 @@ OpenScan includes special support for localhost development:
 ## Code Style
 
 - **Biome** for formatting and linting (config: `biome.json`)
+  - Line width: 100 characters
+  - Indentation: 2 spaces
+  - Scope: `src/**/*.ts`, `src/**/*.tsx`, `src/**/*.json` (excludes CSS files)
+  - Enabled rules: All recommended Biome linting rules
+  - Use `npm run format:fix` to auto-format code before committing
+  - Use `npm run lint:fix` to auto-fix linting issues (max 1024 diagnostics shown)
 - **TypeScript** with strict mode (`noImplicitAny`, `noImplicitReturns`, `noUncheckedIndexedAccess`)
 - **React 19** with functional components and hooks
+- **CSS** All styles should be on `src/styles` folder, avoid using in line component styles.
+
+## Coding Standards and Workflow
+
+### Before Committing Code
+
+ALWAYS run these commands before committing to ensure code quality:
+
+```bash
+# 1. Fix formatting issues
+npm run format:fix
+
+# 2. Fix linting issues
+npm run lint:fix
+
+# 3. Verify type safety
+npm run typecheck
+
+# 4. Run tests (if applicable)
+npm run test:run
+```
+
+### Commits
+
+- Follow the convetional commit standard v1.0.0
+- Commit without claude attribution
+
+### Code Quality Requirements
+
+- All code must pass Biome formatting and linting checks
+- All TypeScript code must pass type checking with zero errors
+- Follow the 100-character line width limit
+- Use 2-space indentation consistently
+- Adhere to Biome's recommended linting rules
+- Keep documentation up to date.
+
+### When Claude Code Modifies Files
+
+- Run `npm run format:fix` and `npm run lint:fix` after making changes
+- Address any remaining linting warnings that cannot be auto-fixed
+- Ensure TypeScript compilation succeeds with `npm run typecheck`
+- Do not commit code with formatting, linting, or type errors
 
 ## Important Patterns
 
@@ -187,9 +245,9 @@ OpenScan includes special support for localhost development:
 
 ### When Working with Cache
 
-- Cache keys format: `${chainId}:${type}:${identifier}`
+- Cache keys format: `${networkId}:${type}:${identifier}`
 - Don't cache "latest" block queries
-- Clear cache when switching networks using `clearCacheForChain(chainId)`
+- Clear cache when switching networks using `clearCacheForChain(networkId)`
 - Default timeout: 30 seconds
 
 ### RPC Strategy Switching