Income and Expense Tracking Standard for Eden on EOS Delegates
The Eden Accounting Standard is a reporting mechanism meant to provide the Eden and EOS community information around how Eden funds are being allocated. Elected delegates may adhere to the standard and easily report their Eden expenses using a specific format for the memo field of the EOS token transfer action.
The Eden community’s feedback and engagement is critical to the success of the project. We hope to make this effort as collaborative and easy to use as possible as the quality of the reports generated are a direct result of the level of participation of the Eden delegates
The list of active delegates and their Income will be automatically sourced from genesis.eden smart contract when delegates withdraw Eden funds to their accounts.
Expenses are then picked up automatically by the application by interpreting the memo field messages that delegates must include using the standard EOS token transfer contract.
The memo field must follow a specific format in order to :
- Identify the token transfer as an Eden delegates expense.
- Categorize the expense into one of several predefined categories.
- Describe with additional information on the nature of the expense.
If a delegate chooses not to apply the memo format, their transactions will still be tracked but their reports will show all expenses as “uncategorized.”
Delegates may include any expense into the reporting system by using the following memo format:
eden_expense: <category>/<description>
-
eden_expense is a general prefix to identify this expense as related to Eden, it must be followed by a colon :
-
category must be one of several predefined category keywords that best describes the nature of the expense. The category must then be followed by a forward slash /
-
description is a free-form short text that describes the use of Eden funds.
The following is an example EOS token transfer memo using the Eden expense tracking format:
eden_expense: salaries/payroll for internship program
Category names are limited to a single word so that they can be used as keywords in the transaction memos.
We have provided the following initial list of categories and would like to ask the Eden Delegates for suggestions on new expense categories.
| Category Name | Description |
|---|---|
| admin | General Administrative |
| charity | Charitable Donations |
| development | Software and Web Development |
| dues | Dues and Subscriptions |
| education | Educational Courses and Materials |
| hardware | Computer hardware |
| infrastructure | Web Hosting and Servers |
| legal | Legal and Professional Fees |
| marketing | Media and Outreach |
| pomelo | Pomelo Projects Support |
| salaries | Salaries and Payroll |
| software | Software Licenses and Subscriptions |
| travel | Travel Expenses |
| uncategorized | Default for non reported expenses |
Follow this link to see an Example Eden expense transaction memo:
The treasury page will present visual information based on the EDAS categories, this will help delegates and other eden members to easily understand what's being done with the funds. A new page with a simple token transfer form will help delegates transact and document their expenses without any added complexity.
The expense tracking platform will source all active Eden delegate’s accounts from the genesis.eden smart contracts.
Every time an election occurs the delegate's accounts will be included in the list of accounts that will be automatically tracked to capture all expense reporting information via the transaction memos.
All income will also be automatically tracked every time a delegate claims their funds.
The application backend service will track all token transfers originating from Eden delegates EOS accounts.
When a token transfer includes the transaction memo format this will be parsed and used to populate the database and automatically track and categorize the expenses.
The database will persist the following data for EOS token transfers that involve an Eden delegates account:
| Field Name | Type | Description |
|---|---|---|
| txid | SHA256 | Token Transfer Transaction ID |
| date | Date | Transaction Date |
| type | text | Income or Expense |
| delegate | EOS Account Name | Eden Delegate’s Account |
| election | Integer | Eden Election Round |
| amount | Number | Transfer Amount in EOS |
| recipient | EOS Account Name | Receiver of Funds |
| category | Text | Expense Category |
| description | Text | Transaction description |
Data can then be aggregated to be displayed on a web application with graphs and other data visualizations.
Some interesting data visualizations to be included in the dashboard could be :
Expenses and Incomes by category pie chart
- Total Expenses and Incomes By Category per Delegate
- Total Expenses and Incomes By Category for All Delegates
Expenses and Incomes by Round Stacked Graph
- Expenses and Incomes by Round per Delegate
Detailed Table
- Expenses and Incomes per Round
- Expenses and Incomes per Delegate
Expenses and Income Across Eden Rounds
- Round 1 Expenses and Incomes vs Round 2 Expenses and Incomes etc.
We are inspired by the Demux Pattern to develop a backend service for sourcing blockchain events to deterministically update queryable datastores and trigger side effects.
- Client sends transaction to blockchain
- Action Watcher invokes Action Reader to check for new blocks
- Action Reader sees transaction in new block, parses actions
- Action Watcher sends actions to Action Handler
- Action Handler processes actions through Updaters and Effects
- Actions run their corresponding Updaters, updating the state of the Datastore
- Actions run their corresponding Effects, triggering external events
- Client queries API for updated data
We will use the Dfuse history service's ability to query blockchain events to listen for transactions and trigger side effects outside of the blockchain. The blockchain remains as the single source of truth for all application state nonetheless.
The backend service will subscribe to the following smart contract actions required in order to trigger updates when Eden specific token transfers occur on chain.
-
genesis.eden::electprocess Triggers process that sources all accounts with an
election_rank > 0from thegenesis.edencontract's members table when elections take place. -
genesis.eden::withdraw Triggers a database entry that registers Eden income for a given delegate account.
-
eosio.token::transfer Triggers a database entry when an Eden del action that updates referral when invitee completes KYC for a new account.
This application features the following technology stack :
- React JS : A Front End Web Application Framework.
- Hapi : Node JS HTTP API.
- Dfuse : Full History API.
- Hasura : GraphQL Engine for PostgreSQL Database.
- EOSIO : Blockchain protocol with industry-leading transaction speed.
- Kubernetes : Docker Container Orchestration.
This project is being developed on the Jungle Testnet using the genesisdeden smart contract account. This contract is a copy of the current smart contract used by Eden on EOS.
The backend service is currently using Edenia's testnet API Node
We use the EOS JS javascript API for integration with EOSIO-based blockchain networks using EOSIO RPC API.
EOS JS documentation can be found here
This FullStack Template uses React.js as a Frontend Library which together with other tools like Apollo Client, GraphQL and Material UI brings a robust solution for building Single Page Applications out of the box.
Hasura technology maps a PostgreSQL database and provides a reliable and easy-to-use API. This allow us to focus on critical features of our projects, delegating mechanic CRUD (Create, Read, Update, Delete) operations.
Hasura also enables custom REST handling capabilities with the possibility to integrate a custom REST server, that way we can extend the base CRUD functionalities and build custom business logic.
The Dfuse event listener is configured withing the HAPI nodeJS backend service. We also need to handle REST custom requests coming from the Hasura GraphQL server. For this, we will use hapi.dev, which is a simple and easy-to-use backend framework.
Within this repository you will find the following directories and files:
.
├── docs .......................... Documentation
│ └── images .................... Images and Diagrams
├── hapi .......................... Node JS backend & HTTP API
│ └── src
│ └── config ................ Backend Configurations
│ └── routes ................ HTTP routes
│ └── utils ................. Utilities and Libraries
│ └── services .............. Project Business Logic
| └── dfuse .......... Demux Implementation
├── hasura ........................ Hasura GraphQL Engine
├── kubernetes .................... Kubernetes Manifests
├── utils ......................... Makefiles for project build
└── webapp ........................ ReactJS Web Application
Some things you need before getting started:
- WSL and Ubuntu 18.04 LTS: If you are using Windows operative system you will need to install WSL and Ubuntu 18.04.5 LTS. You can do it following this steps.
- Git: You will need to use git to clone and colaborate in this repository.
- Docker Desktop: You will need docker and docker compose to run different images. When you have Docker Desktop installed you have to go to settings then Resources after that select WSL Integration and active the swich.
- Nodejs: This installation also depents of the operative system.
- Yarn: You have to install first npm for then install yarn. The installation depents of the operative system.
- Hasura CLI: You will need it to handle DB.
Copy the .env.example then update the environment variables according to your needs.
cp .env.example .env
- Clone this repo using
git clone --depth=1 https://github.com/edenia/eden-spend-explorer.git <YOUR_PROJECT_NAME>. - Move to the appropriate directory:
cd <YOUR_PROJECT_NAME>. - Run
make runin order to start the project using docker compose.
At this point you can navigate to http://localhost:3000.
Please read Edenia's Open Source Contributing Guidelines.
Please report bugs big and small by opening an issue
Edenia runs independent blockchain infrastructure and develops web3 solutions. Our team of technology-agnostic builders has been operating since 1987, leveraging the newest technologies to make the internet safer, more efficient, and more transparent.