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/EventRegister.res

@@ -75,6 +75,7 @@ let onBlockOptionsSchema = S.schema(s =>
     "interval": s.matches(S.option(S.int->S.intMin(1))->S.Option.getOr(1)),
     "startBlock": s.matches(S.option(S.int)),
     "endBlock": s.matches(S.option(S.int)),
+    "onlyWhenReady": s.matches(S.option(S.bool)->S.Option.getOr(false)),
   }
 )
 
@@ -123,6 +124,7 @@ let onBlock = (rawOptions: unknown, handler: Internal.onBlockArgs => promise<uni
               interval: options["interval"],
               chainId,
               handler,
+              onlyWhenReady: options["onlyWhenReady"],
             }: Internal.onBlockConfig
           ),
         ],
@@ -138,6 +140,7 @@ let onBlock = (rawOptions: unknown, handler: Internal.onBlockArgs => promise<uni
             interval: options["interval"],
             chainId,
             handler,
+            onlyWhenReady: options["onlyWhenReady"],
           }: Internal.onBlockConfig
         ),
       )

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

@@ -1262,3 +1262,94 @@ let getUnorderedMultichainProgressBlockNumberAt = ({buffer} as fetchState: t, ~i
   | _ => bufferBlockNumber
   }
 }
+
+/**
+Activates deferred events and block handlers when the chain becomes ready.
+This is called when a chain transitions from historical sync to realtime.
+The deferred events will start being fetched from the current progress block.
+*/
+let activateDeferredEventsAndHandlers = (
+  fetchState: t,
+  ~deferredEventConfigs: array<Internal.eventConfig>,
+  ~deferredOnBlockConfigs: array<Internal.onBlockConfig>,
+): t => {
+  if deferredEventConfigs->Array.length === 0 && deferredOnBlockConfigs->Array.length === 0 {
+    fetchState
+  } else {
+    // Separate events into those that depend on addresses and those that don't
+    let notDependingOnAddresses = []
+    let dependingOnAddresses = []
+
+    deferredEventConfigs->Array.forEach(ec => {
+      if ec.dependsOnAddresses {
+        dependingOnAddresses->Array.push(ec)
+      } else {
+        notDependingOnAddresses->Array.push(ec)
+      }
+    })
+
+    // Start from the current latestFullyFetchedBlock
+    let newPartitions = []
+
+    // Create partition for events that don't depend on addresses
+    if notDependingOnAddresses->Array.length > 0 {
+      newPartitions->Array.push({
+        id: (fetchState.nextPartitionIndex + newPartitions->Array.length)->Int.toString,
+        status: {
+          fetchingStateId: None,
+        },
+        latestFetchedBlock: fetchState.latestFullyFetchedBlock,
+        selection: {
+          dependsOnAddresses: false,
+          eventConfigs: notDependingOnAddresses,
+        },
+        addressesByContractName: Js.Dict.empty(),
+      })
+    }
+
+    // For events that depend on addresses, we need to:
+    // 1. Add them to normalSelection
+    // 2. Add them to existing partitions that depend on addresses
+    let updatedNormalSelection = if dependingOnAddresses->Array.length > 0 {
+      {
+        dependsOnAddresses: true,
+        eventConfigs: fetchState.normalSelection.eventConfigs->Array.concat(dependingOnAddresses),
+      }
+    } else {
+      fetchState.normalSelection
+    }
+
+    // Update existing partitions that depend on addresses
+    let updatedPartitions = if dependingOnAddresses->Array.length > 0 {
+      fetchState.partitions->Array.map(p => {
+        if p.selection.dependsOnAddresses {
+          {
+            ...p,
+            selection: {
+              ...p.selection,
+              eventConfigs: p.selection.eventConfigs->Array.concat(dependingOnAddresses),
+            },
+          }
+        } else {
+          p
+        }
+      })
+    } else {
+      fetchState.partitions
+    }
+
+    // Combine partitions
+    let allPartitions = updatedPartitions->Array.concat(newPartitions)
+
+    // Add deferred block handlers
+    let updatedOnBlockConfigs = fetchState.onBlockConfigs->Array.concat(deferredOnBlockConfigs)
+
+    {
+      ...fetchState,
+      partitions: allPartitions,
+      nextPartitionIndex: fetchState.nextPartitionIndex + newPartitions->Array.length,
+      normalSelection: updatedNormalSelection,
+      onBlockConfigs: updatedOnBlockConfigs,
+    }
+  }
+}

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 =
@@ -187,6 +189,8 @@ type onBlockConfig = {
   endBlock: option<int>,
   interval: int,
   handler: onBlockArgs => promise<unit>,
+  // If true, this block handler will only be invoked when the chain is ready (after historical backfill)
+  onlyWhenReady: bool,
 }
 
 @tag("kind")

codegenerator/cli/src/cli_args/init_config.rs

@@ -60,6 +60,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(),
             }