protocol
Melon ([méllō], μέλλω; Greek for "destined to be") is blockchain software that seeks to enable participants to set up, manage and invest in technology regulated investment funds in a way that reduces barriers to entry while minimizing the requirements for trust.
It does so by leveraging off the fact that digital assets on distributed quasi turing complete machines can be held solely by smart-contract code and spent only if its preprogrammed within this code. The Melon protocol is a set of rules for how digital assets can be spent once held in a Melon smart-contract, or a Melon investment fund. It's meant to protect the investor and fund manager from malevolent behaviour of each other even when both parites remain private.
Melon is for investment funds what Bitcoin is for accounting, a set of rules, enforced by blockchain technology, legitimized by the consent of its participants.
This repository contains a reference implementation of the Melon protocol written in Solidity, as specified in our paper.
Table of Contents
Implementation
Governance
The main functionality of the Governance contract is to add new protocol versions such as this Version contract and to shut down existing versions once they become obsolete.
Adding new protocol version is done by anyone proposing a version to be added and is executed once authority consensus has been established.
Shutting down an existing protocol version is done by anyone proposing a version to be shut down and is executed once authority consensus has been established.
Shutting down a version disables the ability to setup new funds using this version and enables anyone to shut down any existing funds of this version.
Funds
The Participation module takes as input the following parameters:
Requests: Describes and logs whenever asset enter and leave fund due to Participants
| Name | Data Type | Description |
|---|---|---|
| participant | address |
Participant in Melon fund requesting subscription or redemption |
| status | enum |
Enum: active, cancelled, executed; Status of request |
| requestType | enum |
Enum: subscribe, redeem |
| shareQuantity | uint256 |
Quantity of Melon fund shares |
| giveQuantity | uint256 |
Quantity in Melon asset to give to Melon fund to receive shareQuantity |
| receiveQuantity | uint256 |
Quantity in Melon asset to receive from Melon fund for given shareQuantity |
| incentiveQuantity | uint256 |
Quantity in Melon asset to give to person executing request |
| lastDataFeedUpdateId | uint256 |
Data feed module specific id of last update |
| lastDataFeedUpdateTime | uint256 |
Data feed module specific timestamp of last update |
| timestamp | uint256 |
Time of request creation |
While the Risk Management module takes as input the following parameters:
Orders: Describes and logs whenever assets enter and leave fund due to Manager
| Name | Data Type | Description |
|---|---|---|
| exchangeId | uint256 |
Id as returned from exchange |
| status | enum |
Enum: active, partiallyFilled, fullyFilled, cancelled |
| orderType | enum |
Enum: make, take |
| sellAsset | address |
Asset (as registered in Asset registrar) to be sold |
| buyAsset | address |
Asset (as registered in Asset registrar) to be bought |
| sellQuantity | uint256 |
Quantity of sellAsset to be sold |
| buyQuantity | uint256 |
Quantity of sellAsset to be bought |
| timestamp | uint256 |
Time in seconds when this order was created |
| fillQuantity | uint256 |
Buy quantity filled; Always less than buy_quantity |
Modules
List of Melon modules
Melon has six different module classes:
- Exchange Adapters
- Rewards
- Participation
- Risk Management
- Asset registrars
- Data feeds
Which can be categorized into three sub sets:
- Libraries
- Boolean function
- Infrastructure
Libraries
They interact with the Melon protocol using as pre-linked libraries to the Melon version contract. These Melon modules are:
-
Exchange Adapters: These are adapters between Melon protocol and decentralized exchanges. Responsible for relaying information, making and taking orders on exchanges.
-
Rewards: This module defines functions for calculating management and performance rewards for the fund manager. Management reward is calculated on the time managed irrespective of performance of the fund while performance reward is calculated based on the performance.
Boolean functions
They interact with the Melon protocol using boolean functions. That is functions which take a certain set of inputs and return either true or false. These Melon modules are:
-
Participation: It comprises of two primary boolean functions isSubscriptionPermitted and isRedemptionPermitted which enforce rules for investing and redemption from the fund. They take the parameter inputs as specified in the earlier section.
-
Risk Management: It currently comprises of two boolean functions isMakePermitted and isTakePermitted. They take the parameter inputs as specified in the earlier section. This module can be extended with custom logic to prevent malevolent actions by the fund manager. This may include checks if the order price is significantly different from the reference price, e.t.c.
Infrastructure
These are security critical infrastructure modules. These Melon modules are:
- Asset registrars: It is a chain independent asset registrar module. Only the registered assets will be available. Cross-chain asset integration is enabled through Polkadot in future. An asset can be registered via the register function by specifying the following parameters:
| Name | Data Type | Description |
|---|---|---|
| asset | address |
Address of the asset |
| name | string |
Human-readable name of the Asset as in ERC223 token standard |
| symbol | string |
Human-readable symbol of the Asset as in ERC223 token standard |
| decimal | uint |
Decimal, order of magnitude of precision, of the Asset as in ERC223 token standard |
| url | string |
URL for extended information of the asset |
| ipfsHash | bytes32 |
Same as url but for ipfs |
| chainid | bytes32 |
Chain where the asset resides |
| breakIn | address |
Break in contract on destination chain |
| breakOut | address |
Break out contract on this chain |
- Data feeds: Data feeds route external information such as asset prices to Melon fund smart contracts.
The reason they are security critical is that the correctness of the data they provide cannot directly be enforced or guaranteed and trust is placed on a central authority.
Interaction
Smart contract interaction for the following scenarios:
- Setup of a new Melon fund
- Participant invests in a Melon fund
- Participant redeems from a Melon fund
- Manager makes an order
- Manager takes an order
- Manager converts rewards into shares
- Manager shuts down the fund
Setup of a new Melon fund
A new Melon fund can be setup by specifying the following parameters via setupFund function of the version contract:
| Name | Data Type | Description |
|---|---|---|
| name | string |
A human readable name of the fund |
| referenceAsset | address |
Asset against which performance reward is measured against |
| managementRewardRate | uint |
Reward rate in referenceAsset per delta improvement |
| performanceRewardRate | uint |
Reward rate in referenceAsset per managed seconds |
| participation | address |
Participation module |
| riskMgmt | address |
Risk management module |
| sphere | address |
Sphere module |
Participant invests in a Melon fund
- A participant starts to invest in a fund F by first creating a subscription request R. Parameters to be specified are:
| Name | Data Type | Description |
|---|---|---|
| giveQuantity | uint |
Quantity of Melon tokens to invest |
| shareQuantity | uint |
Quantity of fund shares to receive |
| incentiveQuantity | uint |
Quantity of Melon tokens to award the entity executing the request |
- R parameters are checked against restriction rules specified in the participation module P by the boolean function P.isSubscriptionPermitted (E.g Participant being an attested Uport identity).
- R is then executed in by any entity via F.executeRequest after certain conditions are satisfied. These conditions include if currentTimestamp - R.timestamp >= DF.INTERVAL (DF refers to datafeed module and INTERVAL corresponds to update frequency value) and if DF.getLastUpdateId >= R.lastDataFeedUpdateId + 2. This is to minimize unfair advantage from information asymmetries associated with the investor.
Participant redeems from a Melon fund
- A participant can redeem from a fund by first creating a redemption request. Parameters to be specified are:
| Name | Data Type | Description |
|---|---|---|
| shareQuantity | uint |
Quantity of fund shares to redeem |
| receiveQuantity | uint |
Quantity of Melon tokens to receive in return |
| incentiveQuantity | uint |
Quantity of Melon tokens to award the entity executing the request |
- Request parameters are checked against restriction rules specified in the participation module P via the boolean function P.isRedemptionPermitted.
- R is then executed in a similar way as mentioned earlier.
Manager makes an order
- Manager can make an order by specifying asset pair, sell and buy quantities as parameters. Asset pair is checked against datafeed module DF through the function DF.existsData. Order parameters are then checked against restriction rules specified in the risk management module R via the boolean function R.isMakePermitted.
- The specified quantity of the asset is given allowance to the selected exchanging via ERC20's approve function.
- Order is then placed on the selected exchange through the exchangeAdapter contract E via E.makeOrder by specifying the exchange and order parameters as parameters.
- The order is filled on the selected exchange (In future, can be any compatible decentralized exchange like OasisDex, Kyber, e.t.c) when the price is met.
Manager takes an orders
- Manager can take an order by specifying an order id and quantity as parameters. Asset pair is checked against datafeed module DF through the function DF.existsData. Order parameters are then checked against restriction rules specified in the risk management module R via the boolean function R.isTakePermitted.
- The specified quantity of the asset is given allowance to the selected exchanging via ERC20's approve function.
- Order id must correspond to a valid, existing order on the selected exchange. Order is then placed on the selected exchange through the exchangeAdapter contract E via E.takeOrder by specifying the exchange and order parameters as parameters.
Manager converts rewards into shares
- Manager rewards in the form of ownerless shares of the fund F can be allocated to the manager via F.convertUnclaimedRewards function. Ownerless shares refer to the quantity of shares, representing unclaimed rewards by the Manager such as rewards for managing the fund and for performance. First internal stats of F are calculated using F.performCalculations function. The quantity of unclaimedRewards is calculated internally using calcUnclaimedRewards function.
- A share quantity of unclaimedRewards * gav (from Calculations) is assigned to the manager.
Manager shuts down the fund
- A Manager can shut down a fund F he owns via F.shutdown function.
- Investing, redemption (Only in reference asset, investors can still redeem in the form of percentage of held assets), managing, making / taking orders, convertUnclaimedRewards are rendered disabled.
Get started
Installation
You will need the dapp developer tools, which you can install using these steps.
-
Clone this repository
git clone --recursive git@github.com:melonproject/protocol.git cd protocol -
Install dependencies
npm install -
Generate bytecode and abi of smart-contracts using dapp suite
npm run compile
Testing
After installation is complete, go to the above protocol directory, open a terminal and:
-
Launch a testrpc client:
npm run localnode -
Open a second terminal and deploy the contracts to the development network:
npm run deploy:development -
Run the test framework:
npm test
Linting
After installation is complete, go to the above protocol directory, open a terminal and run:
npm run lint
Deployment
After installation is complete, go to the above protocol directory, open a terminal and:
-
Launch an ethereum client. For example something similar to this:
parity --chain kovan --author <some address> --unlock <some address> --password <some password file> -
Open a second terminal and deploy the contracts:
npm run deploy:kovan
Contribute
As an open-source project we welcome any kind of community involvement. Whether that is by contributing code, reporting issues or engaging in insightful discussions.
Security Issues
If you find a vulnerability that may affect live or kovan deployments please send your report privately to admin@melonport.com. Please DO NOT file a public issue.
Protocol Design
When considering protocol design proposals, we are looking for:
- A description of the problem this design proposal solves
- Discussion of the tradeoffs involved
- Review of other existing solutions
- Links to relevant literature (RFCs, papers, etc)
- Discussion of the proposed solution
Please note that protocol design is hard, and meticulous work. You may need to review existing literature and think through generalized use cases.
Implementation Design
When considering design proposals for implementations, we are looking for:
- A description of the problem this design proposal solves
- Discussion of the tradeoffs involved
- Discussion of the proposed solution