Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
For full implementation details please see github.
Our docs site is here. Here you will find details on the protocol design, financial contracts and main net deployment addresses. You can also find it directly from this repo in the documentation folder.
The repository is broken up into 4 main packages, managed using yarn workspaces. You can find these in the packages directory. These packages are as follows:
packages/contractsSmart contracts, deployment scripts and integration tests for the Honeylemon protocol. The contract bring together MarketProtcol 0x MinterBridge and custom HoneyLemon contracts to create the protocols financial contracts.
packages/honeylemon.jsJavascript library used to connect to the Honeylemon protocol. This library is used by the front end to wrap complex interactions like submitting orders or batch token redemption.
packages/subgraphThe Graph subgraph used to index contract events for front end retrieval. Used directly by honeylemon.js.
packages/webappReact Typescript, dApp front end. Can be found online .
You'll need the latest LTS release of nodejs and npm installed. You'll also need Docker installed for your operating system. Assuming that's done, run:
Once this is done you can start the local development env by running a make command. This will clean all data and start/restart docker containers. Some unit tests are coupled and require you to run this between executions as well such as running If running order-test.js script.
After running this you will have a local 0x API, a Ganache instance and a Subgraph running on your local machine in docker containers. You can run docker ps -a to see all the containers running.
Next, you can run the tests. There are three main tests kinds of tests: 1) Smart contract tests, 2) Honeylemon.js service tests that validate the service data retrieval and on-chain interactions including the Graph Protocol and 3) integration tests that show full life cycle interconnection between the Marketprotocol, 0x order book, DSProxy contracts and the custom honey lemon smart contracts.
TODO: UPDATE with actual commands.
Running the front end can be done by executing:
If you want to deploy smart contracts to a test network you can run:
When MarketContractProxy address changes it needs to be updated in the following places:
docker/docker-compose-local.yml (look for HONEYLEMON_MARKET_CONTARCT_PROXY_ADDRESS)
subgraph/subgraph.yml (in the MarketContractProxy source address field)
To run the formatter, run:
We use the package to generate our coverage reports. These can be generated manually by developers. There are no regression tests or published reports. CircleCI does generate a coverage report automatically, but if you'd like to generate it locally, run:
The full report can be viewed by opening the core/coverage/index.html file in a browser. The full report can be viewed by opening the core/coverage/index.html file in a browser. You can also find an online version of our coverage report on .
Coming soon!
This document explains the general technical architecture of Honellemon's synthetic Bitcoin mining contracts built on Ethereum.
Honeylemon has a number of interconnected components. Primarily, the market mechanism is built on the Market Protocol and the 0x Protocol, as well as a number of custom contract wrappers and proxies.
The market Protocol is used to create a Contract for Differences (CFD) between the miner and investor who each hold a short or long position token respectively. These tokens represent a “bet” on the future Bitcoin hash rate, expressed in Miner Mining Revenue Index (MRI) Index. This represents the network daily average block rewards & fees earned in BTC per terahash (TH) of hash power.
The 0x Protocol is used to create an order book wherein miners can publish sell orders which are filled by investors. The orderbook is not a standard two-sided orderbook. Rather, miners can only place limit orders(makers) and investors can only fill orders(takers). This is to enable the traditional order flow of a cloud mining contract. The 0x orderbook is hosted using a modified version of 0x Mesh which enables unfilled order retrieval from the front end.
The diagram below shows a full order flow in the system.
There are 3 main roles in the protocol: the Honeylemon admin, Miner and Investor. Below are scenarios that each of them perform.
Everyday we deploy a new MarketContract, PositionTokenShort and PositionTokenLong. We register the latest MarketContract in MarketContractProxy in order to make it easier to interact with the latest deployed MarketContract.
Honeylemon admin maintains an Oracle that posts daily BTC payoffs per 1Th on-chain. This data is used by the modified Market protocol contracts to calculate payoffs at settlement. For now, this is a centralized oracle operated by the team. In the future this component will be refined to be more trustless. The oracle provides several indexes for various purposes:
Current hashrate index (MRI) - used to calculate collateral requirements at contract start (this value doesn’t need to be onchain, it is used only when deploying daily Market contracts.
Miner goes to the UI.
Miner enters the sale price and amount of TH they want to sell. The UI shows required imBTC collateral and whether there’s enough in the wallet (otherwise order can’t be created).
Gives approval to draw the collateral token (imBTC) from their wallet. MetaMask popup with ETH transaction - once per address.
The UI constructs a 0x order, opens MetaMask to sign it (no transaction, just signature).
Investor goes to the UI, sees the best price based on all current orders. They have no optionality; always offered the best market price.
Investor enters TH amount they want to buy. The UI recalculates the final price (in case multiple orders are required to fill the size).
Gives approval to draw USDT token from their wallet. MetaMask popup with ETH transaction - once per address.
The miner and the investor have the option to deploy a DSProxy wallet to simplify batch token redemption. DSProxy smart contract wallet that can be used to receive Long and Short position tokens on the investor and miners behalf. DSProxy enables a user to perform complex batch operations on-chain in one block. Each daily market protocol contract deployment creates two associated ERC20 tokens (long & short). Without a DSProxy wallet, a token holder will need to a) approve and b) call settleAndClose on each days contract they entered into. In some cases this could be a considerable number of transactions. If a miner has, for example, sold contracts over 2 months they will need to submit 60 transactions to redeem all their short tokens. Using DSProxy this can be batched to be executed in one transaction to drastically improve the UX. One downside with DSProxy is, however, it’s initial deployment gas cost but this is outweighed by the savings from batch redemption.
0x v3 contract enables custom logic execution on order fill. That logic can mint Market protocol position tokens () and distribute them to buyer and seller atomically within a single 0x ‘fillOrder’ transaction. Such orders are fully-compatible with the rest of 0x infrastructure and libraries. The diagram below shows the interconnection of all technical components in the system.
The custom smart contracts in the honey lemon system are now briefly discussed. Contracts outside of 0x protocol and Market protocol are:
- responsible for deploying, settlement and keeping the list of daily MarketContract and PositionToken instances. Proxies market protocol position token minting to the daily contract. Emits an event that our indexer captures to keep track of all entered contracts and their prices.
- an implementation of 0x that enables custom logic execution on 0x order fill. Interacts with MarketContractProxy to mint position tokens.
- an instance is deployed for each user to enable redemption of multiple position tokens at once. Position tokens are minted to DSProxy, this allows users to redeem multiple contracts in a single transaction, without having to give approval for each position token (this is particularly useful for miners who are likely to hold multiple contracts).
All contracts in the honey lemon service have been audited by PeckShield. The report can be found here.
0x API - used by the front-end to store signed 0x orders. Keeps track of order state and fillable amounts. Returns a sorted order book of fillable orders. Interacts with 0x Mesh instance to perform some of the functions. We use the API docker image as-is.
0x Mesh - is used by 0x API to keep track of order states and fillable amounts. We had to fork the code and modify the logic that calculates order fillable amount.
Graph Protocol node - indexes on-chain events and provides a GraphQL API to query them. Is used by the front-end to get the list of current/expired contracts.
See for details.
yarnmake local-resetyarn run contract-tests
yarn run honeylemon-service-tests
yarn run integration testsyarn starttruffle migrate --network kovannpm run lint-fix./ci/coverage.sh coreHoneylemon Alpha has been audited by Peckshield.
Last 28 days payoff index - used to calculate payoffs at contract settlement.
Order is sent to the server to be stored in a DB (0x relayer / mesh node)
The miner optionally can ask the server to remove the order. Canceled orders require on-chain transactions.
Miners see their contracts with status: not filled, filled, partially filled, settled. The data for the list is read from chain checking all PositionTokens in the wallet as well as from the API using open 0x orders created by the current wallet.
After contract settlement miner can withdraw excess collateral from MarketCollateralPool contract by calling MarketCollateralPool.settleAndClose
Once the tx is mined both miner and investor receive Market position tokens
After contract settlement investor can claim imBTC reward from MarketCollateralPool contract by calling MakerCollateralPool.settleAndClose.
Postgres DB - stores data for 0x API and the Graph Node.
IPFS node - is used by the graph node.
Mobile
The Honeylemon Mining Revenue Contract is the first of a series of Mining Revenue Contracts designed to replicate the payoff of existing cloud mining.
The Honeylemon 28-Day Mining Revenue Contract is a forward-like product that settles to the market-wide block reward and fees per terahash over 28 days as published in the BTC Mining Revenue Index (MRI_BTC), with a 125% max revenue cap for the buyer. The buyer pays a fixed price in stable coin (USDT) upfront and later receives the mining output in ERC-20 representation of BTC (wBTC) upon contract settlement. Honeylemon contracts are built upon Market Protocol and 0x Protocol .
Honeylemon dApp provides a simple mobile-first trading interface and a one-sided orderbook, allowing sellers (miners or traders) to be short both network difficulty and BTC price. This allows sellers to receive cash upfront and hedge mining risks, and gives buyers the opportunity to receive mining payoff without the hassle of mining operations.
The BTC Mining Revenue Index (MRI_BTC_d) represents the network daily average block rewards plus fees earned in BTC per 1 terahash (TH) of hash power in the past d days. MRI_BTC_d follows the mining industry convention of Full Pay-Per-Share (FPPS) approach.
For example, MRI_BTC_1 represents “1-day BTC Mining Revenue Index” (abbreviated as MRI_BTC). MRI_BTC_28 represents the “28-day BTC Mining Revenue Index”.
MRI_BTC_d represents the d-day BTC Mining Revenue Index. The oracle will publish the 1-day Mining Revenue Index MRI_BTC_1 at UTC 00:01 each day, abbreviated as MRI_BTC.
avgHashrate_d is the average hashrate starting from block height i over d days
The index MUST have a clear physical meaning.
The index SHOULD closely replicate miners’ revenue in reality.
The index SHOULD make the contract easy for miners to trade in order to hedge the risk exposure of mining practice over some certain period of time.
The index SHOULD be consistent with the mining industry conventional practices.
Honeylemon admin maintains an oracle that posts MRI_BTC on-chain. This data is used by the Market Protocol smart contracts to calculate payoffs at settlement. Currently the oracle is centralized and operated by Honeylemon admin. The oracle component will be redesigned towards a more trustless approach in the future. The oracle currently provides two indices:
MRI_BTC_1 - used to calculate collateral requirements upon contract creation when an offer is taken.
MRI_BTC_28 - used to calculate payoffs at contract settlement.
A market for a new 28-day contract is deployed each day at UTC 00:01.
New contracts are issued (i.e. long/short positions token minted) when an order is filled.
While Honeylemon does not provide an interface for secondary market trading, the long/short ERC20 position tokens can be traded OTC (i.e. via Uniswap).
Early redemption for collateral prior to settlement is enabled for market makers who hold both long/short position token pairs.
Here is an example of the life span of a MRI_BTC_28 contract.
Bob places an offer of 1,000 TH of the current day MRI_BTC_28 contract at the price of 0.08 USDT / TH / Day. In order for Bob to place this offer, he needs to allocate a collateral in the amount of his maximum possible pay to his counterparty in wBTC upon contract expiration.
Assuming the MRI_BTC_1 is 0.00000833 / TH / Day, then in this case the collateral deposit Bob needs is:
0.00000833 / TH / Day * 28 Days * 125% * 1,000 TH = 0.29155 wBTC
Alice, on the other hand, would like to buy 1,000 TH of hashpower and finds the price 0.08 USDT/TH/Day acceptable. In order for Alice to buy 1,000 TH of hashpower, she needs to pay:
0.08 USDT / TH / Day * 28 Days * 1,000 TH = 2,440 USDT
Once Alice confirms her purchase on-chain, the smart contract then matches Bob’s offer with Alice’s purchase. Then an equal number of long and short position tokens are created representing the corresponding positions held by the two parties.
Bob receives the 2,240 USDT immediately upon transaction completion and his 0.29155 wBTC is designated as collateral.
The payoff for Alice is expected to happen upon settlement of the contract 1 day after expiration, or 29 days after today. The payoff will be deducted directly from the 0.29155 wBTC collateral set aside by Bob.
Since the payoff is capped by the collateral, no forced liquidation would happen during the 28-day lifetime of the contract.
The market for MRI_BTC_28 contracts is NOT one with a traditional Continuous Double Auction (CDA)* system as adopted by many traditional and centralized exchanges. It is an auction house type of market where the sellers place offers with prices and buyers decide whether to take those offers. Buyers are not able to place bids with their desired prices. One can also consider this as a one-sided CDA type system with only offers in its order book.
Although the Honeylemon interface does not support secondary market trading, buyers and sellers who hold the position tokens can directly trade the position tokens on decentralized exchanges such as Uniswap.
The cap of 125% is determined based on analysis of the Bitcoin network hashpower evolvement from Jan 1, 2016 to Jun 1, 2020. The probability of an over 25% increase in BTC hashpower over a 28-day period is close to 0 with statistical significance.
On the other hand, the mechanism of the MRI_BTC_28 contract would not break even in the case that overall hashpower increases by more than 25%. This is due to the fact that the cap is an open piece of information known by all parties of the market and therefore market prices already reflect the cap in place.
The long and short side of an MRI_BTC contract is asymmetrical. The buyer pays in full upfront and thus is not required collateral. The seller, on the other hand must set aside 125% of the then current MRI_BTC_1 * 28 (also the max revenue payoff possible) as collateral.
Since the payoff is capped and fully collateralized, no forced liquidation may occur.
BTC 28-Day Mining Revenue Contracts settle at the earlier of the two:
24-hours after contract expiration (normal settlement),
cap price breach before expiration (early settlement).
If the cap price is not breached throughout the contract duration, the contract will be settled 24 hours after expiration. The settlement value will be the MRI_BTC_28 index.
The settlement timestamp is updated when the settlement value is last updated.
Initial settlement value is typically set within minutes of the expiration timestamp but may also be updated in the event of a settlement arbitration.
In the event of MRI_BTC breaching the cap price prior to expiration, the contracts are settled 24 hours after the breach. In such cases, the settlement value for the long side will be the cap price, and the settlement value for the short side will be 0.
Arbitration, if necessary, happens between a settlement value update time and the corresponding settlement time.
After settlement, the settled value of long positions can be redeemed by the buyer.
Sellers can also redeem the remaining balance of their collateral if there’s a positive balance after settlement.
Honeylemon smart contract supports early contract redemption if an address owns both the short and long position tokens for the same contract. This is convenient for market makers and traders in general to net out their long/short exposure in the contract and unlock their collateral.
Position Tokens are ERC-20 tokens that can be traded on any exchange that supports the ERC-20 token standard. When they are created (through a process called “minting”), wBTC collateral is locked in the Market Protocol smart contract in return for long and short position tokens.
When an order is filled, a long position token and a short position token is created to represent the two sides of the contract. Position tokens are fungible within the same MRI_BTC contract with each position token representing 1 TH / day for the duration of the contract.
i represents the block height
d represents the number of days corresponding to BTC Mining Revenue Index (MRI_BTC)
N_d represents the number of blocks produced within d day(s)
Difficulty_i represents the value of network difficulty at block height i
Coinbase_i represents the amount of block rewards at block height i
Fee_i represents the amount of fees at block height i
Long position collateral: a buyer pays USDT upfront without the need for actual collateral.
Upfront cost in USDT = entry price * quantity
Short position collateral: a seller is required to set aside a certain amount of wBTC as collateral in the smart contract until the position is closed or when the MRI_BTC contract is settled.
Collateral required in wBTC = cap price * quantity
There is NO margin call or forced liquidation.
Contract Start
The timestamp the contract starts to trade (i.e. UTC 00:01 of the contract issue date).
Contract Expiration
The timestamp the contract stops trading (i.e. UTC 00:01 of the expiration date).
Settlement Value
Long settlement value = MAX(MRI_BTC_28 at contract expiration, cap price) * 28 days
Short settlement value = (cap price - MRI_BTC_28 at contract expiration) * 28 days
Settlement Time
The earlier time of the two:
24-hours after contract expiration;
the unlikely event of a cap price breach before expiration.
Arbitration
The process of updating settlement value in event of settlement value in dispute.
Withdrawal Period
Buyers and sellers may withdraw their settlement value after settlement.
Position Tokens & Naming Method
Long/short positions are represented as ERC20 tokens, named in the following format:
index name-token symbol-forward length-start date-direction.
For example, the long and short position tokens of a 28-Day BTC Mining Revenue Contract starting on June 1, 2020 and expiring on June 28, 2020 are, respectively named
MRI-BTC-28D-20200601-Long
MRI-BTC-28D-20200601-Short
Long and short position tokens are fungible within the same MRI_BTC contract.
Each position token represents 1 TH / Day of hashpower till contract expiration.
Protocols
Market Protocol + 0x Protocol
Description
A BTC Mining Revenue Contract represents the amount of Bitcoin earned with 1 terahash (TH) of hashpower per day for 28 days.
Trading Currency
BTC Mining Revenue Contracts are bought and sold in USDT.
Settlement Currency
The BTC Mining Revenue Index (MRI_BTC) is denominated in BTC. The contract is collateralized and settled in wBTC.
The BTC/wBTC precision is 1 satoshi or 1e-8.
Tick Size
1e-6 USDT is the minimum price movement.
Contract Size
1 TH (per day for 28 days) is the minimum increment of contract size.
Cap Price
125% of the last updated MRI_BTC when a contract offer is taken, denominated in wBTC.
Cap price determines the collateral requirement for issuance of short positions, and caps the maximum settlement value for long positions.
Collateral Requirement
Minter Bridge
0xF5F91F83872727aB02E8AfED2ca8e14EF2cA34C0
Collateral Token (wBTC)
0x3212b29e33587a00fb1c83346f5dbfa69a458923
Payment Token (USDT)
0xdac17f958d2ee523a2206206994597c13d831ec7
Contract
Address
Market Contract Collateral Pool
0x4FD0B30A721955bbaF60502A75A04A24Dc466B08
Market Contract Proxy
0x3270070240747337Dbc27C7C7CD70D1921098eD2
Minter Bridge
0x5D35B6dB6d6FF772A2F9B660D028aa671752b644
Collateral Token (wBTC)
0xE2F58b9747e0b417C0D4c36390Ea40E1e064D592
Payment Token (USDT)
0x3CE983761C26c2F36CB438a3B0103Aa72D43B299
Example in this tutorial uses Chrome Browser and Metamask Wallet extension.
1) Enter url in browser: juice.honeylemon.market , then click Connect Wallet to Trade, select Metamask then Unlock (log in) your Metamask wallet.
2) Go to Buy Contract page through either Homepage selection or Sidebar Menu
Enter quantity under either Budget tab or Amount tab. If you have already entered Budget in USDT, then switch to Amount tab, you will see pre-filled terahash (TH) value based on the budget (USDT) you entered, and vice versa.
If the quantity you entered exceeds your wallet USDT balance, you will see a notification for insufficient funds. In this case you will need to go to Sidebar Menu, click Get More Tokens, which directs you to decentralized exchange Tokenlon.im . Alternatively, you can also go on any exchange of your choice to get more USDT to your Connected Wallet.
Review Price Quote, click on Find Out More to expand details, then click BUY NOW button
3) You will see a 3-step pop-up
Create Honeylemon Vault
Approve USDT
Complete Payment
If you have completed the first 2 steps through a previous purchase, you will only be prompted to the 3rd step: Complete Payment. Click the Buy button, then click Confirm button on the Metamask pop-up window to submit transaction on chain. Due to the recent surge in Ethereum blockchain transactions, expected wait time can range from 30 seconds to 15 minutes.
4) Once the transaction is mined onto the Ethereum blockchain, you will be re-directed to your Portfolio page. Your position will show up under ACTIVE tab, within Contracts Bought (Long) table. If your position does not show up automatically, you may wait for 30 seconds for the page to auto-refresh, or follow the line of instruction under the ACTIVE tab to manually refresh.
You may review your Active Long Position Details by clicking on the three dots on the right hand side of the table. You can go to blockchain explorer Etherscan to verify your transaction details on chain.
Buyers are subject to Ethereum transaction fee (gas) and 0x protocol fee. Sellers are subject to only Ethereum transaction fee (gas).
Honeylemon Alpha does not charge any fees at the moment.
While actual costs of the protocol function varies case by case, we provide the following table for guidance.
Function
ETH Price: $ 250.00
Gas Price: 30 Gwei
Average Number of Orders per Fill
Buyers Only: 1.5 Orders per Fill
If a buyer places a large order, multiple orders or use Honeylemon services more than once, create a Honeylemon Vault will deploy a DSProxy contract for the connected wallet, which reduces future gas fee and streamline the redemption user experience. DSProxy contract holds position tokens on behalf of the user. Deploying DSProxy is an optional one-time operation.
If a seller places a large offer, multiple orders or use Honeylemon services more than once, create a Honeylemon Vault will deploy a DSProxy contract for the connected wallet, which reduces future gas fee and streamline the redemption user experience. DSProxy contract holds position tokens on behalf of the user. Deploying DSProxy is an optional one-time operation.
Average Number of Contracts per Batch Redemption:
Buyers: 2 Contracts per Batch
Sellers: 5 Contracts per Batch
Redeem Positions
Ξ0.0060
$1.51
28%
One-time cost per transaction.
Buyer's Total Fees
Ξ0.0215
$5.37
100%
Buy Contract
Ξ0.0141
$3.53
34%
One-time cost per transaction.
Batch Redeem Positions
Ξ0.0064
$1.59
15%
One-time cost per transaction.
Buyer's Total Fees
Ξ0.0414
$10.35
100%
Cancel Offer
Ξ0.0020
$0.51
22%
One-time per cancellation (optional).
Redeem Positions
Ξ0.0060
$1.51
64%
One-time cost per transaction.
Seller's Total Fees
Ξ0.0094
$2.35
100%
Create Offer
Free
Free
0%
No cost to offer.
Cancel Offer
Ξ0.0020
$0.51
6%
One-time per cancellation (optional).
Batch Redeem Positions
Ξ0.0119
$2.97
34%
One-time cost per transaction.
Buyer's Total Fees
Ξ0.0349
$8.72
100%
Typical Cost
Notes
DSProxy Deploy
654,000 * Gas Price
Optional for both Buyers and Sellers.
One-time cost per address.
Payment Token (USDT) Approval
44,456 * Gas Price
Applies to Buyers.
One-time cost per address.
Collateral Token (wBTC) Approval
44,468 * Gas Price
Applies to Sellers.
One-time cost per address.
Cancel Offer
67,793 * Gas Price
Applies to Sellers.
Buy Contract
365,036 * Gas Price
+ 70,000 * number of 0x orders filled
Applies to Buyers.
Redeem (Batch)
88,881 * Gas Price
+ 61,552 * number of contracts in a batch
Applies to both Buyers and Seller.
Fees
Cost (ETH)
Cost (US$)
Cost %
Frequency
Payment Token USDT Approval
Ξ0.0013
$0.33
6%
One-time cost per address.
Buy Contract
Ξ0.0141
$3.53
66%
Fees
Cost (ETH)
Cost (US$)
Cost %
Frequency
DSProxy Deployment
Ξ0.0196
$4.91
47%
One-time cost per address (optional).
Payment Token USDT Approval
Ξ0.0013
$0.33
3%
Fees
Cost (ETH)
Cost (US$)
Cost %
Frequency
Collateral Token wBTC Approval
Ξ0.0013
$0.33
6%
One-time cost per address.
Create Offer
Free
Free
0%
Fees
Cost (ETH)
Cost (US$)
Cost %
Frequency
DSProxy Deployment
Ξ0.0196
$4.91
56%
One-time cost per address (optional).
Payment Token USDT Approval
Ξ0.0013
$0.33
4%
One-time cost per transaction.
One-time cost per address.
No cost to offer.
One-time cost per address.
