feat: events: Lotus API to consume events (smart contract + built-in Actor events)

[aarshkshah1992]

TODO

• Rebase on feat/nv22 after the FFI/ref-fvm/actor changes have been bubbled up to the feat/nv22 branch

Related Issues

• For feat: events: Implement API for clients to subscribe to and consume built-in Actor events  #11457
• FIP-discussion for built-in Actor events at Actor events for the verified registry, miner, and market actors (FIP-0083) FIPs#754
• FIP-0083 for built-in Actor events

Proposed Changes

This PR is for #11457. It implements a new API in Lotus for clients to consume both smart contract and the upcoming built-in Actor events in FIP-0083

Note that this is the first draft and it would be great to get community feedback on improvements we can make to the API here.

The existing ETH events API will remain as is and no changes have been made to it.

API Definition

type ActorEventAPI interface {
	GetActorEvents(ctx context.Context, filter *types.ActorEventFilter) ([]*types.ActorEvent, error)
	SubscribeActorEvents(ctx context.Context, filter *types.SubActorEventFilter) (<-chan *types.ActorEvent, error)
}

type ActorEventBlock struct {
	// what value codec does client want to match on ?
	Codec uint64 `json:"codec"`
	// data associated with the "event key"
	Value []byte `json:"value"`
}

type SubActorEventFilter struct {
	Filter  ActorEventFilter `json:"filter"`
	Prefill bool             `json:"prefill"`
}

type ActorEventFilter struct {
	// Matches events from one of these actors, or any actor if empty.
	// TODO: Should we also allow Eth addresses here?
	// For now, this MUST be a Filecoin address.
	Addresses []address.Address `json:"address"`

	// Matches events with the specified key/values, or all events if empty.
	// If the `Blocks` slice is empty, matches on the key only.
	Fields map[string][]ActorEventBlock `json:"fields"`

	// Epoch based filtering ?
	// Start epoch for the filter; -1 means no minimum
	MinEpoch abi.ChainEpoch `json:"minEpoch,omitempty"`

	// End epoch for the filter; -1 means no maximum
	MaxEpoch abi.ChainEpoch `json:"maxEpoch,omitempty"`
}

type ActorEvent struct {
	Entries     []EventEntry
	EmitterAddr address.Address // f4 address of emitter
	Reverted    bool
	Height      abi.ChainEpoch
	TipSetKey   cid.Cid // tipset that contained the message
	MsgCid      cid.Cid // cid of message that produced event
}

There are some changes/details we need to drive consensus on which I've left as review comments on the PR.

Additional Info

Checklist

Before you mark the PR ready for review, please make sure that:

• Commits have a clear commit message.
• PR title is in the form of of <PR type>: <area>: <change being made>
  • example: fix: mempool: Introduce a cache for valid signatures
  • PR type: fix, feat, build, chore, ci, docs, perf, refactor, revert, style, test
  • area, e.g. api, chain, state, market, mempool, multisig, networking, paych, proving, sealing, wallet, deps
• If the PR affects users (e.g., new feature, bug fix, system requirements change), update the CHANGELOG.md and add details to the UNRELEASED section.
• New features have usage guidelines and / or documentation updates in
  • Lotus Documentation
  • Discussion Tutorials
• Tests exist for new functionality or change in behavior
• CI is green

[aarshkshah1992]

itests will be green after we merge the FFI/ref-fvm deps changes for NV22 to this branch.

[Stebalien]

itests will be green after we merge the FFI/ref-fvm deps changes for NV22 to this branch.

Merged.

[rvagg]

I've merged feat/nv22 back in here, but it also needs a newer builtin-actors. Unfortunately, the v13.0.0-rc.1 already has the optional AggregateProofType change which requires the additional fixes in go-state-types and back here, so it has to be v13.0.0-dev.0; which can be installed with:

(cd build/actors/; ./pack.sh v13 v13.0.0-dev.0)

Then this works as is.

[rvagg]

@aarshkshah1992 latest commit from me is a cleanup and doc of the test. I've tried to structure it a bit better to be more easily understood since there's so many things going on in there.

I got to simplify a bunch of things while in there, including that height problem! Switching to using ChainGetMessagesInTipset and then following that up with a general StateSearchMsg (can't use the actual tipset for that call, has to be types.EmptyTSK, I guess because receipts come after the tipset..?). Then you end up with exactly the same events as the GetActorEvents produces and a simple require.Equal(t, expected, actual) works for comparing.

I think I also made the whole allocation->claim testing thing a bit clearer and actually tested the claim is what we expect. Which then verifies that data collection for the DDO flow is possible with this workflow.

[rvagg]

Some notes related to the differences to the Eth events API for this one, for anyone reviewing this who may think this is important:

• FromEpoch instead of FromBlock, ToEpoch instead of ToBlock - we're still using hex to communicate the epoch but we take it as a string so we can also do "earliest" and "latest".
  • The hex is still something we could revisit, is there a good reason to use hex for this when it's just an epoch number? The returned ActorEvent object has a plain epoch integer in it, maybe we should be mirroring that and accepting a plain number (as a string) instead of a hex?
  • It's named height in ActorEvent returned by you use FromEpoch and ToEpoch, should we make the terms consistent?
• FromEpoch and ToEpoch are string with json:omitempty, in the Eth API they are *string with json:omitempty. Does this matter? Empty string signals default and you don't have to mess with pointers to literals. For RPC it should be essentially the same I believe.
• There's no direct equivalent to EthLog in here, although ActorEvent as some of the information; you're stuck with a raw EventEntry slice to decode yourself. We could do something like "topics" in EthLog and extract the $type up to the top level. But maybe that's something we can do later.

[rjan90]

Given that the TODO of Rebase on feat/nv22 after the FFI/ref-fvm/actor changes have been bubbled up to the feat/nv22 branch now is done, I think this PR now is ready for merge @aarshkshah1992 ?

[rvagg]

I'm fine with this getting merged, probably needs to be squashed up because it's a bit of a mess.

I have some additional proposals for the API but they can be done separately.

[rvagg]

#11618 has all of this and is condensed and is receiving updates. So moving discussion to there.