Events

[armaniferrante]

Summary

Adds an API for emitting and subscribing to events.

Example

• Defining an event in a Rust program

#[event]
pub struct MyEvent {
  data: u64,
  #[index]
  label: String,
}

• Emitting an event from a Rust program:

emit!(MyEvent {
    data: 5,
    label: "hello".to_string(),
});

• Subscribing to an event from JavaScript:

listener = program.addEventListener("MyEvent", (event, slot) => {
  // Do something with the event.
});

• Subscribing to an event from a Rust client

program.on(|ctx: &EventContext, event: MyEvent| {
  // Do something with the event.
});

Note that the #[index] attribute is used as a marker to add to the IDL. No indexing is actually done by solana validators and it's up to a client consuming the events to perform any indexing.

Open questions

I'm not sure how event ordering w.r.t. slot number is handled by the Solana logsSubscribe API. Ideally, this API would provide exactly once semantics, but it may be possible that events show up out of order or appear more than once. In this case, either the anchor client, or user of the client, will need to add additional logic to ensure applications behave as expected.

[armaniferrante]

This depends on the changes in solana-labs/solana#16045.

[armaniferrante]

This seems to be required due to @solana/web3.js 1.0.0, though I have not yet confirmed with a minimal example.