Interactions with the Polymath Network - PolymathNetwork/polymath-apps GitHub Wiki

A high-level description of how the main interactions with the Polymath Network.

These are the main interactions with the Polymath Network:

General concepts

Contracts

Autonomous agents that run pieces of code when they receive a message/transaction

Accounts

Have the following attributes:

  • Nonce: Counter used to make sure each transaction is only processed once
  • Balance: Account's current ether balance
  • Contract code: (If present)
  • Storage: (Starts empty)

Externally-owned accounts: (User accounts)

  • Has no code
  • One can only send messages from this type of accounts by creating and signing a transactions

Contract-owned accounts: (Controlled by code)

  • Its code activates any time it receives a message / transaction
  • They incur a cost whenever you use them
  • Can read/write to internal storage
  • Can send messages

Transaction

Signed data package that stores a message to be sent from externally-owned Account

Main attributes:

  • Recipient
  • Signature identifying the sender
  • Amount of Ether to transfer from sender to recipient (if require)

Gas

Cost of executing a transaction, proportional to resources consumed by the transaction

Gas Price

How much 1 Gas is worth in ETH

Transaction Fee

This means that a transaction that costs 21000 Gas where the Gas Price is 5 Gwei will cost 0.000105 ETH

Message

Virtual objects that exist only in Ethereum's execution environment. They are sent from one contract to another

Main attributes:

  • Sender
  • Recipient
  • Amount of ether to transfer alongside the message
  • Data (optional)

Faucet

A Smart Contract that transfers tokens to an address for free. Faucets exist in test networks and are usually required for testing purposes

Authenticating with Offchain

This process allows off-chain services to verify the identity of a request's sender. Basically: "how do I know you are the address you say you are?"

The way we authenticate the sender of a request is by sending them a verificationCode that the sender must sign and include along with their address. If we can retrieve their address, then we can be certain they are who they say they are.

Current steps:

  1. Client requests verification code and a typedName to [Offchain][poly-offchain]

  2. Code is signed locally along with typedName

    • Code is signed by the client using eth_signTypedData, for more info read EIP-712

  3. Signed message is sent to Offchain:

    • Sends code, address and sig (signature)
    • Offchain based on these parameters retrieves the address that signed the message
    • If the address retrieved matches the one sent by the client, then the client is who it says it is

Creating and Issuing a Security Token

You can read a detailed description of this process done from the issuer app here

Steps:

  1. Reserving a Ticker
  2. Creating a Security Token
  3. Whitelisting Addresses
  4. Minting Tokens
  5. Deploying an STO (Security Token Offering)

Reserving a Ticker

The first step a user must go through is reserving a the Security Token's symbol or "ticker". This prevents any other address to issue a Security Token through Polymath, though this symbol cannot be ensured to be unique in the Ethereum Network. Once the ticker reservation goes through, the ticker will be reserved for a certain amount of days. After this period, if the token is not deployed, it will be released and available for anyone to reserve again.

The contract that deals with ticker reservations is the TickerRegistry. When SecurityTokenRegistry receives a request to issue a Security Token, it will check if the ticker exists in the TickerRegistry and was reserved by the requester's address.

NOTE: In the release 2.0 of the smart contracts the TickerRegistry will be merged into the SecurityTokenRegistry

Steps:

  • Approve the required amount of POLY to be spent by the registry (use approve method)
  • Call the required function to register the ticker

Creating a Security Token

Once you have reserved your ticker, you can deploy your Security Token (note that this will not launch an STO yet, it will just deploy the token to the network)

Steps:

  • Approve the required amount of POLY to be spent by the registry (use approve method)
  • Call the required function to register the ticker with the required information about the ticker

Whitelisting Addresses

This process can occur before or during an STO and in consist on setting a list of investors that are allowed to own tokens before/during the STO. The whitelist is setup on the GeneralTransferManager which is by default attached to your Security Token. It will also control lockup dates before investors can transfer tokens and limits in the amount of tokens they can own.

Steps:

  • Call the required function to add addresses to the whitelist

Minting Tokens

Before an STO start, you can mint tokens to previously whitelisted addresses

Steps:

  • Call the required function in the SecurityToken's smart contract

Deploying an STO

An STO the Security Token's equivalent of an ICO (Initial Coin Offering). This is where the Security Token will be available to purchase by investors.

To deploy your STO, you must attach an STO Module with the help of its STO Factory, the STO Module attached to the Security Token will define the rules of the STO.

Steps:

  • Retrieve the setup cost from the STO Factory of your STO Module of choice
  • Pay the cost of attaching the module (Note: It is unclear why a transfer is required instead of an approve() here), the payment is done to the SecurityToken's address
  • Call the required function to add the module in the SecurityToken Smart Contract.