feat(events): add "Raw" suffix to {Get,Subscribe}ActorEvents

This is done with the intention to add new {Get,Subscribe}ActorEvents in a future release (i.e. soon!) with both decoded values (dag-json represented) and simplified (no flags or codec). But because this comes with some trade-offs wrt fidelity of information (e.g. likely needing to drop events with badly encoded values, and not retaining original codec), we need to also have a Raw form of these APIs for consumers that want to take on the burden of consuming them as they are.
filecoin-project · Mar 22, 2024 · f4b4cd3 · f4b4cd3
1 parent 250914d
commit f4b4cd3
Show file tree

Hide file tree

Showing 14 changed files with 97 additions and 85 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -144,20 +144,22 @@ Additionally, Filecoin is not Ethereum no matter how much we try to provide API/
 
 [handlefilecoinmethod]: https://fips.filecoin.io/FIPS/fip-0054.html#handlefilecoinmethod-general-handler-for-method-numbers--1024
 
-### GetActorEvents and SubscribeActorEvents
+### GetActorEventsRaw and SubscribeActorEventsRaw
 
 [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 `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.
+Actor events are available on message receipts, but can now be retrieved from a node using the new `GetActorEventsRaw` and `SubscribeActorEventsRaw` 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.
 
-Both `GetActorEvents` and `SubscribeActorEvents` take a filter parameter which can optionally filter events on:
+Both `GetActorEventsRaw` and `SubscribeActorEventsRaw` take a filter parameter which can optionally filter events on:
 
 * `Addresses` of the actor(s) emitting the event
 * Specific `Fields` within the event
 * `FromHeight` and `ToHeight` to filter events by block height
 * `TipSetKey` to restrict events contained within a specific tipset
 
-`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.
+`GetActorEventsRaw` provides a one-time query for actor events, while `SubscribeActorEventsRaw` 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.
+
+A future Lotus release may include `GetActorEvents` and `SubscribeActorEvents` methods which will provide a more user-friendly interface to actor events, including deserialization of event data.
 
 ### Events Configuration Changes
 

diff --git a/api/api_full.go b/api/api_full.go
@@ -909,16 +909,16 @@ type FullNode interface {
 
 	// Actor events
 
-	// GetActorEvents returns all user-programmed and built-in actor events that match the given
+	// GetActorEventsRaw returns all user-programmed and built-in actor events that match the given
 	// filter.
 	// This is a request/response API.
 	// Results available from this API may be limited by the MaxFilterResults and MaxFilterHeightRange
 	// configuration options and also the amount of historical data available in the node.
 	//
 	// This is an EXPERIMENTAL API and may be subject to change.
-	GetActorEvents(ctx context.Context, filter *types.ActorEventFilter) ([]*types.ActorEvent, error) //perm:read
+	GetActorEventsRaw(ctx context.Context, filter *types.ActorEventFilter) ([]*types.ActorEvent, error) //perm:read
 
-	// SubscribeActorEvents returns a long-lived stream of all user-programmed and built-in actor
+	// SubscribeActorEventsRaw returns a long-lived stream of all user-programmed and built-in actor
 	// events that match the given filter.
 	// Events that match the given filter are written to the stream in real-time as they are emitted
 	// from the FVM.
@@ -932,7 +932,7 @@ type FullNode interface {
 	//
 	// Note: this API is only available via websocket connections.
 	// This is an EXPERIMENTAL API and may be subject to change.
-	SubscribeActorEvents(ctx context.Context, filter *types.ActorEventFilter) (<-chan *types.ActorEvent, error) //perm:read
+	SubscribeActorEventsRaw(ctx context.Context, filter *types.ActorEventFilter) (<-chan *types.ActorEvent, error) //perm:read
 }
 
 // reverse interface to the client, called after EthSubscribe

diff --git a/api/api_gateway.go b/api/api_gateway.go
@@ -130,7 +130,7 @@ type Gateway interface {
 	EthTraceBlock(ctx context.Context, blkNum string) ([]*ethtypes.EthTraceBlock, error)
 	EthTraceReplayBlockTransactions(ctx context.Context, blkNum string, traceTypes []string) ([]*ethtypes.EthTraceReplayBlockTransaction, error)
 
-	GetActorEvents(ctx context.Context, filter *types.ActorEventFilter) ([]*types.ActorEvent, error)
-	SubscribeActorEvents(ctx context.Context, filter *types.ActorEventFilter) (<-chan *types.ActorEvent, error)
+	GetActorEventsRaw(ctx context.Context, filter *types.ActorEventFilter) ([]*types.ActorEvent, error)
+	SubscribeActorEventsRaw(ctx context.Context, filter *types.ActorEventFilter) (<-chan *types.ActorEvent, error)
 	ChainGetEvents(context.Context, cid.Cid) ([]types.Event, error)
 }
diff --git a/api/mocks/mock_full.go b/api/mocks/mock_full.go
diff --git a/api/proxy_gen.go b/api/proxy_gen.go
diff --git a/documentation/en/api-v1-unstable-methods.md b/documentation/en/api-v1-unstable-methods.md
@@ -116,7 +116,7 @@
   * [GasEstimateGasPremium](#GasEstimateGasPremium)
   * [GasEstimateMessageGas](#GasEstimateMessageGas)
 * [Get](#Get)
-  * [GetActorEvents](#GetActorEvents)
+  * [GetActorEventsRaw](#GetActorEventsRaw)
 * [I](#I)
   * [ID](#ID)
 * [Log](#Log)
@@ -285,7 +285,7 @@
   * [StateVerifierStatus](#StateVerifierStatus)
   * [StateWaitMsg](#StateWaitMsg)
 * [Subscribe](#Subscribe)
-  * [SubscribeActorEvents](#SubscribeActorEvents)
+  * [SubscribeActorEventsRaw](#SubscribeActorEventsRaw)
 * [Sync](#Sync)
   * [SyncCheckBad](#SyncCheckBad)
   * [SyncCheckpoint](#SyncCheckpoint)
@@ -3389,8 +3389,8 @@ Response:
 ## Get
 
 
-### GetActorEvents
-GetActorEvents returns all user-programmed and built-in actor events that match the given
+### GetActorEventsRaw
+GetActorEventsRaw returns all user-programmed and built-in actor events that match the given
 filter.
 This is a request/response API.
 Results available from this API may be limited by the MaxFilterResults and MaxFilterHeightRange
@@ -8831,8 +8831,8 @@ Response:
 ## Subscribe
 
 
-### SubscribeActorEvents
-SubscribeActorEvents returns a long-lived stream of all user-programmed and built-in actor
+### SubscribeActorEventsRaw
+SubscribeActorEventsRaw returns a long-lived stream of all user-programmed and built-in actor
 events that match the given filter.
 Events that match the given filter are written to the stream in real-time as they are emitted
 from the FVM.

diff --git a/gateway/node.go b/gateway/node.go
@@ -147,8 +147,8 @@ type TargetAPI interface {
 	EthTraceBlock(ctx context.Context, blkNum string) ([]*ethtypes.EthTraceBlock, error)
 	EthTraceReplayBlockTransactions(ctx context.Context, blkNum string, traceTypes []string) ([]*ethtypes.EthTraceReplayBlockTransaction, error)
 
-	GetActorEvents(ctx context.Context, filter *types.ActorEventFilter) ([]*types.ActorEvent, error)
-	SubscribeActorEvents(ctx context.Context, filter *types.ActorEventFilter) (<-chan *types.ActorEvent, error)
+	GetActorEventsRaw(ctx context.Context, filter *types.ActorEventFilter) ([]*types.ActorEvent, error)
+	SubscribeActorEventsRaw(ctx context.Context, filter *types.ActorEventFilter) (<-chan *types.ActorEvent, error)
 	ChainGetEvents(ctx context.Context, eventsRoot cid.Cid) ([]types.Event, error)
 }
 

diff --git a/gateway/proxy_fil.go b/gateway/proxy_fil.go
@@ -437,18 +437,28 @@ func (gw *Node) StateWaitMsg(ctx context.Context, msg cid.Cid, confidence uint64
 	return gw.target.StateWaitMsg(ctx, msg, confidence, limit, allowReplaced)
 }
 
-func (gw *Node) GetActorEvents(ctx context.Context, filter *types.ActorEventFilter) ([]*types.ActorEvent, error) {
+func (gw *Node) GetActorEventsRaw(ctx context.Context, filter *types.ActorEventFilter) ([]*types.ActorEvent, error) {
 	if err := gw.limit(ctx, stateRateLimitTokens); err != nil {
 		return nil, err
 	}
-	return gw.target.GetActorEvents(ctx, filter)
+	if filter != nil && filter.FromHeight != nil {
+		if err := gw.checkTipSetHeight(ctx, *filter.FromHeight, types.EmptyTSK); err != nil {
+			return nil, err
+		}
+	}
+	return gw.target.GetActorEventsRaw(ctx, filter)
 }
 
-func (gw *Node) SubscribeActorEvents(ctx context.Context, filter *types.ActorEventFilter) (<-chan *types.ActorEvent, error) {
+func (gw *Node) SubscribeActorEventsRaw(ctx context.Context, filter *types.ActorEventFilter) (<-chan *types.ActorEvent, error) {
 	if err := gw.limit(ctx, stateRateLimitTokens); err != nil {
 		return nil, err
 	}
-	return gw.target.SubscribeActorEvents(ctx, filter)
+	if filter != nil && filter.FromHeight != nil {
+		if err := gw.checkTipSetHeight(ctx, *filter.FromHeight, types.EmptyTSK); err != nil {
+			return nil, err
+		}
+	}
+	return gw.target.SubscribeActorEventsRaw(ctx, filter)
 }
 
 func (gw *Node) ChainGetEvents(ctx context.Context, eventsRoot cid.Cid) ([]types.Event, error) {

diff --git a/itests/direct_data_onboard_test.go b/itests/direct_data_onboard_test.go
@@ -274,7 +274,7 @@ func TestOnboardMixedMarketDDO(t *testing.T) {
 
 		// check "deal-published" actor event
 		var epochZero abi.ChainEpoch
-		allEvents, err := miner.FullNode.GetActorEvents(ctx, &types.ActorEventFilter{
+		allEvents, err := miner.FullNode.GetActorEventsRaw(ctx, &types.ActorEventFilter{
 			FromHeight: &epochZero,
 		})
 		require.NoError(t, err)