Expressions

The empty project opens in the Expression tab, where you can create new expressions for calculation and proving:

A project can contain several expressions and for each of them you can create different proofs for different ranges of Ethereum blocks.

To create a new expression, click the “+ Expression” button:

After which the expression editor with step-by-step flows will open:

First, the user must select a data source:

Event Data allows you to use data from the transaction receipt logs of Ethereum blocks, which contain events generated by smart contracts. By selecting the “Expressions” source, the user can create Compound Expressions using other expressions.

Event Data Expression

Let's look at the case of selecting “Event Data”:

Since all Events are generated by smart contracts, each Event contains the address of the contract and first of all it is required that the user specify it.

For example, to calculate Stablecoin exchange volumes in Curve 3pool in Etherium, the address “0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7” should be specified. After adding the smart contract address, the Maru system will find all Events that the selected smart contract creates and the user can select any of them from the drop-down list.

In some cases, the user may need to manually load the smart contract ABI (for example, if the smart contract code is not verified in Etherscan). To do this, the user needs to click “Upload custom ABI” and drag the contract ABI file into the insertion area or select the file through the browser explorer.

The ABI file will be prepared for uploading to the system:

After clicking the “Continue” button, the ABI will be downloaded and saved for this project, linked to the previously specified smart contract address. This ABI will not be used in other projects.

After selecting Event, the following blocks will be added to the expression editor page:

• filter by indexed event parameters;

• field for entering the name of the expression;

• field for entering an expression formula that will be applied for each found event (map operation);

• map calculation results filter;

• aggregation function;

• constants and parameters that can be used in an expression.

Below is an example expression for calculating the exchange volume of a DAI token:

Filter by indexed event parameters (topics)

To filter the events that will be used in the calculation, you can use a filter based on indexed event parameters. To add a filter, you need to select from the drop-down list the parameter by which to filter and enter the value. By clicking the “+” button, the user can add another filtering condition. A maximum of three filters can be added due to Ethereum restrictions (there can be a maximum of three indexed parameters).

Field for entering the name of the expression

The name can be used in Compound Expressions to create more complex calculations. The calculated value of the expression will be used in the Compound Expressions formula. If the name was not specified, it will be assigned to the expression automatically by the system (for example, expr_187).

Expression formula input field

In expressions the arithmetic operations “+”, “-”, “*”, “/”, and ternary conditional operations (c ? a : b) can be used with the following comparison operations: “==”, “!=”, “>=”, “<=”, “!=”, “>”, “<”. As values in expressions it is possible to use constants and parameters, which are described below.

Filter map calculation results

Allows the user to add a filtering condition to map results. For example, result > 0 for further AVE aggregation.

Aggregation function

SUM or AVE can be selected.

When choosing SUM, all resulting values calculated in map will be summed. This is the most common case and is selected by default. When choosing AVE, the arithmetic mean of all resulting values calculated in map will be calculated. This aggregator can be used, for example, to calculate the average price of a token over a selected period of blocks.

Constants and parameters that can be used in an expression

Different events may have different parameters, which are described in the event signature in the smart contract code. All of these parameters can be used in an expression.

The user can also use token prices that provide AccessControlledOffchainAggregator ChainLink contracts and tokens decimals multipliers to correctly calculate the values of different tokens. Token prices contain the price of a token in USD and allow you to recalculate the values of various tokens to one unit of measurement (USD). The price of tokens periodically changes abruptly using ChainLink oracles in accordance with the market price of the asset. Therefore, using the ChainLink Price Feed allows us to properly account for changes in asset prices over time. Our system tracks in which block the price change events occurred and substitutes the corresponding price value into each expression depending on the block number in which the event took place.

For various contracts in the Maru system, additional contract constants have been added, which the system obtains from contracts. These constants are preset in the system. In the future, users will be able to add various new constants themselves through a special interface.

Precalculation

To check whether an expression is written correctly, the user can check the calculation using the Precalculation functionality:

By default, the system takes a range of 100 blocks: 19213000-19213100. The user can change it to another by clicking on the range of blocks and editing the valuesю

The new saved range will be used in Precalculation for all expressions included in the project. In each project, the user can edit the range for pre-calculation separately. When the user clicks the “Precalculation” button, the system calculates the value of the expression for the selected range of blocks.

All calculation results represent int256 numbers. The user must independently monitor the units of measurement and convert the numbers correctly given the known decimal value of each number.

Save

After clicking the “Save” button, the expression is saved in the database and presented in a short form:

A brief view displays all the basic blocks of the expression with the ability to delete or edit the expression. When deleting an expression, the user should confirm the deletion again to prevent accidental deletion of expressions.

Prove

Once the expression has been verified and saved, the user can submit it to the proving system.

To do this, the user needs to specify the block range manually.

Please note that the range of blocks from Precalculation is not automatically used as the proving block range! After clicking the “Prove” button, a proving task will be created and added to the queue for subsequent proving.

The user can add several proving tasks by manually changing the block range or select periodic calculation, which allows you to create several consecutive proving tasks with a given period of blocks.

This form of task proving allows you to schedule future calculations for ranges of blocks that have not yet been added to the blockchain at the time the task was created. As blocks appear, provings will be made for new ranges of blocks.

Compound Expressions

Compound Expressions allow you to compose more complex expressions that consist of several ordinary expressions.

To create Compound Expressions, select “Expressions” Data source:

After which the expression editor will be opened, consisting of three blocks:

• name of the expression;

• expression formula;

• a list of named expressions.

In this type of expression, the user can only use arithmetic operations “+”, “-”, “*”, “/” and named expressions from the list below that the user has created previously.

Precalculation and proving tasks for Compound Expressions work the same as in regular Expressions.

For the convenience of checking the results of precalculation, in addition to the calculated final value of the Compound Expression, the calculated values of the expressions that are included in the Compound Expression formula are also displayed: