github.com/muhammedhassanm/blockchain@v0.0.0-20200120143007-697261defd4d/sawtooth-core-master/docs/source/app_developers_guide/about_events.rst (about)

     1  *********************
     2  About Sawtooth Events
     3  *********************
     4  
     5  Sawtooth events occur when blocks are committed --- that is, the validator
     6  broadcasts events when a commit operation succeeds --- and are not persisted in
     7  state. Each transaction family can define the events that are appropriate for
     8  its business logic.
     9  
    10  An event has three parts:
    11  
    12  * Event type (the name of the event)
    13  * Opaque payload whose structure is defined by the event type
    14  * List of attributes
    15  
    16  An attribute is a key-value pair that contains transparent metadata about the
    17  event. The key is the name of the attribute, and the value is the specific
    18  contents for that key. The same key can be used for multiple attributes in an
    19  event.
    20  
    21  It is important to define meaningful event attributes, so that the attributes
    22  can be used to filter event subscriptions. Note that although attributes are not
    23  required, an event filter cannot operate on an event without attributes. For
    24  more information, see :doc:`about_event_subscriptions`.
    25  
    26  Events are represented with the following protobuf message:
    27  
    28  .. code-block:: protobuf
    29  
    30     message Event {
    31       // Used to subscribe to events and servers as a hint for how to deserialize
    32       // event_data and what pairs to expect in attributes.
    33       string event_type = 1;
    34  
    35       // Transparent data defined by the event_type.
    36       message Attribute {
    37         string key = 1;
    38         string value = 2;
    39       }
    40       repeated Attribute attributes = 2;
    41  
    42       // Opaque data defined by the event_type.
    43       bytes  data = 3;
    44     }
    45  
    46  The ``event_type`` field (the name of the event) is used to determine how opaque
    47  (application-specific) data has been serialized and what transparent event
    48  attributes to expect.
    49  
    50  For more information, see
    51  :doc:`/architecture/events_and_transactions_receipts`.
    52  
    53  
    54  Event Namespace
    55  ===============
    56  
    57  By convention, event names use the transaction family as a prefix, such as
    58  ``xo/create`` for a create event from the XO transaction family.
    59  
    60  Core Sawtooth events are prefixed with ``sawtooth/``. The core events are:
    61  
    62    * ``sawtooth/block-commit``
    63  
    64    * ``sawtooth/state-delta``
    65  
    66  sawtooth/block-commit
    67  ---------------------
    68  
    69  A ``sawtooth/block-commit`` event occurs when a block is committed. This event
    70  contains information about the block, such as the block ID, block number, state
    71  root hash, and previous block ID. It has the following structure:
    72  
    73  .. code-block:: protobuf
    74  
    75     Event {
    76       event_type = "sawtooth/block-commit",
    77       attributes = [
    78         Attribute { key = "block_id", value = "abc...123" },
    79         Attribute { key = "block_num", value = "523" },
    80         Attribute { key = "state_root_hash", value = "def...456" },
    81         Attribute { key = "previous_block_id", value = "acf...146" },
    82       ],
    83     }
    84  
    85  sawtooth/state-delta
    86  --------------------
    87  
    88  A ``sawtooth/state-delta`` occurs when a block is committed. This event contains
    89  all state changes that occurred at a given address for that block. This event
    90  has the following structure:
    91  
    92  .. code-block:: python
    93  
    94       Event {
    95         event_type = "sawtooth/state-delta",
    96         attributes = [Attribute { key = "address", value = "abc...def" }],
    97         event_data = <bytes>
    98       }
    99  
   100  Note that the addresses that match the filter are in the attributes. Changed
   101  values are part of the event data.
   102  
   103  
   104  Example: An Application-specific Event
   105  ======================================
   106  
   107  The XO transaction family could define an ``xo/create`` event that is sent when
   108  a game has been created. The following examples show a simple ``xo/create``
   109  event in several languages.
   110  
   111  Python example:
   112  
   113     .. code-block:: python
   114  
   115        context.add_event(
   116            "xo/create", {
   117                'name': name,
   118                'creator': signer_public_key
   119        })
   120  
   121  Go example:
   122  
   123     .. code-block:: go
   124  
   125      attributes := make([]processor.Attribute, 2)
   126      attributes = append(attributes, processor.Attribute{
   127        Key:   "name",
   128        Value: name,
   129      })
   130      attributes = append(attributes, processor.Attribute(
   131        Key:   "creator",
   132        Value: signer_public_key,
   133      })
   134      var empty []byte
   135      context.AddEvent(
   136        "xo/create",
   137        attributes,
   138        empty)
   139  
   140  JavaScript example:
   141  
   142     .. code-block:: javascript
   143  
   144        context.addEvent(
   145          'xo/create',
   146          [['name', name], ['creator', signer_public_key]],
   147          null)
   148  
   149  
   150  Rust example:
   151  
   152     .. code-block:: rust
   153  
   154        context.add_event(
   155          "xo/create".to_string(),
   156          vec![("name".to_string(), name), ("creator".to_string(), signer_public_key)],
   157          vec![].as_slice())
   158  
   159  
   160  .. Licensed under Creative Commons Attribution 4.0 International License
   161  .. https://creativecommons.org/licenses/by/4.0/