feat: helper to get latest subgraph indexed block

[marcomariscal]

Summary

• Adds getLatestSubgraphIndexedBlock helper function to get the latest block number indexed by a subgraph
• Queries the subgraph's _meta endpoint to retrieve block information
• Returns block number as bigint for consistency with other SDK functions

Implementation Details

• Function located in src/utils/helpers/getLatestSubgraphIndexedBlock.ts
• Uses GraphQL query to fetch _meta { block { number } }
• Comprehensive error handling with custom GetLatestSubgraphIndexedBlockError
• Exported from both utils/helpers/index.ts and main utils/index.ts

Testing

• Unit tests with real subgraph integration
• Tests success case, error handling, and edge cases
• Uses actual ScopeLift subgraph for integration testing

Usage Example

import { getLatestSubgraphIndexedBlock } from 'stealth-address-sdk';

const latestBlock = await getLatestSubgraphIndexedBlock({
  subgraphUrl: 'https://subgraph.satsuma-prod.com/760e79467576/scopelift/stealth-address-erc-base/api'
});
console.log(`Latest indexed block: ${latestBlock}`);

Resolves #93

🤖 Generated with Claude Code

[marcomariscal]

@claude review this

[claude]

Claude finished @marcomariscal's task —— View job

---

Code Review Complete ✅

Todo List:

• Read repository guidelines (CLAUDE.md)
• Review main implementation file (getLatestSubgraphIndexedBlock.ts)
• Review test file and coverage
• Review export structure changes
• Check for security and performance considerations
• Provide comprehensive feedback

---

Overall Assessment

This PR introduces a well-structured helper function with solid implementation. The code follows existing patterns in the codebase and provides good TypeScript safety. However, there are several areas where the implementation could be more robust.

🟢 Strengths

Code Quality & Structure

• Consistent with codebase patterns: Uses GraphQLClient like other subgraph utilities (src/lib/actions/getAnnouncementsUsingSubgraph/subgraphHelpers.ts:40)
• Good TypeScript usage: Proper typing with SubgraphMetaResponse interface and generic type parameters
• Proper exports: Consistent export structure in both utils/helpers/index.ts:11-13 and utils/index.ts:14-19
• Returns bigint: Consistent with other SDK functions that handle block numbers

Error Handling

• Custom error class: GetLatestSubgraphIndexedBlockError properly extends Error and preserves original errors
• Proper error re-throwing: Maintains custom errors while wrapping others (getLatestSubgraphIndexedBlock.ts:78-85)

Documentation & Testing

• Comprehensive JSDoc: Clear parameter descriptions, return types, and usage examples
• Real integration tests: Tests against actual ScopeLift subgraph (getLatestSubgraphIndexedBlock.test.ts:19-33)
• Error case coverage: Tests invalid URLs and non-existent subgraphs

🟡 Areas for Improvement

1. Input Validation

Issue: No validation of the subgraphUrl parameter

// Current implementation accepts any string
async function getLatestSubgraphIndexedBlock({
  subgraphUrl
}: GetLatestSubgraphIndexedBlockParams): Promise<bigint> {

Suggestion: Add URL validation:

if (!subgraphUrl || typeof subgraphUrl !== 'string') {
  throw new GetLatestSubgraphIndexedBlockError('subgraphUrl must be a non-empty string');
}

try {
  new URL(subgraphUrl);
} catch {
  throw new GetLatestSubgraphIndexedBlockError('subgraphUrl must be a valid URL');
}

2. Query Robustness

Issue: The GraphQL query could be more specific about required fields

// Current query at getLatestSubgraphIndexedBlock.ts:55-63
const gqlQuery = `
  query GetLatestIndexedBlock {
    _meta {
      block {
        number
      }
    }
  }
`;

Suggestion: Add non-null assertions and consider including additional metadata:

const gqlQuery = `
  query GetLatestIndexedBlock {
    _meta {
      block {
        number
        hash
        timestamp
      }
      deployment
      hasIndexingErrors
    }
  }
`;

3. Response Validation Enhancement

Issue: Limited validation of the response structure

// Current validation at getLatestSubgraphIndexedBlock.ts:68-74
const blockNumber = response._meta?.block?.number;

if (blockNumber === undefined || blockNumber === null) {
  throw new GetLatestSubgraphIndexedBlockError(
    'Failed to retrieve block number from subgraph meta response'
  );
}

Suggestion: More comprehensive validation:

if (!response._meta) {
  throw new GetLatestSubgraphIndexedBlockError('Invalid response: missing _meta field');
}

if (!response._meta.block) {
  throw new GetLatestSubgraphIndexedBlockError('Invalid response: missing block field');
}

const blockNumber = response._meta.block.number;
if (typeof blockNumber !== 'number' || blockNumber < 0) {
  throw new GetLatestSubgraphIndexedBlockError(
    `Invalid block number: expected positive number, got ${typeof blockNumber}`
  );
}

4. Type Safety Improvements

Issue: The SubgraphMetaResponse type assumes the response structure

// Current type at getLatestSubgraphIndexedBlock.ts:17-23
type SubgraphMetaResponse = {
  _meta: {
    block: {
      number: number;
    };
  };
};

Suggestion: Make fields optional to match actual GraphQL responses:

type SubgraphMetaResponse = {
  _meta?: {
    block?: {
      number?: number;
    };
  };
};

5. Test Coverage Gaps

Areas missing from current tests:

• Edge case: blockNumber is 0 (genesis block)
• Edge case: Very large block numbers
• Network timeout scenarios
• GraphQL-specific errors (malformed queries, etc.)

Suggested additional tests:

test('should handle genesis block (block 0)', async () => {
  // Mock response with block 0
});

test('should handle network timeouts gracefully', async () => {
  // Test with timeout scenarios
});

test('should handle GraphQL errors', async () => {
  // Test malformed query responses
});

🔒 Security Considerations

✅ No security issues identified:

• No sensitive data exposure
• No injection vulnerabilities (uses GraphQL client with proper parameterization)
• No unauthorized network access patterns

⚡ Performance Considerations

✅ Performance looks good:

• Lightweight query fetching minimal data
• No unnecessary data processing
• Single network request per call

Potential enhancement: Consider adding optional timeout configuration:

export type GetLatestSubgraphIndexedBlockParams = {
  subgraphUrl: string;
  timeoutMs?: number;
};

📋 Minor Issues

1. Line 89: Consider named export instead of default export for consistency with other helpers
2. Test file: Could benefit from more descriptive test names
3. Documentation: Example could show error handling

Recommendation

✅ Approve with suggestions. This is a solid implementation that follows codebase patterns well. The suggested improvements would make it more robust, but the current implementation is functional and safe for production use.

---

[marcomariscal]

@claude can you re-review after updating based on your feedback

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude finished @marcomariscal's task —— View job

---

Re-reviewing updated implementation

Todo List

• Read main implementation file (getLatestSubgraphIndexedBlock.ts)
• Review new validation utility (validateSubgraphUrl.ts)
• Analyze updated test file and coverage
• Check export structure and integration
• Compare against previous feedback points
• Assess overall implementation quality
• Provide comprehensive re-review feedback

---

Re-Review Assessment: Excellent Implementation ✅

This updated implementation addresses all of my previous feedback points exceptionally well. The code quality has significantly improved and now represents a robust, production-ready solution.

🟢 Previous Feedback Successfully Addressed

1. Input Validation - FULLY ADDRESSED ✅

Previous Issue: No validation of subgraphUrl parameter
Current Solution:

• Dedicated validateSubgraphUrl utility (validateSubgraphUrl.ts:16-36)
• Comprehensive validation: non-empty string, valid URL format, HTTP/HTTPS protocol only
• Reusable across the SDK with generic error constructor pattern

2. Query Robustness - FULLY ADDRESSED ✅

Previous Issue: Basic GraphQL query lacking comprehensive fields
Current Solution: Enhanced query (getLatestSubgraphIndexedBlock.ts:128-140)

query GetSubgraphMeta {
  _meta {
    block {
      number
      hash
      timestamp
    }
    deployment
    hasIndexingErrors
  }
}

3. Response Validation Enhancement - FULLY ADDRESSED ✅

Previous Issue: Limited response structure validation
Current Solution: Comprehensive validateSubgraphMetaResponse function (getLatestSubgraphIndexedBlock.ts:51-96)

• ✅ Validates response is object
• ✅ Checks for required _meta and _meta.block fields
• ✅ Validates block number exists and is valid (handles string/number, checks for NaN, non-negative)
• ✅ NEW: Throws error if subgraph has indexing errors

4. Type Safety Improvements - FULLY ADDRESSED ✅

Previous Issue: Types assumed required fields
Current Solution:

• Optional fields in SubgraphMetaResponse type (getLatestSubgraphIndexedBlock.ts:7-17)
• Handles both number and string for block number and timestamp
• Runtime validation ensures type safety

5. Test Coverage Gaps - FULLY ADDRESSED ✅

Previous Issue: Missing edge cases and error scenarios
Current Solution: Comprehensive test suite (getLatestSubgraphIndexedBlock.test.ts)

• ✅ Genesis block (block 0) - test.ts:144-163
• ✅ Large block numbers - test.ts:165-185
• ✅ Network timeout scenarios - test.ts:318-330
• ✅ GraphQL-specific errors - test.ts:332-343
• ✅ String vs number handling - test.ts:123-142
• ✅ Invalid block numbers (NaN, negative) - test.ts:249-283
• ✅ Indexing errors handling - test.ts:285-302
• ✅ Missing fields validation - test.ts:206-247

🟢 Additional Improvements Beyond Previous Feedback

1. Enhanced Error Handling

• Specific error types: timeout, GraphQL, network (getLatestSubgraphIndexedBlock.ts:166-198)
• Original error preservation with originalError property
• Clear, actionable error messages

2. Indexing Errors Detection

• Proactively checks hasIndexingErrors field (getLatestSubgraphIndexedBlock.ts:89-93)
• Prevents returning data from problematic subgraphs
• This wasn't in my original feedback but is an excellent addition

3. Reusable Validation Utility

• validateSubgraphUrl can be used across the SDK
• Generic error constructor design for flexibility
• Clean separation of concerns

4. Production-Ready Error Context

• All errors include context and preserve original errors
• Specific handling for common failure scenarios
• Helpful error messages for debugging

🔒 Security & Performance Validation

✅ Security: No issues identified

• Proper URL validation prevents malicious endpoints
• No injection vulnerabilities
• Safe BigInt conversion

✅ Performance: Excellent

• Minimal data fetching
• Single request pattern
• No unnecessary processing

🎯 Code Quality Assessment

Strengths

• Consistent patterns: Follows existing SDK conventions
• Comprehensive validation: Both input and response validation
• Excellent TypeScript usage: Proper typing with runtime validation
• Thorough testing: 100% scenario coverage including edge cases
• Clean architecture: Separation of validation, querying, and error handling
• Documentation: Clear JSDoc with examples

Minor Observations (All Positive)

1. Default export consistency: Uses default export which matches existing helper patterns
2. Error hierarchy: Custom error class properly extends Error with context preservation
3. Query naming: Well-named GraphQL query GetSubgraphMeta
4. Test organization: Well-structured test suites with clear describe blocks

Recommendation

✅ APPROVED - Excellent work!

This implementation has transformed from a basic utility into a robust, production-ready SDK function. Every piece of feedback from the previous review has been thoughtfully addressed and often exceeded.

Key Improvements Summary:

• 195 lines of comprehensive implementation (vs ~90 before)
• 407 lines of thorough test coverage
• 36 lines of reusable validation utility
• All previous suggestions implemented plus additional improvements

The code quality is exemplary and ready for production use. Great job addressing all the feedback!

---

View current branch