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

CHANGELOG.md

@@ -132,20 +132,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 `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 `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.
 
 ### 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.

api/api_full.go

@@ -906,16 +906,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.
@@ -929,7 +929,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

api/api_gateway.go

@@ -131,7 +131,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)
 }

build/openrpc/full.json

@@ -9392,9 +9392,9 @@
             }
         },
         {
-            "name": "Filecoin.GetActorEvents",
-            "description": "```go\nfunc (s *FullNodeStruct) GetActorEvents(p0 context.Context, p1 *types.ActorEventFilter) ([]*types.ActorEvent, error) {\n\tif s.Internal.GetActorEvents == nil {\n\t\treturn *new([]*types.ActorEvent), ErrNotSupported\n\t}\n\treturn s.Internal.GetActorEvents(p0, p1)\n}\n```",
-            "summary": "GetActorEvents returns all user-programmed and built-in actor events that match the given\nfilter.\nThis is a request/response API.\nResults available from this API may be limited by the MaxFilterResults and MaxFilterHeightRange\nconfiguration options and also the amount of historical data available in the node.\n\nThis is an EXPERIMENTAL API and may be subject to change.\n",
+            "name": "Filecoin.GetActorEventsRaw",
+            "description": "```go\nfunc (s *FullNodeStruct) GetActorEventsRaw(p0 context.Context, p1 *types.ActorEventFilter) ([]*types.ActorEvent, error) {\n\tif s.Internal.GetActorEventsRaw == nil {\n\t\treturn *new([]*types.ActorEvent), ErrNotSupported\n\t}\n\treturn s.Internal.GetActorEventsRaw(p0, p1)\n}\n```",
+            "summary": "GetActorEventsRaw returns all user-programmed and built-in actor events that match the given\nfilter.\nThis is a request/response API.\nResults available from this API may be limited by the MaxFilterResults and MaxFilterHeightRange\nconfiguration options and also the amount of historical data available in the node.\n\nThis is an EXPERIMENTAL API and may be subject to change.\n",
             "paramStructure": "by-position",
             "params": [
                 {

build/openrpc/gateway.json

@@ -5219,8 +5219,8 @@
             }
         },
         {
-            "name": "Filecoin.GetActorEvents",
-            "description": "```go\nfunc (s *GatewayStruct) GetActorEvents(p0 context.Context, p1 *types.ActorEventFilter) ([]*types.ActorEvent, error) {\n\tif s.Internal.GetActorEvents == nil {\n\t\treturn *new([]*types.ActorEvent), ErrNotSupported\n\t}\n\treturn s.Internal.GetActorEvents(p0, p1)\n}\n```",
+            "name": "Filecoin.GetActorEventsRaw",
+            "description": "```go\nfunc (s *GatewayStruct) GetActorEventsRaw(p0 context.Context, p1 *types.ActorEventFilter) ([]*types.ActorEvent, error) {\n\tif s.Internal.GetActorEventsRaw == nil {\n\t\treturn *new([]*types.ActorEvent), ErrNotSupported\n\t}\n\treturn s.Internal.GetActorEventsRaw(p0, p1)\n}\n```",
             "summary": "There are not yet any comments for this method.",
             "paramStructure": "by-position",
             "params": [

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)
@@ -282,7 +282,7 @@
   * [StateVerifierStatus](#StateVerifierStatus)
   * [StateWaitMsg](#StateWaitMsg)
 * [Subscribe](#Subscribe)
-  * [SubscribeActorEvents](#SubscribeActorEvents)
+  * [SubscribeActorEventsRaw](#SubscribeActorEventsRaw)
 * [Sync](#Sync)
   * [SyncCheckBad](#SyncCheckBad)
   * [SyncCheckpoint](#SyncCheckpoint)
@@ -3386,8 +3386,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
@@ -8801,8 +8801,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.

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)
 }