feat(config): move Fevm.Events->Events, implement soft deprecation

Closes: #11679

* Introduce a `moved:"To.New.Config"` tag which prints a stderr warning when
  you use one of these, but will move any set value to the new location if the
	new location isn't already set itself.
* Look for `X is DEPRECATED` to hold certain fields back from documentation.
* Use `toml:"omitempty"` to prevent the default config output from having these
  deprecated values.

CHANGELOG.md

@@ -136,7 +136,7 @@ Additionally, Filecoin is not Ethereum no matter how much we try to provide API/
 
 [FIP-0049](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0049.md) introduced _Actor Events_ that can be emitted by user programmed actors. [FIP-0083](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0083.md) introduces new events emitted by the builtin Verified Registry, Miner and Market Actors. These new events for builtin actors are being activated with network version 22 to coincide with _Direct Data Onboarding_ as defined in [FIP-0076](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0076.md) which introduces additional flexibility for data onboarding. Sector, Deal and DataCap lifecycles can be tracked with these events, providing visibility and options for programmatic responses to changes in state.
 
-Actor events are available on message receipts, but can now be retrieved from a node using the new `GetActorEvents` and `SubscribeActorEvents` methods. These methods allow for querying and subscribing to actor events, respectively. They depend on the Lotus node both collecting events (with `Fevm.Events.RealTimeFilterAPI` and `Fevm.Events.HistoricFilterAPI`) and being enabled with the new configuration option `Events.EnableActorEventsAPI`. Note that a Lotus node can only respond to requests for historic events that it retains in its event store.
+Actor events are available on message receipts, but can now be retrieved from a node using the new `GetActorEvents` and `SubscribeActorEvents` methods. These methods allow for querying and subscribing to actor events, respectively. They depend on the Lotus node both collecting events (with `Events.RealTimeFilterAPI` and `Events.HistoricFilterAPI`) and being enabled with the new configuration option `Events.EnableActorEventsAPI`. Note that a Lotus node can only respond to requests for historic events that it retains in its event store.
 
 Both `GetActorEvents` and `SubscribeActorEvents` take a filter parameter which can optionally filter events on:
 
@@ -147,7 +147,14 @@ Both `GetActorEvents` and `SubscribeActorEvents` take a filter parameter which c
 
 `GetActorEvents` provides a one-time query for actor events, while `SubscribeActorEvents` provides a long-lived connection (via websockets) to the Lotus node, allowing for real-time updates on actor events. The subscription can be cancelled by the client at any time.
 
+### Events Configuration Changes
+
+All configuration options previously under `Fevm.Events` are now in the top-level `Events` section along with the new `Events.EnableActorEventsAPI` option mentioned above. If you have non-default options in `[Events]` under `[Fevm]` in your configuration file, please move them to the top-level `[Events]`.
+
+While `Fevm.Events.*` options are deprecated and replaced by `Events.*`, any existing custom values will be respected if their new form isn't set, but a warning will be printed to standard error upon startup. Support for these deprecated options will be removed in a future Lotus release, so please migrate your configuration promptly.
+
 ### GetAllClaims and GetAllAlocations
+
 Additionally the methods `GetAllAllocations` and `GetAllClaims` has been added to the Lotus API. These methods lists all the available allocations and claims available in the actor state.
 
 ### Lotus CLI

documentation/en/default-lotus-config.toml

@@ -337,68 +337,67 @@
   # env var: LOTUS_FEVM_ETHTXHASHMAPPINGLIFETIMEDAYS
   #EthTxHashMappingLifetimeDays = 0
 
-  [Fevm.Events]
-    # DisableRealTimeFilterAPI will disable the RealTimeFilterAPI that can create and query filters for actor events as they are emitted.
-    # The API is enabled when EnableEthRPC or Events.EnableActorEventsAPI is true, but can be disabled selectively with this flag.
-    #
-    # type: bool
-    # env var: LOTUS_FEVM_EVENTS_DISABLEREALTIMEFILTERAPI
-    #DisableRealTimeFilterAPI = false
-
-    # DisableHistoricFilterAPI will disable the HistoricFilterAPI that can create and query filters for actor events
-    # that occurred in the past. HistoricFilterAPI maintains a queryable index of events.
-    # The API is enabled when EnableEthRPC or Events.EnableActorEventsAPI is true, but can be disabled selectively with this flag.
-    #
-    # type: bool
-    # env var: LOTUS_FEVM_EVENTS_DISABLEHISTORICFILTERAPI
-    #DisableHistoricFilterAPI = false
-
-    # FilterTTL specifies the time to live for actor event filters. Filters that haven't been accessed longer than
-    # this time become eligible for automatic deletion.
-    #
-    # type: Duration
-    # env var: LOTUS_FEVM_EVENTS_FILTERTTL
-    #FilterTTL = "24h0m0s"
-
-    # MaxFilters specifies the maximum number of filters that may exist at any one time.
-    #
-    # type: int
-    # env var: LOTUS_FEVM_EVENTS_MAXFILTERS
-    #MaxFilters = 100
-
-    # MaxFilterResults specifies the maximum number of results that can be accumulated by an actor event filter.
-    #
-    # type: int
-    # env var: LOTUS_FEVM_EVENTS_MAXFILTERRESULTS
-    #MaxFilterResults = 10000
 
-    # MaxFilterHeightRange specifies the maximum range of heights that can be used in a filter (to avoid querying
-    # the entire chain)
-    #
-    # type: uint64
-    # env var: LOTUS_FEVM_EVENTS_MAXFILTERHEIGHTRANGE
-    #MaxFilterHeightRange = 2880
-
-    # DatabasePath is the full path to a sqlite database that will be used to index actor events to
-    # support the historic filter APIs. If the database does not exist it will be created. The directory containing
-    # the database must already exist and be writeable. If a relative path is provided here, sqlite treats it as
-    # relative to the CWD (current working directory).
-    #
-    # type: string
-    # env var: LOTUS_FEVM_EVENTS_DATABASEPATH
-    #DatabasePath = ""
+[Events]
+  # DisableRealTimeFilterAPI will disable the RealTimeFilterAPI that can create and query filters for actor events as they are emitted.
+  # The API is enabled when Fevm.EnableEthRPC or EnableActorEventsAPI is true, but can be disabled selectively with this flag.
+  #
+  # type: bool
+  # env var: LOTUS_EVENTS_DISABLEREALTIMEFILTERAPI
+  #DisableRealTimeFilterAPI = false
 
+  # DisableHistoricFilterAPI will disable the HistoricFilterAPI that can create and query filters for actor events
+  # that occurred in the past. HistoricFilterAPI maintains a queryable index of events.
+  # The API is enabled when Fevm.EnableEthRPC or EnableActorEventsAPI is true, but can be disabled selectively with this flag.
+  #
+  # type: bool
+  # env var: LOTUS_EVENTS_DISABLEHISTORICFILTERAPI
+  #DisableHistoricFilterAPI = false
 
-[Events]
   # EnableActorEventsAPI enables the Actor events API that enables clients to consume events
   # emitted by (smart contracts + built-in Actors).
   # This will also enable the RealTimeFilterAPI and HistoricFilterAPI by default, but they can be
-  # disabled by setting their respective Disable* options in Fevm.Events.
+  # disabled by setting their respective Disable* options.
   #
   # type: bool
   # env var: LOTUS_EVENTS_ENABLEACTOREVENTSAPI
   #EnableActorEventsAPI = false
 
+  # FilterTTL specifies the time to live for actor event filters. Filters that haven't been accessed longer than
+  # this time become eligible for automatic deletion.
+  #
+  # type: Duration
+  # env var: LOTUS_EVENTS_FILTERTTL
+  #FilterTTL = "24h0m0s"
+
+  # MaxFilters specifies the maximum number of filters that may exist at any one time.
+  #
+  # type: int
+  # env var: LOTUS_EVENTS_MAXFILTERS
+  #MaxFilters = 100
+
+  # MaxFilterResults specifies the maximum number of results that can be accumulated by an actor event filter.
+  #
+  # type: int
+  # env var: LOTUS_EVENTS_MAXFILTERRESULTS
+  #MaxFilterResults = 10000
+
+  # MaxFilterHeightRange specifies the maximum range of heights that can be used in a filter (to avoid querying
+  # the entire chain)
+  #
+  # type: uint64
+  # env var: LOTUS_EVENTS_MAXFILTERHEIGHTRANGE
+  #MaxFilterHeightRange = 2880
+
+  # DatabasePath is the full path to a sqlite database that will be used to index actor events to
+  # support the historic filter APIs. If the database does not exist it will be created. The directory containing
+  # the database must already exist and be writeable. If a relative path is provided here, sqlite treats it as
+  # relative to the CWD (current working directory).
+  #
+  # type: string
+  # env var: LOTUS_EVENTS_DATABASEPATH
+  #DatabasePath = ""
+
 
 [Index]
   # EXPERIMENTAL FEATURE. USE WITH CAUTION

itests/kit/node_opts.go

@@ -65,7 +65,7 @@ var DefaultNodeOpts = nodeOpts{
 			// test defaults
 
 			cfg.Fevm.EnableEthRPC = true
-			cfg.Fevm.Events.MaxFilterHeightRange = math.MaxInt64
+			cfg.Events.MaxFilterHeightRange = math.MaxInt64
 			cfg.Events.EnableActorEventsAPI = true
 			return nil
 		},

node/builder_chain.go

@@ -266,13 +266,13 @@ func ConfigFullNode(c interface{}) Option {
 
 		// Actor event filtering support
 		Override(new(events.EventHelperAPI), From(new(modules.EventHelperAPI))),
-		Override(new(*filter.EventFilterManager), modules.EventFilterManager(cfg.Fevm)),
+		Override(new(*filter.EventFilterManager), modules.EventFilterManager(cfg.Events)),
 
 		// in lite-mode Eth api is provided by gateway
 		ApplyIf(isFullNode,
 			If(cfg.Fevm.EnableEthRPC,
 				Override(new(full.EthModuleAPI), modules.EthModuleAPI(cfg.Fevm)),
-				Override(new(full.EthEventAPI), modules.EthEventHandler(cfg.Fevm)),
+				Override(new(full.EthEventAPI), modules.EthEventHandler(cfg.Events, cfg.Fevm.EnableEthRPC)),
 			),
 			If(!cfg.Fevm.EnableEthRPC,
 				Override(new(full.EthModuleAPI), &full.EthModuleDummy{}),
@@ -282,7 +282,7 @@ func ConfigFullNode(c interface{}) Option {
 
 		ApplyIf(isFullNode,
 			If(cfg.Events.EnableActorEventsAPI,
-				Override(new(full.ActorEventAPI), modules.ActorEventHandler(cfg.Events.EnableActorEventsAPI, cfg.Fevm)),
+				Override(new(full.ActorEventAPI), modules.ActorEventHandler(cfg.Events)),
 			),
 			If(!cfg.Events.EnableActorEventsAPI,
 				Override(new(full.ActorEventAPI), &full.ActorEventDummy{}),

node/config/cfgdocgen/gen.go

@@ -74,6 +74,11 @@ func run() error {
 			name := f[0]
 			typ := f[1]
 
+			if len(comment) > 0 && strings.HasPrefix(comment[0], fmt.Sprintf("%s is DEPRECATED", name)) {
+				// don't document deprecated fields
+				continue
+			}
+
 			out[currentType] = append(out[currentType], field{
 				Name:    name,
 				Type:    typ,

node/config/def.go

@@ -110,17 +110,15 @@ func DefaultFullNode() *FullNode {
 		Fevm: FevmConfig{
 			EnableEthRPC:                 false,
 			EthTxHashMappingLifetimeDays: 0,
-			Events: Events{
-				DisableRealTimeFilterAPI: false,
-				DisableHistoricFilterAPI: false,
-				FilterTTL:                Duration(time.Hour * 24),
-				MaxFilters:               100,
-				MaxFilterResults:         10000,
-				MaxFilterHeightRange:     2880, // conservative limit of one day
-			},
 		},
 		Events: EventsConfig{
-			EnableActorEventsAPI: false,
+			DisableRealTimeFilterAPI: false,
+			DisableHistoricFilterAPI: false,
+			EnableActorEventsAPI:     false,
+			FilterTTL:                Duration(time.Hour * 24),
+			MaxFilters:               100,
+			MaxFilterResults:         10000,
+			MaxFilterHeightRange:     2880, // conservative limit of one day
 		},
 	}
 }