Security Token Manager documentation¶
Here is a documentation for TokenMarket Security Token Manager. Security Token Manager is an open source project that provides a command line tool and API library to interact and integrate security tokens to your business systems.
Security Token Manager provides technical operations for corporate governance including e.g.
- Issue out new stock series as security tokens
- Distributing shares to primary market investors
- Printing out cap table
- Managing bad transactions and lost privat keys
- Paying dividends and interest
- Delivering voting ballots
- Maintaining audit logs of delivered actions
The command line tool is locally installed via Docker and available for Windows, OSX and Linux. The API is written in Python programming language.
New to tokens and securities? Read an introduction for security tokens
Installation¶
Security token interaction happens through a command line sto command that connects to an Ethereum network node and a local database. sto command is automatically installed via Docker.
Requirements¶
Skills needed
- Command line usage experience
- Ethereum and smart contract experience
Software or services needed
- Ethereum node, for example a local Parity installation or Infura-node-as-a-service - see how to install
- Docker
Normal users¶
This tool is for command line users and developers only. We do not provide an end user application as open source. For business services please contact TokenMarket business representatives.
Advanced users¶
The sto command line application is provided as a Docker image to minimize the issues with painful native dependency set up for your operating system. To use sto we will set up a command line alias, as Docker command itself is quite long.
Install Docker (Windows, OSX).
OSX and Linux¶
Set up a shell alias for sto command that executes Dockerised binary:
alias sto='docker run -p 8545:8545 -v `pwd`:`pwd` -w `pwd` miohtama/sto:latest'
Then you can do:
sto --help
Docker will automatically pull an image from Docker registry for your local computer on the first run. We map port 8545 to the localhost as that is normal Ethereum JSON-RPC API.
After installing see how to set up the software.
Windows¶
Windows PowerShell instructions coming soon.
Meanwhile use Linux instructions and Linux Subsystem for Windows.
Developers¶
Python 3.6+ required.
Create Python virtual environment.
Then within the activated venv do:
git clone "git+https://github.com/TokenMarketNet/sto.git"
python -m venv venv # Python 3 needed
source venv/bin/activate
pip install -U pip # Make sure you are at least pip 18.1 - older versions will fail
pip install -e ".[dev,test]"
How to set up and first run¶
Below are short instructions how to set up an Ethereum node, account and configuration file for the Kovan testnet (no real money involved).
You need an Ethereum node. You can either install yourself (see Install Parity) or use a Ethereum node provider like Infura.
Install Parity (Option b)¶
First install Parity. For example on OSX using Brew package management:
brew install parity
Start Parity in another terminal and connect it to Kovan test network:
parity --chain=kovan
Parity will now sync you to Kovan network using warp (fast mode). This will take up to two hours. You can continue to follow instructions below.
Set up Ethereum account¶
To start playing with tokenised shares we first need to create a new Ethereum account we use for management operations.
Create an Ethereum account:
sto --network=kovan ethereum-create-account
This will give you a new raw private key and related Ethereum address to play with:
Creating new Ethereum account.
Account address: 0xDE5bC059aA433D72F25846bdFfe96434b406FA85
Account private key: 3fac35a57e1e2867290ae37d54c5de61d52644b42819ce6af0c5a9c25f4c...
Now create a file myconfig.ini and add the content:
# Your personal configuration file as we told you on Github example
# Network we are using
network = kovan
# This is for Parity - if you are using Infura get your Kovan node URL from your Infura dashboard
ethereum-node-url = http://localhost:8545
# The private key for your generated Ethereum account
ethereum-private-key = 3fac35a57e1e2867290ae37d54c5de61d52644b42819ce6af0c5a9c25f4c....
Top up¶
Visit Kovan faucet.
Request Kovan ETH (KETH) on your account you just create above. A Github account is needed for verification. This should give you 1 Kovan ETH to play with and you become a testnet millionaire.
Diagnose and test run¶
Use sto diagnose command to check your account has balance and your Ethereum node works:
sto --config-file=myconfig.ini diagnose
This should output:
Now your can proceed to issue out your first play shares.
Issuing out security tokens¶
Before issuing out stock you need to have set up a functional Ethereum account set up.
To issue out stock you need to give stock name, ticker symbol and amount of shares:
sto --config-file=myconfig.ini issue --symbol=STO --name="Mikko's magic corp" --amount=10000
You will get a list of Ethereum transactions needed to perform this operation:
Prepared transactions for broadcasting for network kovan
TXID Status Nonce From To Note
------ -------- ------- ------------------------------------------ ------------------------------------------ --------------------------------------------------------------
waiting 1 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0x3cD6f4004e310c0E5Ae7eaf5B698386ccF1d78F2 Token contract for Mikko's magic corp
waiting 2 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0x1abECD8dF601e6e56eca99Ec1F1c50eEAe61B289 Unrestricted transfer manager for Mikko's magic corp
waiting 3 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0x3cD6f4004e310c0E5Ae7eaf5B698386ccF1d78F2 Setting security token transfer manager for Mikko's magic corp
waiting 4 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0x3cD6f4004e310c0E5Ae7eaf5B698386ccF1d78F2 Creating 10000 initial shares for Mikko's magic corp
Next see how to broadcast created transactions.
Broadcasting transactions¶
Ethereum transactions are first written to a local SQlite database. A separate step of broadcasting transactions is needed in order to write the data to Ethereum blockchain. Furthermore local database allows us to add human friendly annotations for transactions, so that diagnostics and future audits are easy.
Using a local database and locally generated nonces ensures we can always safely rebroadcast transactions and issue out new transactions even under severe network conditions.
To broadcast:
sto --config-file=myconfig.ini tx-broadcast
Transactions are send out to Ethereum network and they get a transaction id. You will see txid in output:
Pending 5 transactions for broadcasting in network kovan
Our address 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 has ETH balance of 0.955684 for operations
TXID Status and block Nonce From To Note
------------------------------------------------------------------ ------------------ ------- ------------------------------------------ ------------------------------------------ ---------------------------------------------------------
0x6bb9755f492f9d4497457df0da8cfd91ab32efaad7bb67444f4e2e00351e9427 broadcasted 74 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0xdaE00e2fbD21924443e133E14A9206CeDC046824 Deploying token contract for Moobar
0xefd6ad3b3c8a8364b315b6c73667baf6d657493d8dad14423b41a32b22444d60 broadcasted 75 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0x533FeDE8F86C3e8a7923fEa4f55007f25AF5db30 Deploying unrestricted transfer policy for Moobar
0x4d31a1d15c1f479c48a21798f5d81d275b34b3fa8cbf9e450dc2ad20b0001e41 broadcasted 76 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0xdaE00e2fbD21924443e133E14A9206CeDC046824 Whitelisting deployment account for Moobar issuer control
0xe45a64c71a42100858b9880c40a59e7728fb4c5a11adf14ff509323fc08f21de broadcasted 77 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0xdaE00e2fbD21924443e133E14A9206CeDC046824 Making transfer restriction policy for Moobar effective
0x948b9925f8afe134b39e8c3384c51e0027c839a9737b6307ab77419992b293c7 broadcasted 78 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0xdaE00e2fbD21924443e133E14A9206CeDC046824 Creating 10000 initial shares for Moobar
Run sto tx-update to monitor your transaction propagation status
Update transaction status¶
Blockchain transactions are asynchronous. First the transactions are broadcasted to the network. The transactions propagade from a node to a node until a miner node decides to include your transactions in a block.
tx-update command will read tranactions from network and update the local database for pending transasctions. It will also detect if a transaction has failed e.g. due to smart contract permission errors.
To check your transaction status:
sto --config-file=myconfig.ini tx-update
After a while repeating this command you should see all your transactions included in blockchain with success status:
TXID Status and block Nonce From To Note
------------------------------------------------------------------ ------------------ ------- ------------------------------------------ ------------------------------------------ ---------------------------------------------------------
0x4bd273895b21a3b57e93113c26895ea142f989cde13ff0c23bb330de1889238a success:9513331 70 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0xc48DA079aab7FEf3a2476B493f904509d1891Fa3 Deploying unrestricted transfer policy for Doobar
0xc5bb03a49bdc58cecb0ad36ff7f1aac84e29b08c2ed67c17d7ecab2f55d63c54 success:9513331 71 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0xC423aCf9757c25048E0f10F21A4eC6a1322b4299 Whitelisting deployment account for Doobar issuer control
0xbbe0e59db71839b4b7cf7c8ac082c9204513243d3ae3ca38c98b8d443f9699ed success:9513331 72 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0xC423aCf9757c25048E0f10F21A4eC6a1322b4299 Making transfer restriction policy for Doobar effective
0x565eda7f18c9d05255b3f29c9d677734bbdb97e25d62d10d1033208030dda0a7 success:9513331 73 0xDE5bC059aA433D72F25846bdFfe96434b406FA85 0xC423aCf9757c25048E0f10F21A4eC6a1322b4299 Creating 10000 initial shares for Doobar
You can also enter TXID to Kovan EtherScan explorer to see how your transactions are doing to check more information about your transactions.
After you have get your transactions to Ethereum blockchain, see how to view the token summary.
Further information¶
See tx-broadcast or tx-update commands.
Viewing token summary¶
After all your transactions have been pushed out and are succesfully included in blocks, you can view the token status by entering the contract address:
sto --config-file=myconfig.ini token-status --address=0xa2016C64D4687Ad4184bA1dA98711e83a36eD1c2
This outputs:
Name: Boobar
Symbol: STO
Total supply: 10000
Decimals: 18
Owner: 0xDE5bC059aA433D72F25846bdFfe96434b406FA85
Transfer verified: 0x7598E970888F51d7D35468E50768Fa5F21B46Bb3
Fetching token holder balances¶
Token holder balances ae managed in a blockchain. Accessing token holder information real time from a blockchain is non-trivial. For complex operations, like printing out the cap table, we need to crunch the blockchain data first to a local database.
sto can scan the blockchain and construct a database of all past token transactions. Based on this information we can print out the cap table in any point of time.
Scanning token holders¶
To scan all transactions of your security token use token-scan command. Use the token address for which you have created a distribution.
sto --config-file=myconfig.ini token-scan --token-address=0x1091aA1ED6070eDEDFdf46f665C1eD78Bd2c7431
Scan may take few minutes, as the operation walks through the whole blockchian. In the end, it should print:
Scanning token: Mikko's corp 5
Current last block for chain kovan: 9880112
Scanning blocks: 133739 - 9880112
Last scan ended at block: 133749
Scanning block: 9524384, batch size: 500000: : 9890620it [00:13, 104737.39it/s]
Updated 3 token holder balances
Reruns¶
Rerunning sto token-scan starts from the block where it was left last time. We look back few blocks (10) to ensure that any transfers lost in minor blockchain forks are corrected.
About the scan algorithm¶
The provided scan algorithm is referential in the nature. It may not scale to large number or tokens or token holders. The algorithm has been designed the limitations of SQLite databases in mind.
Printing to cap table¶
After you have scanned the balances you can print the cap table.
Further information¶
See token-scan command.
Cap table¶
Cap table show the current ownership, or token holding addresses, of security tokens.
Cap table can be printed for the current moment or any moment in the past.
Cap table output may contain the real world identities of the owners, if supplied via external CSV file, or just plain Ethereum addresses.
Scanning token holders first¶
To print out the cap table, first you need to build the local database of token transactions. See token scanner for details.
Printing out the token holder cap table¶
Use sto cap-table command to print out different views on the table.
Here we print out the cap table
- For security token we issued earlier
- Distributed to the share holders in the example file we used earlier
First we download the file that contain read world identities of token holder addresses:
# Download example CSV file provided with source code repository
curl -O "https://raw.githubusercontent.com/TokenMarketNet/sto/master/docs/source/example-ids.csv"
Then we can use this file and our local token transfer database to print out the current cap table:
sto --config-file=myconfig.ini cap-table \
--identity-file=example-ids.csv \
--token-address=0xAEFafd1Ae9b0e9acFF2b22596C40da3FFD8dff99
Cap table looks like this:
Cap table for any ERC-20 token¶
sto token-scan and sto cap-table command support creating token holder database of any ERC-20 token, not just security tokens or tokens you have issued yourself. If you need to use token holder or transfer data in your application you can read it directly from sto SQLite database.
Note
As most of the ERC-20 tokens are payment terms, using term cap table is little bit misleading. The term “token holders” is more generic.
Preparing and printing out token holders¶
Here is a quick tutorial how to print out the token holders of Reality Clash token.
First create a INI configuration while that connects to Infura Ethereum mainnet node or your local mainnet node.
mainnet.ini example:
# Network we are using
network = ethereum
# Get this from your Infura dashboard
ethereum-node-url = https://mainnet.infura.io/v3/453...
Then scan all RCC token transactions of all time. Please note that the scan process may take anywhere between 15 minutes to few hours depening on how fast your connection to the node and computer are.
sto --config-file=mainnet.ini token-scan --token-address=0x9b6443b0fb9c241a7fdac375595cea13e6b7807a
Note
If the scan is interrupted it will pick up where it was left last time. You can also manually interrupt the application with CTRL+C.
Now you can print out the cap table. Here is how to print out top 10 token holders:
sto --config-file=mainnet.init cap-table \
--token-address=0x9b6443b0fb9c241a7fdac375595cea13e6b7807a \
--order-by=balance \
--order-direction=desc \
--max-entries=10
And it prints out the RCC top holders table:
EtherScan integration¶
Verifying contracts on EtherScan¶
EtherScan is a popular service for blockchain exploring. It’s verify contract feature allows you to create reproducible builds of your Solidity source code and then EtherScan can introspect your contract state. This is very useful for diagnostics.
For example, you can see browse STO transactions easily:
To verify your contracts on EtherScan, you need to first ensure all contract deployement transactions are broadcasted and mined.
Then add your EtherScan API key in myconfig.ini:
# Obtained after signing in to etherscan.io
etherscan-api-key = T2JC4....
Now you can run verify:
sto --config-file=myconfig.ini tx-verify
Protocols¶
Supported token standards and protocols¶
This project currently support
- TokenMarket SecurityToken for issuance
- Any ERC-20 token for cap tables, token holdership and such operations
Future protocols¶
Any ERC-20 like token should work with very little modifications to the tool. We are actively looking to other token models (Polymath) as soon as we establish proper partnerships.
Support for other networks (EOS) is coming as well, as soon as we establish proper partnerships.
Command line reference¶
Here is the command line reference for sto command.
Options and config files¶
Settings can be either given in a config file, specified by --config-file switch or directly to the main command.
E.g. these are equivalent.
Command line:
sto --ethereum-node-url="https://mainnet.infura.io/v3/453d2049c15d4a8da5501a0464fa44f8" token-scan ...
As with INI file mainnet.ini:
# Infura mainnet net node url
ethereum-node-url = https://mainnet.infura.io/v3/453d2049c15d4a8da5501a0464fa44f8
sto --config-file=mainnet.ini token-scan ...
Subcommands take their own options that cannot be specified in the settings file.
Main command and options¶
When running sto --help you get list of settings and subcommands:
Usage: sto [OPTIONS] COMMAND [ARGS]...
TokenMarket security token management tool.
Manage tokenised equity for things like issuing out new, distributing and revoking shares.
Options:
--config-file PATH INI file where to read options from
--database-file PATH SQLite file that persists transaction broadcast status
--network TEXT Network name. Either 'ethereum' or 'kovan' are supported for now.
--ethereum-node-url TEXT Parity or Geth JSON-RPC to connect for Ethereum network access
--ethereum-abi-file TEXT Solidity compiler output JSON to override default smart contracts
--ethereum-gas-price TEXT How many GWei we pay for gas
--ethereum-gas-limit INTEGER What is the transaction gas limit for broadcasts
--ethereum-private-key TEXT Private key for the broadcasting account
--etherscan-api-key TEXT EtherScan API key used for the contract source code verification
--log-level TEXT Python logging level to tune the verbosity of the command
--auto-restart-nonce BOOLEAN Automatically restart nonce for the deployment account if starting with a fresh database
--help Show this message and exit.
Commands:
cap-table Print out token holder cap table.
diagnose Check your node and account status.
distribute-multiple Distribute shares to multiple shareholders whose address info is read from a file.
distribute-single Send out tokens to one individual shareholder.
ethereum-create-account Creates a new Ethereum account.
issue Issue out a new security token.
issue-logs Print out transactions of for tokens issued in the past.
reference Print out the command line reference for the documentation.
token-scan Update token holder balances from a blockchain to a local database.
token-status Print token contract status.
tx-broadcast Broadcast waiting transactions.
tx-last Print latest transactions from database.
tx-next-nonce Print next nonce to be consumed.
tx-restart-nonce Resets the broadcasting account nonce.
tx-update Update transaction status.
tx-verify Verify source code of contract deployment transactions on EtherScan.
cap-table¶
Print out token holder cap table.
The token holder data must have been scanned earlier using token-scan command.
You can supply optional CSV file that contains Ethereum address mappings to individual token holder names.
Usage: sto cap-table [OPTIONS]
Print out token holder cap table.
The token holder data must have been scanned earlier using token-scan
command.
You can supply optional CSV file that contains Ethereum address mappings
to individual token holder names.
Options:
--identity-file PATH CSV file containing address real world
identities
--token-address TEXT Token contract address [required]
--order-by [balance|name|updated|address]
How cap table is sorted
--order-direction [asc|desc] Sort direction
--include-empty BOOLEAN Sort direction
--max-entries INTEGER Print only first N entries
--accuracy INTEGER How many decimals include in balance output
--help Show this message and exit.
diagnose¶
Check your node and account status.
This command will print out if you are properly connected to Ethereum network and your management account has enough Ether balance.
Usage: sto diagnose [OPTIONS]
Check your node and account status.
This command will print out if you are properly connected to Ethereum
network and your management account has enough Ether balance.
Options:
--help Show this message and exit.
distribute-multiple¶
Distribute shares to multiple shareholders whose address info is read from a file.
Usage: sto distribute-multiple [OPTIONS]
Distribute shares to multiple shareholders whose address info is read from
a file.
Options:
--csv-input TEXT CSV file for entities receiving tokens [required]
--address TEXT Token contract address [required]
--help Show this message and exit.
distribute-single¶
Send out tokens to one individual shareholder.
Usage: sto distribute-single [OPTIONS]
Send out tokens to one individual shareholder.
Options:
--token-address TEXT Token contract address [required]
--to-address TEXT Receiver [required]
--external-id TEXT External id string for this transaction - no
duplicates allowed [required]
--email TEXT Receiver email (for audit log only) [required]
--name TEXT Receiver name (for audit log only) [required]
--amount TEXT Amount of tokens as a decimal number [required]
--help Show this message and exit.
ethereum-create-account¶
Creates a new Ethereum account.
Usage: sto ethereum-create-account [OPTIONS]
Creates a new Ethereum account.
Options:
--help Show this message and exit.
issue¶
Issue out a new security token.
- Creates a new share series
- Allocates all new shares to the management account
- Sets the share transfer restriction mode
Usage: sto issue [OPTIONS]
Issue out a new security token.
* Creates a new share series
* Allocates all new shares to the management account
* Sets the share transfer restriction mode
Options:
--symbol TEXT [required]
--name TEXT [required]
--amount INTEGER [required]
--transfer-restriction TEXT
--help Show this message and exit.
issue-logs¶
Print out transactions of for tokens issued in the past.
Usage: sto issue-logs [OPTIONS]
Print out transactions of for tokens issued in the past.
Options:
--help Show this message and exit.
reference¶
Print out the command line reference for the documentation.
Usage: sto reference [OPTIONS]
Print out the command line reference for the documentation.
Options:
--help Show this message and exit.
token-scan¶
Update token holder balances from a blockchain to a local database.
Reads the Ethereum blockchain for a certain token and builds a local database of token holders and transfers.
If start block and end block information are omitted, continue the scan where we were left last time. Scan operations may take a while.
Usage: sto token-scan [OPTIONS]
Update token holder balances from a blockchain to a local database.
Reads the Ethereum blockchain for a certain token and builds a local
database of token holders and transfers.
If start block and end block information are omitted, continue the scan
where we were left last time. Scan operations may take a while.
Options:
--start-block TEXT The first block where we start (re)scan
--end-block TEXT Until which block we scan, also can be 'latest'
--token-address TEXT Token contract address [required]
--help Show this message and exit.
token-status¶
Print token contract status.
Usage: sto token-status [OPTIONS]
Print token contract status.
Options:
--address TEXT Token contract addrss [required]
--help Show this message and exit.
tx-broadcast¶
Broadcast waiting transactions.
Send all management account transactions to Ethereum network. After a while, transactions are picked up by miners and included in the blockchain.
Usage: sto tx-broadcast [OPTIONS]
Broadcast waiting transactions.
Send all management account transactions to Ethereum network. After a
while, transactions are picked up by miners and included in the
blockchain.
Options:
--help Show this message and exit.
tx-last¶
Print latest transactions from database.
Usage: sto tx-last [OPTIONS]
Print latest transactions from database.
Options:
--limit INTEGER How many transactions to print
--help Show this message and exit.
tx-next-nonce¶
Print next nonce to be consumed.
Usage: sto tx-next-nonce [OPTIONS]
Print next nonce to be consumed.
Options:
--help Show this message and exit.
tx-restart-nonce¶
Resets the broadcasting account nonce.
Usage: sto tx-restart-nonce [OPTIONS]
Resets the broadcasting account nonce.
Options:
--help Show this message and exit.
tx-update¶
Update transaction status.
Connects to Ethereum network, queries the status of our broadcasted transactions. Then print outs the still currently pending transactions or freshly mined transactions.
Usage: sto tx-update [OPTIONS]
Update transaction status.
Connects to Ethereum network, queries the status of our broadcasted
transactions. Then print outs the still currently pending transactions or
freshly mined transactions.
Options:
--help Show this message and exit.
tx-verify¶
Verify source code of contract deployment transactions on EtherScan.
Users EtherScan API to verify all deployed contracts from the management account.
Usage: sto tx-verify [OPTIONS]
Verify source code of contract deployment transactions on EtherScan.
Users EtherScan API to verify all deployed contracts from the management
account.
Options:
--help Show this message and exit.
Developer notes¶
Information for package developers.
Making a release¶
Instructions for the future-maintainers-to-be.
First send out PyPi release:
# Build and upload PyPi egg
export VERSION=0.2.0
make release
Then push out new Docker:
# Build docker image
docker login --username=miohtama
make publish-docker