ch.epfl.dedis.lib.omniledger.contracts

Class EventLogInstance

java.lang.Object

ch.epfl.dedis.lib.omniledger.contracts.EventLogInstance

public class EventLogInstance
extends Object

EventLogInstance is for interacting with the eventlog contract on OmniLedger.

Contrary to ordinary event logging services, we offer better security and auditability. Below are some of the main features that sets us apart.

• Collective witness - a collection of nodes, or conodes, indepdently observe the logging of an event. The event will only be accepted if a 2/3-majority think it is valid, e.g., the timestamp is reasonable, the client is authorised and so on.
• Distributed access control - fine-grained client access control with delegation support is configured using DARC.
• Configurable acceptance criteria - we execute a smart-contract on all nodes, nodes only accept the event if the smart-contract returns a positive result.
• Existance proof - once an event is logged, an authorised client can request a cryptographic proof (powered by collection) that the event is indeed stored in the blockchain and has not been tampered.

Constructor Summary

Constructors

Constructor and Description
EventLogInstance(OmniledgerRPC ol, InstanceId id) Constructor for when the caller already knows the eventlog instance.
EventLogInstance(OmniledgerRPC ol, List<Signer> signers, DarcId darcId) Constructor for when do you not know the eventlog instance, use this constructor when constructing for the first time.

Method Summary

Modifier and Type	Method and Description
Event	get(InstanceId key) Retrieves the stored event by key.
InstanceId	getInstanceId() Gets the instance ID which can be stored to re-connect to the same eventlog instance in the future.
InstanceId	log(Event event, List<Signer> signers) Logs an event, the returned value is the ID of the event which can be retrieved later.
List<InstanceId>	log(List<Event> events, List<Signer> signers) Logs a list of events, the returned value is a list of ID for every event which can be used to retrieve events later.
SearchResponse	search(String topic, long from, long to) Searches for events based on topic and a time range.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EventLogInstance

public EventLogInstance(OmniledgerRPC ol,
                        List<Signer> signers,
                        DarcId darcId)
                 throws CothorityException

Constructor for when do you not know the eventlog instance, use this constructor when constructing for the first time. This constructor expects the omniledger RPC to be initialised with a darc that contains "spawn:eventlog".

Parameters:

ol - the omniledger RPC

signers - a list of signers that has the "spawn:eventlog" permission

darcId - the darc ID that has the "spawn:eventlog" permission

Throws:

CothorityException

EventLogInstance

public EventLogInstance(OmniledgerRPC ol,
                        InstanceId id)
                 throws CothorityException

Constructor for when the caller already knows the eventlog instance.

Parameters:

ol - the omniledger RPC

id - the instance ID, it must be already initialised and stored on omniledger

Throws:

CothorityException

Method Detail

log

public List<InstanceId> log(List<Event> events,
                            List<Signer> signers)
                     throws CothorityException

Logs a list of events, the returned value is a list of ID for every event which can be used to retrieve events later. Note that when the function returns, it does not mean the event is stored successfully in a block, use the get function to verify that the event is actually stored.

Parameters:

events - a list of events to log

signers - a list of signers with the permission "invoke:eventlog"

Returns:

a list of keys which can be used to retrieve the logged events

Throws:

CothorityException

log

public InstanceId log(Event event,
                      List<Signer> signers)
               throws CothorityException

Logs an event, the returned value is the ID of the event which can be retrieved later. Note that when this function returns, it does not mean the event is stored successfully in a block, use the get function to verify that the event is actually stored.

Parameters:

event - the event to log

signers - a list of signers that has the "invoke:eventlog" permission

Returns:

the key which can be used to retrieve the event later

Throws:

CothorityException

get

public Event get(InstanceId key)
          throws CothorityException

Retrieves the stored event by key. An exception is thrown when if the event does not exist.

Parameters:

key - the key for which the event is stored

Returns:

The event if it is found.

Throws:

CothorityException

search

public SearchResponse search(String topic,
                             long from,
                             long to)
                      throws CothorityException

Searches for events based on topic and a time range. If the topic is an empty string, all topics within that range are returned (from < when <= to). The query may not return all events, this is indicated by the truncated flag in the return value.

Parameters:

topic - the topic to search, if it is an empty string, all topics are included, we do not support regex

from - the start of the search range (exclusive).

to - the end of the search range (inclusive).

Returns:

a list of events and a flag indicating whether the result is truncated

Throws:

CothorityException

getInstanceId

public InstanceId getInstanceId()

Gets the instance ID which can be stored to re-connect to the same eventlog instance in the future.

Returns:

the instance ID