Polymath Core Feature Spotlight — Setting an Investor Limit

Published in

Polymath Network

6 min readJun 27, 2018

The article below is about the software engineering aspects of writing a token contract. It is not advice on accounting or securities law; please do not take it as such.

Beginning with the Polymath Toro 1.1.0 release we are publishing a series of articles featuring new key functionalities to cover the exact thought process that went into building them, how these new features work, and how to work with them.

In v1.1.0 we introduced a bunch of new features — covered in this article — which we are going to explore in this “Feature Spotlight” series.

The first feature I will be discussing: Setting an Investor Limit. Why might you want to do this? Well, as explained in prior release notes:

We added a CountTransferManager that restricts the total number of token holders. This is particularly useful if the Issuer needs to comply with any securities laws that prevent them from having more than — for example — 99 or 2000 investors.

The Investor Limit Problem

There are some situations where issuers need to limit how many investors they can have since going over that limit would mean having to support more onerous reporting obligations. For example, let’s look at the “2000 investors limit” according to Investopedia:

The 2,000 investor limit or rule is a key threshold for private businesses which do not wish to disclose financial information for public consumption. Congress raised the limit from 500 individual investors in 2016 as part of the Jumpstart Our Business Startups Act (the (“JOBS Act”) and Title LXXXV of the Fixing America’s Surface Transportation Act (the “FAST Act”).

According to this rule, if you sell securities in the US and you have 2000 or more securities holders, you need to disclose a large amount of financial information for public consumption, which certainly makes your endeavor more complicated and costly. It’s only logical that you might want to prevent such a thing from happening.

So, how do we ensure that no more than 2000 people can hold our securities tokens at the same time? Can we do that with regular ERC-20 tokens?

If you’ve followed my articles so far, you might know the answer to that question.

NO. There’s no way to prevent people from trading regular ERC-20 tokens.

Limiting the Number of Token Holders

Knowing that limiting the number of token holders was an important feature to support, we had to do a few modifications to our SecurityToken smart contract.

Getting an Up-to-date Investor/Holder Count

In order to limit the amount of token holders, we — obviously — need to know how many token holders we have at any given moment. In order to do that, we have to:

Monitor each transfer transaction.
Check if that transfer would end up resulting in a token holder count increase or decrease.
If there is a change in token holder count, update the investor count.

Let’s see how that works:

function transfer(address _to, uint256 _value) public returns (bool success) {
        adjustInvestorCount(msg.sender, _to, _value);
        require(verifyTransfer(msg.sender, _to, _value), "Transfer is not valid");
        require(super.transfer(_to, _value));
        return true;
    }

In order to keep track of the investor count we made a few changes to transfer, transferFrom and mint. All of these methods now include a call to a new method called adjustInvestorCount that keeps the investor count current.

function adjustInvestorCount(address _from, address _to, uint256 _value) internal {
        if (_value == 0) {
            return;
        }
        // Check whether sender is moving all of their tokens
        if (_value == balanceOf(_from)) {
            investorCount = investorCount.sub(1);
        }
        // Check whether receiver is a new token holder
        if (balanceOf(_to) == 0) {
            investorCount = investorCount.add(1);
        }}

AdjustInvestorCount is quite simple:

If the amount of tokens being sent would result in the sender (_from) being left with no tokens, then we reduce the investor count.
At the same time, if the transfer operation would result in a receiver (_to) who did not have tokens now having a balance higher than 0, then we increase the investor count.

By adding this method call to every other method that could result in tokens moving in or out of accounts, we can be sure we have an updated holder/investor count.

Preventing our Token from Going Over the Investor Count Limit

Now that we can get the current number of token holders and use that number within our SecurityToken smart contract, all we need to do is set the limit we want to enforce so that we reject transactions that would exceed that limit.

In order to restrict transfers based on the current amount of holders, we introduced the CountTransferManager module in v1.1.0.

This transfer manager can be attached to the SecurityToken just like any other module we’ve explored in past articles by using the addModule method.

The CountTransferManager is pretty straightforward, having only one property and one method that really matter to us:

uint256 public maxHolderCount;

MaxHolderCount is entered upon module configuration (and can be later modified by the issuer) and it represents the limit we want to set for our token holder/investor count.

function verifyTransfer(address _from, address _to, uint256 /* _amount */) public view returns(Result) {
        if (!paused) {
            if (maxHolderCount < ISecurityToken(securityToken).investorCount()) {
                // Allow transfers to existing maxHolders
                if (ISecurityToken(securityToken).balanceOf(_to) != 0) {
                    return Result.NA;
                }
                return Result.INVALID;
            }
            return Result.NA;
        }
        return Result.NA;
    }

As explained in previous articles, when a transfer / transferFrom is attempted, the SecurityToken will loop over all the transfer managers attached to it and call the verifyTransfer method on each of them.

In the case of the CountTransferManager, if the current investor count is higher than the maxHolderCount, it will make transactions fail by returning theResult.INVALID code.

The verifyTransfer method from CountTransferManager also takes into consideration situations where the maxHolderCount has already been reached and, for some reason, the issuer decides to reduce the limit even further (maybe due to some new regulation that has arisen). If they were to do so, they would have a token with more investors than allowed by the transfer manager. In that case, the CountTransferManager prevents transfers that would result in new investors being added to the list. For example, if Bob has 50 tokens and Susan has 0 tokens, Bob sending tokens to Susan would fail since that would increase the investor count. But! If Bob has 50 tokens and Susan has 10 tokens, Bob can send tokens to Susan, because this transaction does not increase the investor count.

Summary

In this article we went over one of the new features introduced in v1.1.0: Limiting the amount of holders a token can have.

We learned that as of v1.1.0 SecurityToken has a mechanism that allows it to keep track of token holders, and that a new transfer manager was added to the mix: the CountTransferManager. This transfer manager allows the issuer to set a maximum number of holders for their token. It also makes transfers fail when the transfer would cause the investor count to go over the limit the issuer has set.

Where to go next?

With the release of Toro v1.1.0 [EDIT: and now v1.2.0] we are one step closer to a framework that we feel confidently applies to most issuers with regard to functionality requirements and regulatory-compliance.

Want to chat about Polymath Core and all things crypto?

Please reach out to me by commenting below. I’m also pretty active on Twitter. We started a Gitter channel as an open means for communicating with fellow developers looking into using Polymath Core.

Exploring Polymath Core

Are you a developer interested in how securities tokens work? Take a look at our Github repo and feel free to ask any questions and submit any issues you find.

Take Part in our Bug Bounty Program

We launched our Bug Bounty Program this month. Help us squash those nasty bugs! 🐛 🐞
Check our Bug Bounty Program’s terms here: https://blog.polymath.network/announcing-the-polymath-network-bug-bounty-3e4a78ac9809

Joining Polymath

Are you interested in joining the security token revolution? We are always looking for high quality talent and have lots of current openings. Check out our careers page at https://polymath.bamboohr.com/jobs/ to apply!

About Polymath

Polymath Network (Polymath) is a decentralized platform that makes it easy to create security tokens. The Polymath ST-20 standard embeds regulatory requirements into the tokens themselves, restricting trading to verified participants only. The platform simplifies the complex technical challenges of creating a security token and aims to bring the multi-trillion dollar financial securities market to the blockchain.