TOKENF
TOKENF
Distributed Lab
March 2024
Distributed Lab
Table of Contents:
1. Introduction........................................................................................................................ 3
2. TokenF Core........................................................................................................................5
2.1. TokenF Architecture.................................................................................................... 5
2.2. Access Control............................................................................................................ 6
2.3. Compliance Control.....................................................................................................6
2.4. Execution Context....................................................................................................... 7
2.5. Handlers...................................................................................................................... 8
2.6. Claim Topics and Claim Topic Keys............................................................................ 8
3. TokenF Modules................................................................................................................. 9
3.1. Modules Architecture...................................................................................................9
3.2. AbstractModule Contract...........................................................................................10
3.3. AbstractKYCModule Contract................................................................................... 10
3.4. AbstractRegulatoryModule Contract..........................................................................11
5. GitHub Repository........................................................................................................... 13
2
Distributed Lab
1. Introduction
Demand for on-chain tokenization resulted in the creation of a few competing ERC
standards. These are ERC-1400, ERC-1155, ERC-3643 (T-REX) as well as CMTA
and tZERO approaches.
TokenF is an open-source product released under an MIT license that can be used
as a set of abstract tokenization smart contracts for those who are building their own
RWA solutions.
3
Distributed Lab
TokenF may be configured to include (but is not limited to) the following list of
regulatory limitations that we think are essential for any regulated on-chain token:
*Depending on the specific country regulation rules may differ, but the general
regulatory approach and functionality usually stay the same.
While creating the TokenF framework, we studied the following existing tokenization
solutions:
⌀ ERC-3643 (T-REX):
- Frictionless Protocol (Defyca) framework that enables the tokenization
of securities in compliance with European law.
- Tokeny Solutions
- Tokenforge
⌀ ERC-1155:
- FinRamp
⌀ ERC-1400:
- Matrixdock
- Polymath
⌀ ERC-20 with additional modifications:
- Tokenize.it
- tZERO
- ADDX
⌀ CMTA Token:
- TAURUS framework that enables the tokenization of securities in
compliance with Swiss law.
4
Distributed Lab
2. TokenF Core
The central part of the framework is the TokenF smart contract which represents one
particular tokenized asset. TokenF is an ERC-20 compatible contract built on a
Diamond architecture, which allows for a seamless extension of standard TokenF
functionality. One of the key benefits is that Diamond architecture enables contracts
to bypass the maximum bytecode size restriction, making complex rules and checks
feasible.
The diagram depicts the basic TokenF structure. The token itself is a Diamond proxy
contract that extends the ERC-20 and AccessControl smart contracts while
containing KYCCompliance and RegulatoryCompliance as standard Diamond
facets.
5
Distributed Lab
The role list may be configured according to the given tokenization logic and may
include:
- “DAO” role with access to mint, burn, recover, and forced transfer
functions.
- “Investor” role for transfer and transfer from functions.
- “Compliance officer” role for setting up and updating compliance rules.
Having custom roles set does not limit you from checking that users follow regulatory
compliance rules. Instead, access control allows for an additional layer of security
and customization.
As mentioned above, TokenF is a Diamond contract with two facets included in the
base implementation:
The compliance control is achieved via hooks that are called every time the user
interacts with the TokenF token. These hooks initialize the assembly of “context” that
will be forwarded to the plugged-in modules:
6
Distributed Lab
Let’s take a look at the TokenF transfer function execution flow. By KYC
compliance rules we assume that the token sender and receiver have to be KYCed
by possessing an SBT token from the trusted KYC provider. Additionally, we assume
that not less than 1 token could be sent. In the TokenF terms, we treat this rule as a
compliance rule.
Having all checks pass, _transferred hook gets called after the successful token
transfer (balance update). The hook can be used, for example, to update the
transaction count for statistics, analytics, or other purposes.
When users interact with the TokenF contract, a certain context is forwarded to the
Compliance and KYC modules. Depending on that context, regulatory checks are
configured. The Context contains the following information:
7
Distributed Lab
2.5. Handlers
These handler functions are associated with special “claim topics” (claim topic =>
handler function) that in turn describe what these handlers do. The handler function
may integrate with some external service to authenticate the user / perform some
accounting system state checks.
In a nutshell, a claim topic is an identifier of the handler function that will perform
some compliance checks. Since there may be more than one check to execute, the
framework has to support the set of claim topics to be configured.
Indeed, the configuration is performed through the specification of “claim topic key”
that points to the array of “claim topics”. During the transaction execution, the
TokenF module is passed an “execution context” (section 2.4.) which eventually
becomes the source of “claim topic key” construction. The associated “claim topics”
are extracted from this “claim topic key”, the corresponding “handler functions” are
obtained, and, at last, called.
Suppose we want to add a rule to the token contract that no more than 10 ether
tokens can be transferred per transaction. In this case, we can define a bytes32
public constant MIN_TRANSFER_LIMIT_TOPIC =
keccak256("MIN_TRANSFER_LIMIT") claim topic, for which we will set up a
handler:
8
Distributed Lab
function _handleMaxTransferLimitTopic(TokenF.Context
memory ctx_) internal view virtual returns (bool) {
return ctx_.amount <= 10 ether;
}
3. TokenF Modules
Modules are the backbone of the TokenF framework regulatory mechanics. All rules,
requirements, and compliance for KYC and various token transfers can be
customized via modular plugin-based architecture.
In the vanilla TokenF version there are two main types of modules:
1. KYC modules
2. Regulatory modules
The KYC modules are responsible for any KYC-related compliance checks while
Regulatory modules are used to perform conditional transfer limits / token balance
obligations / operational limits / etc.
Modules represent quite a complex set of smart contracts that are related through
inheritance and plugged in through composition to the aforementioned
RegulatoryCompliance and KYCCompliance facets.
9
Distributed Lab
The diagram depicts the relationships between contracts within the TokenF modules
architecture. The bulk of the logic is implemented in the AbstractModule that
AbstractKYCModule and AbstractRegulatoryModule extend. Certain
modules will then inherit from AbstractKYCModule and
AbstractRegulatoryModule contracts to define handlers, their relation to claim
topics, claim topics keys construction, context extensions, and perform the required
checks.
The AbstractModule contract is the basis for writing new modules for the TokenF
framework. The contract implements the logic of claim topics management, the
definition of handlers, the extension of contexts, and stores the “weak reference” to
the TokenF token contract itself (for certain operations that should only be called by
the token).
10
Distributed Lab
Let's start our comparison with the architecture. The T-REX standard accommodates
a large number of contracts that need to be properly linked together. Upgradable
functionality is present, but it is almost impossible to extend the token contract or any
other protocol contract. The connection between all contracts is quite tight, so it is
difficult to implement custom logic, which is needed quite often. As a result, we have
a solution that may be suitable for a narrow list of cases, provided everything is
properly configured.
The TokenF framework architecturally has one central token contract and a set of
custom modules for a specific business task. TokenF contract itself is made
according to the Diamond pattern, so it allows you to easily customize the basic
logic, expand it, and upgrade as needed. As a result, we have a small and flexible
core that can be easily integrated with other protocol contracts and is almost infinitely
extendable in terms of functionality.
In large systems, a good role system is often needed to manage access to contracts.
In T-REX there are only two roles: owner and agent. All agents are equal to each
other, while the owner can do absolutely anything. This approach is not very flexible,
because all custom functions for a token have the onlyAgent modifier, which takes
11
Distributed Lab
away the ability to configure accesses for each function of the same ERC-20 token.
For small and simple projects, it may be a good solution, but for medium and large
protocols it becomes a problem.
TokenF has a more flexible role system, based on the AccessControl contract
from the Solarity library (which is also used in our TokenE solution). The idea behind
AccessControl itself is quite simple - we have roles to which we can add or
remove addresses. Accordingly, in the TokenF contract, we can manage existing
roles and flexibly customize them. For all functions of system contracts where at
least some access is required, roles can be configured independently of each other.
For example, for mint and burn functions there can be different roles.
Here we come to the key parts of our tokenization protocol - these are the rules for
the various regulations. Let's start with KYC. In the T-REX protocol, contracts are
hardwired into the OnChain ID protocol only. Everyone using T-REX must measure
up to the fact that they will only use OnChain ID for KYC functionality. This part of
T-REX protocol is completely inflexible and does not allow the use of other KYC and
identity protocols.
TokenF has a separate type of compliance for KYC. The essence of this approach is
that we can implement the necessary KYC modules to meet the specific
requirements of the project. These modules can integrate with absolutely any KYC
provider, which gives full freedom for customization. You can easily integrate TokenF
with the open-source zk-powered Rarimo identity solution based on biometric
passports. Also, TokenF allows you to integrate with several providers at once.
Accordingly, there is also a logic of claim topics, so you can flexibly configure
different ways of KYC checking for different contexts if such logic is necessary.
The second key part of regulation is setting up rules for interacting with the tokens.
That is forwarding, creating, restoring, freezing, etc. ERC-3643 (T-REX) has different
hooks in which modules will check conditions, but there is a nuance, modules do not
know anything about the context of the transaction, so it is impossible to set different
checks for transfer and, for example, for mint functions. You will check the same
thing everywhere, which is very inconvenient and sometimes is a critical problem.
12
Distributed Lab
As it was mentioned earlier, TokenF has a system of context and claim topics, which
can be set by custom keys. Accordingly, developers, depending on the business
requirements of the project, will be able to determine how specific rules should be
implemented. Also, the handler system allows to avoid huge if-else structures in
module functions, which makes the code clearer and cheaper for execution.
5. GitHub Repository
Here is a link to the TokenF repository. The framework is distributed under the MIT
license.
13