Skip to content

Commit cd2ba84

Browse files
fubhyclaude
andcommitted
docs: Add struct field access documentation to subgraph manifest
Update section 1.5.3 "Declaring calls" to include comprehensive documentation for the new struct field access capabilities in declarative calls. ## Documentation Updates ### Enhanced Expression Types - Extended `Expr` table with all supported access patterns - Added struct field access by numeric index and field name - Documented nested struct access with arbitrary depth ### Comprehensive Examples - **Named Access**: `event.params.asset.addr` (recommended) - **Numeric Access**: `event.params.asset.0` (backward compatible) - **Mixed Patterns**: `event.params.transfers.0.recipient` (flexible) - **Deep Nesting**: `event.params.data.1.user.addr` (unlimited depth) ### Real-World Usage - Provided complete ABI JSON example showing struct components - Multiple usage patterns with clear explanations - Practical YAML configuration examples Addresses reviewer feedback to update documentation for the struct field access feature implemented in the accompanying code changes. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 9cb1975 commit cd2ba84

1 file changed

Lines changed: 91 additions & 1 deletion

File tree

docs/subgraph-manifest.md

Lines changed: 91 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,97 @@ Each call is of the form `<ABI>[<address>].<function>(<args>)`:
118118
| **function** | *String* | The name of a view function in the contract |
119119
| **args** | *[Expr]* | The arguments to pass to the function |
120120

121-
The `Expr` can be either `event.address` or `event.params.<name>`.
121+
#### Expression Types
122+
123+
The `Expr` can be one of the following:
124+
125+
| Expression | Description | Example |
126+
| --- | --- | --- |
127+
| **event.address** | The address of the contract that emitted the event | `event.address` |
128+
| **event.params.&lt;name&gt;** | A simple parameter from the event | `event.params.token` |
129+
| **event.params.&lt;name&gt;.&lt;index&gt;** | A field from a struct parameter by numeric index | `event.params.asset.0` |
130+
| **event.params.&lt;name&gt;.&lt;fieldName&gt;** | A field from a struct parameter by field name | `event.params.asset.addr` |
131+
| **Nested struct access** | Arbitrary nesting depth with mixed access patterns | `event.params.data.1.user.id` |
132+
133+
#### Struct Field Access
134+
135+
_Available from spec version 1.2.0_
136+
137+
When event parameters contain struct types (tuples in ABI), you can access individual fields using either numeric indices or field names:
138+
139+
**Numeric Access (Traditional):**
140+
```yaml
141+
calls:
142+
tokenAddress: ERC20[event.params.asset.0].name() # First field
143+
tokenAmount: ERC20[event.params.asset.1].decimals() # Second field
144+
```
145+
146+
**Named Access (Recommended):**
147+
```yaml
148+
calls:
149+
tokenAddress: ERC20[event.params.asset.addr].name() # By field name
150+
tokenAmount: ERC20[event.params.asset.amount].decimals() # By field name
151+
```
152+
153+
**Mixed Access Patterns:**
154+
```yaml
155+
calls:
156+
# Access first transfer, then recipient field by name
157+
recipient: Token[event.params.transfers.0.recipient].balanceOf()
158+
159+
# Deep nesting with mixed numeric and named access
160+
innerValue: Contract[event.params.data.1.user.addr].someFunction()
161+
```
162+
163+
#### Struct Field Access Examples
164+
165+
Given an event with this ABI structure:
166+
```json
167+
{
168+
"name": "AssetTransfer",
169+
"type": "event",
170+
"inputs": [
171+
{
172+
"name": "asset",
173+
"type": "tuple",
174+
"components": [
175+
{"name": "addr", "type": "address"},
176+
{"name": "amount", "type": "uint256"},
177+
{"name": "active", "type": "bool"}
178+
]
179+
}
180+
]
181+
}
182+
```
183+
184+
You can access fields in multiple ways:
185+
```yaml
186+
calls:
187+
# Named field access (clearest and recommended)
188+
tokenContract: ERC20[event.params.asset.addr].name()
189+
tokenDecimals: ERC20[event.params.asset.addr].decimals()
190+
191+
# Numeric field access (backward compatible)
192+
tokenContract: ERC20[event.params.asset.0].name()
193+
194+
# Mixed access for complex nested structures
195+
nestedField: Contract[event.params.data.0.inner.fieldName].process()
196+
```
197+
198+
#### Error Handling
199+
200+
When using invalid field names, Graph Node provides helpful error messages:
201+
202+
```
203+
In declarative call 'myCall': unknown field 'invalid' in struct parameter 'asset'.
204+
Available field names: [active, addr, amount]. Available numeric indices: [0, 1, 2]
205+
```
206+
207+
**Best Practices:**
208+
- Use named field access (`asset.addr`) for better readability and maintainability
209+
- Named access requires the struct field names to be present in the ABI
210+
- Numeric indices (`asset.0`) work as a fallback and for backward compatibility
211+
- Both access methods can be mixed in the same expression for complex nested structures
122212

123213
## 1.6 Path
124214
A path has one field `path`, which either refers to a path of a file on the local dev machine or an [IPLD link](https://github.com/ipld/specs/).

0 commit comments

Comments
 (0)