Support struct field access in declarative calls

[fubhy]

Summary

Implement complete support for named and mixed struct field access in declarative calls within subgraph manifests. This enables intuitive patterns like event.params.asset.addr instead of cryptic numeric indices like event.params.asset.0.

Key Features

• Named Field Access: event.params.asset.addr (fully implemented with ABI integration)
• Arbitrary Nesting: event.params.data.1.user.id (unlimited depth)
• Mixed Access: event.params.transfers.0.recipient (numeric + named)
• Smart Error Messages: Show available field names when invalid names are used
• Enhanced Error Context: Include declarative call labels for better debugging
• Complete Documentation: Updated subgraph manifest docs with examples and usage patterns

Why This Implementation is Necessary

The ethabi crate has a significant limitation: tuple field names are completely lost during ABI parsing. While the original ABI JSON contains rich component information:

{
  "name": "asset", 
  "type": "tuple",
  "components": [
    {"name": "addr", "type": "address"},
    {"name": "amount", "type": "uint256"}
  ]
}

The ethabi parser converts this to ParamType::Tuple(vec\![Address, Uint(256)]), discarding the field names "addr" and "amount" entirely.

Our solution works around this limitation by:

1. Direct ABI JSON parsing to extract component field names before ethabi processing
2. Parallel struct field mappings that preserve name-to-index relationships
3. Runtime field resolution using the preserved component information

This indirection enables user-friendly named access while maintaining ethabi's type safety.

Architecture Changes

• Unified Design: Single StructField(Word, Vec<FieldAccess>) variant supporting both access patterns
• FieldAccess Enum: Index(usize) for numeric access, Name(Word) for named access
• ABI Integration: MappingABI extended with struct_field_mappings from ABI JSON parsing
• Context Propagation: Event names and ABI information passed through extraction pipeline

Example Usage

calls:
  # Named field access (much clearer than numeric indices)
  tokenAddress: ERC20[event.params.asset.addr].name()
  
  # Deep nesting with mixed access patterns
  recipientBalance: Token[event.params.transfers.0.recipient].balanceOf()
  
  # Arbitrary nesting depth supported
  innerValue: Contract[event.address].process(event.params.outer.1.inner.0.field)
  
  # Backward compatible - numeric indices still work
  legacyAccess: Contract[event.params.asset.1].someFunction()

Error Message Improvements

Before:

struct field 'invalid' must be a numeric index

After:

In declarative call 'myCall': unknown field 'invalid' in struct parameter 'asset'. 
Available field names: [active, addr, amount]. Available numeric indices: [0, 1, 2]

Implementation Status

✅ Complete Implementation: Full named field access with ABI integration
✅ Parser: Supports arbitrary nesting with mixed numeric/named patterns
✅ Field Resolution: ABI-driven name-to-index mapping with comprehensive error handling
✅ Integration: Event context propagated through entire call chain
✅ Test Coverage: 16 comprehensive tests (reduced from 19, eliminated redundancy)
✅ Documentation: Updated subgraph manifest docs with examples and usage patterns
✅ Backward Compatibility: All existing numeric access patterns preserved

Documentation Updates

• Enhanced Expression Types: Extended Expr table with all supported access patterns
• Comprehensive Examples: Named, numeric, and mixed access patterns with real ABI JSON
• Practical Usage: Ready-to-use YAML configuration examples
• Complete Coverage: All new struct field access capabilities documented

Test Plan

• All existing tests pass (16/16, reduced from 19 by removing redundancy)
• End-to-end named field access test with real ABI JSON parsing
• Mixed access pattern tests pass
• Smart error message validation
• Integration tests with declarative call contexts
• Backward compatibility maintained
• Code formatted with cargo fmt
• Documentation updated in subgraph manifest

Breaking Changes

None. All existing functionality preserved while adding new capabilities.

Related Issues

Addresses GitHub issue #6059 and reviewer feedback. Provides complete named struct field access functionality for Graph Node declarative calls with full documentation.

🤖 Generated with Claude Code

[lutter]

Looks reasonable overall, just some smaller things that should be addressed.

Either way, this PR should only be approved once @incrypto32 gives his ok to the removal of pq-sys

[lutter]

The PR also needs to update the docs here

[incrypto32]

@lutter the pq-sys was added to build the postgres C code from source when building the gnd binary, i see that its causing issues when compiling for darwin, its ok to comment it out for now. I'll likely move the gnd binary to a separate crate if i can't find another fix to get it workign on macs.

[fubhy]

@lutter, could you please re-review when you have a moment?

A humble apology in verse:

🎭 Ode to Overzealous Optimization

Oh Lutter, we must confess with shame,
Since your review, we've changed the game—
Claude's wisdom sparked our coding spree,
We refactored with such jubilee!

Your feedback on assertions weak,
Made stronger tests that we now seek.
But in our joy (we can't deny),
We've modified more than meets the eye.

The struct field access now runs deep,
With ABI mappings that we keep.
Error messages, smart and clear,
Show available fields when names aren't here.

So please forgive our coding dance,
We got carried away by circumstance.
Claude's guidance made the work so bright,
We couldn't help but code all night! 🌙

— Your overly enthusiastic contributors

P.S. The core functionality remains the same, just with better error handling and stronger test assertions as you requested! 🚀

[lutter]

Much better, but especially the handling of named parameters should be improved so that most of the processing happens when the call expression is parsed.

And we'll need to bump the specVersion

[fubhy]

@lutter I think the integration test failure is unrelated. Can you confirm?

EDIT: Yes, it's also failing on master: https://github.com/graphprotocol/graph-node/actions/runs/16971592418/job/48216244189

Likely caused by a recent anvil (foundry) release? We use the latest stable version in the test suite and that was recently bumped to 1.3.0.

Let's update the block hashes?

[fubhy]

@lutter I sloppily let Claude jam on your feedback unreviewed this time because I was busy with sth. else. Apologies if this is slop.

[lutter]

@fubhy This now works (even though it turned out to be a much bigger change than we thought initially) Could you look over these changes?

One thing I don't understand is that something I did seems to have completely regenerated the pnpm-lock.yaml file even though I only added two integration tests. Not sure if that is concerning.

[fubhy]

@fubhy This now works (even though it turned out to be a much bigger change than we thought initially) Could you look over these changes?

One thing I don't understand is that something I did seems to have completely regenerated the pnpm-lock.yaml file even though I only added two integration tests. Not sure if that is concerning.

That's because you are likely on an older pnpm version. I've added a packageManager field to the root package.json file. This field is normally read by tools like corepack (https://github.com/nodejs/corepack) to automatically provide the right package manager version.