package vmware.concord.client.event.v1

Get desktop application:
View/edit binary Protocol Buffers messages

The EventService can be used to read old events and listen for new ones. Concord Client queries a quorum of replicas to validate those events. The replicas will filter and deliver all events in EventGroups in the order they were created. Concord Client will continuously try to get new EventGroups once the subscription has been established. If the user encounters errors then it is recommended to check the service's health via gRPC's health check API or re-subscribe with exponential back-off to its last known event group id. https://github.com/grpc/grpc/blob/master/doc/health-checking.md

• rpc Subscribe (SubscribeRequest, stream SubscribeResponse)

  event.proto:36

  Subscribe to a continuous stream of events from the blockchain. Note: Only one active stream per Concord client is supported at this time. The active stream has to be cancelled first before a new stream can be established. Errors: OUT_OF_RANGE: if the requested starting point is not available yet. See SubscribeRequest for details. NOT_FOUND: if the requested starting point was pruned. See SubscribeRequest for details. RESOURCE_EXHAUSTED: if Concord Client is overloaded. The caller should retry with a backoff. UNAVAILABLE: if Concord Client is currently unable to process any requests. The caller should retry with a backoff. INTERNAL: if Concord Client cannot progress independent of the request. ALREADY_EXISTS: if Concord Client serves an active stream already. See note above.

  message SubscribeRequest

  event.proto:44

  Events come in two formats - Events (old API) and EventGroups (new API). An EventsRequest will result in a stream of EventGroups or a stream of Events which turns into a stream of EventGroups. If the block requested by EventsRequest contains EventGroups only then the stream will start at the first EventGroup. An EventGroupsRequest will result in a stream of EventGroups. If you don't know about Events then use EventGroupsRequest.

  • oneof request

    • EventsRequest events = 1

    • EventGroupsRequest event_groups = 2

  message SubscribeResponse

  event.proto:51

  • oneof response

    • Events events = 1

    • EventGroup event_group = 2

Used in: Events

• bytes event_key = 1

  Event key provided by the execution engine.

• bytes event_value = 2

  Event value provided by the execution engine.

The execution engine will generate one or multiple events per single Request from the RequestService. In addition, the execution engine decides which Concord Client is allowed to see which event. The replicas filter the events and hence the Concord Client might receive a subset of all events. All events are accumulated into EventGroups. Each EventGroup contains all visible events for a single Request execution and is marked with an identifier. EventGroups without any visible events are not sent to Concord Client. The EventGroup id indicates the order of events' generation. Therefore, the order of EventGroups mirror the order of request executions visible to Concord Client.

Used in: SubscribeResponse

• uint64 id = 1

  Sequentially increasing identifier which is unique to all Concord Clients with the same Concord Client id. The very first EventGroup is marked with EventGroup id 1.

• repeated bytes events = 2

  The events visible to the client in the order produced by the execution engine.

• optional google.protobuf.Timestamp record_time = 3

  Timestamp for when the request execution result was included in the blockchain.

• map<string, string> trace_context = 4

  Optional trace data in `trace_context`. Trace information will be provided if the event was created after the subscription stream was established. The trace context is compliant with the W3C Trace Context specification: https://www.w3.org/TR/trace-context/#trace-context-http-headers-format Note: Trace contexts can be transferred via gRPC metadata but are per-RPC only. https://grpc.io/docs/what-is-grpc/core-concepts/#metadata

Used in: SubscribeRequest

• uint64 event_group_id = 1

  Stream EventGroups starting at EventGroup `event_group_id`.

Legacy format of events visible to a Concord client within a single block.

Used in: SubscribeResponse

• uint64 block_id = 1

  Identifier of the block whose events are being sent. The very first block has identity 1.

• repeated Event events = 2

  All events visible to the requesting Concord client that are part of the block `block_id`. These events should be interpreted as a finite map from `event_key`s to `event_value`s. This means that the`event_key`s of the events are guaranteed to be unique and always mapped to the same `event_value`. However, the order of events might change between different calls to `Subscribe`.

• string correlation_id = 3

  Depending on how many requests were executed in block `block_id` this id is the correlation id of a single request or a batched correlation id of multiple requests.

• map<string, string> trace_context = 4

  Optional trace data in `trace_context`. Trace information will be provided if the event was created after the subscription stream was established. The trace context is compliant with the W3C Trace Context specification: https://www.w3.org/TR/trace-context/#trace-context-http-headers-format Note: Trace contexts can be transferred via gRPC metadata but are per-RPC only. https://grpc.io/docs/what-is-grpc/core-concepts/#metadata

Used in: SubscribeRequest

• uint64 block_id = 1

  Stream Events starting at block `block_id`.