Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FIP-0049 (actor events): align with implementation. #581

Merged
merged 27 commits into from
Jan 9, 2023
Merged
Changes from 1 commit
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
2cec4c2
FIP-0049 (actor events): round of editing. Missing gas costs.
raulk Dec 27, 2022
cb88b82
fix nits.
raulk Dec 28, 2022
a3a4467
add a link to DAG-CBOR spec.
raulk Dec 28, 2022
06da825
add access control example.
raulk Dec 28, 2022
744fba1
elaborate on how events are committed on chain.
raulk Dec 28, 2022
2c4e9a6
address nits around flags.
raulk Dec 28, 2022
786201d
update the syscall.
raulk Dec 28, 2022
48e5e66
add test cases.
raulk Dec 28, 2022
742a46a
clarify 'external'.
raulk Dec 28, 2022
9fb21c5
cover fatal errors.
raulk Dec 28, 2022
f99cd75
link to indexing implementation in Lotus.
raulk Dec 28, 2022
a9ba904
paint the shed.
raulk Dec 30, 2022
d195975
another editing pass.
raulk Dec 30, 2022
b4dcba9
restrict values to DAG-CBOR byte strings; add Eth event.
raulk Dec 30, 2022
151d691
do not insert the event AMT into the blockstore.
raulk Dec 30, 2022
c6302d3
specify error situations in emit_event syscall.
raulk Dec 30, 2022
218c219
add Chain commitment section; align with implementation.
raulk Dec 30, 2022
1b370b6
restructure sections.
raulk Dec 30, 2022
0f5dee4
rearchitect gas costs.
raulk Dec 30, 2022
d06fdf1
various edits.
raulk Dec 30, 2022
c547b15
add security considerations.
raulk Dec 30, 2022
05f693f
minor edit for clarity.
raulk Jan 3, 2023
d002339
edits for clarity.
raulk Jan 9, 2023
53bf960
discuss choice of receipt data structure.
raulk Jan 9, 2023
2733c85
remove comment about events for built-in actors.
raulk Jan 9, 2023
9d88dcf
multiple edits.
raulk Jan 9, 2023
38e6aa4
update ToC.
raulk Jan 9, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
restrict values to DAG-CBOR byte strings; add Eth event.
  • Loading branch information
raulk committed Dec 30, 2022

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
commit b4dcba9e038035432372622cbf9700197aa8af87
52 changes: 44 additions & 8 deletions FIPS/fip-0049.md
Original file line number Diff line number Diff line change
@@ -88,20 +88,20 @@ Two main motivations warrant the introduction of actor events at this time.

### New chain types

We introduce a [DAG-CBOR] encoded `StampedEvent` type to represent an actor
event as committed on chain.
We introduce the following data model to represent and commit events on chain.
These objects are DAG-CBOR encoded with tuple encoding.

```rust
/// Represents an event emitted throughout message execution, stamped by the FVM
/// with additional metadata.
/// with additional metadata, and committed on chain.
struct StampedEvent {
/// Carries the actor ID of the emitting actor (stamped by the FVM).
jennijuju marked this conversation as resolved.
Show resolved Hide resolved
emitter: u64,
/// Payload of the event, as emitted by the actor.
event: ActorEvent,
}

/// An event as emitted by the actor.
/// An event as originally emitted by the actor.
struct ActorEvent {
/// The key-value entries that make up the event.
entries: [Entry],
@@ -113,6 +113,7 @@ struct Entry {
/// The key of this entry.
key: String,
/// The value of this entry.
/// Any DAG-CBOR encoded type, but currently restricted to byte strings only (CBOR major type 2).
value: any,
}
```
@@ -121,8 +122,11 @@ Its main constituent is a list of ordered key-value **entries**. This approach
is inspired by structured logging concepts. **Keys** are UTF-8 strings, while
**values** can be any DAG-CBOR encodeable type.

Every **entry** contains a u64 **flags** bitmap, which conveys metadata or hints
about the entry. These are the currently supported flags:
However, this FIP restricts accepted types to byte strings only (CBOR major type
raulk marked this conversation as resolved.
Show resolved Hide resolved
2). A future FIP will loosen this restriction.

Every **entry** contains a **flags** bitmap with underlying type u64, conveying
metadata or hints about the entry. These are the currently supported flags:

| hex | binary | meaning |
|--------|-------------|-------------------------|
@@ -159,8 +163,27 @@ proposals.
The following examples demonstrate how to use these structures in practice.
raulk marked this conversation as resolved.
Show resolved Hide resolved
Payloads are DAG-CBOR encoded types.
raulk marked this conversation as resolved.
Show resolved Hide resolved

_Ethereum-style event_

See FIP-0054 for more information.

```rust
Event {
emitter: 1234,
entries: [
(0x03, "t1", <32-byte array>), // CBOR major type 2
(0x03, "t2", <32-byte array>), // CBOR major type 2
(0x03, "t3", <32-byte array>), // CBOR major type 2
(0x03, "t4", <32-byte array>), // CBOR major type 2
(0x03, "p", <32-byte array>), // CBOR major type 2
],
}
Comment on lines +180 to +189
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These keys are more compact since we'll be charging for bytes indexed, which includes keys.

```

_Fungible token transfer_

**NOTE: value types not supported yet.**
raulk marked this conversation as resolved.
Show resolved Hide resolved

```rust
// type, sender, and receiver indexed by key and value.
Event {
@@ -176,6 +199,8 @@ Event {

_Non-fungible token transfer_

**NOTE: value types not supported yet.**

```rust
// All entries indexed, carrying the event type as a key (transfer).
Event {
@@ -191,6 +216,8 @@ Event {

_Access control_

**NOTE: value types not supported yet.**

```rust
// Compact representation of an "access denied" event, indexing the object id but not its key.
Event {
@@ -204,6 +231,8 @@ Event {

_Multisig approval_

**NOTE: value types not supported yet.**

```rust
// Only type and signers indexed; signer is a variadic entry.
Event {
@@ -301,6 +330,8 @@ Refer to FIP-0054.

## Design Rationale

### Brainstorm and simplification

A large part of the architectural discussion has been documented in issue
[filecoin-project/ref-fvm#728]. Some ideas we considered along the way included:

@@ -317,11 +348,16 @@ further research into is Filecoin light clients and the kinds of proofs that
could endorse queries for events, including inclusion, non-inclusion, and
completeness proofs.

### Data model

In terms of the technical design, we considered making the event payload an
opaque IPLD blob accompanied by some form of a type discriminator. However, that
would require an IDL upfront to interpret the payload. We posit that the
unwrapped data model we've proposed enables straightforward introspection and
comprehension by chain explorers, developer tools, and monitoring tools.
see-through key-value inspired data model we've proposed enables straightforward
introspection and comprehension by chain explorers, developer tools, and
monitoring tools.

### Flags

Concerning the concept of `flags`, we had initially considered a top-level
`indexed` bitmap, but later generalised it to a `flags` field for extensibility.