Contract events =============== Contract events provide a way for contracts to deliver event-like information to external applications. This mechanism allows off-chain applications to react to Tezos contracts execution. Sending events -------------- Contract events can be emitted by invoking the Michelson instruction ``EMIT``. ``EMIT %tag ty`` pops an item of type ``ty`` off the stack and pushes an ``operation`` onto the stack. The type ascription ``ty`` is special since annotations in ``ty`` are preserved and eventually transmitted in the event so that indexers have a choice to present the event body with appropriate labels. Both the ``ty`` type ascription and ``%tag`` are optional. If ``ty`` is absent, this type is inferred from the type of the top element of the stack. If ``%tag`` is absent, no tag is attached to the event. To actually send out the events, most importantly, the produced ``operation``\s must be included in the list of operations, along with ``TRANSFER_TOKEN`` operations for example, that the contract wants to effect. Event ----- Each successful contract execution attaches into the transaction receipt a list of contract events arranged in the order of appearance in the resultant list of operations. There, the events are made ready for consumption by services observing the chain. Example ------- Suppose a contract wants to emit events with the following type: :: or (nat %int) (string %str) Then, this contract may generate an event emission operation with the following instructions. Note that the ``EMIT`` instruction will emit an event with a tag ``notify_client``. In addition, it allows indexers to recognise the two variants as ``int`` and ``str`` and, therefore, be able to present the values with the appropriate variant labels. :: PUSH string "right"; RIGHT nat; EMIT %notify_client (or (nat %int) (string %str)); Retrieving events ----------------- Events successfully emitted can be read off directly from transaction results. This is typically achieved by making JSON RPCs to the block service. It will return a list of operations, each including the event entries with the information above. Here is a sample result from a call, corresponding to the example above. :: { "protocol": "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK", "hash": "opNX59asPwNZGu2kFiHFVJzn7QwtyaExoLtxdZSm3Q3o4jDdSmo", // ... fields elided for brevity "contents": [ { "kind": "transaction", // ... fields elided for brevity "metadata": { // ... fields elided for brevity "internal_operation_results": [ { "kind": "event", // ... fields elided for brevity "source": "KT1M1ynE3YXkM7qLZoMppq6szMbBvxX9yQVL", "nonce": 0, "type": { "prim": "or", "args": [ { "prim": "nat", "annots": [ "%int" ] }, { "prim": "string", "annots": [ "%str" ] } ] }, "tag": "notify_client", "payload": { "prim": "Right", "args": [ { "string": "right" } ] }, "result": { "status": "applied", "consumed_milligas": "1000000" } } ] } } ] } Note that the ``operation`` produced by ``EMIT`` does not constitute a call to any other contract.