Ethereum Tutorials

ShareHolder Contract User Guide

About this tutorial

In this tutorial we are going to explain the concept ShareHolder uses, review some practical cases where one can benefit from using it, and provide a complete hands-on step-by-step guide.

  1. ShareHolder: the concept.
  2. ShareHolder: practical cases.
  3. ShareHolder: step-by-step guide.
  4. ShareHolder: programmers guide.
  5. License.

ShareHolder: the concept.

ShareHolder Web Site.

No mater how nasty the license agreement is, there always are people tempted to (illegally) copy the contract in order to use it independently. Leaving aside all legal reasons, here are some practical considerations proving that using it through our contract is a better idea:

1. Web Site

2. Advertizing network


ShareHolder contract was created as an "ICO 2.0" solution. It can be used with your contract (any contract in Ethereum block chain) or (with some caveats) with any off-chain business. The contract sends part of its profit to ShareHolder contract, and ShareHolder takes care of it.

Currently, most ICOs use ERC20 contracts: they sell "tokens" to raise funds, then those tokens can be traded on online exchanges at market price. In theory, the more successful is the busines you have raised funds for, the higher the market price of a token.


However it isn't so. While the "real world" companies are bound by rules and regulations, ICOs are not and technically, after fund raising is over, they owe you nothing.

Here comes ShareHolder contract.

Say you have a block-chain based business, for example an exchange. Or a casino. Or a Oraclize service... The point is, it should be based on an Ethereum contract. Then you can write (in that contract, immutable and final) that a certain percent of profits will be sent to ShareHolder. It means that payments will happen automatically and as long as your contracts runs, ShareHolder gets its "share".

What ShareHolder does then is distributing the money among share holders.

It can (as mentioned above, with some caveats) work for an off-chain business, too. Of course for an owner of an off-chain business to send part of the profit (think of it as of dividends) to ShareHolder, that business should care for its reputation, as being off-chain it is not forced to make payments by contract's code. But as practice shows, it still works.

The following image illustrates the ShareHolder work flow. As an example contract we chose the "Duke of Ether" game, an "outside" contract sending a profit stream to ShareHolder contract. Note that a single ShareHolder can receive profit from unlimited number of contracts.

ShareHolder can work in parallel with ERC20 contracts, if necessary. Or you can create an ICO based on ShareHolder alone. Share holders can buy and sell their shares, and price of shares steadily goes up as more profit is being sent to a ShareHolder contract.

Of course, ShareHolder also supports bonus shares (for example, you can give free shares to developers team or to bounty campaign participants).


In a perfect world, a SHARE would be a cumulative account: you put money in it when you buy it, and you get it back when you sell it (minus commission). Then a company (one that issued a ShareHolder contract) pays dividends, they go into your account, and price of your share goes up. Now you can sell it at a higher price.

However this business model just means that you will distribute your profit to strangers, for free. To justify issuing shares for the business, we have to turn it to a fund raising action. You SELL shares and take money (fund raising). When you reach the goal of your ICO campaign, you begin sending profit to shares, so their price begins to go up: from zero. Hopefully, at some point you will put enough profit for share holders to have a positive balance.

When you think about it, this is exactly what happens with ERC20 based ICOs, except share holders profit from your business (if succeeded), instead of market fluctuations.

The following picture illustrates the pricing model for shares a ShareHolder contract manages.

First, we begin selling shares at min. price (an initial price). This is a fund raising stage of our ICO, as you can see, the price we offer to buy shares back is zero and funds raised are distributed to the owner.

After the goal is reached, the "buy back" price begin increasing: the more profit our business generates, the higher the price.

At some point we put enough profit to the contract for the "buy back" price to exceed the min. (initial) price. After that point, the both "buy" and "sell" price go up (as more profit is deposited), and the difference between them is just the trade commission.

Therefore, ShareHolder contract makes it unnecessary to use the 3rd party online exchanges: it serves as an exchange itself.

As ShareHolder buys shares back, they can (unless you specify otherwise in your settings) become available for other people to buy.

Say, had a share, and you sold it. Now that same share is back in ShareHolder's pool. ShareHolder owns it, and whatever dividends and price appreciation it has, all belongs to owner of a ShareHolder contract. This is similar to company owning its own shares.

At any moment, a ShareHolder contract can sell that share to any one willing to pay the price. Note that as that share has some dividends in it, its price is higher. So a person buying share pays more than you originally paid. If she sells share, she'll get more, too.

Next dividends, next price increase, and so on.


Normally, a buy and sell operations are performed (by ShareHolder contract, automatically) in exchange for a small commission. An exact commission is set by ShareHolder owner at the time a contract is created. Also, commission (a different one) is charged at dividends (distributed profit) arriving.

Note that commission can not be changed later on, as adding such feature would give contract owner a powerful tool for stealing share holders' money.

One might ask why paying commission on money we send to our contract? Isn't it better to send less? The problem is, sometimes your ShareHolder contract will receive money from sources that are not yours.

If you know for sure that this particular ShareHolder will only receive money from you, you can set profit commission to zero.

Two types of shares

To make a contract more flexible, we have two kinds of shares.

Regular Shares. To buy this share, one has to pay its "current" (initial plus dividends) price.

Bonus Shares. These shares are not for sale. A contract owner can distribute them from owner's pool (it means that other share holders will not loose profits, only contract's owner will). Shares can be sold at any moment, but as their owners paid nothing, they will get nothing. As dividends accumulate, price of both regular and bonus shares goes up.

Bonus shares can be used to reward developers team; this is just an example, in reality, there are many possible use cases. Another example is a "business that is not entirely in a block chain". For example, group of people bought an appartment building and intend to distribute profits via a ShareHolder contract. The money they brought to the business are invested to real estate, so there is no need to ask them to pay for shares.

Regular shares can be used as a fund rising tool, as money share holders pay are instantly awailable to owner of a ShareHolder contract (in exchange for participation in future profits).

ShareHolder: practical cases.

Team Rewarding Scenario

Group of programmers works on a contract and Web site, plus software a company wants to sell. Currently the company has no funds to pay them so it assigns them bonus shares that (a company believes so) will accumulate signifficant value as software sells well.

Ad Campaign Scenario

We perform what is called "airdropping": distribute Bonus shares to any qualified audience. We pay part of our profit as dividends.

The reason is: we expect that share holders will promote our business as they are directly interested in its success. The higher our profits, the higher dividends.

Bounty Campaign Scenario

Usually, a bounty campaign is part of an aggressive ICO promotion only. However nothing prevents you from creating large number of relatively cheap shares and distributing them in exchange for promotion OUTSIDE the ICO time frame.

Fund Rising Scenario

None of scenarios discussed so far is applicable to a fund rising, as during fund rising we need to get money, not bunch of followers we owe money to.

Now, the ShareHolder contract. To run a fund rising, we need to have an access to share holders' money immediately upon purchase. To do it, we can simply sell Regular shares, but treat them as if they were Bonus shares.

Note: there is more than one way to describe the process. We can say we sell shares at high commission. Or we can say that we sell the promise of future dividends... The point is, share holders pay for an EMPTY account (share with no money in it), that is connected to our business. If the business is 100% in block chain, the connection takes form of a bounding Ethereum contract, which makes any cheating impossible.

The image you have already seen above:

ShareHolder: step-by-step guide.

We are going to walk through features ShareHolder contract offers, accessing them from the Web site we put online for your convenience.

As a contract resides in a block chain while Web Browser works with Internet, it is not possible to access block chain from Web Browser directly, without some kind of an additional software. For our example, we are going to use Chrome Web browser and a Chrome plug-in called MetaMask. MetaMask is an easy to install and use software, handling both "talking" to block chain and security issues.

Metamask is a plugin for Chrome browser, it handles passwords internally (safe) and connects fast. You use it to access our "Duke" contract, for example.

First of all, download and install the plugin, the procedure is trivial. As you may not want to keep it always "on", note that you can go to Chrome's "manage plugins" menu, and disable it when you do not need it. Or you can uninstall it, which takes same 10 seconds. Just make sure you do not loose your wallets during uninstallation.

Create an account (again, this is not a MetaMask tutorial, but it is really easy and the program guides you through providing all possible explanations). Add some ether to the account, so that you can pay for transactions you perform.

The contract is located here

If you access it without MetaMask on, you will get an error message.

Wallet Info.

The combo box lists all your accounts (wallets). There is, however, an important point to keep in mind.

First, this combo box is for Geth and some other low-level tools for block chain access. If you use MetaMask, you will have this combo box disabled; instead you will have to switch accounts in MetaMask itself (it has a similar combo box).

For our tutorial, we'll use 3 accounts (1, 2, 3 positions in a combo box above). "1" is there in case someone wants to follow our tutorial using Geth instead of a MetaMask; if you use MetaMask, you will only need 2 and 3. Create them in your MetaMask.

Owner vs. User.

A ShareHolder contract can be created using a Share Hloder Factory contract. If you do it, you (the account you used, in this tutorial it is account 2) will become the owner of a resulting ShareHolder contract. You need it, if you plan on creating your own campaign. However, if you only want to buy/sell shares of an existing campaign, you don't have to create a new contract (obviously).

In this tutorial we'll set marks "owner" and "user", so that you could follow only what you need. The ShareHolder contract mentioned above is already created, therefore you can only use it as a user. The ShareHolder Factory contract can be used to create new ShareHolder contracts, with you as an owner.

Share Holder and Contract Info.

Initial state of a ShareHolder contract:

Share Holder Info section contains info relevant to a currently selected account. In this example, it is a (2): owner's account. Therefore, it owns 10000 shares (set at creation time, you can set any number in your own contract).

It does not have any bonus shares nor confirmed bonus shares. A Confirmed bonus share is a former bonus share of a campaign that was finalizzed. Now it is the same as a regular share, and can be converted to a regular share at any moment.

Contract Info section contains info relevant for the contract.

Note that Bid is 0.01 (plus 1% commission) ether, while Ask is zero. This is because (see explanation above) we are at fund raising stage.

Contract Operations.

User: A client can buy shares from the contract (if available) and sell shares to the contract (if has some).

Owner: Additionally, Owner can create new campaigns (in order to being able to distribute shares to it) and distribute shares to these campaigns. Note that Account 2 (owner) is selected, otherwise this option would be hidden.

List of Operations.

Two empty operations are added for presentation sake, one for "yesterday" and one for today.

Creating a Campaign.

Owner: Select owner's account. Click "New Campaign". Enter a campaign name (in our case it is "Campaign 1") and an optional URL for a campaign (to have a link from our site to your site). Click "Create Bonus Campaign" button.

MetaMask will ask you to confirm a transaction, then (it will take some time, unless you do it all in a private net running on your computer) you will have to reload the page. new campaign shows in a combo box:

Owner, User: The campaign you created will be displayed in a drop down list: press "Expand Campaigns" in a Contract Info section:

Distributing Bonus Shares.

Owner: From the owner's account, fill the form, specifying anumber of shares to distribute and a receiver (we choose Account 3):

Press "Distribute Bonus Shares". Wait for transaction to be reflected in a block chain and reload the page:

Note, that for owner's account, these shares are shown in a Contract Info section, but not in Share Holder Info. However if you select Account 3 as an active account, you will see shares that were distributed to it:

Confirming Bonus Campaign.

Owner: From the owner's account, select Campaign 1 and click "Confirm Bonus Campaign" button.

Convert Confirmed shares to Regular ones.

User: As the owner of a contract confirmed a campaign, it means that it can not be deleted; all its shares are there to stay: they are just like regular shares now. The reason they are not converted automatically is due to problems it can create to the contract. It is a standard approach in an Ethereum world to let the users to handle this sort of job (the "on demand" pattern).

So the user has to tell the contract to convert shares to regular ones (there is no need to hurry, the only reason shares has to be converted, is to sell them: you can only sell regular shares).

Expand campaigns in Share Holder Info section and click "Convert" button next to a confirmed campaign.

Confirmed bonus shares will be converted to regular ones.

Buying and selling shares.

User: A user can buy (if contract has available shares) or sell (if the user has available shares) shares directly from and to a ShareHolder contract.

Shares purchaces are reflected in a Contract Info:

Additionally, list of operations is updated to reflect transaction. Note that it is not a list of SEPARATE transactions, but a daily totals summary:


State of the contract is being reflected in charts. For example:

Sending profit to a contract.

To send profit to a contract, we are goint to use Mist, an advanced wallet capable of calling specific functions of a contract. You can use any tool that can do it.

The function we have to call is

addToShareHoldersProfit(string strContractName, string strContractUrl)

The contract's balance will increase, and the money received will be added to your fund rising campaign.

ShareHolder: programmers guide.

To use ShareHolder contract in your project:

1. Create a ShareHolder contract.

ShareHolder contract can be created by a Factory contract called ShareHolder Factory. We run it for you (accessiple by the link above) and provide a Web UI so that its functionality is available from the MetaMask enabled Browser.

Fill the form, specifying parameters of a ShareHolder contract you need, and click the button:

The conract you created will show up in a list, this is how you can find its address:

2. Attach your contract to ShareHolder.

This step is not mandatory, after all, you can send ether to ShareHolder contract manually. However, if you want your business model to be encoded in a contract, add the following lines to it:

// --- ShareHolder forward declaration ---
contract ShareHolder
	// Arguments: string strContractName, string strContractUrl
	function addToShareHoldersProfit(string, string) public payable
		// ...
// --- End of ShareHolder forward declaration ---

This is a forward declaration of a ShareHolder contract, making its functionality available to your contract. Now you can send it money:

contract YourContract
	// addr. of your ShareHolder Profit Manager
	address m_addrShareHolder = 0;
	function processShareHolderFee(uint nFee, string strNickName) internal
		// --- ShareHolder interface --- TBD: keep contract in a member variable?
		if(m_addrShareHolder != 0)
            ShareHolder contractShareHolder = ShareHolder(m_addrShareHolder);
            contractShareHolder.addToShareHoldersProfit.value(nFee)(strNickName, "");
	// Function that gets profit
	function getProfit() public payable
		// you are going to send 4% of your profit to ShareHolder
		uint nFee = msg.value / 25;	
		processShareHolderFee(nFee, strNickName);


We believe that our audience is intelligent enough to use a "no-nonesence" version of agreement. No legalese.

Please read this license carefully.

Visibility is very important for this site. If you like it please link from your page to this URL or share info using Social Buttons below.
(C), all rights reserved

Please read the disclaimer