The Polymath Core smart contracts provide a system for launching regulatory-compliant securities tokens on a decentralized blockchain. This particular repository is the implementation of a system that allows for the creation of ST-20-compatible tokens. This system has a modular design that promotes a variety of pluggable components for various types of issuances, legal requirements, and offering processes.
An ST-20 token is an Ethereum-based token implemented on top of the ERC-20 protocol that adds the ability for tokens to control transfers based on specific rules. ST-20 tokens rely on Transfer Managers to determine the ruleset the token should apply in order to allow or deny a transfer, be it between the issuer and investors, in a peer to peer exchange, or a transaction with an exchange.
ST-20 tokens must implement a verifyTransfer method which will be called when attempting to execute a transfer or transferFrom method. The verifyTransfer method will determine whether that transaction can be completed or not. The implementation of verifyTransfer can take many forms, but the default approach is a whitelist controlled by the GeneralTransferManager.
contract IST20 {
// off-chain hash
bytes32 public tokenDetails;
//transfer, transferFrom must respect the result of verifyTransfer
function verifyTransfer(address _from, address _to, uint256 _amount) view public returns (bool success);
//used to create tokens
function mint(address _investor, uint256 _amount) public returns (bool success);
}
The diagram below depicts a high-level view of the various modules, registries, and contracts implemented in Polymath Core:
SecurityToken is an implementation of the ST-20 protocol that allows the addition of different modules to control its behavior. Different modules can be attached to SecurityToken:
- TransferManager modules: These control the logic behind transfers and how they are allowed or disallowed.
By default, the ST (Security Token) gets a
GeneralTransferManagermodule attached in order to determine if transfers should be allowed based on a whitelist approach. TheGeneralTransferManagerbehaves differently depending who is trying to transfer the tokens. a) In an offering setting (investors buying tokens from the issuer) the investor's address should be present on an internal whitelist managed by the issuer within theGeneralTransferManager. b) In a peer to peer transfer, restrictions apply based on real-life lockups that are enforced on-chain. For example, if a particular holder has a 1-year sale restriction for the token, the transaction will fail until that year passes. - Security Token Offering (STO) modules: A
SecurityTokencan be attached to one (and only one) STO module that will dictate the logic of how those tokens will be sold/distributed. An STO is the equivalent to the Crowdsale contracts often found present in traditional ICOs. - Permission Manager modules: These modules manage permissions on different aspects of the issuance process. The issuer can use this module to manage permissions and designate administrators on his token. For example, the issuer might give a KYC firm permissions to add investors to the whitelist.
- Checkpoint Modules: These modules allow the issuer to define checkpoints at which token balances and the total supply of a token can be consistently queried. This functionality is useful for dividend payment mechanisms and on-chain governance, both of which need to be able to determine token balances consistently as of a specified point in time.
The ticker registry manages the sign up process to the Polymath platform. Issuers can use this contract to register a token symbol (which are unique within the Polymath network). Token Symbol registrations have an expiration period (7 days by default) in which the issuer has to complete the process of deploying their SecurityToken. If they do not complete the process in time, their ticker symbol will be made available for someone else to register.
The security token registry keeps track of deployed STs on the Polymath Platform and uses the TickerRegistry to allow only registered symbols to be deployed.
Modules allow custom add-in functionality in the issuance process and beyond. The module registry keeps track of modules added by Polymath or any other users. Modules can only be attached to STs if Polymath has previously verified them. If not, the only user able to utilize a module is its owner, and they should be using it "at their own risk".
The CLI is for users that want to easily walkthrough all the details of an STO issuance. The CLI documentation is located on our Github Wiki. You can easily navigate through it with the sidebar directory in order to run the CLI and set up and test the following:
- Prerequisite Instructions / Deploy and setup the Polymath contracts
- Launch the CLI on Ganache
- Use the Faucet to get POLY
- Deploy a token + Launch a USDTieredSTO
- Whitelist investors
- Work with the Dividends module
- Using other CLI features
New SecurityTokenRegistry (2.0.1): 0x538136ed73011a766bf0a126a27300c3a7a2e6a6 (fixed bug with getTickersByOwner())
New ModuleRegistry (2.0.1): 0xbc18f144ccf87f2d98e6fa0661799fcdc3170119 (fixed bug with missing transferOwnership function)
New ManualApprovalTransferManager 0x6af2afad53cb334e62b90ddbdcf3a086f654c298 (Fixed 0x0 from bug)
New Kovan PolyTokenFaucet: 0xb347b9f5b56b431b2cf4e1d90a5995f7519ca792
New ManualApprovalTransferManager 0x9faa79e2ccf0eb49aa6ebde1795ad2e951ce78f8 (Fixed 0x0 from bug)
- node v8.x.x or v9.x.x
- npm v6.x.x or newer
- Yarn v1.3 or newer
- Homebrew v1.6.7 (for macOS)
- Truffle v4.1.11 (core: 4.1.11)
- Solidity v0.4.24 (solc-js)
- Ganache CLI v6.1.3 (ganache-core: 2.1.2) or newer
The smart contracts are written in Solidity and tested/deployed using Truffle version 4.1.0. The new version of Truffle doesn't require testrpc to be installed separately so you can just run the following:
# Install Truffle package globally:
$ npm install --global truffle
# (Only for windows) set up build tools for node-gyp by running below command in powershell:
$ npm install --global --production windows-build-tools
# Install local node dependencies:
$ yarnTo test the code simply run:
# on *nix systems
$ npm run test
# on windows systems
$ npm run wintest-
Deploy
ModuleRegistry.ModuleRegistrykeeps track of all available modules that add new functionalities to Polymath-based security tokens. -
Deploy
GeneralTransferManagerFactory. This module allows the use of a generalTransferManagerfor newly issued security tokens. The General Transfer Manager gives STs the ability to have their transfers restricted by using an on-chain whitelist. -
Add the
GeneralTransferManagerFactorymodule toModuleRegistryby callingModuleRegistry.registerModule(). -
Deploy
TickerRegistry. This contract handles the registration of unique token symbols. Issuers first have to claim their token symbol through theTickerRegistry. If it's available they will be able to deploy a ST with the same symbol for a set number of days before the registration expires. -
Deploy SecurityTokenRegistry. This contract is responsible for deploying new Security Tokens. STs should always be deployed by using the SecurityTokenRegistry.
Security Token Offerings (STOs) grant STs the ability to be distributed in an initial offering. Polymath offers a few out-of-the-box STO models for issuers to select from and, as the platform evolves, 3rd party developers will be able to create their own offerings and make them available to the network.
As an example, we've included a CappedSTO and CappedSTOFactory contracts.
In order to create a new STO, developers first have to create an STO Factory contract which will be responsible for instantiating STOs as Issuers select them. Each STO Factory has an STO contract attached to it, which will be instantiated for each Security Token that wants to use that particular STO.
To make an STO available for Issuers, first, deploy the STO Factory and take note of its address. Then, call moduleRegistry.registerModule(STO Factory address);
Once the STO Factory has been registered to the Module Registry, issuers will be able to see it on the Polymath dApp and they will be able to add it as a module of the ST.
Note that while anyone can register an STO Factory, only those "approved" by Polymath will be enabled to be attached by the general community. An STO Factory not yet approved by Polymath may only be used by it's author.
The polymath-core repo follows the Solidity style guide.