ch.epfl.dedis.eventlog

Class EventLogInstance

java.lang.Object

ch.epfl.dedis.eventlog.EventLogInstance

public class EventLogInstance
extends Object

EventLogInstance is for interacting with the eventlog contract on ByzCoin. 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, independently 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.
• Existence 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.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ContractId

Constructor Summary

Constructors

Constructor and Description
EventLogInstance(ByzCoinRPC bc, DarcId darcId, List<Signer> signers) Constructor for when do you not know the eventlog contract, use this constructor when constructing for the first time.

Method Summary

Modifier and Type	Method and Description
static EventLogInstance	fromByzcoin(ByzCoinRPC bc, InstanceId id) Constructor for when the caller already knows the eventlog contract.
Event	get(InstanceId key) Retrieves the stored event by key.
InstanceId	getInstanceId() Gets the contract ID which can be stored to re-connect to the same eventlog instance in the future.
InstanceId	log(Event event, DarcId darcId, 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, DarcId darcId, 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

Field Detail

ContractId

public static String ContractId

Constructor Detail

EventLogInstance

public EventLogInstance(ByzCoinRPC bc,
                        DarcId darcId,
                        List<Signer> signers)
                 throws CothorityException

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

Parameters:

bc - the byzcoin RPC

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

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

Throws:

CothorityException - if something goes wrong

Method Detail

log

public List<InstanceId> log(List<Event> events,
                            DarcId darcId,
                            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

darcId - the darc ID

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 - if something goes wrong

log

public InstanceId log(Event event,
                      DarcId darcId,
                      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

darcId - the darc ID

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 - if something goes wrong

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 - if something goes wrong

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 - if something goes wrong

getInstanceId

public InstanceId getInstanceId()

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

Returns:

the contract ID

fromByzcoin

public static EventLogInstance fromByzcoin(ByzCoinRPC bc,
                                           InstanceId id)
                                    throws CothorityException

Constructor for when the caller already knows the eventlog contract.

Parameters:

bc - the byzcoin RPC

id - the contract ID, it must be already initialised and stored on byzcoin

Returns:

a new EventLogInstance

Throws:

CothorityException - if something goes wrong