fix(tangle-cloud): QA improvements for cloud earnings and rewards

[vutuanlinh2k2]

Summary

• Improve earnings page with richer asset display, pagination, and exact payout ledger usage
• Polish rewards page with better claim UX, explorer action links, and claim history
• Fix typecheck error for undefined showExplorerActions in rewards page

Video

CleanShot.2026-02-13.at.13.42.18.mp4

Test plan

• Verify earnings page displays correct asset metadata and pagination works
• Verify rewards claim flow works end-to-end
• Verify claim history table renders with explorer links when available
• Confirm tangle-cloud:typecheck passes cleanly

🤖 Generated with Claude Code

[claude]

Claude finished @vutuanlinh2k2's task —— View job

---

PR Review: fix(tangle-cloud): QA improvements for cloud earnings and rewards

I've completed my review of this substantial PR that improves the earnings and rewards pages in Tangle Cloud. Here's my comprehensive feedback:

✅ Strengths

Architecture & Code Quality

• Excellent separation of concerns: New useDeveloperPayments hook properly separates exact payout ledger data from the legacy earnings hook
• Clean data flow: Well-structured GraphQL queries with proper error handling and type safety
• Consistent patterns: All components follow established React patterns and use proper TypeScript typing
• Reusable components: Good abstraction with EarningsAssetCell, PendingAssetCell, etc.

User Experience Improvements

• Rich asset display: Enhanced token metadata with proper icons, names, and explorer links
• Pagination: Proper pagination implementation for payout events
• Explorer integration: Consistent explorer links for transactions and addresses
• Better error handling: Comprehensive error states and loading indicators

⚠️ Issues & Recommendations

Performance Concerns

1. Multiple API calls in table rows (apps/tangle-cloud/src/pages/earnings/page.tsx:68, apps/tangle-cloud/src/pages/rewards/page.tsx:554)

   // This creates N API calls for N rows - could be expensive
   const { data: metadata, isLoading } = useTokenMetadata(token);

   Recommendation: Consider batching token metadata requests or implementing a token metadata cache.

2. Synchronous formatting in render (libs/tangle-shared-ui/src/data/graphql/useDeveloperPayments.ts:291-302)

   const formatEarningsAmount = (amount: bigint, decimals = 18): string => {
     // Complex calculation happens in render...

   Recommendation: Memoize formatting results for identical inputs.

Code Quality Issues

3. Duplicated utility functions

   • shortenAddress, shortenTxHash, formatTimestamp appear in multiple files
   • resolveTokenIconSymbol and isFallbackSymbol are duplicated
     Recommendation: Extract to shared utilities in libs/tangle-shared-ui/src/utils/

4. Complex conditional rendering (apps/tangle-cloud/src/pages/earnings/page.tsx:326-492)

   • 166-line conditional rendering block is hard to maintain
     Recommendation: Break into smaller sub-components

5. Magic numbers without constants

   const PAYOUT_EVENTS_PAGE_SIZE = 10; // Good
   staleTime: 60_000, // Should use named constants

Potential Bugs

6. Explorer URL construction (apps/tangle-cloud/src/utils/explorer.ts:20-36)

   • No validation of constructed URLs
   • Potential issues with malformed explorer URLs
     Recommendation: Add URL validation or fallback handling

7. BigInt comparison edge cases (libs/tangle-shared-ui/src/data/graphql/useDeveloperPayments.ts:142-147)

   return a.totalPaid > b.totalPaid ? -1 : 1; // Could be problematic with very large numbers

   Recommendation: Use .toString() for consistent comparison

Security Considerations

8. External link handling - ✅ Good: Proper use of target="_blank" with rel="noreferrer"

9. Input validation - ✅ Good: Proper address validation and lowercasing

10. XSS prevention - ✅ Good: No dangerous HTML injection patterns found

TypeScript & Type Safety

11. Type assertions could be improved (libs/tangle-shared-ui/src/data/graphql/useDeveloperPayments.ts:131)

    recipient: entry.recipient as Address, // Type assertion without validation

    Recommendation: Add runtime validation for address formats

📋 Minor Improvements

12. Loading states: Consider skeleton loaders that match the actual content structure more closely

13. Accessibility: Add more descriptive aria-label attributes for screen readers

14. Error messages: Could be more user-friendly (less technical)

🔍 Testing Recommendations

• Test with large datasets to verify pagination performance
• Test token metadata fallback scenarios
• Verify explorer link generation across different chain configurations
• Test error handling when GraphQL endpoints are unavailable

📊 Overall Assessment

This is a well-implemented improvement that significantly enhances the user experience. The code follows good practices and the architecture is sound. The main concerns are around performance optimization and code deduplication.

Recommendation: ✅ Approve with minor improvements

The issues identified are mostly optimization opportunities rather than blocking problems. The core functionality is solid and the UX improvements are valuable.

---

[vutuanlinh2k2]

Follow-up plan after reviewing Claude feedback and current code:

• Verified duplicate helper logic and large earnings render block are worth fixing.
• Verified unsafe GraphQL address casts are worth fixing with runtime validation.
• Confirmed BigInt comparator concern is not a bug (bigint comparisons are safe); no comparator rewrite planned.

Planned fix buckets in this pass:

1. Deduplicate cloud formatting/token-presentation helpers.
2. Split earnings page into focused subcomponents (no UX behavior changes).
3. Add runtime address validation in GraphQL mappers + focused tests.

Deferred intentionally for a later pass: metadata batching optimization, staleTime constant normalization, broad a11y/copy polish, explorer URL hardening.

[vutuanlinh2k2]

Implemented follow-up fixes for the high-value Claude review items.

Completed:

• Deduplicated cloud-only formatting/token helpers.
  • Added apps/tangle-cloud/src/utils/displayFormatting.ts
  • Added apps/tangle-cloud/src/utils/tokenPresentation.ts
  • Rewired earnings/rewards pages + OperatorExitPanel to use shared helpers.
• Refactored earnings page into focused components (behavior preserved).
  • Added:
    • apps/tangle-cloud/src/pages/earnings/components/EarningsLoadingState.tsx
    • apps/tangle-cloud/src/pages/earnings/components/EarningsErrorState.tsx
    • apps/tangle-cloud/src/pages/earnings/components/EarningsAssetsCard.tsx
    • apps/tangle-cloud/src/pages/earnings/components/PayoutEventsCard.tsx
  • Simplified apps/tangle-cloud/src/pages/earnings/page.tsx to orchestration.
• Enforced runtime GraphQL address validation in mapping paths.
  • Replaced unsafe casts with parseAddressOrThrow mapping logic for developer payments and reward claims.
  • Added pure mapper modules for testability:
    • libs/tangle-shared-ui/src/data/graphql/developerPaymentMapper.ts
    • libs/tangle-shared-ui/src/data/graphql/rewardClaimMapper.ts
• Added focused tests:
  • apps/tangle-cloud/src/utils/displayFormatting.test.ts
  • apps/tangle-cloud/src/utils/tokenPresentation.test.ts
  • libs/tangle-shared-ui/src/data/graphql/useDeveloperPayments.test.ts
  • libs/tangle-shared-ui/src/data/graphql/useRewards.test.ts

Validation run:

• corepack yarn nx run-many --target=lint --projects=tangle-cloud,tangle-shared-ui ✅
• corepack yarn nx test tangle-shared-ui ✅
• corepack yarn nx build tangle-cloud ✅
• corepack yarn nx test tangle-cloud ✅ (extra verification for the new cloud util tests)

Deferred intentionally (unchanged from plan):

• Metadata batching/prefetch optimization
• staleTime constant normalization
• Broad accessibility/copy polish
• Explorer URL hardening
• BigInt comparator rewrite (not needed; current bigint comparison is correct)

[claude]

Claude finished @vutuanlinh2k2's task —— View job

---

Code Review: QA Improvements for Cloud Earnings and Rewards

Todo List

• Analyze changed files and implementation approach
• Review code quality and best practices
• Check for potential bugs or issues
• Evaluate performance considerations
• Assess security implications
• Provide comprehensive feedback

---

✅ Overall Assessment: APPROVED

This is a well-implemented improvement that significantly enhances the user experience for earnings and rewards pages. The code demonstrates good architectural patterns and addresses many concerns from previous reviews.

🔍 Code Quality Analysis

Strengths ⭐

1. Clean Component Architecture

   • Well-structured React components following established patterns
   • Proper separation of concerns between UI and data logic
   • Good use of custom hooks for data fetching (useDeveloperPayments, useRewards)

2. Type Safety

   • Strong TypeScript typing throughout
   • Proper interface definitions for GraphQL responses
   • Consistent use of Address and other viem types

3. User Experience Improvements

   • Enhanced token display with icons, names, and explorer links
   • Proper pagination implementation with user-friendly controls
   • Comprehensive loading and error states
   • Good accessibility with proper aria-label attributes

4. Security Best Practices ✅

   • Proper external link handling with target="_blank" and rel="noreferrer"
   • No dangerous HTML injection patterns
   • Proper input validation and sanitization

Areas for Improvement ⚠️

Performance Concerns (Medium Priority)

1. Multiple Token Metadata API Calls (earnings/page.tsx:68, rewards/page.tsx:554)

   const { data: metadata, isLoading } = useTokenMetadata(token);

   • Issue: Each table row triggers its own API call for token metadata
   • Impact: Could result in N API calls for N tokens
   • Recommendation: Consider implementing token metadata batching or caching

2. Synchronous Formatting in Render

   const formattedAmount = formatEarningsAmount(amount, decimals);

   • Issue: Complex formatting calculations happen on every render
   • Recommendation: Memoize formatting results for identical inputs

Code Organization (Low Priority)

3. Helper Function Duplication

   • Functions like shortenAddress, shortenTxHash, formatTimestamp appear in multiple files
   • Found in: earnings/page.tsx:35-42, rewards/page.tsx:56-62
   • Recommendation: Extract to shared utilities in libs/tangle-shared-ui/src/utils/

4. Token Resolution Logic Duplication

   // Similar logic in earnings/page.tsx:46-59 and rewards/page.tsx:64-77
   const resolveTokenIconSymbol = (chainId, symbol, address) => { ... }
   const isFallbackSymbol = (symbol) => { ... }

   • Recommendation: Move to shared token utilities

🐛 Potential Issues

Minor Issues

1. Explorer URL Construction (utils/explorer.ts:20-36)

   • No validation of constructed URLs
   • Could potentially create malformed URLs in edge cases
   • Recommendation: Add URL validation or try-catch blocks

2. Magic Numbers

   const PAYOUT_EVENTS_PAGE_SIZE = 10; // ✅ Good
   staleTime: 60_000, // Should use named constants

   • Recommendation: Define named constants for cache durations

Follow-up Work Status 📋

Based on the comments, the author mentioned implementing several improvements:

• ❓ Unclear: The mentioned utility files (displayFormatting.ts, tokenPresentation.ts, mapper modules) don't appear in the changed files
• ❓ Missing: Referenced test files are not visible in the PR
• Recommendation: Verify if these files were committed or if they're planned for a future PR

🚀 Performance Considerations

1. GraphQL Query Efficiency ✅

   • Well-structured queries with proper pagination
   • Good use of React Query for caching
   • Appropriate error handling

2. Component Rendering ⚠️

   • Some expensive operations in render functions could be optimized
   • Consider useMemo for complex calculations

🔒 Security Assessment ✅

• No security vulnerabilities identified
• Proper handling of external links
• No XSS risks detected
• Address validation appears appropriate

📝 Documentation & Testing

• Code Documentation: Good inline comments and JSDoc
• Testing: No test files visible in this PR (mentioned but not included)
• Recommendation: Add unit tests for the new GraphQL hooks and utility functions

🎯 Recommendations Summary

High Impact, Low Effort

1. Extract duplicate helper functions to shared utilities
2. Add named constants for magic numbers
3. Add URL validation in explorer utilities

Medium Impact, Medium Effort

1. Implement token metadata batching/caching
2. Add memoization for expensive formatting operations

Low Priority

1. Add more comprehensive error messages
2. Improve loading skeleton accuracy
3. Enhance accessibility attributes

---

Final Verdict: ✅ APPROVED

This PR delivers significant UX improvements with solid code quality. The identified issues are mostly optimizations rather than blocking problems. The architecture is sound and follows established patterns well.

---