Add contractevent macro and event support to contract spec

[leighmcculloch]

What

Add contractevent macro for defining events, and event support to contract spec.

In it's most basic form, as follows, where an automatic prefix topic based on the name will be published, with any topic fields appended to the topic list, and any other fields emitted as map entries in a map:

    #[contractevent]
    #[derive(Clone, Default, Debug, Eq, PartialEq)]
    pub struct MyEvent {
        #[topic]
        pub my_topic: u32,
        pub my_event_data: u32,
        pub more_event_data: u64,
    }

But also supporting more advanced customisable forms, where prefix topics can be overriden and a max of two provided, and where the data section can be defined as either being a vec or a single-value instead.

Why

The contractevent macro will achieve a couple things for events.

It will allow developers to define the event as a type, in a similar way that they can define an event in Solidity contracts. Defining it as a type makes it easier to reuse the event, and to define the types safely and be clear about what types within the event are being published.

It will provide a foundation that the Rust SDK can use to include in the contract interface (spec) an entry for the event. That entry can then be used by downstream systems to bring more meaning to the raw event data that is visible in transaction / ledger close meta. For an example of what that looks like, see https://github.com/orgs/stellar/discussions/1724#discussioncomment-13118291.

The advanced customisations are a necessity to be able to make the events and the event schema describe existing contract events. The network already has a variety of events and some contracts use two fields as fixed prefix topics, such as the Soroswap contracts. Some use vecs for the data section, and even a single value such as an amount: i128, such as the Stellar Asset Contract.

Close #1097

Docs for the contractevent attribute macro

Generates conversions from the struct into a published event.

Fields of the struct become topics and data parameters in the published event.

Includes the event in the contract spec so that clients can generate bindings for the type and downstream systems can understand the meaning of the event.

Examples

Basic Contract Event

Defining a basic contract event.

The event will have a single fixed prefix topic matching the name of the struct in lower snake case. The fixed prefix topic will appear before any topics listed as fields. In the example below, the topics for the event will be:

• "my_event"
• u32 value from the my_topic field

The event’s data will be a Map, containing a key-value pair for each field with the key being the name as a Symbol. In the example below, the data for the event will be:

• key: my_event_data => val: u32
• key: more_event_data => val: u64

    #![no_std]
    use soroban_sdk::contractevent;
    
    // Define the event using the `contractevent` attribute macro.
    #[contractevent]
    #[derive(Clone, Default, Debug, Eq, PartialEq)]
    pub struct MyEvent {
        // Mark fields as topics, for the value to be included in the events topic list so
        // that downstream systems know to index it.
        #[topic]
        pub my_topic: u32,
        // Fields not marked as topics will appear in the events data section.
        pub my_event_data: u32,
        pub more_event_data: u64,
    }

Prefix Topics

Defining a contract event with a custom set of fixed prefix topics.

The prefix topic list can be set to another value. In the example below, the topics for the event will be:

• "my_contract"
• "an_event"
• u32 value from the my_topic field

    #![no_std]
    use soroban_sdk::contractevent;
    
    // Define the event using the `contractevent` attribute macro.
    #[contractevent(topics = ["my_contract", "an_event"])]
    #[derive(Clone, Default, Debug, Eq, PartialEq)]
    pub struct MyEvent {
        // Mark fields as topics, for the value to be included in the events topic list so
        // that downstream systems know to index it.
        #[topic]
        pub my_topic: u32,
        // Fields not marked as topics will appear in the events data section.
        pub my_event_data: u32,
        pub more_event_data: u64,
    }

Data Format

Defining a contract event with a different data format. The data format of the event is by default a map, but can alternatively be defined as a vec or single-value.

Vec

In the example below, the data for the event will be a Vec containing:

• u32
• u64

    #![no_std]
    use soroban_sdk::contractevent;
    
    // Define the event using the `contractevent` attribute macro.
    #[contractevent(data_format = "vec")]
    #[derive(Clone, Default, Debug, Eq, PartialEq)]
    pub struct MyEvent {
        // Mark fields as topics, for the value to be included in the events topic list so
        // that downstream systems know to index it.
        #[topic]
        pub my_topic: u32,
        // Fields not marked as topics will appear in the events data section.
        pub my_event_data: u32,
        pub more_event_data: u64,
    }

Single Value

In the example below, the data for the event will be a u32.

When the data format is a single value there must be no more than one data field.

    #![no_std]
    use soroban_sdk::contractevent;
    
    // Define the event using the `contractevent` attribute macro.
    #[contractevent(data_format = "single-value")]
    #[derive(Clone, Default, Debug, Eq, PartialEq)]
    pub struct MyEvent {
        // Mark fields as topics, for the value to be included in the events topic list so
        // that downstream systems know to index it.
        #[topic]
        pub my_topic: u32,
        // Fields not marked as topics will appear in the events data section.
        pub my_event_data: u32,
    }

A Full Example

Defining a contract event, publishing it in a contract, and testing it.

    #![no_std]
    use soroban_sdk::{contract, contractevent, contractimpl, contracttype, symbol_short, Env, Symbol};
    
    // Define the event using the `contractevent` attribute macro.
    #[contractevent]
    #[derive(Clone, Default, Debug, Eq, PartialEq)]
    pub struct Increment {
        // Mark fields as topics, for the value to be included in the events topic list so
        // that downstream systems know to index it.
        #[topic]
        pub change: u32,
        // Fields not marked as topics will appear in the events data section.
        pub count: u32,
    }
    
    #[contracttype]
    #[derive(Clone, Default, Debug, Eq, PartialEq)]
    pub struct State {
        pub count: u32,
        pub last_incr: u32,
    }
    
    #[contract]
    pub struct Contract;
    
    #[contractimpl]
    impl Contract {
        /// Increment increments an internal counter, and returns the value.
        /// Publishes an event about the change in the counter.
        pub fn increment(env: Env, incr: u32) -> u32 {
            // Get the current count.
            let mut state = Self::get_state(env.clone());
    
            // Increment the count.
            state.count += incr;
            state.last_incr = incr;
    
            // Save the count.
            env.storage().persistent().set(&symbol_short!("STATE"), &state);
    
            // Publish an event about the change.
            Increment {
                change: incr,
                count: state.count,
            }.publish(&env);
    
            // Return the count to the caller.
            state.count
        }
    
        /// Return the current state.
        pub fn get_state(env: Env) -> State {
            env.storage().persistent()
                .get(&symbol_short!("STATE"))
                .unwrap_or_else(|| State::default()) // If no value set, assume 0.
        }
    }
    
    #[test]
    fn test() {
        let env = Env::default();
        let contract_id = env.register(Contract, ());
        let client = ContractClient::new(&env, &contract_id);
    
        assert_eq!(client.increment(&1), 1);
        assert_eq!(client.increment(&10), 11);
        assert_eq!(
            client.get_state(),
            State {
                count: 11,
                last_incr: 10,
            },
        );
    }

[leighmcculloch]

TODO:

• What happens if fields are longer than the symbol max length? Will it be a friendly compiler error?
• Do we have a test for no topic? Yes
• Consider adding #[data] on data fields. Decided against

[leighmcculloch]

Yet another alternative way to define topics, which is largely a simplification, although in the default case there is more to do:

Replace this:

    #[contractevent]
    #[derive(Clone, Default, Debug, Eq, PartialEq)]
    pub struct MyEvent {
        #[topic]
        pub my_topic: u32,
        pub my_event_data: u32,
        pub more_event_data: u64,
    }

With:

    #[contractevent(topics = ["my_event"])]
    #[derive(Clone, Default, Debug, Eq, PartialEq)]
    pub struct MyEvent {
        #[topic]
        pub my_topic: u32,
        pub my_event_data: u32,
        pub more_event_data: u64,
    }

In this way there is no "default" behaviour where a topic is inserted with the type name. Topics are always explicitly defined.

[leighmcculloch]

    #[contractevent(topics = ["my_event"])]

I gave this approach a go, but it's not particularly enjoyable to have to type the topics out in the cases where the struct name matches the event name, and it becomes really easy to publish events with no topics which can make it a little harder to filter different types of events. So I'm leaning away from that back to the original solution.

[leighmcculloch]

I got feedback offline about the concept of prefix_topics being unintuitive.

So I've renamed prefix_topics to simply topics.

[leighmcculloch]

I found a bug in how the map variant of events are passed to the host.

[leighmcculloch]

I found a bug in how the map variant of events are passed to the host.

Fixed in 3f977d4.

[leighmcculloch]

I've opened a follow up to this PR that uses the contractevent macro to capture the events for the token (SEP-41) and the Stellar Asset Contract:

• Add contractevent types for tokens and stellar asset contract #1489