github.com/darrenli6/fabric-sdk-example@v0.0.0-20220109053535-94b13b56df8c/proposals/r1/Custom-Events-High-level-specification.md (about)

     1  
     2  @muralisrini and @pmullaney
     3  
     4  ## Introduction
     5  
     6  The events framework supports the ability to emit 2 types of audible events, block and custom/chaincode events (of type ChaincodeEvent defined in events.proto). The basic idea is that clients (event consumers) will register for event types (currently "block" or "chaincode") and in the case of chaincode they may specify additional registration criteria namely chaincodeID and eventname. ChaincodeID indentifies the specific chaincode deployment that the client has interest in seeing events from and eventname is a string that the chaincode developer embeds when invoking the chaincode stub's `SetEvent` API. Invoke transactions are currently the only operations that can emit events and each invoke is limited to one event emitted per transaction. It should be noted that there are no “transient” or “ephemeral” events that are not stored on the ledger. Thus, events are as deterministic as any other transactional data on the block chain. This basic infrastructure can be extended for successful
     7  
     8  ## Tactical design: Use TransactionResult to store events
     9  
    10  Add an Event message to TransactionResult
    11  
    12  ```
    13  / chaincodeEvent - any event emitted by a transaction
    14  type TransactionResult struct {
    15  	Uuid           string          
    16  	Result         []byte
    17  	ErrorCode      uint32
    18  	Error          string
    19  	ChaincodeEvent *ChaincodeEvent
    20  }
    21  ```
    22  Where **ChaincodeEvent** is
    23  
    24  ```
    25  type ChaincodeEvent struct {
    26  	ChaincodeID string
    27  	TxID        string
    28  	EventName   string
    29  	Payload     []byte
    30  }
    31  ```
    32  
    33  Where ChaincodeID is the uuid associated with the chaincode, TxID is the transaction that generated the event, EventName is the name given to the event by the chaincode(see `SetEvent`), and Payload is the payload attached to the event by the chaincode. The fabric does not impose a structure or restriction on the Payload although it is good practice to not make it large in size.
    34  
    35  SetEvent API on chaincode Shim
    36  
    37  ```
    38  func (stub *ChaincodeStub) GetState(key string)
    39  func (stub *ChaincodeStub) PutState(key string, value [\]byte)
    40  func (stub *ChaincodeStub) DelState(key string)
    41  …
    42  …
    43  func (stub *ChaincodeStub) SetEvent(name string, payload []byte)
    44  …
    45  …
    46  ```
    47  
    48  When the transaction is completed, SetEvent will result in the event being added to TransactionResult and commited to ledger. The event will then be posted to all clients registered for that event by the event framework.
    49  
    50  
    51  ##General Event types and their relation to Chaincode Events
    52  
    53  
    54  Events are associated with event types. Clients register interest in the event types they want to receive events of.
    55  Life-cycle of an Event Type is illustrated by a “block” event
    56  
    57  	1. On boot-up peer adds "block" to the supported event types
    58  	2. Clients can register interest in “block” event type with a peer (or multiple peers)
    59  	3. On Block creation Peers post an event to all registered clients
    60  	4. Clients receive the “block” event and process the transactions in the block
    61  
    62  Chaincode events add an additional level of registration filtering. Instead of registering for all events of a given event type, chaincode events allow clients to register for a specific event from a specific chaincode. For this first version, for simplicity, we have not implemented wildcard or regex matching on the eventname but that is planned. More information on this in "Client Interface" below.
    63  
    64  ## Client Interface
    65  
    66  The current interface for client to register and then receive events is a gRPC interface with pb messages defined in protos/events.proto. The Register message is a series (`repeated`) of Interest messages. Each Interest represents a single event registration.
    67  
    68  ```
    69  message Interest {
    70      EventType eventType = 1;
    71      //Ideally we should just have the following oneof for different
    72      //Reg types and get rid of EventType. But this is an API change
    73      //Additional Reg types may add messages specific to their type
    74      //to the oneof.
    75      oneof RegInfo {
    76          ChaincodeReg chaincodeRegInfo = 2;
    77      }
    78  }
    79  
    80  //ChaincodeReg is used for registering chaincode Interests
    81  //when EventType is CHAINCODE
    82  message ChaincodeReg {
    83      string chaincodeID = 1;
    84      string eventName = 2;
    85      ~~bool anyTransaction = 3;~~ //TO BE REMOVED
    86  }
    87  
    88  //Register is sent by consumers for registering events
    89  //string type - "register"
    90  message Register {
    91      repeated Interest events = 1;
    92  }
    93  
    94  ```
    95  
    96  As mentioned in previous section, clients should register for chaincode events using `ChaincodeReg` message where `chaincodeID` refers to the ID of chaincode as returned by the deploy transaction and `eventName` refers to the name of the event posted by the chaincode.  Setting `eventName` with empty string (or "*") will cause all events from a chaincode to be sent to the listener.
    97  
    98  There is a service defined in events.proto with a single method that receives a stream of registration events and returns an stream that the client can use to read events from as they occur.
    99  
   100  <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
   101  s