[go: up one dir, main page]

0% found this document useful (0 votes)
44 views13 pages

TOKENF

Uploaded by

sofia.rikov
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
44 views13 pages

TOKENF

Uploaded by

sofia.rikov
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 13

TokenF

On-chain Real World Assets


Tokenization Framework

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

4. TokenF vs ERC-3643 (T-REX).......................................................................................... 11


4.1. Diamond Pattern Architecture................................................................................... 11
4.2. Solarity Based Role Management............................................................................. 11
4.3. KYC Providers Integration.........................................................................................12
4.4. Claim Topics and Context Execution Flow................................................................ 12

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.

Having extensive experience in developing private / L2 tokenization frameworks


(TokenD, TokenE) and custom solutions on top of them we decided to take a one
step further and build the next-generation framework that is lightweight, abstract, and
fully on-chain.

We reimagined ERC-3643 (T-REX) techniques, expanded its architecture


capabilities, solved a slew of tight-coupling problems T-REX has, added a set of KYC
/ compliance modules, and named the framework - TokenF.

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.

Functionality covered by TokenF:

- Extensive Diamond-pattern-based modularity that allows any KYC / regulatory


compliance checks to be implemented, allowing integration with various
3rd-party KYC providers. For instance, integration with the zk-powered
Rarimo proof-of-human (PoH) identity solution.
- Flexible role-based access-control management system which enables
custom access rules for privileged parties to be set up. The RWA solution may
require dedicated access to a certain functionality / asset, which is now easy
to tackle.
- Context-driven transaction execution flow that allows precise tracking of
parties, actions, checks, and rules involved in the transaction to be exercised.
Simply put, TokenF will push the entire transaction knowledge to the
connected modules so they can check the KYC / compliance with ease.
- ERC-20 compatibility which provides flexibility for implementing eligibility
checks through the integration of compliance modules without affecting the
standard ERC-20 behavior.
- Conditional rules for standard ERC-20 functions with simple configurability.
Configuration is supported on both pre-deployment (scripts) and
post-deployment (runtime) stages.
- State-of-the-art codebase that leverages advanced development techniques,
seamlessly abstracting complexity behind the rich, though-out smart
contracts. We used Solarity and Openzeppelin to tie everything together.

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:

- Thorough KYC procedure before customer onboarding.


- Constant AML and KYC customer activity analysis in respect of suspect
transactions to be related to money laundering or terrorist financing.
- Freeze and suspension of a customer's wallet.
- Freeze of partial or total tokens on a customer's wallet.
- Suspend the token.
- Impose limits to reduce the size of the position or exposure in a token.
- Limit the ability of any customer wallet to enter into a token, including the
introduction of limits on the size of a position any wallet can hold at all times.

*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

2.1. TokenF Architecture

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.

Another crucial aspect of TokenF architecture is the modules. Every TokenF-based


token may be additionally configured with a custom set of modules that work as
standalone token plugins. Modules are composed of rules and checks that users
have to abide by to use the token. These modules, in turn, integrate with 3rd-party
KYC providers, monitoring services, etc.

Pic. 1 TokenF architecture

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.

Custom modules may be plugged into the corresponding KYCCompliance and


RegulatoryCompliance facets, giving you flexibility in following any business
logic through custom integrations.

5
Distributed Lab

2.2. Access Control

TokenF contract extends AccessControl (from Openzeppelin) functionality, which


gives you convenience in managing existing roles in the tokenization project.

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.

2.3. Compliance Control

As mentioned above, TokenF is a Diamond contract with two facets included in the
base implementation:

- Compliance Facet (RegulatoryCompliance)


- KYC Facet (KYCCompliance)

These facets enable module management functionality for compliance contracts, as


well as functions for validating rules from the corresponding compliance interfaces.

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:

1. _canTransfer - Read-only hook that is used by RegulatoryCompliance


modules to check if the token transfer (amount) satisfies assigned rules.
2. _isKYCed - Read-only hook that is used by KYCCompliance modules to
check that users follow the set of KYC rules.
3. _transferred - Read / Write hook that is used by RegulatoryCompliance
modules to update some custom state of the accounting system.

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.

As soon as the sender executes transfer transaction, the _canTransfer hook is


called and the minimal transferred amount is checked. If the amount is less than 1
token, the transaction will be reverted. Then, the _isKYCed hook gets called. It
checks that both the token sender and receiver possess SBT tokens from the KYC
provider. If that check fails, the transaction will be reverted.

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.

2.4. Execution Context

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:

- Function called (selector), for example, transfer, transfer from, or


other function;
- Address from which tokens are transferred;
- Address to which tokens are transferred;
- Amount of tokens transferred;
- Address of an operator;
- Additional bytes data for custom compliance checks.

Simply put, context-based flow allows us to implement diverse regulatory checks.


For example, for transfer function, the minimum transaction amount as 1 token
can be set. However, transfer from function may be configured with a minimum
amount of 10 tokens.

Moreover, the explicitness of the context makes it possible to implement different


rules for different users (sender / recipient / operator). You may specify the sender to
hold a certain amount of tokens before they are allowed to spend them.

All these checks are explicitly configured via handlers.

7
Distributed Lab

2.5. Handlers

Handler is an internal function of a module-contract with a specific signature


(specified below) that internally implements the KYC / regulatory checks required for
the business logic.

function <name>(TokenF.Context memory) internal view


virtual returns (bool);

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.

2.6. Claim Topics and Claim Topic Keys

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.

In the basic implementation, the claim topic key is formed as follows:

- For KYC modules - keccak256(function selector, transfer


party), where transfer party is from, to, or operator.
- For Regulatory modules - keccak256(function selector).

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;
}

We will associate the MIN_TRANSFER_LIMIT_TOPIC with the “claim topic key”


keccak256(transfer.selector). During the transaction execution this “claim
topic key” will be reconstructed from the given “execution context” (TokenF will take
the context selector) and perform the compliance flow.

3. TokenF Modules

3.1. Modules Architecture

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

Pic. 2 TokenF modules architecture

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.

3.2. AbstractModule Contract

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).

Moreover, the AbstractModule contract defines an interface through which the


TokenF managers will “speak” with the module.

3.3. AbstractKYCModule Contract

The AbstractKYCModule contract implements the AbstractModule interface


and extends it by introducing the isKYCed function. This function is used by the
KYCCompliance TokenF facet to authorize the user of the token. The module also

10
Distributed Lab

overrides the rules of claim topic key construction to be bytes32 claimTopicKey


= keccak256(function selector, transfer party).

3.4. AbstractRegulatoryModule Contract

The AbstractRegulatoryModule contract is very similar to the


AbstractKYCModule in terms that it also implements the AbstractModule
interface. However, two new functions are introduced: canTransfer and
transferred. RegulatoryCompliance TokenF facet will call them to perform
regulatory compliance checks. The module overrides the claim topic key construction
to be bytes32 claimTopicKey = keccak256(function selector).

4. TokenF vs ERC-3643 (T-REX)

4.1. Diamond Pattern Architecture

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.

4.2. Solarity Based Role Management

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.

4.3. KYC Providers Integration

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.

4.4. Claim Topics and Context Execution Flow

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

You might also like