Token Creation

How to Create your Security Token

GitHub - PolymathNetwork/token-creator: A simple dapp to demo Security Token creation on Polymath protocolGitHub

👀 Overview

This app covers the most basic and essential functionality of the Polymath protocol: security token creation. Creating a token requires two transactions with Polymath's SecurityTokenRegistry contract, both of which charge a fee in POLY:

1. Reserve your preferred symbol.

2. Configure and deploy the security token.

The Polymath SDK abstracts the smart contract operations, so special knowledge of the SecurityTokenRegistry contract is required.

💎 Deploying your first Security Token

First, we need to reserve a token symbol. The SDK interacts with the SecurityTokenRegistry contract to make reserving token symbols simple:

try {
    const reservationQueue = await polyClient.reserveSecurityToken({
        symbol: 'ABC123',
    });
    const reservation = await reservationQueue.run(); // Will run every required transaction sequentially
    
    const creationQueue = await reservation.createSecurityToken({
        name: 'ABC 123 Inc.',
        detailsUrl: 'http://example.com',
        divisible: true
    });
    const token = await creationQueue.run();
    // Ta-da!! you've deployed your first Security Token!
    
} catch(error) {
  // Transaction has reverted, transaction has been rejected by app user, network issues...etc
  console.error(error);
  if (error.message.contains('has already been registered')) {
    // Symbol 'ABC123' had been registered by someone else. Handle accordingly.
  }
}

A successful reserveSecurityToken() call reserves a symbol to the current user address. Reserving a symbol means that no one else will be able to reserve it while you complete the necessary steps to deploy your security token.

Once reservation.run() has resolved, it will return a reservation entity. We can use that entity to proceed with the token creation. Method createSecurityToken() accepts four parameters:

• name: the human-friendly token name.

• detailsUrl: an off-chain resource about the token (i.e., webpage).

• divisible: whether or not the token is divisible.

Note that reserveSecurityToken(), as well as all SDK functions, typically receive named parameters in the form of an object. That object wraps all required params such as symbol and name.

Symbols are reserved for a period of 60 days, after which they can be claimed by other issuers. You may also renew your reservation before it expires.

All SDK write operations are represented as transaction queues. For each operation, the SDK creates as many transactions as needed to complete the operation. Upon calling queue.run(), the SDK executes these transactions, sequentially, until completion. Running a queue can result in values (for example, running the queue that creates a security token will return an entity that represents said token).

Transaction Errors

In a perfect world, your token reservation and creation transactions will go through without any issues. However, there are many reasons why a transaction may fail. Some errors are operational, for example, you've lost internet connection during script execution, or the Ethereum account responsible for signing transactions has ran out of ETH.

Another class of errors are revert errors (smart contract execution errors). One common revert error occurs when we attempt to reserve a token symbol that's been reserved before and has not expired. You may catch the error in the example below:

...
} catch(error) {
  // Transaction has reverted, transaction has been rejected by app user, network issues...etc
  console.error(error);
  if (error.message.contains('has already been registered')) {
    // Symbol 'ABC123' had been registered by someone else. Handle accordingly.
  }
}

💻 Reading token data

Finally, you can retrieve the token you've created, either by symbol or by your own address:

const token = await polyClient.getSecurityToken({symbol: 'ABC123'});

// or

const token = (await polyClient.getSecurityTokens({owner: ISSUER_ADDRESS}))[0]; // This call returns all tokens created by that address

console.log(token);
// =>
// SecurityToken {
//  symbol: "ABC123",
//  name: "ABC 123 Inc.",
//  owner: "0xC257274276a4E539741Ca11b590B9447B26A8051",
//  address: "0xCD959e71449425F6E4ac814b7f5aeBdE93012E24",
//  uid: "c2VjdXJpdHlUb2tlbjp7InN5bWJvbCI6IktPVkFOM1RFU1QifQ=="
...

A SecurityToken entity is a js object representation of your deployed securitytoken contract. You may fetch properties such as the token name, symbol, divisibility, and manage all aspects of your security token. User permissions, tokenholder management, and launching your first STO are among some of the features covered in later tutorials.