HeroToken Purple Paper

Jul 19 · 8 min read


As part of the product release, Hero is releasing this ‘Purple Paper’ to give a public understanding of the technological details surrounding how the product will work.

The Hero marketplace relies on a set of Ethereum smart contracts to facilitate financial relations among platform participants. Besides determining the eligibility of access to the marketplace, such set of smart contracts codifies the protocol used for submitting loan requests, pricing, funding and repaying them.

The contracts are available via GitLab here

The diagram provides a high-level overview of smart contract interaction in Hero:

The smart contracts can be roughly classified into 4 modules:

  1. Subscriptions, which handles user subscription through deposits of HERO tokens and the referral program.
  2. Platform usage authorization, which other contracts query on whether an Ethereum address is eligible for interaction with the platform.
  3. Lending, which encompasses the main logic of loan funding and repayment.
  4. DAI integration, which allows use of DAI as a stable medium for lending.

In the following sections, each module is described in greater detail.


This module constitutes three contracts: the existing Hero ERC20 utility token, the deposit registry and the referral tracker.

The Hero token follows the ERC20 standard, meaning that it is freely transferable to any address and can be used in any decentralized application that works with fungible tokens. In Hero platform, a fixed amount of tokens is deposited by an address in order to interact with the platform.

The deposit registry accepts and tracks Hero deposits. In order to deposit, a user must first allow (by calling the ERC20 approve()function) the deposit registry contract to spend their Hero tokens, and then call the deposit’s function depositFor() to lock these tokens and be cleared to use the platform.

Verified users can cancel their subscriptions by calling the withdraw() function, which sends their membership tokens back to them.

Finally, the referral tracker tracks the number of referrals registered for each referrer’s address. To register a referral, in the deposit registry, instead of deposit For() the user calls depositForWithReferral(), specifying the referrers address.

Platform usage authorization

This module constitutes the KYC registry contract and the authorization proxy contract.

The KYC registry simply keeps a record of addresses that are eligible to use the platform. Addresses are added to this registry by Hero when users complete the verification process for their accounts. Different KYC requirements exist for lenders and borrowers.

Hero has currently partnered with trusted identity verification providers to manage the KYC registry and will keep investigating the viability of leveraging fully decentralized KYC solutions when they are at the appropriate level of maturity.

The authorization proxy is a convenience contract that forwards calls to the KYC registry and the deposit registry, serving as a single source of truth for other contracts regarding the users’ eligibility to interact with the platform.

In most cases, users of the platform are not required to interact with contracts from this module.


This module constitutes the Loan Dispatcher contract and numerous uniform Loan Contracts created by the Dispatcher.

The loan dispatcher implements the factory pattern — it creates new loan contracts when its deploy() function is called by an address that has passed KYC.

Each loan contract represents a single loan and facilitates all the stages of its lifecycle, from creating a loan request, its pricing phase and maturity.

When the user creates a new loan contract through loan dispatcher, it starts out in the funding phase. The lenders submit tokens (currently, DAI) to the contract through the DAI Proxy (more on that below).

Once the loan amount is reached, the contract switches into the repayment stage and allows the borrower to withdraw the loan amount by calling withdrawLoan(). In case the loan goes to the repayment period, but the borrower fails to withdraw funds (because of, e.g., losing their keys), the Hero team is able to intervene by freezing the contract and allowing the lenders to withdraw their DAI back.

The borrower must repay the loan with the interest by the end of the repayment period. Currently, if the borrower doesn’t repay the loan, the Hero team will facilitate further interaction between the borrower and lenders. At the later stages, a separate ecosystem of collection services is to be introduced to further decentralize the platform.

The borrower also uses DAI Proxy to repay the loan, and then lenders call withdrawRepayment() to retrieve their contribution plus interest.

Motivation for using the factory pattern

The primary advantage of this pattern is modularity: currently, only a single loan type is available, but in the future adding new loan types (e.g., a loan with monthly repayments) would be as simple as creating a new loan dispatcher that deploys contracts for this new type of a loan.

Measuring time

Note that time is measured differently during the auction period and the repayment period. During the auction, the growth of interest rate is a sensitive parameter that is dependent on time, so using timestamps would render the system susceptible to manipulation by miners. Therefore, block numbers are used instead as a measure of time.

Conversely, over prolonged periods measuring time in blocks becomes imprecise, since changes in mining power can increase or decrease the rate of block production. Therefore, for the repayment period, block timestamps are used — although they can be manipulated by up to 10 minutes, this is insignificant on the scale of weeks or months, which is common for the repayment period. The length of the repayment period is set in days.

Loan pricing

Hero uses a Dutch auction model in loan funding. In a Dutch auction model, instead of a rigid interest rate, the borrower specifies a maximal interest rate. At the beginning of funding, the loan starts out at a 0% interest rate, increasing to the maximal rate over the course of the auction period. Once the loan is funded, all lenders get the interest rate that was reached at the moment of the last contribution (e.g., if the loan was funded in the middle of the funding period, the interest rate will be half of the maximal interest rate).

While at first glance this sounds more complex than creating a loan request with a single interest rate value, in reality this introduces a market price discovery mechanism that simplifies economical reasoning for lenders and ultimately contributes to a successful funding of a loan.

With a rigid interest rate, a borrower may set a rate only to find out that it is too low to attract lenders. If, instead, they set a high enough maximal rate, these lenders would wait for a moment where the rate has increased to a level that is acceptable to them and only fund the loan at this moment, resulting in efficient price discovery instead of the borrower trying to guess the optimal rate by hand.

In cases where the borrower is a prime candidate with good credit history, this mechanism could be even beneficial for the borrower, since lenders would compete to buy into a good deal as soon as possible, funding the loan early, which ultimately results in a lower interest rate.

DAI integration

This module constitutes the existing DAI ERC20 token and the DAI proxy.

DAI is an algorithmic stablecoin that was chosen as a medium for loans to minimize volatility risk, which would be present with floating rate cryptocurrencies, and would be especially severe considering the time-prolonged nature of loan contracts.

The DAI ERC20 is only assumed to implement the basic ERC20 interface.

In Ethereum, the contract can detect when it receives Ether and act accordingly, but such a mechanism is not present for ERC20 tokens. Although it is possible to implement such functionality in an ERC20, the current version of DAI does not support it.

Usually this issue is solved by requiring 2 transactions from the user when a smart contract is paid with some ERC20 — one for allowing the contract to spend funds, and another for the actual transfer. However, this is not convenient when the user interacts with the platform on a regular basis.

Instead, Hero uses a special DAI proxy contract that significantly streamlines the interaction. The user has to allow the contract to spend an unlimited amount of DAI only once, after which they can use this proxy contract to fund or repay loans with DAI many times, by calling either fund() or repay() while specifying the contract’s address. The proxy contract then notifies the loan contract that DAI was sent, triggering the necessary logic.

Note that even with unlimited allowance, only the user themselves can call the DAI proxy contract to spend those funds — token transfers are only performed in specific immutable functions in the contract, and no user can call these functions for another user.

Also note that with the aforementioned factory pattern the proxy may be reused for multiple types of loan contracts, once they are deployed in the future, as long as the new contracts adhere to certain interface and implement functions called in fund() and repay() (namely, onFundingReceived() and onRepaymentReceived()).

Further notes

Decentralization in the Hero protocol

Hero retains certain centralization points in its contracts. These points include:

  1. Hero’s ability to censor withdrawals of Hero token deposits. This is done in order to prevent abuse of the referral system, since malicious users could try to receive a 50% premium on their Hero tokens through registering Sybil addresses. Verified accounts — users that complete the KYC process successfully — will be able to withdraw their membership deposits at any time.
  2. Hero collaborates with a trusted provider to act as the source of truth for the KYC registry of addresses. Hero will keep monitoring the maturity of decentralized KYC solutions so that account verification can take place without intermediaries.
  3. In case of a loan default, Hero will facilitate an arbitration between the debtors and creditors with the objective of settling each position. Hero will keep investigating the possibility of implementing a decentralized marketplace of collection services to remove this centralization point
  4. At the point where the loan is funded but the borrower hasn’t withdrawn the funds yet, the Hero team is able to call an admin-only function to freeze the funds in the loan contract and allow lenders to retrieve their contributions. This is done to prevent loss of funds due to, e.g., borrower losing their keys before withdrawing. This is meant to be an emergency procedure not to be used during normal operations

Contract user interaction

When we say “user calls a function”, we mean that the Hero UI forms and sends the transaction on behalf of the user, only requiring the user to sign it through a browser client such as Metamask, while the user only interacts with a web interface. However, it is possible for the user to interact with the smart contracts directly, using an Ethereum client of their choice.


Written by


HERO Origen Token: Promoting Financial Inclusion, Transparency, and Efficiency in Southeast Asia http://herotoken.io/

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade