Auxo-Reporter

The Auxo reporter is used to create MerkleTrees for the Auxo protocol. It fetches data from The Graph, Snapshot and Directly from the blockchain, then calculates the rewards for each user and generates a MerkleTree of claims that can be uploaded on chain.

Structure

Makefile        # set of pre-defined scripts to get you started

# Python files
reporter/        # Python application to parse config data into rewards database
  models/        # Classes and class behaviours
  queries/       # on chain and subgraph queries
  rewards/       # Reward calculations
  test/          # Unit tests
  run.py         # Main script to run the reporter
  *.py           # other misc python files needed for the app
reports/         # Output files relating to claims, voting, proposals, rewards and the final tree
config/          # Config files for the reporter
pyproject.toml   # Python tooling setup
requirements.txt # Python dependencies

# Typescript files
merkleTree/     # Typescript MerkleTree generator with OpenZeppelin
package.json    # NodeJS dependencies and scripts
tsconfig.json   # Typescript config

Installation

Make sure you have Python, Pip, NodeJS, Yarn installed. Python 3.10+ is recommended.

The Makefile contains a set of scripts to get you started. Provided you have make installed:

Setup the python venv and activate:

make venv
source venv/bin/activate

Install everything :

make setup

Check for type errors and format everything:

make lint

Run unit tests

make test

Running the Application

Setting up the .env:

The example env file requires you to grab a number of contract addresses, subgraph endpoints and API keys. This needs only doing once and a lot of these are pre-populated for you.

Running each epoch

Provided the env is configured, everything else is built from a config file, you can find full details by reading the example file.

You can autogenerate a config file from the example with:

make conf

This will create a config/example.json file with some example data and the schema incorporated. The schema provides some basic warnings and validations to help you get started but it is not essential.

IMPORTANT: remember to create claims for the month that has passed and not for the current month. Example: If the operator runs the reporter at the start of July 2023, the operator will likely be needing to run for JUNE 2023.

Create the database of claims and rewards:

# You will be promoted to provide the path to your config file.
make claims

If all goes well, you should have a new folder reports/{year}-{month}/, i.e. reports/2022-11/. Where {year} and {month} are the year and month as defined in your config file.

In it you will have the following files:

csv/                  # Report data in CSV format
json/                 # Report data in JSON format
claims.json           # Rewards by ethereum address, nil for inactive/slashed users
epoch-conf.json       # autogenerated config file based on your input config file
reporter-db.json      # Full breakdown of all generated data. Can be readable by TinyDB

You can then generate the merkle tree file with:

make tree

This will output a merkle-tree.json file in the reports folder for your passed epoch.

You will be asked whether to post to IPFS. If you want to do this, you will need to follow the instructions below before building the merkle tree.

Posting to IPFS

You can use Web3.storage to create an API Key.

Add it to a .env file by copying the .env.example and adding your key.

That's it! Just follow the instructions in the command prompt and you will automatically post to the IPFS and generate a link.

Compounding

Compounding refers to users delegating their claim back to the DAO, in exchange for more Auxo.

Config

Similar to building claims, compounding works of a config file. Examples and schema are defined in the config folder.

Compounding is a 4 step process:

1. Generate the list of Claims that need compounding (a claim object is associated with the Merkle Distributor, passing the claim when delegated will transfer rewards from a user to the delegated sender).

2. Claim against each distributor, then purchase Auxo with the claimants' WETH, to get the total compounded value.

3. Set the total purchased Auxo in the config, and generate the amount of PRV to stake on behalf of compounders.

(1) and (3) can be run with make compound-fetch and make compound-send respectively. You'll be asked for a config file. You can share the same config file across both commands, but in the compound-send step, you'll need to provide details of the reward quantity.

Both compound-send and compound-fetch output JSON files that can be used with a Safe multisig. In the case of compound-fetch you can upload these files using the transaction builder in the Safe UI. At time of writing there is a bug in the UI where we cannot create transactions including nested arrays, so for claimMultiDelegated, you need to either use the autogenerated Safe JSON file from this reporter or submit the claims array another way (i.e. using cast/foundry to create the raw calldata).

Fetch the list of compounders that have not claimed

NB: It is suggested you lock the Distributors before fetching the list of compounders: to avoid someone claiming during the generation process.

make compound-fetch

You will be asked for the epoch, put it in the form [YYYY]-[MM] where MM is the month without leading zeros (2023-6)

This will create some new files inside reports/{EPOCH}/compounding:

• recipients-{TOKEN}-{X}: the list of users for ARV or PRV who have yet to claim
• A Safe TX in JSON format

Determine the Amount of Auxo/ARV/PRV to compound

Before running this command, ensure the config file has its rewards.amount set.

make compound-send

This will output a compound-{X} file, similar to the claims.json file. It shows the amount of PRV that should be sent to each user, based on their WETH compounded.

At the time of writing, Delegated rewards are converted to PRV only.

Steps for compounding:

1. User must delegate claim to the Multisig
2. Fetch claims for delegated users
3. Treasury can claim on behalf of delegated users, WETH is sent to the treasury
4. WETH is used to purchase Auxo
5. Based on the number of Auxo purchased, a pro-rata figure for WETH is computed
6. Users are sent (pro-rata * WETH_qty) PRV

TODO

• Clean up the code
  • Move out of the god script
  • Refactor
  • Create makecalls to build the relevant piece
    • fetch
    • send
• Rounding errors
• Add PRV compounding support
• Replace Auxo with PRV
• Add the pro-rata unit tests
• Add a bit of documentation
• Export JSON transactions
• Add better config support for compounding
• Safe TX
• [] Combine PRV/ARV integration (final step)
• [] Support for combining multiple epochs