One of the most common problems with contracts is that we do not know how to promote them properly. Another problem is, we do not know how to use them properly as we would use corporate shares (this second problem is part of the first one, but they are still different). After all, we are just programmers, not Warrens Buffets, right?
At this point I am supposed to say few words about corporate shares... Which I really would rather do not. Shares allow you to profit from the company, as it gets profit. Also, price of the stock can go up and down as market breathes. Also, regulating comitees can attack you any moment as your contract is "just like a share, but you haven't registered". Finally, share holders can vote, affecting company's policies.
Out of all those, I am only going to address participating in profit (for share holder), protecting share holder's money by not allowing the share to drop below its initial price and (for a company that is represented by a contract) making shares sold to work for the company's objectives.
Note that this is just one of countless ways the task can be approached. I use it to demonstrare a contract that is a bit more complex than "grab and run" Duke of Ether.
Also note, that Vitalic Buterin mentioned similar objectives in long term Ethereum dev. plan, so we are probably on the right track.
Let's address these issues by creating a mechanism allowing the person - any person - to invest in our contract. And as the investment is made, that person will probably spread the word, as the more he/she advertizes the contract, the higher the dividends are.
In other words, we have a tough decision to make: shall we share our profits with strangers and if so, how exactly should it work. There are many ways of getting money in exchange for future profit, from simple "give me money and I promise..." aka crowdfunding, and to the government regulated corporate shares. I am going to choose something in between: something that does not require implementing a stock exchange contract with its bells and whissels, but still capable of providing the shareholder with some profit that is connected to our contract's profit.
Note however, that this example is not exactly the best: our Duke contract does not require investments in order to work. Let me explain. If I had a casino or a "dice" game, a person entering the game would have to wait for others to join, which, if the casino is not very popular, might take days. Unless casino had funds of its own, so that the game could start immediately: the player bets, casino meets the bet with its own money, game begins. In this case, casino would benefit from some initial investments, though not necessarily large ones.
If I ran a coin exchange, I would need even more "free cash", as an exchange should be ready to handle orders that are potentially large.
But in case of a "Duke", there is no reason to bring investments, as the game works as is, requiring no free funds. Except, as I mentioned above, for the promotion part. If the investor brings us some money, we can expect, at least, that he'll "like", "repost" and "tweet" the information, acting as our agent.
Is it going to be enough? In other words, what if a person purchases $1000 worth of our "stock", only to "repay" by a single "tweet"? Well, this is a risk, and I will explain dealing with it below; for now: if investor does not act, price does not meet his expectations, and he'll sell our contract's shares to someone who is more active.
Still, we have to pay part of our profit to total strangers, not knowing if they will do at least something. But look at it this way: the Duke contract is simple, we spent relatively little time on it, and if we do not promote it, we'll get nothing in return. There are, after all, many other Dukes, Kings and Presidents out there in the block chain. So yes, we'll have to pay for promotion. Here is how.
First of all, we create a business - any business we want to promote. The only requirement is, it should earn money via the Ethereum contract, so that all its profits are transparent for shareholders. In this example, I am going to use Duke contract, after all, no mater how simple, it IS a business, and it can earn money - when promoted properly.
Then we take the idea from ethereum tokens: we create an entity that can be sold in exchange for Ethereum at a predictable and initially small price. By small I mean some basic minimum price, just to make sure our "token" (Note quotes: it is not a standart Ethereum token. Just to establish a term, let's call it "duke": one duke is one "token") does not go to zero. Then we redirect Duke's profits into it. The more Duke earns, the higher the cost of a "duke" is:
duke = duke_min_price + profit / numberOfDukeTokens
Below I am going to walk the you through the logic of the pricing model, to explain choices that were made. To do it, I am going to consider some choices, including bad ones, so that the final choice became more clear.
The obvious question we get after looking at the formula above is, how many "dukes" should we create and what are the rules of minting them. To answer it, we need to figure out what we want from this strange pseudo-currency. First, whoever holds "dukes", has to be rewarded for Duke contract's profits. We can either have fixed number of "dukes" and increase their price, or fix the price and increase number of "dukes". Technically, there is no difference. However, as the profit arrives, we have to divide it between shareholders. If we mint 1,000,000 dukes, and you are the only happy holder of one duke, you will get 0,000001 of the profit, which may or may not keep you motivated.
So should we distribute profit between REAL holders of shares?
duke = duke_min_price + profit / numberOfDukeTokensCurrentlyInPosession
This formula creates another problem: if you are the only owner of one duke, you'll get ALL the profit, which is kind of not deserved. Consider this: the profit is 100 ether, you paid 1 finney, and then all the profit is distributed to you... what kind of business is it?
In the world of "real" tokens the problem is being solved by ICO (initial coin offer), in other words, if the contract fails to get certain amount of funds, it returns money and that's all. But we want the system to work permanently, without dividing it to pre- and post- ICO.
We can limit profits (say, to 100% per year, which is very good considering that ether goes up by itself and the profit in $$$ will be 100% * ethereum growth factor). But it is just another way of saying "we don't know what to do". Also, what if our contract is very successfull this year, and not very successfull the next year?
Ok, we can use Exponential Moving Average of profit... but we still do not know how to distribute it (the profit)! It seems that we have two cases to consider: first, the contract is not very popular (yet) and second, it is (finally!) popular so we have many investors. Let's face it, we do not know how many investors is "many" for our Duke. Ten? Ten thousands? So part of a problem is purely psychological, we can not make a choice because we do not have criteria. This is a very popular "antipattern", so one should be aware of it.
At this point we have considered and rejected enough flawed scenarios to switch to a final one.
1. we are going to create a fixed amount of shares. Say, 10,000.
2. all shares are originally owned by the contract (by its owner) and all profit from the unsold shares goes to the contract.
3. a share holder participates in profit, proportionally to number of shares owned.
4. there is a small initial price of a share. We can not sell cheaper than it.
5. a contract can buy shares back at shares' current price (small comission applies to both buy and sell operations).
6. to rule out irregular nature of profit, we will calculate an exponential moving average of it, which is just a smoothed version of a "spiky' profit line.
As we work on a potentially valuable project, we need to make sure that at some point we can sell it (the project) for a profit. To do so, we are going to implement a standard ownership contract and make our contract its child.
As we are creating something that is intended for a long term investments but can, nevertheless, be traded short term, we need to protect ourselves against "market makers" that would buy and sell in order to move the price. I am not sure if it is that important in case of a Duke contract, but if you use the same approach with Ford company, you better play it safe.
Surprisingly, we have a solution, same one Ethereum used to guard the blockchain against endless cycles: we introduce a penalty (price of operation, gas price). In our case, we'll simply set a comission on sales, something between 1 to 5% (see withdrawStocks() function below).
Then we need to attach our Duke to the contract. To do it, we implement the ownership as
Ownable <- ShareHolder <- DukeOfEther
When you deploy the contract in a test environment and reload the HTML page (below), make sure the active account is not the eth.accounts. This is because you are the creator/owner of the contract and you have all initial tokens. We do not allow the owner to do some operations (as otherwise he could run away with all the money). To test the contract from the non-owner's perspective, type in the geth's console (the second geth we opened works in console mode, in case you have forgotten):
This will make another wallet "active", providing that you have more than one (you can add wallets (accounts) from Mist or directly from geth, Mist is easier).
In other words, here is a collision: in the code, I have forbiden the owner to buy tokens, but to log into an account (testing environment), we use web3.eth.accounts. Keep that in mind when you will test the code: deploy the contract (say, in Mist) from the SECOND account. Then test it from the FIRST one.
We have a working and reasonably nice-looking contract, so this is the time to re-address the theory behind ShareHolder in general and profit calculation in particular - just to make clear what is it we have.
There is a pretty much traditional way of estimating the price of a company; it is assets and profit based. First, a company has some assets of value (cash, buildings, patents, pending payments, debts etc), they are worth certain amount of money. In our case, the "company" (which is our contract) has money Share Holders invested in its tokens. So if a company has 100 tokens distributed, the company costs 100 * price of a token.
Note, that Share Holders could have purchased shares at 0.1 ether, and then the cost went up - it is ok, company price is not a constant. Also note that the contract itself may be of value as some "real world" company might want to purchase it from us. Or not. We ignore it as in our case it is improbable.
The second part of the price is based on profit, basically, we state that the company is worth its 10 years' profit (in the real world, in the fast changing world of block chain it can be set to any number, so we use 5 years). Then we add asset and profit based estimations - and voila!
Now, equipped with this knowlege, let's see what the "fair" price of our token should be.
First of all, let me remind you why I am not going to follow a traditional path, which would be going to ICO (Initial Coin Offering). ICO is not directly attached to a contract's profit. It is nothing but a fund raising. Nothing prevents a coin issuer to a) fail (and so the price of coins you have goes to zero) or b) to disappear with all your money, yeilding pretty much the same result.
On the contrary, a ShareHolder contract is designed in such a way that its price will never go down. You pay for tokens, you hold them and - very important! - you can always sell them via the same contract. Yes, the ShareHolder contract is its own "stock exchange". Once you paid, a ShareHolder-based contract holds your money (minus a small comission to the owner), and that's it. It is not a fund raising event, in other words, a contract owner can not touch your money. See the next paragraph.
A price of the token is initially set to a minimum, then as profit (of a contract ShareHolder contract is attached to, in our case it is "Duke") accumulates, the price goes up. Therefore, it will never go down, if you sell your token, you will get more (minus a small comission) then you have invested. In ether.
About the last "in ether" comment. A simple example. One costly mistake people do when playing Forex with crypto currencies is when they think in terms of "profit in dollars". Say, you have a wonderful strategy yeilding 100% profit per year. So you start trading bitcoins with $1000 and year later you have $2000. Did you win?
The answer is NO. You have lost, as a simple "buy bitcoin and hold" strategy would give you ten times more. In other words, you have started with 1 Bitcoin and ended up with 0.2 Bitcoin ($1000 vs $2000).
So as long as the market goes up, it is a good idea to count profit in crypto currency you are dealing with, not in fiat (dollars).
Back to ShareHolder: price of its tokens in ether can only go up, period. An owner of a contract gives part of his profit to you. Why? One of possible reasons is spreading the word: as an owner (of Duke of Ether, in this example) I am paying you: here, the more people you bring to Duke's pyramid, the higher your profit will be. This is not exactly a salary (though I am thinking about writing such a contract), but quite close to it. If all works as intended, share holders will be motivated to create posts in social networks, bring up the web sites, wear T-shirts with commercials promoting the Duke of Ether :) Who knows.
Let's walk through the profit calculation ShareHolder uses.
The "Config. constants" block contains contract's "settings", such as percent of the profit the contract's owner receives etc. In a current contract, we use 1% as a comission for buying / selling shares and 5% - comission on profit a contract sends (5% of, say, 4% that Duke sends to addToShareHoldersProfit()). What does it mean: "5% of 4%"? See, Duke of Ether makes some profit for the owner, by charging a small comission whenever a new Duke takes the throne. We can not charge more than few percents, so 4% is a current fee I use in the code. In other words, in order for a company to be alive, the owner shouldn't take all its profit.
Following the Bitcoin's example, we are going to limit the number of shares our "company" issues. Unlike Bitcoin, a share can not be divided - one share is a minimum one can buy or sell. This, together with a tiny initial share price, creates a certain danger. On one hand, we want people to buy our shares - the more people buy them, the more advertizing our little project gets. On the other hand, what if someone buys ALL shares at initial price (which is 1 finney) and all our profits will go to that person with no or insufficient efforts on his side?
To fix this glitch, we are going to issue shares DAILY; we hope that as profits (and share prices) will go up, people will notice our company and invest in it.
Here we have our next problem: let's say our company is an overwhelming success and people are DYING to buy its shares. If that fact does not affect the price (no corellation between price and demand), then we (the owner of a contract) are going to loose potential profit and some kind of shortage of supply is created: whoever pays first, gets shares, rest of people get nothing.
An obvious solution is to create an auction of some kind (in real time trading systems it is called a "glass"): you place an order stating "I want to buy N shares at X price". Now, say price of a share, based on the money contract holds (we are only talking about Share Holders' money, which is money they paid for shares plus profit they got from an underlying contract). Say, the price of a share is 1 ether, and today we are issuing 10 shares. Now, we look up the list of orders and see that there are two orders: buy 5 shares at 3 ether and buy 20 shares at 1 ether. Then we sell 5 shares at 3 ether and 5 (total supply is 10) shares at 1. The order for 15 ether for 1 ether (20 - 5 = 15) stays in the list of orders, unfulfilled.
In other words, we can allow our clients to buy (only buy!) on a hype, on expectation that the price will go up. Most likely, the higher a person buys, the more we should expect in terms of him/her spreading the word and bringing us clients.
There is a second way we can calculate price based on demand, however. Let's say we "issued" 100 shares at 1:00 am and they are all sold at 1:15. Then tomorrow we can rise the price 10% over the "calculated price". if next daily supply of 100 shares is sold before 24 hours interval is over, we increase the price again, next day, else we decrease it (down to the calculated price, in few steps).
In terms of computational price and code complexity, the second approach is better, so we definitely have to choose it. In the code (below) it is handled by uint m_nPriceOnDemandIncrease = 10; if shares supplied are sold faster than in 24 hours, increase the price 10% over the price that was calculated based on profit.
An additional interesting question is, should we issue just fixed amount of shares per day, or should it be a DECREASING amount. For example, Bitcoin's supply is decreasing, which makes it possible (in theory) to keep the sale running for over 200 years.
To answer this question, we need to analyse our contract's use, in other words, what is the expected profit flow from it?
If the "underlying contract" we use is "Duke of Ether" as we listed it above (note that below it is going to change), then there is no point to think about remote future! The Duke is a pyramid and sooner or later it will get stuck. No more Dukes means no profit for Share Owners, and as soon as they figure it out, they will sell their shares, and that's all.
The first and obvious solution is to modify Duke contract (which I am going to do in one of the following chapters), so that it could work infinitely. We can either make Duke "expire", as it was done in the original King of Ether, or make new Duke lines available (the contract holding not one country, but many countries, each owned by a separate Duke).
The second solution is a bit more ambitious: let's have MANY contracts, different ones, that rely on ShareHolder for advertizing purposes (in other words, pay Share Holders to spread the word). The idea is to build an "advertizing empire", a contract any other contract can pay to, hoping that Share Holders will get interested enough in promoting it - in exchange for profit.
In that case our ShareHolder contract might exist long enough. So, back to the original question: should we slow down the supply of shares? Pro: the later we sell a share, the higher the price and our profit, too. Con: what is better - selling 100 shares now or one a year later? It depends on the price, and we can not predict it at the moment.
There is, of course, a third way: we can sell our 36,500 shares in 365 days, and then continue issuing shares at a decreasing speed (this approach is just a twist on selling on a decreasing speed from the very beginning).
This is one of many situation in business, where a business person (that would be us) can not make a justified decision as the information simply isn't enough. That person should be, no mater how strange it sounds, not smart but, on the contrary, bold and even to some degree stubborn: to choose one of possible choices and to hold onto it does take being stubborn.
I choose to make 100 shares per day available, plus I am going to implement an additional price multiplyer in case demand is too high. The price will be calculated as 5-years' profit, and to make it smooth, I am going to use an EMA (Exponential Moving Average) of profit.