@tokenize.it/contracts NPM

tokenize.it

These smart contracts implement tokenize.it's tokenized cap table management. Using tokenize.it, it is possible to:

generate tokens that grant economical rights to the token holder
sell these tokens to investors either publicly or privately
distribute tokens to employees or partners, either directly or through a vesting contract

Getting Started

... for usage

yarn add @tokenizeit/contracts

npm install @tokenizeit/contracts

... for development

clone repository: git clone --recurse-submodules git@github.com:corpus-ventures/tokenize.it-smart-contracts.git
enter project root folder: cd tokenize.it-smart-contracts
if repository was cloned without submodules, init submodules now (not necessary if cloning command above was used): git submodule update --init --recursive
init project: yarn install
run tests: yarn test

If you are missing dependencies:

node/npm:
- install nvm
- nvm install 18
- nvm use 18
yarn: npm install yarn
foundry: install guide

More dev information can be found here:

Main Concept

Using tokenize.it's legal approach, a company can create tokens that grant economical rights to the token holders. The best smart contract to create these tokens is Token.sol
Funds are raised through selling of these tokens:
- a customized deal to a specific investor can be realized through the PrivateOffer.sol contract.
- crowdinvesting, which is open to everyone meeting the requirements, is done through the Crowdinvesting.sol contract
Employee participation is easy:
- direct distribution of tokens (does not need another smart contract)
- vesting can be realized using the Vesting.sol contract

The requirements for an address to send or receive tokens are checked against the AllowList.sol contract. Fees are collected according to the settings in FeeSettings.sol. Tokenize.it will deploy and manage at least one AllowList and one FeeSettings contract.

Contracts

The smart contracts can be found in the contracts/ folder.

All contracts are based on the well documented and tested OpenZeppelin smart contract suite.

EIP-2771

It is possible to directly use all smart contracts in this project, without going through the platform's frontend at all. In order to improve UX, though, a frontend will be offered. In order to improve UX even more, the user will not have to pay gas when using this frontend. This is achieved through three approaches:

the platform executes transactions like contract deployments that do not require the user's signature
actions concerning our own contracts that require the user's approval are executed as meta-transactions, using EIP-2711
granting allowances on external currencies is possible through EIP-2612 (ERC20Permit), which is widely adopted. This is not in the scope of this documentation though.

Several of the contracts implement EIP-2771, and therefore use a trusted forwarder. The forwarder will be set in the constructor and there is no way to change it after deployment. The forwarder used will be the openGSN v2 forwarder deployed on mainnet. Some information about this contract:

Documentation and addresses
Code
Audit reports
Deployment: 0xAa3E82b4c4093b4bA13Cb5714382C99ADBf750cA
- deployed 2022-04-21
- Visit on etherscan (see transactions here)
- This dashboard lists the forwarder as second most active forwarder contract with over 2000 transactions executed
- used in our tests.

The platform will maintain a hot wallet (EOA) in order to send transactions to the forwarder contract. This results in the following flow:

contract A supports EIP-2771 and uses forwarder as its (one and only, immutable) trusted forwarder
user (investor or founder) wants to use function a(...) of contract A and uses the platform for this
platform (tokenize.it) prepares meta transaction payload and asks user for signature
user signs the payload with their own key (using metamask or similar)
platform now has payload and signature and uses its hot wallet to call forwarder.execute(payload, signature, ...)
forwarder verifies signature and payload on-chain
forwarder executes A.a(...) with parameters according to payload
contract A only verifies it is being called by the ONE forwarder it trusts. It does not verify any signatures. This is why the forwarder is called trusted forwarder: it is trusted to do the verification.
contract A executes function a(...) in the name of user

This is a trustless process, because:

the forwarder contract can not be updated
the trusted forwarder setting in contract A is immutable
signature verification is executed on-chain

Open gas station network provides tools to execute meta transactions without involving a third party hot wallet. Tokenize.it does not plan on using these tools though. Exclusively using a hot wallet for transaction execution does not harm security at all.

The hot wallet approach might reduce availability, which is not a major concern for this use case (the hot wallet being available whenever the frontend is available is good enough). Keep in mind that EIP-2771 is purely offered for UX reasons. All smart contracts can be used directly, too, further reducing concerns about hot wallet availability.

An Openzeppelin Defender Relay may be used as hot wallet.

Supported Currencies

The currencies used for payments must conform to the ERC20 standard. This standard is not very strict though. It can be implemented in many ways, including incompatible and even malicious contracts. Therefore, tokenize.it will limit the currencies supported in the web frontend to this list:

These implementations have been checked and tested to work well with the tokenize.it smart contracts. The use of any other currencies is HIGHLY DISCOURAGED and might lead to:

loss of funds due to various attacks
partial payments due to the currency deducting a transfer fee
other issues

To enforce the use of trusted currencies only, they are added to the AllowList.sol contract with the special TRUSTED_CURRENCY bit. PrivateOffers and Crowdinvesting campaigns will only accept currencies that are on the AllowList and have the TRUSTED_CURRENCY bit set. This makes using a malicious currency by mistake impossible, but still allows either the platform or other operators of their own AllowLists to edit and extend the list of supported currencies.