Metadata-Version: 2.1
Name: sto
Version: 0.1.2
Summary: Security token management tool
Home-page: https://tokenmarket.net
Author: TokenMarket Ltd.
Author-email: mikko@tokenmarket.net
License: Apache 2.0
Description: A tool and Python API for issuing out and managing out security tokens.
        
        
        .. image:: https://badges.gitter.im/TokenMarketNet/sto.svg
           :alt: Join the chat at https://gitter.im/security-token/Lobby
           :target: https://gitter.im/security-token/Lobby
        
        .. image:: https://img.shields.io/travis/TokenMarketNet/sto.svg
                :target: https://travis-ci.org/TokenMarketNet/sto
        
        **Technical dragons ahead**
        
        This software is for technically sophisticated users only. If you are looking for business services go to `TokenMarket commercial support <https://tokenmarket.net/security-token-offering>`_.
        
        Table of contents
        =================
        
        .. contents::
        
        Benefits
        ========
        
        This Python package provides a command line tool and API to manage and integrate security token functionality:
        
        * Issue out new stock series
        
        * Printing out cap table
        
        * Printing out my portfolio
        
        * Managing bad transactions and lost privat keys
        
        * Paying dividends
        
        * Delivering voting ballots
        
        In theory the APIs are backend neutral, but only EVM compatible chains are supported at the moment.
        
        * `Read an introduction for security tokens <https://tokenmarket.net/news/security-tokens/what-are-security-tokens/>`_
        
        * `View security token management source code on Github <http://github.com/tokenmarketnet/sto>`_
        
        * `View security token management package on Python package index <https://pypi.org/project/sto/>`_
        
        Supported networks and tokens
        =============================
        
        We currently support
        
        * In-house Ethereum based tokens
        
        We are looking to expand support to other networks (EOS) and other token models (Polymath) as soon as we establish proper partnerships.
        
        Requirements
        ============
        
        * Ethereum node, for example a local Parity install or Infura-node-as-a-service
        
        * Command line tool experience
        
        * Docker
        
        Install
        =======
        
        Security token interaction happens through a command line `sto` command that connects to an Ethereum network node and a local database. This command is written in Python.
        
        Normal users
        ------------
        
        For business users please contact TokenMarket for arranging tokenised equity deals.
        
        
        Advanced users
        --------------
        
        The `sto` command line application is provided as a `Docker image <https://hub.docker.com/r/miohtama/sto/>`_ 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 <https://www.docker.com/products/docker-desktop>`_.
        
        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.
        
        .. image:: https://github.com/TokenMarketNet/sto/raw/master/docs/source/screenshots/help.png
            :width: 500 px
        
        Windows
        ~~~~~~~
        
        TODO: Windows instructions coming soon.
        
        Developers
        ----------
        
        Python 3.6+ required.
        
        Create `Python virtual environment <https://packaging.python.org/tutorials/installing-packages/#optionally-create-a-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 -e ".[dev,test]"
        
        How to set up
        =============
        
        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 <https://infura.io/>`_.
        
        Sign up for Infura (Option a)
        -----------------------------
        
        `Sign up for Infura <https://infura.io/>`_.
        
        Get a **Kovan** node URL from your dashboard (use dropdown):
        
        .. image:: https://github.com/TokenMarketNet/sto/raw/master/docs/source/screenshots/infura.png
            :width: 500 px
        
        Install Parity (Option b)
        -------------------------
        
        First `install Parity <https://wiki.parity.io/Setup>`_. 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 ahsers
        
        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 <https://faucet.kovan.network/>`_.
        
        Request Kovan ETH (KETH) on your account you just create above. A `Github account <http://github.com/>`_ 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:
        
        .. image:: https://github.com/TokenMarketNet/sto/raw/master/docs/source/screenshots/diagnose.png
            :width: 500 px
        
        
        Playing with security tokens
        ============================
        
        Issuing out stock
        -----------------
        
        Before issuing out stock you need to have set up a functional Ethereum account like described above.
        
        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
        
        
        Pushing Ethereum transactions out
        ---------------------------------
        
        Ethereum transactions are first written to a local `SQlite database <https://www.sqlite.org/index.html>`_. 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 <http://kovan.etherscan.io/>`_ to check more information about your transactions.
        
        View STO token information
        --------------------------
        
        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
        
        Making a release
        ================
        
        First send out PyPi release::
        
        
            export bump="--new-version 0.1.1 devnum"
            make release
        
        
        Then push out new Docker::
        
            docker login --username=miohtama
            docker tag miohtama/sto:latest miohtama/sto:0.1
            docker push miohtama/sto:latest
            docker push miohtama/sto:0.1
        
        Other
        =====
        
        `Ethereum smart contracts are managed in ICO repository <http://github.com/tokenmarketnet/ico>`_.
        
        
        
        
        
        
Keywords: ethereum blockchain smartcontract security token
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Provides-Extra: test
Provides-Extra: dev
