Security Token

Security Token Documentation

Introduction

The Security Token system is designed to create and manage tokenized securities on the blockchain. It implements the ERC1400 standard, which extends ERC20 functionality with features specific to security tokens, such as transfer restrictions and partitioned balances. This system provides a flexible and compliant framework for issuing and managing security tokens.

Key Components

SecurityToken

The main contract that represents a security token. It implements the ERC1400 standard and includes additional features for issuance, redemption, and transfer control.

SecurityTokenFactory

A factory contract that deploys new instances of the SecurityToken. It uses the upgradeable beacon pattern for easy upgrades of all deployed instances.

ISecurityToken

The interface defining the core functionality of the Security Token system, including initialization parameters and key functions.

Functionality

Token Issuance

Authorized addresses can issue new tokens to specified recipients. This process involves:

1. Calling the issue function, specifying the recipient and amount.

2. Optionally providing additional data for the issuance.

Token Redemption

Token holders can redeem their tokens, effectively destroying them and potentially receiving underlying assets in return.

Transfer Restrictions

The Security Token implements transfer restrictions as per the ERC1400 standard. Transfers can be restricted based on various criteria, including regulatory requirements.

Partitioned Balances

Tokens can be divided into different partitions, allowing for more granular control over token ownership and transfers.

Controller Operations

Authorized controllers can force transfers between addresses, providing a mechanism for regulatory compliance or legal actions.

Usage Guide

Deploying a Security Token

1. Deploy the SecurityTokenFactory.

2. Call the deploy function on the factory, providing initialization parameters:

bytes32 stId = keccak256("mySecurityToken");
ISecurityToken.InitializeParams memory params = ISecurityToken.InitializeParams({
    name: "My Security Token",
    symbol: "MST",
    granularity: 1,
    controllers: controllers,
    defaultPartitions: defaultPartitions,
    extension: extensionAddress,
    owner: ownerAddress,
    minter: minterAddress
});
bytes memory stInitData = abi.encodeWithSelector(SecurityToken.initialize.selector, params);
address deployedSecurityToken = stFactory.deploy(stId, stInitData);

Issuing Tokens

As an authorized minter:

securityToken.issue(recipientAddress, amount, "");

Redeeming Tokens

As a token holder:

securityToken.redeem(amount, "");

Transferring Tokens

Standard ERC20 transfer:

securityToken.transfer(recipientAddress, amount);

Transfer with partition:

securityToken.transferByPartition(partitionBytes32, recipientAddress, amount, "");

Checking Transfer Validity

Before attempting a transfer:

bytes memory reason = securityToken.canTransfer(recipientAddress, amount, "");
require(reason.length == 0, "Transfer not allowed");

Managing Controllers

As the token owner:

securityToken.addController(controllerAddress);
securityToken.removeController(controllerAddress);

Security Considerations

1. Access Control: Ensure that only authorized addresses can call sensitive functions like issue, redeem, and controller operations.

2. Transfer Restrictions: Implement and thoroughly test transfer restriction logic to comply with regulatory requirements.

3. Upgrades: The upgradeable beacon pattern allows for upgrades. Ensure that upgrade processes are secure and well-tested.

4. Partitions: Be cautious when working with partitioned balances to avoid accounting errors.

5. Extension Contracts: If using extension contracts (e.g., for transfer validation), ensure they are secure and properly integrated.