core: Implement struct field access in declarative calls (spec v1.4.0)

This commit implements support for struct field access in declarative calls,
allowing subgraphs to access nested struct fields using dot notation.

Key changes:
- Add struct field access parsing and validation
- Support arbitrary nesting depth for field access
- Update subgraph manifest documentation
- Add comprehensive tests for struct field access functionality
- Update API version to support new feature
- Initial deserialization stores calls as raw strings in UnresolvedCallDecls
- Resolution phase parses calls with ABI context using CallExpr::parse()
- Spec version validation happens during parsing with clear error messages
- Add UnresolvedCallDecls struct to store raw call strings
- Add UnresolvedMappingEventHandler and UnresolvedEntityHandler
- Move call parsing from deserialization to resolution phase
- Replace eprintln! with proper logger.warn() calls
- Remove obsolete validation functions
- Add a justfile target to recompile test contracts
- Extract their ABIs into tests/contracts/abi/
- Add integration tests for using struct fields in declared calls

Co-Authored-By: Claude <[email protected]>
Co-Authored-By: Sebastian Lorenz <[email protected]>

Author: 2 people

chain/ethereum/src/data_source.rs

@@ -6,7 +6,8 @@ use graph::components::store::{EthereumCallCache, StoredDynamicDataSource};
 use graph::components::subgraph::{HostMetrics, InstanceDSTemplateInfo, MappingError};
 use graph::components::trigger_processor::RunnableTriggers;
 use graph::data_source::common::{
-    CallDecls, DeclaredCall, FindMappingABI, MappingABI, UnresolvedMappingABI,
+    AbiJson, CallDecls, DeclaredCall, FindMappingABI, MappingABI, UnresolvedCallDecls,
+    UnresolvedMappingABI,
 };
 use graph::data_source::{CausalityRegion, MappingTrigger as MappingTriggerType};
 use graph::env::ENV_VARS;
@@ -800,7 +801,7 @@ impl DataSource {
                     "transaction" => format!("{}", &transaction.hash),
                 });
                 let handler = event_handler.handler.clone();
-                let calls = DeclaredCall::from_log_trigger(
+                let calls = DeclaredCall::from_log_trigger_with_event(
                     &self.mapping,
                     &event_handler.calls,
                     &log,
@@ -1200,6 +1201,7 @@ impl blockchain::UnresolvedDataSource<Chain> for UnresolvedDataSource {
         resolver: &Arc<dyn LinkResolver>,
         logger: &Logger,
         manifest_idx: u32,
+        spec_version: &semver::Version,
     ) -> Result<DataSource, anyhow::Error> {
         let UnresolvedDataSource {
             kind,
@@ -1210,7 +1212,7 @@ impl blockchain::UnresolvedDataSource<Chain> for UnresolvedDataSource {
             context,
         } = self;
 
-        let mapping = mapping.resolve(resolver, logger).await.with_context(|| {
+        let mapping = mapping.resolve(resolver, logger, spec_version).await.with_context(|| {
             format!(
                 "failed to resolve data source {} with source_address {:?} and source_start_block {}",
                 name, source.address, source.start_block
@@ -1221,7 +1223,7 @@ impl blockchain::UnresolvedDataSource<Chain> for UnresolvedDataSource {
     }
 }
 
-#[derive(Clone, Debug, Default, Hash, Eq, PartialEq, Deserialize)]
+#[derive(Clone, Debug, Default, Eq, PartialEq, Deserialize)]
 pub struct UnresolvedDataSourceTemplate {
     pub kind: String,
     pub network: Option<String>,
@@ -1247,6 +1249,7 @@ impl blockchain::UnresolvedDataSourceTemplate<Chain> for UnresolvedDataSourceTem
         resolver: &Arc<dyn LinkResolver>,
         logger: &Logger,
         manifest_idx: u32,
+        spec_version: &semver::Version,
     ) -> Result<DataSourceTemplate, anyhow::Error> {
         let UnresolvedDataSourceTemplate {
             kind,
@@ -1257,7 +1260,7 @@ impl blockchain::UnresolvedDataSourceTemplate<Chain> for UnresolvedDataSourceTem
         } = self;
 
         let mapping = mapping
-            .resolve(resolver, logger)
+            .resolve(resolver, logger, spec_version)
             .await
             .with_context(|| format!("failed to resolve data source template {}", name))?;
 
@@ -1294,7 +1297,7 @@ impl blockchain::DataSourceTemplate<Chain> for DataSourceTemplate {
     }
 }
 
-#[derive(Clone, Debug, Default, Hash, Eq, PartialEq, Deserialize)]
+#[derive(Clone, Debug, Default, Eq, PartialEq, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct UnresolvedMapping {
     pub kind: String,
@@ -1307,7 +1310,7 @@ pub struct UnresolvedMapping {
     #[serde(default)]
     pub call_handlers: Vec<MappingCallHandler>,
     #[serde(default)]
-    pub event_handlers: Vec<MappingEventHandler>,
+    pub event_handlers: Vec<UnresolvedMappingEventHandler>,
     pub file: Link,
 }
 
@@ -1357,6 +1360,7 @@ impl UnresolvedMapping {
         self,
         resolver: &Arc<dyn LinkResolver>,
         logger: &Logger,
+        spec_version: &semver::Version,
     ) -> Result<Mapping, anyhow::Error> {
         let UnresolvedMapping {
             kind,
@@ -1376,9 +1380,7 @@ impl UnresolvedMapping {
             // resolve each abi
             abis.into_iter()
                 .map(|unresolved_abi| async {
-                    Result::<_, Error>::Ok(Arc::new(
-                        unresolved_abi.resolve(resolver, logger).await?,
-                    ))
+                    Result::<_, Error>::Ok(unresolved_abi.resolve(resolver, logger).await?)
                 })
                 .collect::<FuturesOrdered<_>>()
                 .try_collect::<Vec<_>>(),
@@ -1390,15 +1392,35 @@ impl UnresolvedMapping {
         .await
         .with_context(|| format!("failed to resolve mapping {}", link.link))?;
 
+        // Resolve event handlers with ABI context
+        let resolved_event_handlers = event_handlers
+            .into_iter()
+            .map(|unresolved_handler| {
+                // Find the ABI for this event handler
+                let (_, abi_json) = abis.first().ok_or_else(|| {
+                    anyhow!(
+                        "No ABI found for event '{}' in event handler '{}'",
+                        unresolved_handler.event,
+                        unresolved_handler.handler
+                    )
+                })?;
+
+                unresolved_handler.resolve(abi_json, &spec_version)
+            })
+            .collect::<Result<Vec<_>, anyhow::Error>>()?;
+
+        // Extract just the MappingABIs for the final Mapping struct
+        let mapping_abis = abis.into_iter().map(|(abi, _)| Arc::new(abi)).collect();
+
         Ok(Mapping {
             kind,
             api_version,
             language,
             entities,
-            abis,
+            abis: mapping_abis,
             block_handlers: block_handlers.clone(),
             call_handlers: call_handlers.clone(),
-            event_handlers: event_handlers.clone(),
+            event_handlers: resolved_event_handlers,
             runtime,
             link,
         })
@@ -1442,8 +1464,8 @@ pub struct MappingCallHandler {
     pub handler: String,
 }
 
-#[derive(Clone, Debug, Hash, Eq, PartialEq, Deserialize)]
-pub struct MappingEventHandler {
+#[derive(Clone, Debug, Eq, PartialEq, Deserialize)]
+pub struct UnresolvedMappingEventHandler {
     pub event: String,
     pub topic0: Option<H256>,
     #[serde(deserialize_with = "deserialize_h256_vec", default)]
@@ -1456,6 +1478,41 @@ pub struct MappingEventHandler {
     #[serde(default)]
     pub receipt: bool,
     #[serde(default)]
+    pub calls: UnresolvedCallDecls,
+}
+
+impl UnresolvedMappingEventHandler {
+    pub fn resolve(
+        self,
+        abi_json: &AbiJson,
+        spec_version: &semver::Version,
+    ) -> Result<MappingEventHandler, anyhow::Error> {
+        let resolved_calls = self
+            .calls
+            .resolve(abi_json, Some(&self.event), spec_version)?;
+
+        Ok(MappingEventHandler {
+            event: self.event,
+            topic0: self.topic0,
+            topic1: self.topic1,
+            topic2: self.topic2,
+            topic3: self.topic3,
+            handler: self.handler,
+            receipt: self.receipt,
+            calls: resolved_calls,
+        })
+    }
+}
+
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+pub struct MappingEventHandler {
+    pub event: String,
+    pub topic0: Option<H256>,
+    pub topic1: Option<Vec<H256>>,
+    pub topic2: Option<Vec<H256>>,
+    pub topic3: Option<Vec<H256>>,
+    pub handler: String,
+    pub receipt: bool,
     pub calls: CallDecls,
 }
 

chain/near/src/data_source.rs

@@ -333,6 +333,7 @@ impl blockchain::UnresolvedDataSource<Chain> for UnresolvedDataSource {
         resolver: &Arc<dyn LinkResolver>,
         logger: &Logger,
         _manifest_idx: u32,
+        _spec_version: &semver::Version,
     ) -> Result<DataSource, Error> {
         let UnresolvedDataSource {
             kind,
@@ -372,6 +373,7 @@ impl blockchain::UnresolvedDataSourceTemplate<Chain> for UnresolvedDataSourceTem
         resolver: &Arc<dyn LinkResolver>,
         logger: &Logger,
         _manifest_idx: u32,
+        _spec_version: &semver::Version,
     ) -> Result<DataSourceTemplate, Error> {
         let UnresolvedDataSourceTemplate {
             kind,

chain/substreams/src/data_source.rs

@@ -187,6 +187,7 @@ impl blockchain::UnresolvedDataSource<Chain> for UnresolvedDataSource {
         resolver: &Arc<dyn LinkResolver>,
         logger: &Logger,
         _manifest_idx: u32,
+        _spec_version: &semver::Version,
     ) -> Result<DataSource, Error> {
         let content = resolver.cat(logger, &self.source.package.file).await?;
 
@@ -317,6 +318,7 @@ impl blockchain::UnresolvedDataSourceTemplate<Chain> for NoopDataSourceTemplate
         _resolver: &Arc<dyn LinkResolver>,
         _logger: &Logger,
         _manifest_idx: u32,
+        _spec_version: &semver::Version,
     ) -> Result<NoopDataSourceTemplate, anyhow::Error> {
         unimplemented!("{}", TEMPLATE_ERROR)
     }
@@ -330,7 +332,7 @@ mod test {
     use graph::{
         blockchain::{DataSource as _, UnresolvedDataSource as _},
         components::link_resolver::LinkResolver,
-        data::subgraph::LATEST_VERSION,
+        data::subgraph::{LATEST_VERSION, SPEC_VERSION_1_2_0},
         prelude::{async_trait, serde_yaml, JsonValueStream, Link},
         slog::{o, Discard, Logger},
         substreams::{
@@ -433,7 +435,10 @@ mod test {
         let ds: UnresolvedDataSource = serde_yaml::from_str(TEMPLATE_DATA_SOURCE).unwrap();
         let link_resolver: Arc<dyn LinkResolver> = Arc::new(NoopLinkResolver {});
         let logger = Logger::root(Discard, o!());
-        let ds: DataSource = ds.resolve(&link_resolver, &logger, 0).await.unwrap();
+        let ds: DataSource = ds
+            .resolve(&link_resolver, &logger, 0, &SPEC_VERSION_1_2_0)
+            .await
+            .unwrap();
         let expected = DataSource {
             kind: SUBSTREAMS_KIND.into(),
             network: Some("mainnet".into()),
@@ -470,7 +475,10 @@ mod test {
             serde_yaml::from_str(TEMPLATE_DATA_SOURCE_WITH_PARAMS).unwrap();
         let link_resolver: Arc<dyn LinkResolver> = Arc::new(NoopLinkResolver {});
         let logger = Logger::root(Discard, o!());
-        let ds: DataSource = ds.resolve(&link_resolver, &logger, 0).await.unwrap();
+        let ds: DataSource = ds
+            .resolve(&link_resolver, &logger, 0, &SPEC_VERSION_1_2_0)
+            .await
+            .unwrap();
         let expected = DataSource {
             kind: SUBSTREAMS_KIND.into(),
             network: Some("mainnet".into()),

docs/subgraph-manifest.md

@@ -98,7 +98,7 @@ The `mapping` field may be one of the following supported mapping manifests:
 
 ### 1.5.3 Declaring calls
 
-_Available from spec version 1.2.0_
+_Available from spec version 1.2.0. Struct field access available from spec version 1.4.0_
 
 Declared calls are performed in parallel before the handler is run and can
 greatly speed up syncing. Mappings access the call results simply by using
@@ -118,7 +118,17 @@ Each call is of the form `<ABI>[<address>].<function>(<args>)`:
 | **function** | *String* | The name of a view function in the contract |
 | **args** | *[Expr]* | The arguments to pass to the function |
 
-The `Expr` can be either `event.address` or `event.params.<name>`.
+#### Expression Types
+
+The `Expr` can be one of the following:
+
+| Expression | Description |
+| --- | --- |
+| **event.address** | The address of the contract that emitted the event |
+| **event.params.&lt;name&gt;** | A simple parameter from the event |
+| **event.params.&lt;name&gt;.&lt;index&gt;** | A field from a struct parameter by numeric index |
+| **event.params.&lt;name&gt;.&lt;fieldName&gt;** | A field from a struct parameter by field name (spec version 1.4.0+) |
+
 
 ## 1.6 Path
 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/).

graph/src/blockchain/mock.rs

@@ -193,6 +193,7 @@ impl<C: Blockchain> UnresolvedDataSource<C> for MockUnresolvedDataSource {
         _resolver: &Arc<dyn LinkResolver>,
         _logger: &slog::Logger,
         _manifest_idx: u32,
+        _spec_version: &semver::Version,
     ) -> Result<C::DataSource, anyhow::Error> {
         todo!()
     }
@@ -243,6 +244,7 @@ impl<C: Blockchain> UnresolvedDataSourceTemplate<C> for MockUnresolvedDataSource
         _resolver: &Arc<dyn LinkResolver>,
         _logger: &slog::Logger,
         _manifest_idx: u32,
+        _spec_version: &semver::Version,
     ) -> Result<C::DataSourceTemplate, anyhow::Error> {
         todo!()
     }

graph/src/blockchain/mod.rs

@@ -378,6 +378,7 @@ pub trait UnresolvedDataSourceTemplate<C: Blockchain>:
         resolver: &Arc<dyn LinkResolver>,
         logger: &Logger,
         manifest_idx: u32,
+        spec_version: &semver::Version,
     ) -> Result<C::DataSourceTemplate, anyhow::Error>;
 }
 
@@ -407,6 +408,7 @@ pub trait UnresolvedDataSource<C: Blockchain>:
         resolver: &Arc<dyn LinkResolver>,
         logger: &Logger,
         manifest_idx: u32,
+        spec_version: &semver::Version,
     ) -> Result<C::DataSource, anyhow::Error>;
 }
 

graph/src/data/subgraph/api_version.rs

@@ -60,8 +60,11 @@ pub const SPEC_VERSION_1_2_0: Version = Version::new(1, 2, 0);
 // represents the write order across all entity types in the subgraph.
 pub const SPEC_VERSION_1_3_0: Version = Version::new(1, 3, 0);
 
+// Enables struct field access in declarative calls
+pub const SPEC_VERSION_1_4_0: Version = Version::new(1, 4, 0);
+
 // The latest spec version available
-pub const LATEST_VERSION: &Version = &SPEC_VERSION_1_3_0;
+pub const LATEST_VERSION: &Version = &SPEC_VERSION_1_4_0;
 
 pub const MIN_SPEC_VERSION: Version = Version::new(0, 0, 2);
 

graph/src/data/subgraph/mod.rs

@@ -1074,14 +1074,20 @@ impl<C: Blockchain> UnresolvedSubgraphManifest<C> {
             data_sources
                 .into_iter()
                 .enumerate()
-                .map(|(idx, ds)| ds.resolve(resolver, logger, idx as u32))
+                .map(|(idx, ds)| ds.resolve(resolver, logger, idx as u32, &spec_version))
                 .collect::<FuturesOrdered<_>>()
                 .try_collect::<Vec<_>>(),
             templates
                 .into_iter()
                 .enumerate()
                 .map(|(idx, template)| {
-                    template.resolve(resolver, &schema, logger, ds_count as u32 + idx as u32)
+                    template.resolve(
+                        resolver,
+                        &schema,
+                        logger,
+                        ds_count as u32 + idx as u32,
+                        &spec_version,
+                    )
                 })
                 .collect::<FuturesOrdered<_>>()
                 .try_collect::<Vec<_>>(),