Optional event processing on historical indexing

codegenerator/cli/npm/envio/evm.schema.json

@@ -204,6 +204,13 @@
               "type": "null"
             }
           ]
+        },
+        "only_when_ready": {
+          "description": "If true, this event will only be tracked when the chain is ready (after historical backfill is complete). No queries will be made for this event during historical sync. Useful for speeding up indexing when historical data is not needed. (default: false)",
+          "type": [
+            "boolean",
+            "null"
+          ]
         }
       },
       "additionalProperties": false,

codegenerator/cli/npm/envio/fuel.schema.json

@@ -142,6 +142,13 @@
             "string",
             "null"
           ]
+        },
+        "onlyWhenReady": {
+          "description": "If true, this event will only be tracked when the chain is ready (after historical backfill is complete). No queries will be made for this event during historical sync. Useful for speeding up indexing when historical data is not needed. (default: false)",
+          "type": [
+            "boolean",
+            "null"
+          ]
         }
       },
       "additionalProperties": false,

codegenerator/cli/npm/envio/src/Internal.res

@@ -103,6 +103,8 @@ type eventConfig = private {
   handler: option<handler>,
   contractRegister: option<contractRegister>,
   paramsRawEventSchema: S.schema<eventParams>,
+  // If true, this event will only be tracked when the chain is ready (after historical backfill)
+  onlyWhenReady: bool,
 }
 
 type fuelEventKind =

codegenerator/cli/src/cli_args/init_config.rs

@@ -58,6 +58,7 @@ pub mod evm {
                         event: EvmAbi::event_signature_from_abi_event(&event),
                         name: None,
                         field_selection: None,
+                        only_when_ready: None,
                     })
                     .collect();
 

codegenerator/cli/src/cli_args/interactive_init/fuel_prompts.rs

@@ -134,6 +134,7 @@ async fn get_contract_import_selection(args: ContractImportArgs) -> Result<Selec
             name: log.event_name.clone(),
             log_id: Some(log.id.clone()),
             type_: None,
+            only_when_ready: None,
         })
         .collect();
 
@@ -147,6 +148,7 @@ async fn get_contract_import_selection(args: ContractImportArgs) -> Result<Selec
     selected_events.extend(event_names.iter().map(|&name| EventConfig {
         name: name.to_string(),
         log_id: None,
+        only_when_ready: None,
         type_: None,
     }));
     if !args.all_events {

codegenerator/cli/src/config_parsing/graph_migration/mod.rs

@@ -342,6 +342,7 @@ pub async fn generate_config_from_subgraph_id(
                                 event: event_name.to_string(),
                                 name: None,
                                 field_selection: None,
+                                only_when_ready: None,
                             };
 
                             Ok(event)

codegenerator/cli/src/config_parsing/human_config.rs

@@ -542,6 +542,15 @@ pub mod evm {
                            event"
         )]
         pub field_selection: Option<FieldSelection>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        #[serde(default)]
+        #[schemars(
+            description = "If true, this event will only be tracked when the chain is ready (after \
+                           historical backfill is complete). No queries will be made for this event \
+                           during historical sync. Useful for speeding up indexing when historical \
+                           data is not needed. (default: false)"
+        )]
+        pub only_when_ready: Option<bool>,
     }
 }
 
@@ -701,6 +710,15 @@ pub mod fuel {
                            logged struct/enum name."
         )]
         pub log_id: Option<String>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        #[serde(default)]
+        #[schemars(
+            description = "If true, this event will only be tracked when the chain is ready (after \
+                           historical backfill is complete). No queries will be made for this event \
+                           during historical sync. Useful for speeding up indexing when historical \
+                           data is not needed. (default: false)"
+        )]
+        pub only_when_ready: Option<bool>,
     }
 }
 
@@ -926,11 +944,13 @@ address: ["0x2E645469f354BB4F5c8a05B3b30A929361cf77eC"]
                                 name: "NewGreeting".to_string(),
                                 log_id: None,
                                 type_: None,
+                                only_when_ready: None,
                             },
                             fuel::EventConfig {
                                 name: "ClearGreeting".to_string(),
                                 log_id: None,
                                 type_: None,
+                                only_when_ready: None,
                             },
                         ],
                     }),

codegenerator/cli/src/config_parsing/system_config.rs

@@ -1244,6 +1244,7 @@ pub struct Event {
     pub name: String,
     pub sighash: String,
     pub field_selection: Option<FieldSelection>,
+    pub only_when_ready: bool,
 }
 
 impl Event {
@@ -1335,6 +1336,7 @@ impl Event {
                     }
                     None => None,
                 },
+                only_when_ready: event_config.only_when_ready.unwrap_or(false),
             })
         }
 
@@ -1414,31 +1416,36 @@ impl Event {
                         kind: EventKind::Fuel(FuelEventKind::LogData(log.data_type)),
                         sighash: log.id,
                         field_selection: None,
+                        only_when_ready: event_config.only_when_ready.unwrap_or(false),
                     }
                 }
                 EventType::Mint => Event {
                     name: event_config.name.clone(),
                     kind: EventKind::Fuel(FuelEventKind::Mint),
                     sighash: "mint".to_string(),
                     field_selection: None,
+                    only_when_ready: event_config.only_when_ready.unwrap_or(false),
                 },
                 EventType::Burn => Event {
                     name: event_config.name.clone(),
                     kind: EventKind::Fuel(FuelEventKind::Burn),
                     sighash: "burn".to_string(),
                     field_selection: None,
+                    only_when_ready: event_config.only_when_ready.unwrap_or(false),
                 },
                 EventType::Transfer => Event {
                     name: event_config.name.clone(),
                     kind: EventKind::Fuel(FuelEventKind::Transfer),
                     sighash: "transfer".to_string(),
                     field_selection: None,
+                    only_when_ready: event_config.only_when_ready.unwrap_or(false),
                 },
                 EventType::Call => Event {
                     name: event_config.name.clone(),
                     kind: EventKind::Fuel(FuelEventKind::Call),
                     sighash: "call".to_string(),
                     field_selection: None,
+                    only_when_ready: event_config.only_when_ready.unwrap_or(false),
                 },
             };
 

codegenerator/cli/src/hbs_templating/codegen_templates.rs

@@ -338,6 +338,7 @@ pub struct EventMod {
     pub custom_field_selection: Option<system_config::FieldSelection>,
     pub fuel_event_kind: Option<FuelEventKind>,
     pub preload_handlers: bool,
+    pub only_when_ready: bool,
 }
 
 impl Display for EventMod {
@@ -417,14 +418,16 @@ impl EventMod {
                 ),
             };
 
+        let only_when_ready_code = if self.only_when_ready { "true" } else { "false" };
         let base_event_config_code = format!(
             r#"id,
   name,
   contractName,
   isWildcard: (handlerRegister->EventRegister.isWildcard),
   handler: handlerRegister->EventRegister.getHandler,
   contractRegister: handlerRegister->EventRegister.getContractRegister,
-  paramsRawEventSchema: paramsRawEventSchema->(Utils.magic: S.t<eventArgs> => S.t<Internal.eventParams>),"#
+  paramsRawEventSchema: paramsRawEventSchema->(Utils.magic: S.t<eventArgs> => S.t<Internal.eventParams>),
+  onlyWhenReady: {only_when_ready_code},"#
         );
 
         let non_event_mod_code = match fuel_event_kind_code {
@@ -655,6 +658,7 @@ impl EventTemplate {
             custom_field_selection: config_event.field_selection.clone(),
             fuel_event_kind: Some(fuel_event_kind),
             preload_handlers: preload_handlers,
+            only_when_ready: config_event.only_when_ready,
         };
         EventTemplate {
             name: event_name,
@@ -682,6 +686,7 @@ impl EventTemplate {
             custom_field_selection: config_event.field_selection.clone(),
             fuel_event_kind: Some(fuel_event_kind),
             preload_handlers: preload_handlers,
+            only_when_ready: config_event.only_when_ready,
         };
         EventTemplate {
             name: event_name,
@@ -745,6 +750,7 @@ impl EventTemplate {
                     custom_field_selection: config_event.field_selection.clone(),
                     fuel_event_kind: None,
                     preload_handlers: preload_handlers,
+                    only_when_ready: config_event.only_when_ready,
                 };
 
                 Ok(EventTemplate {
@@ -773,6 +779,7 @@ impl EventTemplate {
                             custom_field_selection: config_event.field_selection.clone(),
                             fuel_event_kind: Some(fuel_event_kind),
                             preload_handlers: preload_handlers,
+                            only_when_ready: config_event.only_when_ready,
                         };
 
                         Ok(EventTemplate {
@@ -1775,6 +1782,7 @@ let register = (): Internal.evmEventConfig => {{
   handler: handlerRegister->EventRegister.getHandler,
   contractRegister: handlerRegister->EventRegister.getContractRegister,
   paramsRawEventSchema: paramsRawEventSchema->(Utils.magic: S.t<eventArgs> => S.t<Internal.eventParams>),
+  onlyWhenReady: false,
   }}
 }}"#
             ),
@@ -1790,6 +1798,7 @@ let register = (): Internal.evmEventConfig => {{
                 sighash: "0x50f7d27e90d1a5a38aeed4ceced2e8ec1ff185737aca96d15791b470d3f17363"
                     .to_string(),
                 field_selection: None,
+                only_when_ready: false,
             },
             false,
         )
@@ -1870,6 +1879,7 @@ let register = (): Internal.evmEventConfig => {
   handler: handlerRegister->EventRegister.getHandler,
   contractRegister: handlerRegister->EventRegister.getContractRegister,
   paramsRawEventSchema: paramsRawEventSchema->(Utils.magic: S.t<eventArgs> => S.t<Internal.eventParams>),
+  onlyWhenReady: false,
   }
 }"#.to_string(),
             }
@@ -1891,6 +1901,7 @@ let register = (): Internal.evmEventConfig => {
                         data_type: RescriptTypeIdent::option(RescriptTypeIdent::Address),
                     }],
                 }),
+                only_when_ready: false,
             },
             false,
         )
@@ -1971,6 +1982,7 @@ let register = (): Internal.evmEventConfig => {
   handler: handlerRegister->EventRegister.getHandler,
   contractRegister: handlerRegister->EventRegister.getContractRegister,
   paramsRawEventSchema: paramsRawEventSchema->(Utils.magic: S.t<eventArgs> => S.t<Internal.eventParams>),
+  onlyWhenReady: false,
   }
 }"#.to_string(),
             }

codegenerator/cli/templates/static/codegen/src/eventFetching/ChainFetcher.res

@@ -55,11 +55,14 @@ let make = (
 
   let notRegisteredEvents = []
 
+  // Check if the chain is ready (has caught up to head or endblock)
+  let isReady = timestampCaughtUpToHeadOrEndblock !== None
+
   chainConfig.contracts->Array.forEach(contract => {
     let contractName = contract.name
 
     contract.events->Array.forEach(eventConfig => {
-      let {isWildcard} = eventConfig
+      let {isWildcard, onlyWhenReady} = eventConfig
       let hasContractRegister = eventConfig.contractRegister->Option.isSome
 
       // Should validate the events
@@ -74,14 +77,17 @@ let make = (
 
       // Filter out non-preRegistration events on preRegistration phase
       // so we don't care about it in fetch state and workers anymore
+      // Also filter out events that are only tracked when ready if the chain is not ready yet
       let shouldBeIncluded = if config.enableRawEvents {
         true
       } else {
         let isRegistered = hasContractRegister || eventConfig.handler->Option.isSome
         if !isRegistered {
           notRegisteredEvents->Array.push(eventConfig)
         }
-        isRegistered
+        // Skip events marked as onlyWhenReady if the chain is not ready yet
+        let shouldIncludeBasedOnReadiness = !onlyWhenReady || isReady
+        isRegistered && shouldIncludeBasedOnReadiness
       }
 
       if shouldBeIncluded {

scenarios/test_codegen/config.yaml

@@ -12,6 +12,8 @@ contracts:
     handler: ./src/EventHandlers.res.js
     events:
       - event: "EmptyEvent()"
+      - event: "OnlyWhenReadyEvent()"
+        only_when_ready: true
   - name: EventFiltersTest
     handler: ./src/EventHandlers.res.js
     events: