Actor events for the verified registry, miner, and market actors (FIP-0083)

[anorth]

FIP-0049 introduced an events mechanism for actors, initially motivated to allow the EVM actors to support events from EVM smart contracts. Such events from built-in actors would be also be useful for clients and applications. This discussion is to determine the schemas and conventions for such events, to be eventually formalised in one or more FIPs.

To spur this discussion, I have prototyped an implementation of events for the verified registry actor. We expect to implement similar events for most of the built-in in actors in time. I chose the verified registry as a target because it's relatively simple, the events will be useful immediately, and are probably required for future direct data onboarding capabilities (they answer the question: how does an SP know an allocation was made?).

The prototype is in development at filecoin-project/builtin-actors#1320. I will update it as discussion here converges.

[anorth]

Design question: how much data should events include? E.g., for a new FIL+ allocation, should the event include all the allocation fields, or a subset, or only the ID?

• Including more data makes events easy to filter by clients, without needing state access (e.g. in browser)
• Including more data makes events larger, adding to node receipt storage requirements and associated gas cost for users

What tradeoff here might be appropriate if we consider applying it to all meaningful transitions in the remaining built-in actors (e.g. miner sector state changes & faults, datacap token)?

[anorth]

Thanks @raulk, that makes a lot of sense. Following your comment and brief discussions with others, I'm now leaning towards a minimal event payload, leaving almost all the data to state queries. I think the minimal info would be just an event type discriminator, and an identifier (e.g. allocation ID). Most of the time, all the other data would be just a single record lookup away, and the practical cost of that is likely dominated by the fixed costs of doing any lookup rather than the size of data returned.

Adding fields beyond the bare minimum gets into very hard-to-define measures of usefulness. Many parties will not care about at least some of the fields, or need to perform a lookup in any case. Any subset of fields is optimised only for a client that wants exactly that set. Everyone pays a cost for including too many fields, but there's nearly zero marginal cost for each additional field that needs to be looked up, after the first.

With that and the thread below in mind, I might propose as an example:

["_type": "NEW_ALLOCATION", "id": <allocation-id>]

@Stebalien @arajasek @ZenGround0 thoughts?

[Stebalien]

Sounds reasonable to me!

[Stebalien]

Moving the discussion from filecoin-project/builtin-actors#1471 (comment).

Ok, so, I was mostly focused on the whole _type thing. In terms of fields, I think we do want to include the minimum amount of information necessary to:

1. Identify the event (so we can query for more information).
2. Determine if the event might be interesting (usually just the IDs of the parties involved). This may significantly decrease complexity/costs for developers.

At first blush, I wouldn't include things like amounts because they can be queried. However, I'm not entirely sure about that because queries:

1. Can only only see the state between top-level messages.
2. Can only efficiently see the state between tipsets.

E.g., if a token is transferred multiple times within a single top-level message, being able to query the state isn't sufficient.

So, really, there's a third item: Any information the user might not be able to accurately and/or efficiently query for.

[Stebalien]

We should also make sure whatever we do is in-line with Ethereum. E.g., ERC20 has:

• Transfer(from, to, value).
• Approval(owner, spender, value).

If you look at 0x events (DEX), they're even more explicit: https://goethereumbook.org/event-read-0xprotocol/.

[anorth]

Good points, and I agree as far as things like token balances. But if fully generalised, I think this would end up requiring full state delta (or equivalent) in every event.

E.g. if the functionality on verified claims/allocs changed a little in the future to allow removal of allocs or claims before long expiry dates, an alloc could be created and deleted in one epoch, or created, claimed and then the claim removed. I don't think that happens to be possible at the moment, but rather by happy accident than design (and it could change).

I think we need to pragmatically draw a line somewhere about what use cases to support before expecting a more sophisticated user to revert to actually executing the transactions for themselves. The current proposal is sufficient for real-life use (a claim that lasts for zero epochs doesn't do anything).

[anorth]

Design question: how should we designate event types?

An event comprises a sequence of key/value pairs, where the value is optional. Because the order is specified, either position or a special key could be used for significant fields like a type specifier.

Version 1:

["event-type", "key1"="value1", "key2"=42]

Version 2:

["type"="event-type", "key1"="value1", "key2"=42]

Is the first position convenient enough to distinguish a type field? Would it be really annoying for clients that attempt to deserialize into an unordered map? Should we use a valueless key here to force clients to handle it, since it could in any case arise at any position? If we use a special key, what should it be?

[anorth]

@Stebalien I'm keen for your thoughts on tradeoffs here.

[raulk]

I'd lean over explicit and uniform payloads, as it results in better introspection and queriability. (This is also a good checkpoint to introduce a general convention for events emitted by built-in actors.)

I'd prefer version 2 but would prefer to name the type discriminator key $type, so that type remains available as a key to the actor without a forceful overload (keys need not be unique, so overloading type is always possible).

[Stebalien]

A bit late but...

1. I'd prefer to not lean on order as I expect tooling (indexing, etc.) to lose order (same as order tends to get lost for HTTP headers).
2. I'd also prefer an explicit "type" field over a valueless field as it'll probably be easier to handle in clients.

But these are just vague opinions.

In terms of sygils versus no sygils ($type versus type versus @type).... I don't like $type but I see why it might be nice: it guarantees no conflict. We could also look at https://json-ld.org/? But this probably doesn't matter much as long as we land on a convention.

[aarshkshah1992]

@anorth @Stebalien

Adding the following Sector lifecycle events to the Miner Actor in the next PR:

1. Sector Precommitted
   This will be emitted for each sector that is precommited either through the Miner Actor Precommit Method or through it's batched variant.

["$type"="sector-precommited", "miner"="{MINER_ACTOR_ID}", "sector"="{SECTOR_NUMBER}"]

We need both the Miner Actor Id and the Sector Number here to uniquely identify the sector that has been pre-commited. Ditto for the Sector Proven event below.

2. Sector Proven

This will be emitted for each sector that is proven i.e. each sector for which a "prove-commit" is received and verified.

 ["$type"="sector-proven", "miner"="{MINER_ACTOR_ID}", "sector"="{SECTOR_NUMBER}"]

Note that the ProveCommitSector method on the Miner Actor schedules a cron job to verify the proof and move the Sector to the proven state. In this case, we will need to emit the event when cron calls back into the Miner Actor to verify the proof. I already discussed this with @anorth offline.

[anorth]

I think we might want to call the miner "provider". In all cases outside of block production, we try to use the term Storage Provider to refer to them. See https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0018.md. Precedent is in the types for the market's DealProposal and verified registry Allocation.

[anorth]

We also need provider events for replica update.

I think we should also bundle built-in market deal activation and expiration/termination into the same set of changes.

[aarshkshah1992]

Update

Provider events for replica update and markets deal lifecycle events will be part of the same set of changes:
filecoin-project/builtin-actors#1471

[anorth]

I've retitled this discussion post to expand scope to the miner and market actors, as well as verified registry. This makes a nice set to target in one FIP.

[anorth]

Thanks @aarshkshah1992 for the draft FIP PR: #872

Moving some design questions from FIP editorial review to here to give more space for discussion.

@magik6k:

Can we add something [to the market deal-published event] that uniquely identifies the deal proposal? Signed proposal hash / client signature / client signature hash would be sufficient here, and extremely useful to clients

[anorth]

And related from @jennijuju

have we considered adding CID - so people can subscribe. to a particular CID and get all the deals info for that piece of data

Which CID is this referring to?

[aarshkshah1992]

@magik6k @jennijuju Any thoughts ?

[jennijuju]

I was referring to the data piece CID. I think it would be useful to build any data marketplaces or related application. Ideally we can add it to allocation/claim/deal/DDO related events imho.

[anorth]

The current draft has an inconsistency in the fields provided with verifreg vs market events. These workflows are quite similar in nature so I think we probably want a similar event schema, unless we can articulate a good reason why not.

The verifreg events currently all have the allocation/claim ID and the client and provider ID (see above). The market deal-publish event has similar, but then subsequent deal events only specify the deal ID.

The market approach does seem minimally sufficient: a party (e.g. a client) can filter for their ID in the deal-publish event, and accumulate a list of deal IDs they are then watching for subsequent events. But this does seem a bit less easy than just being able to filter for all the events on client ID, as they could for the verifreg events.

So which should we choose? My current thought is that the ease-of-use justifies a couple of integer fields in each event, so following the verifreg example.

[aarshkshah1992]

I am inclined to make all the market actor events include the client/provider ID for better UX here and revisit later if that becomes a problem.

[anorth]

Let's do that then, pending any significant objection.

[aarshkshah1992]

Added to draft FIP in 9df8f31.

[anorth]

What should we include in sector activation events? The minimum of a sector ID is there, with the idea that other data can be looked up in state.

The sector data commitment (CommD, unsealed CID) can't be looked up in state, because we don't store it. But this is likely to be useful to some off-chain groups like aggregators, indexers etc. Perhaps we should include it?

Noting @Stebalien's comments above, full support for any possible use case would require emitting all the sector metadata, since the sector could be terminated in the same epoch and the data gone. But I don't think this is practically worthwhile.

[aarshkshah1992]

@Stebalien Yes, this for when deals are activated via sector activation i.e. when SP publishes the ProveCommit/ProveReplicaUpdate message.

[aarshkshah1992]

@anorth

Since a sector can include multiple pieces. what would be the most efficient way to include the (piece cid + piece size) for each piece in the sector activation event payload in CBOR ?

Should it be something like

| flags | key | value                       |
| --- | --- |-----------------------------|
| Index Key + Value | “$type" | "sector-activated" (string) |
| Index Key + Value | “sector” | <SECTOR_NUMER> (int)        |
| Index Key + Value | “piece-cid” | <PIECE_CID> (string)        |
| Index Key + Value | “piece-size” | <PIECE_SIZE> (bigint)        |
| Index Key + Value | “piece-cid” | <PIECE_CID> (string)        |
| Index Key + Value | “piece-size” | <PIECE_SIZE> (bigint)        |

[aarshkshah1992]

Also, what cid -> string representation is the ideal to use here @Stebalien ?

[anorth]

I assume this is part of the deal activation event, right?

@Stebalien @aarshkshah1992 no, this thread is about sector activation events, because the sector CommD cannot be looked up later. Whether or not some deal might also be activated isn't known (generally in the future) by the miner actor. In the present draft, deal activation events do not include the data CID.

Adding post-DDO sector piece CIDs is another, separate thing we might consider (in thread below). Whether either or both is an interesting question.

[aarshkshah1992]

Raised #897 for the proposed change here.

[aarshkshah1992]

The new ProveCommitSectors2 and ProveReplicaUpdates2 method params introduced in https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0076.md also include the piece-cid/piece size to be onboarded in the sector.

We should ideally include the piece-cid/piece-size fields on the sector activation event payloads as clients can't query the Market Actor state to get this piece information for ddo-sector activations/updates as we completely bypass the Market Actor. Just putting the sector-number /miner-id on these event payloads as we do right now might not be enough

[anorth]

CID is an actual type in CBOR, it doesn't need to be stringified first.

Repeated keys, hmm. Yes let's try that, but let's also seek other opinions e.g. from @Stebalien .

Please merge the FIP PR as-is first, and then make a new PR with changes.

[aarshkshah1992]

@Stebalien Any thoughts on this ?

[aarshkshah1992]

@anorth Raised #897 for the proposed change here.

[raulk]

I think the piece CID makes sense as an indexed repeated field. I don't think it's worth making the piece size indexed (*), but it can be repeated and interleaved with the CID to simulate a tuple structure as suggested above.

(*) The reason being that today's API expose event filtering by equality match. If we plan to introduce a more complex event query language with richer predicates (e.g. gt, lt, etc.) I could see an observer filtering by some size criteria. But that's not the state of things today, so indexing this field is a waste. FWIW, the Eth APIs in Lotus will not be able to handle these events anyway, so if we lean on Filecoin-specific APIs and plan to enhance those as per the above, I'd be fine with making the piece size indexed in anticipation.

[aarshkshah1992]

@raulk Agreed and addressed in #905.

[Fatman13]

Any projection / estimation on the increase of gas for each messages?

[aarshkshah1992]

The event emissions gas costs are trivial.
Here they are:

Note: All of the below mentioned gas costs includes syscall costs as well.

Verif Reg Actor

verifier-balance event

22499 units of gas (i.e. 22499000 **_milligas_**) per event

allocation event

23898 units of gas (i.e. 23898000 **_milligas_**) per allocation

Similar for the other events

Market Actor

deal-published

23966 units of gas (i.e. 23966000 **_milligas_**) per published deal

Similar for other events

Miner Actor

sector-precomitted event

20559 units of gas (i.e. 20559000 **_milligas_**) per precomitted sector

sector-updated event

**With one piece in the sector:**

27835 units of gas (i.e. 27835000 milligas) per updated sector


**With two pieces in the sector:**

32487 units of gas (i.e. 32487000) per updated sector

**_So, the additional marginal per piece cost here is ~4652 units of gas (i.e. 4652000 **_milligas_**)._**

sector-activated event

**With one piece in the sector:**

27870 units of gas per activated sector

[aarshkshah1992]

To put this in perspective:

• A single FVM syscall costs 14000 units of gas
• A single call to verify a replicate update proof costs 36316136 units of gas.

[anorth]

Just to clarify the relative impact, for replica update with a single piece, 27K / 36316K gives an increase of 0.00077 (0.077%).

[aarshkshah1992]

For sector activation with a single piece, i.e. for the ProveCommitSectors3 method,

Total cost of method=57,117,694 gas whereas cost of emitting the sector activation event = 27870 gas i.e. cost of event emission is
0.048%

Span[1-Call(103->f0106::34), self: {sum=57,117,694, OnBlockLink=23,190,303, wasm_exec=16,413,218, OnBlockOpenBase=10,888,920, OnSyscall=3,108,000, OnGetRandomness=1,519,375, OnActorUpdate=475,000, wasm_memory_init=471,860, OnComputeUnsealedSectorCid=394,588, OnScanIpldLinks=222,705, OnBlockOpen=167,470, OnMethodInvocation=75,000, OnActorEvent=69,350, wasm_memory_grow=52,429, OnBlockCreate=42,610, OnVerifySeal=10,000, OnBlockRead=6,898, OnHashing=5,170, OnChainReturnValue=3,900, OnActorGetRoot=600, OnActorSetRoot=300, OnGetActorCodeCid=0, OnNetworkContext=0, OnGetBuiltinActorType=0, OnMessageContext=0, OnSelfBalance=0, OnBlockStat=0}, total: {sum=78,894,883, OnBlockLink=33,419,527, wasm_exec=19,416,128, OnBlockOpenBase=14,080,500, OnSyscall=5,082,000, wasm_memory_init=3,145,728, OnGetRandomness=1,519,375, OnMethodInvocation=525,000, OnActorUpdate=475,000, OnComputeUnsealedSectorCid=394,588, OnScanIpldLinks=253,270, wasm_memory_grow=209,716, OnBlockOpen=185,230, OnActorEvent=98,786, OnBlockCreate=56,620, OnVerifySeal=10,000, OnHashing=7,857, OnBlockRead=7,760, OnChainReturnValue=3,900, OnActorGetRoot=2,400, OnActorSetRoot=1,500, OnSelfBalance=0, OnNetworkContext=0, OnGetActorCodeCid=0, OnBlockStat=0, OnGetBuiltinActorType=0, OnReturnValue=0, OnMessageContext=0}]

[aarshkshah1992]

For the Market Actor PublishStorageDeals method,

cost of method = 38,146,687 gas
cost of a publishing a single deal = 23966 gas so 0.06%

[f8-ptrk]

much love for this. i think events for build in / native actors are a great idea

[aarshkshah1992]

Adding some comments from @jennijuju on https://github.com/filecoin-project/FIPs/pull/872/files here for discussion:

1. The data-cap Allocation event should include the amount of datacap allocated and the piece cid of the data set to make the event more useful to FIL+bots and data explorers.

2. The datacap Allocation claimed event should include the amount of claimed allocation for similar reasons as above.

3. The Sector Activation event should include a has-data boolean. @jennijuju -> Please can you elaborate on what this means ?

[aarshkshah1992]

@jennijuju All the above proposed changes makes sense to me and have been addressed in #905.

[anorth]

I don't think we should add anything to the datacap allocation events. Please see the first comment thread on this topic and the currently-standing decision to include only minimal information in events (reducing the mandatory costs paid by parties who don't want this information). Event fields are not the sum total of information available to clients – they are only the pointers to information.

The datacap allocation size and data CID are available in chain state. An interested party can read from there instead of requiring all validating nodes in the network to pointlessly process it for them. Supplying the client/provider in the event is enough for most individual parties to filter the event stream down to the small set they may be interested in.

I don't think has-data is doing anything. How do you define CC sector? If you mean that it has no pieces, that can be detected by the absence of piece CIDs in the events. If you mean that it has an unsealed CID that guarantees zero data, that can be detected by inspecting the unsealed CID in the events. And even if neither of these were to be included in the event payloads, I would still say we should not include this field as a cost to everyone when only a few need it. The zero data weight can also be looked up in chain state after the sector is activated.

[aarshkshah1992]

@anorth Wdym by "The zero data weight can also be looked up in chain state after the sector is activated." ? What is zero data weight ?

[jennijuju]

I don't think has-data is doing anything. How do you define CC sector? If you mean that it has no pieces, that can be detected by the absence of piece CIDs in the events.

if we are including pieces CIDs in the events, which sounds like we are - then I agree!

The zero data weight can also be looked up in chain state after the sector is activated.

@aarshkshah1992 https://github.com/filecoin-project/builtin-actors/blob/f8916da127502cb2dd24651466cd89a2ffbb1f38/actors/miner/src/types.rs#L345 is stored and queryable onchain.

[aarshkshah1992]

@jennijuju Yes, we are including pieces in the events. Please see latest FIP draft.

This is based on #754 (comment).

[aarshkshah1992]

@anorth Do we need the piece-cid/piece-size AND unsealed_cid in BOTH the sector activation and sector updated(Snapdeals) events or only on the sector activation event ?

[jennijuju]

what use case will consume unsealed cid, out of curiosity?

[aarshkshah1992]

@jennijuju See @anorth 's comment here:

#754 (comment)

Basically, we don't store it any where and so it can't be looked up state. So, dosen't hurt to include it on the event payload in case tooling on aggregators/indexers need it.

[jennijuju]

I see - yah makes sense, makes up for https://github.com/filecoin-project/FIPs/pull/819/files

[anorth]

Unfortunately in both. Sector activation is really sector-activation-and-data-commitment-at-once. If we separate these actions as described here, then there will be no pieces in initial sector activation. I.e. definitely needed for replica update as the primary place, and unfortunately also needed for sector activation.

[aarshkshah1992]

This is addressed by #907

[aarshkshah1992]

@rvagg has a comment on the FIP we should discuss

#872 (comment)

I'm pretty sure we don't want to introduce "CBOR" (0x51) to the chain, I don't believe we use that anywhere at the 
moment and it would be a shame to add that to the mix. I think what we want here is "DAG-CBOR" (0x71).

The two problems with just plain CBOR are:

It's not strictly defined in any of our specs, we basically lean on the upstream CBOR specification which brings 
all sorts of wild additions (simple types, tagged extensions, lots of other things that are not so friendly to a 
content addressed and distributed world) and non-deterministic encoding forms.
It doesn't materialise links (CIDs) and a generic "CBOR" encoder typically will reject them, even though we 
managed to reserve the tag in the upstream tag registry.
Also since 0x51 is a rarely used codec in our stack, applications that consume this data will often not even have a 
codec registered to decode it, thereby adding an additional (tho minor) burden for consuming or validating this data.

Should we be using DAG-CBOR over plain CBOR here @Stebalien @anorth ?

[Stebalien]

We already did introduce CBOR to the chain in FIP0071. Well, we did at least for contract-to-contract calls, although I guess it's never actually recorded on-chain.

In this case:

It doesn't materialise links (CIDs) and a generic "CBOR" encoder typically will reject them, even though we
managed to reserve the tag in the upstream tag registry.

Most CBOR decoders/encoders will simply preserve tags as-is, or ignore them.

It's not strictly defined in any of our specs, we basically lean on the upstream CBOR specification which brings
all sorts of wild additions (simple types, tagged extensions, lots of other things that are not so friendly to a
content addressed and distributed world) and non-deterministic encoding forms.

We're not performing any validation here anyways. I'd prefer to use CBOR instead of DagCBOR where possible as it makes fewer promises.

[rvagg]

I was given some additional context via DM that explains all of this that I thought was super helpful and worth sharing for anyone else in the dark: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0071.md#codec-dagcbor - essentially we're using codecs (CBOR vs DAG-CBOR) to determine the amount of validation we do, and therefore cost. And in the case of events, we don't have quite the same requirements so we opt for cheaper. We also use CBOR as a way to terminate graphs, even if CIDs appear in the block we don't traverse so don't need to worry about reachability.

[jennijuju]

Another thing I think would be nice to be captured in the FIP is, if in the future, some actor events' payload needs to be updated, how would the client (event consumers) integrate them?

[jennijuju]

(it might not be strictly necessary for this FIP, tho providing some integration guidance could be nice!

[aarshkshah1992]

@jennijuju I think we can do this as part of an additional doc somewhere as I am not sure we need to put it on the FIP. Is there a good place to add documentation such as this ?

[beng-starboard]

Starboard enthusiastically supports an events mechanism for built-in actors such as the one proposed in FIP-0083.

Our biggest challenge in providing reliable and accurate analytics for the Filecoin ecosystem is that the data that we work with is often provisioned in terms of state transitions. It can be rather tricky to analyse things such as market deal state, where there is no direct information about what the before or after states even are. After implementation of FIP0060, we can currently only definitively tell if a deal is terminated up to the frequency of the cron job, currently 30 days – clearly not ideal.

An event mechanism would circumvent this limitation very efficiently and help Starboard to provision precise and unambiguous analytics for the community.

[bajtos]

Hello from a potential consumer of the new actor events 👋🏻

In SPARK, we are building a network of checker nodes to verify whether data stored in Filecoin storage deals can be retrieved.

For example, FIL+ LDN requires that stored data should be readily retrievable on the network and this can be regularly verified (though the use of manual or automated verification that includes retrieving data from various miners over the course of the DataCap allocation timeframe).

As the first step, a checker node needs to pick a storage deal that is valid and was created by one of the clients with FIL+ LDN allocation. This is very difficult to implement in a decentralised and trustless way.

• pick a valid deal: AFAIK there are two ways how to query the set of all valid storage deals: call the StateMarketDeals API to obtain ~23GB of data or traverse the IPLD AMT structure holding all deals by repeatedly calling the ChainReadObj API. Neither is particularly easy to implement.
• check if the client has FIL+ LDN allocation: I haven't started to look into this, but I think the problem and a potential solution will be similar to querying valid deals.

I am hoping that the new Actor events will make it easier to maintain an off-chain database of all valid deals.

After reading the current proposal, it's unclear to me how an event listener can obtain the full Deal Proposal data based on the payload of a received Market Actor event.

Quoting from https://github.com/filecoin-project/FIPs/blob/580e7ca37098bd4084715d360f844f595748a62c/FIPS/fip-0083.md#deal-activated:

The event payload is defined as:

flags	key	value
Index Key + Value	“$type”	"deal-activated" (string)
Index Key + Value	“id”	<DEAL_ID> (int)
Index Key + Value	"client"	<STORAGE_CLIENT_ACTOR_ID> (int)
Index Key + Value	"provider"	<STORAGE_PROVIDER_ACTOR_ID> (int)

Clearly, the pair (client, provider) is insufficient to identify a deal uniquely.

Does the int value in <DEAL_ID> provide a reference we can use to obtain more data about the deal?

For SPARK, we need to obtain the full Deal Proposal structure - see market.DealProposal in go-state-types.

How can we achieve that?

Is our use case a valid one for actor events, or should we look for different ways how to achieve what we need?

An idea for a solution that would be easy to use for us: What if DEAL_ID was a CID for the DealProposal and/or DealProposal+DealState structure that's already used in the current Market Actor state and event listeners could call an API like ChainReadObj to resolve DEAL CID to deal proposal + state data.

[anorth]

I am hoping that the new Actor events will make it easier to maintain an off-chain database of all valid deals.

They may, but I would view them as an aid to efficient processing rather than a complete solution. It's a non-goal to represent every state transition faithfully in events such that the state could be reconstructed from them. The chain state is the source of truth and inspecting it is the fundamental way to determine what it is. You've noted that the current client access methods available to you are not particularly easy to build on, so maybe something better could be built, but they're doing essentially the right thing.

Does the int value in <DEAL_ID> provide a reference we can use to obtain more data about the deal?

Yes, look up the deal proposal and state in the chain state with this identifier. There is probably a client method to do this.

[anorth]

Moving a discussion from code review filecoin-project/builtin-actors#1491 (comment).

@aarshkshah1992's first attempt at including the piece information in sector activation events for the existing pre-FIP-0076 activation methods involved calling to the market actor to look up the deals and compute piece information from them. I do not think the cost and complexity of making a new call to the market actor to get this information is justifiable.

These methods already call BatchActivateDeals at the market actor once to activate the deals, and get some information back. This info does include the piece CIDs for verified deals, but not for unverified ones. So it's not sufficient to satisfy the events.

The BatchActivateDeals method also supports partial success: it can fail to activate some deals. It fails on a grouped-by-sector basis, and doesn't return any deal information for the failures. If the miner actor will fail to activate the sector if the deal activation fails, then this lack of information is probably ok. I think the pre-FIP-0076 methods both do this.

There's no problem for the FIP-0076 activation methods because the piece information is explicit in the method parameters.

I see two viable options:

1. Alter the BatchActivateDealsResult type to include the CID/size of all deals activated, and plumb that through to the event building.
2. Don't emit any pieces for sectors activated using legacy methods.

Option 2. is definitely simpler! I'm a bit averse to going out of our way to do work to enable new functionality for legacy methods. The motivation for these events in the first place was FIP-0067, which will deprecate the legacy methods. But complete deprecation may take some time and I can see the value in uniform support for the functionality.

[aarshkshah1992]

@anorth I think keeping the event payloads uniform for both legacy and new sector activation/update methods makes sense from a UX perspective.

I've implemented Option #1 in filecoin-project/builtin-actors@aef0fdd. Please can you review ?

[anorth]

Moving discussion initiated by PR #955 which proposes adding piece CID and size to verified registry claim event. Read that first.

My summary of the motivation is: to remove the need for state inspection at the time of the claim event to read out the detailed piece information, at the cost (gas) of slightly larger events when claiming.

I think it unlikely that an attempt to remove the need for state inspection is likely to succeed generally, except in narrow cases. There will be more questions asked of the data that require reading state to fetch some other field not contained in the event. Even the hypothetical questions posed by the PR can't properly be answered without reading out the claim sector ID and joining claim information with sectors (to see if they're still live). So here is an argument in similar form for including the sector ID, and the same might be made for term, and where does it stop?

To repeat an observation I made above:

Adding fields beyond the bare minimum gets into very hard-to-define measures of usefulness. Many parties will not care about at least some of the fields, or need to perform a lookup in any case. Any subset of fields is optimised only for a client that wants exactly that set. Everyone pays a cost for including too many fields, but there's nearly zero marginal cost for each additional field that needs to be looked up, after the first.

On thing that is new since the beginning of this discussion is that we have quantified the gas cost. Built-in actor methods tend to be doing a lot, so the cost of events is very small as a proportion. Perhaps the minimalist approach isn't right here, and we should just include all the near-to-hand information with all events? That will add bloat to chain size, etc, but if (big if) events are priced correctly this is in theory fine and limited by gas market dynamics.

The existing design approach here (and in many places) is to make things like off-chain analysis possible, but not pay more chain validation costs to make them easy. The ecosystem should only need two or three parties to do the complicated state inspection and produce data for other parties to consume. I acknowledge that there might be some cases, including this one, where adding a small bit of work to the thousands of chain validators is globally more efficient than a couple of parties performing a much more complicated task given less structured data, but analysing these costs as protocol designers isn't feasible.

So:

• I could be convinced that we should just add all the things to all built-in events, that minimalism isn't the right approach here given the relatively low gas costs. But that would entail a larger change to schemas to get everything in up front.
• I'm not close enough to the parties that want piece cid/sizes (but nothing else) in claim events to judge the legitimacy of this need. I won't actively oppose this proposal if it has good support, but am uncomfortable with the pick-and-choose nature. It seems like the thin end of a wedge.

[bajtos]

Hello from the Filecoin Station & Spark team!

We are currently using StateMarketDeals JSON snapshots to find all FIL+ LDN deals with a CID-like Label. We consider these deals as publicly retrievable (see FIL+ LDN rules). We use the data from StateMarketDeals snapshots to build a list of (payloadCid, minerId) pairs that serve as the source of tasks - retrieval checks to perform. See https://github.com/filecoin-station/fil-deal-ingester/tree/main

We would love to find a better & less centralised way for sampling retrievable deals, and we also want to support DDO deals (eventually).

It would be awesome if the new design enabled us to run a very light node listening to on-chain events and synchronising only the state we need for our deal sampling.

[bajtos]

Clarifications:

• We are only interested in FIL+ LDN deals that are currently active.
• We are reading the following DealProposal fields:
  • Label as "payload CID"
  • Provider as "miner ID"
  • EndEpoch to find the deal expiration date

[davidgasquez]

Hey folks! Super interesting discussion.

From my use case (chain data analytics) I'm also relying on the StateMarketDeals JSON provided by Gliff. Even if I have to indeed trust Gliff in this case the approach is simple and doesn't require me running any extra infrastructure.

Ideally, post DDO, I'd love to still be able to derive the state without having to run a node and switch to a JSON-RPC endpoint. I don't have the full context but I'm thinking about a way to get historicall events from the JSON RPC.

That way, interested users could send periodically run requests asking for the new events since their last one and store in their infra. I'm sure there might be issues running something like this for full nodes with all the history (e.g: requesting all the events from epoch 0 to 3000000).

[jennijuju]

I could be convinced that we should just add all the things to all built-in events, that minimalism isn't the right approach here given the relatively low gas costs.

👍

I'm not close enough to the parties that want piece cid/sizes (but nothing else) in claim events to judge the legitimacy of this need.

Currently, like Rod mentioned most of toolings are depend on the StateMarketDeal dump, which returns a json object of the market actor state. Some of them will use the deal proposoal dump as well. We tried to convience toolings to migrate to inspect verifreg & datacap actor since FIP0045, however it wasn't worth the hassle as info was all captured in f05. DDO is obviously changing this.

Tools like https://datacapstats.io/storage-providers & https://datacapstats.io/clients needs SP ID, client ID, notary, datacap terms, deal terms and so on, in addition to the piece info.

the "singular paths to ... observability needs" is state inspection

Would've agreed but DDO no longer stores all the information in the state. Toolings should be able to build a system that is adaptive to protocol evolvement without an architecture redesign all the time - establishing a pathway of combining state + events is quite future -proven imho. While i think rod's vision to enable events to be the one source of info is very nice, but unfrotunately i feel like it might be to optimistic, especailly for nodes who dont have all historical state - it will be easier for them to backfill the DB once using the latest state once and using events to update the future state changes. However, we should minimize the ongoing effort tooling needs to take in place, for example, if we do not add the info as rod suggested, for the ecosystem to adapt to DDO

• API service providers needs to add new EXPENSIVE calls and dumps for GetAllClaims and GetAllAllocations. (We have no API service provider indicated interest in supporting this yet)
• API service providers needs to enable event system, and enable GetActorEvent & SubscibeEvent.
• Tooling builders needs to get regular dumps of StateMarketDeals, AllClaims, AllAllocations, Events to build their full system.
  • This leads to most dashboards to not able to provide real-time insights into the network, given the operations are expensive, most of. them are only updating theh system once a day. (primary b/c api service providers are also only providing the dump once a day)

These situation can be improved with minimal cost on protocol level by exposing a bit more info in the actor events.

[willscott]

this may be tangential, but these tools also need to be able to link source and destination for transfers that trigger the verifier_balance event. In particular, which verified client has been given a datacap balance by a verifier? - since the current event is just telling us that a balance has reduced on the verifier, we can't easily get the link of 'verifier A gave datacap to client B'.

[smooth-operator]

Hey folks!

Hello from datacapstats.io! We are investigating using events for fetching all the necessary data to track datacap flow.
We need to track datacap allowances from RKH to verifiers, from verifiers to verified clients and from verified clients to storage providers.

The problem is that for the first 2 paths the only related event is verifier_balance and that doesn't have any information about which operation happened.

Is it posible to add 2 new events to track these 2 flows? Something like (verifier_received_datacap, verifierID, amount) and (client_received_datacap, clientId, verifierID, amount) ?

[anorth]

It's too late for this FIP, but we can probably add something to help here in a future one. This proposal didn't add any events to the datacap token actor, but we should probably extend the FRC-0046 token specification with events similar to ERC-20. cc @rvagg

[smooth-operator]

Got it. But wouldn't it make more sense to add these events in the verified registry actor? I mean, the verifier datacap balance is stored there, and I don't know if we have access to the verifier that's doing the minting in the datacap token actor.

[rvagg]

@anorth would we emulate Ethereum style event logs in the datacap actor for that so they show up as ERC-20 standard format and parsable by standard Ethereum tooling? Or would we give ourselves latitude to come up with our own informative structure beyond ERC-20 and maybe not even use the Ethereum log format but our own CBOR-based ones like builtin actor events?

Plain ERC-20 events seems do-able, although, while working through what I think that means, I suspect it might not be informative enough to add any real value beyond just doing it in the verifreg actor.

We only have a Transfer event to work with and it just ends up being one of:

• "From" 0, "To" the client being from "AddVerifiedClient", where you could at least match up the client from the new verifier-balance event (Mint)
• "From" verifreg, "To" the client, for "RemoveExpiredAllocations" (Transfer)
• "From" verifreg, "To" 0 (I think) is the conversion of an allocation to a claim, or extending a claim with datacap (Burn)
• "From" the client (I think), "To" 0 for "RemoveVerifiedClient", but we don't get the two verifiers (Destroy/Burn)
• "From" the client, "To" verifreg, I believe is the only other case which is creating an allocation (Transfer).

The two big losses of information are the hand-off between verifreg and datacap, the AddVerifiedClient and RemoveVerifiedClient where we don't send verifier information over to datacap.

How useful would this exercise be beyond coming up with an FRC-46 event spec for general use? Are we expecting datacap actor to be more flexible and have more sophisticated flows into the future?

[anorth]

Would we emulate Ethereum style event logs in the datacap actor for that so they show up as ERC-20 standard format and parsable by standard Ethereum tooling? Or would we give ourselves latitude to come up with our own informative structure beyond ERC-20

I don't know. My first instinct would indeed be to attempt something well suited to Filecoin, and there is plenty of room to do better than ERC20.

Everything on the FVM must eventually ground out in the FVM syscalls, so use the CBOR event structure. From FIP-0054 it looks like there's simply a convention for translating less-rich EVM-type events to native ones via some static values ("t1" etc) used as keys. This must be then reinterpreted by clients to present an Ethereum API to tooling. Given that, we can probably develop a more detailed event schema for FRC-0046, but clients can again dumb it down to the ERC-20 schema on request. Specifically using the "t1" etc keys in such events just so that off-chain tooling can use the same convention already developed would seem like a sad outcome to me. But we should consult with someone closer to the F/EVM development.

Are we expecting datacap actor to be more flexible and have more sophisticated flows into the future?

I expect the datacap token to be the target of many on- and off-chain programmed workflows in the future, but am not expecting the token actor itself to gain any more functionality than it currently has (with 🤞).

[rvagg]

After receiving additional feedback on the information currently available in events, including from a raised awareness of the implications of DDO in network version 22 on observability concerns as it inches toward us, we're back again with a new proposal that we're hoping to get approved and shipped with network version 22. #964.

Given the tight time constraints and concerns about stability, we've attempted to craft a line between "near-to-hand" information (i.e. low-risk, minimal code changes) and "maximally useful" when considering the requirements we are hearing from parties concerned about a DDO world.

A lot of the feedback we have received is related to the verified registry and the difficulties in tracking claims, pieces, SPs and clients and their relationships. The events, as they are currently structured, require reactive state inspection to provide enough context to make sense of them, such as the example of claims outlined in the previous attempt at expanding events in #955.

[willscott]

From my read of the update in #964, the additional field in Verifier Balance Updated seems to address the need that @smooth-operator raised about linking assignment of datacap to clients

[anorth]

Regarding the proposal in #955 to add client to the verifier-balance event.

I really don't like this. What's a client doing in an event about verifier balance? How will this extend to future methods that might, e.g. batch distributions of data cap to clients? However I can see that it's solving a linkage problem that @smooth-operator and @willscott mention.

This is trying the squeeze an extra field in to make a "small" change that should really be a larger one. Changes to a verifiers balance are one thing, allocating data cap to a client is another thing. They should have separate events. A better design here is probably:

• A new allocate-datacap event with (verifier, client, amount)
• A matching remove-datacap event for the removal operation
• Leave verifier-balance alone

The AddVerifiedClient operation would then fire two events. (A hypothetical batched one would fire one event per client, plus one for the aggregated delta to the verifiers balance). The event should correspond to logical state changes, not the method APIs that present the various paths into those state changes.

This is a larger change that may not be reasonable to squeeze into a post-last-call FIP. We could do it in a follow-up FIP with time to think it through thoroughly. Things have been getting by without this up until now. I totally see the value in improving it, but object to making a change that isn't the final form we'd choose after a thorough design discussion.

[willscott]

I think technically it's very painful to reduce apis / access to chain state 2 weeks before a network upgrade. Given that downstream builders are expecting to use and have been pointed to events here as the path for getting information about flow of datacap.

[rvagg]

Wow, ok that's not the direction I imagined this going. Where would that leave you @willscott if we removed them entirely? Back to periodic state inspection? If we can't get consensus to make an additive change to the validator events but left it as it is, does it provide any utility in its current form, without relationship to client?

[anorth]

@willscott but what has been removed in this case? Datacap is all is chain state.

Edit: oh, maybe you mean removed from a design, rather than removed from actually implemented protocol.

[rvagg]

My technical recommendation is not to ship a client field in the verifier balance event, but to remove the event entirely.

I don't think I could support a removal at this stage. Event removal seems like a far more disruptive change than some of the additive changes being proposed here that are being pushed to a future FIP. I understand however that it may not be optimal, or useful, but if we can't make it useful now then we may just have to write it off as a historical artefact by nv23.

My preference would be to make it useful now if we can, hence the proposal. I'll have a look at the suggestions above for adjusting what I have now, although I agree that more time for consideration of those would be ideal. I think there are two factors that come in to play here:

• Events should be easier to change than other protocol changes: they're gas-cheap (ish), they only impact consensus inasmuch as they need to sum up to a matching merkle root for a given message and we only have one implementation today that produces them. Ideally we don't keep breaking stuff and treat their schema as somewhat fixed (ideally just being additive over time if change is needed) so users can have a high degree of trust in their reliance on them.
• The audience that would have much interest, concern, or even expertise on some of these (particularly the verifreg changes) is quite small, and can probably be counted on one hand, so I doubt it needs long consultation.

[anorth]

While I technically think we should remove the event, I get that in practise this isn't going to happen as a post-acceptance change to FIP-0083, because there are clearly community concerns with that.

[anorth]

Regarding #955 add previous values for overwritten state (verifier balance, claim term max)

This is a tradeoff that I think is worth discussing more, I'm not sure. The events as a collection would already have complete information without these previous values. The previous value is whatever the new value was from the previous event. No state inspection is required to find the previous value. Including previous values is a further accomodation to consumers to save them from even remembering/indexing past events. Convenient for the few clients that will use each particular field, yes, but is it worth the gas/code/testing costs? I think this might be taking the convenience too far.

[anorth]

A similar discussion goes for the various removal events: should they include all the fields that were already included in the creation/addition event? Event data as a whole is complete without it.

[rvagg]

Also worth noting that with a draft implementation, it turns out there is an additional state load to get the verifier previous balance on the RemoveVerifier case, which is unfortunate and the kind of complication we were trying to skirt around.

Previous values are most useful on the change of existing state events which there are few of, but they're not critical. A consumer will just need to build a stateful map of values they are concerned about, both initially and ongoing, and make sure they don't miss any events (we have some API work to do on reliability of delivery too). My preference is to have full change information, it makes observing a stateful system much more straightforward, but this isn't a strong conviction and I could drop these for the sake of getting merge.

The verifier_balance one is interesting because the event itself feels overloaded: there's a change of value, but then there's also the init and destroy forms. Perhaps it would have been better to isolate change-existing events to something separate, like is done for claim_updated. A bit late for this batch unfortunately but something to pay attention to.

[anorth]

Except for verifier-balance (see below) I don't have a strong objection to previous values. Just think we should think about it. They are happily something that it's quite easy to add later if we run out of time for that thinking now.

[anorth]

Regarding #955 add expiration to sector activation/update

I think we should avoid adding this if possible. Expiration is one part of sector lifecycle that I expect to change significantly in the future. The concept of expiration could also be easily misunderstood by consumers.

• Expiration refers to the minimum epoch which the protocol requires a sector to exist but not the maximum. A consumer could easily miss this and assume a sector will be gone after its expiration.
• If we're talking about true sector exploration, then the fields added here are insufficient to fully track that. We would need to add events in other places that a sector's exploration may be updated, such as the ExtendSectorExpiration method.
• When we implement re-snap, expiration may be removed, or renamed/repurposed to refer to the committed data rather than the sector itself. Which to consumers want it to mean today? The candidate design for this is sketched here.

[rvagg]

This sounds reasonable to me, and these fields aren't the high impact parts of the proposal. They mostly come from wanting to give some additional information on sectors that's easily accessible, and SectorOnChainInfo which has the highest value information, is not easily accessible, so we're not left with much else other than expiration info.

I suspect could be dropped for now unless someone wants to speak up and make a case for them and we can revisit other sector information later when we can afford the refactor.