PR for #75 (Support for Solidity Events)

[Jean-Lessa]

Branch 75-events contains an initial implementation of Solidity events in general. Some things remain to be done, but I believe things are solid enough to be merged right now (just in time for Christmas even, hopefully it'll serve as a nice gift for those who waited so long :eyes:).

What was implemented

• Initial support for emitting Solidity events and generating their ABI:
  • src/contract/event.{h,cpp} has the base Event class, responsible for abstracting the event itself and its data (including whether the event is anonymous, has argument indexing and topics), and the EventManager class, responsible for maintaining emitted events in memory and the database (including built-in commit/revert logic with a temporary buffer)
  • ContractManager is now responsible for committing/reverting events depending on whether a contract call is successful or not
  • eth_getLogs was implemented in the net/http/jsonrpc submodule, reponsible for querying and retrieving events in the same way as it is done on Solidity (same inputs, same outputs)
  • DB has a new prefix: 0x0008 = events, where all of the emitted events are stored upon calling the destructor of EventManager (in the same fashion as the Storage class)
  • ContractReflectionInterface now has a map for storing a contract's event data (eventsMap) and two functions for generating event ABI: registerContractEvents() (used by the contracts as an extra step for registering said events) and getEventDataStructure() (used by JsonAbi to write the JSON ABI itself)
  • SimpleContract was updated to include an example of how to declare, register and emit events (see below for more info)
• General optimizations to code and formatting:
  • blockHeight_ and blockTimestamp_ in ContractGlobals were changed from uint256_tto uint64_t (this was done before in the orderbook branch but it wasn't merged (yet) so this could require a bit of attention later)
  • DB::getKeys() was implemented (get only the keys from a database prefix, it helps a bit)
  • The entirety of TxBlock and ContractReflectionInterface had their code indentations fixed
  • ABI::getABIEnumFromBaseTypes was renamed to ABI::BaseTypesToEnum and squished into 4 lines (that's a win to me)

Flux of how events work in OrbiterSDK

• On the contract side (check SimpleContract for a practical example):
  • Declare an event like this: protected void eventName(args...) { this->emitEvent(__func__, { {arg1, indexed}, {arg2, indexed}, ... }, anonymous); }, where __func__ is the event name, indexed is a flag that indicates whether the argument is indexed or not, and anonymous is a flag that indicates whether the event is anonymous or not (defaults to false so you can omit it if you want)
  • Emit an event by simply calling it inside a non-view/non-pure function (due to const correctness, view/pure functions shouldn't be emitting events), like this: this->eventName(args...);
  • Generate the event ABI by registering it inside registerContract(), using the registerContractEvent() from ContractReflectionInterface, giving it the required parameters as tuples with the event's name, whether it is anonymous or not, and sub-tuples with each of the arguments' names, types (written as if they were in Solidity, so "uint256" instead of "uint256_t" for example), and whether they're indexed or not
  • Event declaration/emission and ABI generation are completely independent from each other (as in, you don't have to register events for them to work inside the contract), but it is recommended to always generate the ABI anyways so things work more seamlessly
• On the backend side (regarding event emission):
  • When an event is emitted via DynamicContract::emitEvent(), an Event object is created on the spot and sent directly to ContractManagerInterface::emitContractEvent() (please note that at this specific moment the Event object lacks State data - this is on purpose, as events can be reverted if a transaction fails)
  • ContractManagerInterface::emitContractEvent() checks if the event was emitted during a contract call - if not, throws, otherwise the event is sent directly to EventManager::registerEvent()
  • EventManager::registerEvent() adds the event to the temporary buffer so it can be properly committed or reverted later
  • State::processNextBlock() provides the rest of the data required by the event, passing them through State::processTransaction(), then ContractManager::callContract(), and finally EventManager::commitEvents()
  • EventManager::commitEvents() inserts the required State data on all emitted events so far in that block (by calling each event's setStateData() function) and effectively commits them all by moving them to the permanent event list so they can be queried and/or saved into the database later
  • If a transaction fails, EventManager::revertEvents() is called instead, discarding all events emitted so far in that block
• On the backend side (regarding ABI generation):
  • When an event is registered via ContractReflectionInterface::registerContractEvents(), each event tuple is registered inside the eventsMap map
  • ContractReflectionInterface::getEventDataStructure() retrieves said event data and puts it into a struct that JsonAbi can parse when ./contractabigenerator is run
  • JsonAbi::registerContractAndGetData() calls the previous function and writes the event data to JSON, effectively generating each registered event's ABI alongside the rest of the contract's ABI

Implementation details

• Event: topics_ is a vector with tecnically no limits in and of itself, but the class constructor actually limits how many topics can exist (3 or 4 for anonymous events)
  • This means that indexing order matters - if an event is emitted with e.g. 10 indexed arguments, only the first 3-4 will actually be indexed/registered as topics, and the rest will be encoded in the data_ field
• EventManager: registerEvent() and commitEvents() MOVE the event objects around instead of copying them (push_back(std::move(event)) instead of push_back(event))
• eth_getLogs has hardcoded sane limits for querying (you can query up to a range of 2000 blocks and a total of 10000 events at once)

What is missing

• Proper documentation on sparq-docs (I'm working on this as we speak)
• Tests (for pretty much everything - e.g. emitting events, committing, reverting, saving, loading, querying via eth_getLogs, etc., also checking if topic parameters are encoded correctly as per official Solidity specification)
  • Tests that call ContractManager::callContract() should be revised, as there are extra parameters required now due to EventManager existing in Blockchain as a pointer (nullptr was passed to those calls as a temporary fix, this is only a placeholder value and should be removed later)
• Periodic saving (would be better to implement this alongside #27 since the Storage class still lacks this functionality, both would have pretty much the same logic anyway)
• If required, a limit of 1000 events in memory (there's no limits right now, logic would be pretty much the same as Storage where we only keep the 1000 most recent blocks in memory)
• Parameter encoding for structs (waiting on @itamarcps for that)

[Jean-Lessa]

Docs have been updated on sparq-docs, under a new branch called events. Once this is merged I'll do the merge there accordingly. Would also appreciate some feedback there, it should be pretty easy to follow.

[Jean-Lessa]

Included merges for the SDKTestSuite, global parameters in Options and other minor fixes developed on separate branches. All that's left is to merge this into development and we should be good to go. Would appreciate a final look into it before merging. @itamarcps @jcarraror