CMTA Token

This repository is a library which proposes an implementation in cameligo of a CMTA token described by the specifications.

It includes features from the basic token standard (TZIP12) and extra features for managing the total supply, for providing snapshots, and granting authorization to other users.

The purpose of this library is to provide a help to create a CMTA token. It provides CMTA features implemented as modules which can be used to designa CMTA Token.

This library is extendable which means that when creating a CMTA token, it is possible to override features and to extend the storage with extra fields. These extra features can rely on extra fields in the storage and thus allow to create custom token with CMTA features and additionnal custom features.

This library relies on the @ligo/fa library which implements the TZIP-12 standard features and provides an implementation for fungible single-asset, fungible multi-asset , and non-fungible token. In the same manner this CMTA Token library also supports these 3 kind of tokens.

How to use this library

Install the library with ligo CLI

ligo install @ligo/cmtat

This command will add a dependency in a ligo.json file.

Here is an example of the resulting ligo.json file.

{ "dependencies": { "@ligo/cmtat": "^1.0.0" } }

Once installed, you can use the cmtat library to create a cmtat token, or design a custom cmtat token by using the modules provided by the library.

Configurations (asset type and extendable)

The library provides a default CMTAT Token implementation which declares all entrypoints. This default CMTAT Token implementation is not extendable (i.e. the storage cannot be extended with extra fields).

The following asset types are supported

• Single asset
• multi asset
• NFT

The library also provides an extendable implementation which helps to create a custom CMTAT Token implementation. Notice that the custom CMTAT Token must declare its entrypoints and can rely on the extendable implementation modules.

The following modules are provided by the library

type	extendable	module name
single	No	CMTAT_SINGLE_ASSET
single	Yes	CMTAT_SINGLE_ASSET_EXTENDABLE
multi	No	CMTAT_MULTI_ASSET
multi	Yes	CMTAT_MULTI_ASSET_EXTENDABLE
nft	No	CMTAT_NFT_ASSET
nft	Yes	CMTAT_NFT_ASSET_EXTENDABLE

How to implement a custom CMTA Token

The library provides an extendable implementation which consist on a module that can be aliased for readingness.

#import "@ligo/cmtat/lib/main.mligo" "CMTAT"
module Token = CMTAT.CMTAT_SINGLE_ASSET_EXTENDABLE

Now we can use all sub modules to complete the implementation of the custom CMTA Token.

Sub-modules

The CMTAT library provides features separated on sub-modules which can be used in the final token contract. This Token contract must declare its entrypoints and can use functions implemented in the CMTAT library.

For example, the declaration of the mint entrypoint can rely on the default implementation provided by the module.

The storage definition can rely on the one provided by the module. It is an extendable storage which expects a type. (Use unit if no extension)

#import "@ligo/cmtat/lib/main.mligo" "CMTAT"

module Token = CMTAT.CMTAT_SINGLE_ASSET_EXTENDABLE
type storage = unit Token.storage
type ret = unit Token.ret

[@entry]
let mint (p: Token.mint_param) (s: storage) : ret =
  Token.mint p s

In the snippet of code (above) the Token.mint function is the default implementation. Notice that this token is a "Single asset" because the CMTAT.CMTAT_SINGLE_ASSET_EXTENDABLE module is used. This module also provides an interface (Token.mint_param) and a default storage (Token.storage).

Extendable library

By "extendable" it is meant that the storage can be extended. This module has been designed to allow to add extra field in the storage. The CMTAT.CMTAT_SINGLE_ASSET_EXTENDABLE module provides a parametric storage which expects an extension custom type.

For example one can define an empty extension by providing a unit type

type storage = unit Token.storage

or add new fields in an "extension" type

type extension = {
  issuer : address
}
type storage = extension Token.storage
type ret = extension Token.ret

This extendability is essential to allow to anyone to create tokens which inherit from CMTA Token behavior.

One may want to override the default behavior provided by the CMTAT.CMTAT_SINGLE_ASSET_EXTENDABLE module. Here's an example of an override where the pause entrypoint can only be called by the issuer (that we just defined previously in the extension) or the administrator (thus ignoring the PAUSER role).

[@entry]
let pause (p : Token.ADMINISTRATION.pause_param) (s : storage) : ret =
  let sender = Tezos.get_sender() in
  let () = assert_with_error ((sender = s.extension.issuer) || (sender = s.administration.admin)) Errors.not_issuer_nor_admin in
  [], { s with administration = Token.ADMINISTRATION.pause p s.administration }

Notice that in this snippet of code, we do not use the Token.pause function but we use the sub-module Token.ADMINISTRATION in order to squizz the default role verification.

The error message is defined in an Errors sub module.

module Errors = struct
  let not_issuer_nor_admin = "Not issuer not admin"
end

Declare entrypoints

In order to finish the implementation of the custom CMTA Token, all expected entrypoints must be declared (and implemented).

Check the test example for an exhaustive snippet of code that defines all entrypoints. (Careful ! in the example the pause entrypoint has been overridden, consider the commented section instead).

[@entry]
let transfer (t : Token.TZIP12.transfer) (s : storage) : ret =
  Token.transfer t s

[@view]
let get_balance (p : (address * nat)) (s : storage) : nat =
  Token.get_balance p s


// [@entry]
// let pause (t : Token.ADMINISTRATION.pause_param) (s : storage) : ret =
//   Token.pause t s

// Exemple of override of pause Entrypoint
[@entry]
let pause (p : Token.ADMINISTRATION.pause_param) (s : storage) : ret =
  let sender = Tezos.get_sender() in
  let () = assert_with_error ((sender = s.extension.issuer) || (sender = s.administration.admin)) Errors.not_issuer_nor_admin in
  [], { s with administration = Token.ADMINISTRATION.pause p s.administration }

[@entry]
let mint (p: Token.mint_param) (s: storage) : ret =
  Token.mint p s

[@entry]
let burn (p: Token.burn_param) (s: storage) : ret =
  Token.burn p s

CMTAT sub modules

FA2 (TZIP-12 standard)

FA2 basic features (from standard) consists on allowing people to transfer assets between them

Total supply

The Totalsupply module consists on keep track of the total supply of the token. The total supply represents the total number of assets. It is updated when some assets are minted or burned.

Administration

The Administration module consists on allowing a special user (administrator) to pause/unpause the contract, and to create assets and to destroy assets.

The Administration module also provide a kill function to destroy the contract. Actually the contract still exist but the storage is cleaned and the entrypoints are disabled.

Authorizations

The Authorizations module allows the administrator of the token to delegate some of his responsabilities to other trusted persons. It allows to grant administration roles to other trusted user.

Being granted of a role allows to call specific entrypoints. Here is a list of roles and corresponding entrypoints.

Role	Entrypoints
PAUSER	pause
MINTER	mint
BURNER	burn
RULER	grantRole, revokeRole
SNAPSHOOTER	scheduleSnapshot, rescheduleSnapshot, unscheduleSnapshot
VALIDATOR	setRuleEngine

When calling one of these entrypoints a role verification is performed. The diagram illustrates this verification for the pause entrypoint.

stateDiagram-v2
    state is_admin_state <<choice>>
    state is_pauser_state <<choice>>
    change_paused_flag: Change paused flag
    [*] --> is_admin_state
    is_admin_state --> change_paused_flag: if sender = admin
    is_admin_state --> is_pauser_state : if sender <> admin
    is_pauser_state --> change_paused_flag: if sender has PAUSER role
    is_pauser_state --> NOT_PAUSER: if sender has not PAUSER role
    change_paused_flag --> [*] 

Loading

The role verification is similar for all entrypoints.

The Authorizations module provides two functions (grantRole, revokeRole) to modify roles for a given user.

The Authorizations module also provides a function (hasRole) to verify if a given user has a given role .

ATTENTION ! Specifically for Multi asset configuration, an additonnal mecanism for role specific per token_id has been added. Though it is not applied to all roles ! Some roles must not be related to a single token_id.

• MINTER, BURNER, RULER roles can be specific to a token_id
• PAUSER, SNAPSHOOTER, VALIDATOR roles are global (cannot not be related to a specific token_id). In other words, the fonctions (pause, scheduleSnapshot, rescheduleSnapshot, unscheduleSnapshot, SetRuleEngine) expects a global role. For example, a user granted with a SNAPSHOOTER role on token_id 1 will not be able to schedule a snapshot (even on token_id 1) !

Validation

The Validation module provides an external mecanism to authorize/unauthorize transfer of asset.

It is required to be able to prevent the execution of a transfer depending on arbitrary rules (such as specific account can be blacklisted). These rules are externalized in an other contract (called RuleEngine).

The Validation module provides a function validateTransfer that asks the RuleEngine contract if a transfer is allowed. This function is called during a Transfer (in the implementation of transfer function in the CMTAT library).

The Validation module provides a function setRuleEngine that modifies the RuleEngine contract that is used to unauthorize a transfer. This function expects the address of the new RuleEngine contract. This function is only callable by the administrator of the token.

A example of RuleEngine contract is provided in the test directory. This example contract implements a naive blacklist and verifies that a given transaction does not involve blcklisted addresses. A RuleEngine contract must have an on-chain view with the following signature:

let validateTransfer (from_, to_, _amount_ : address * address * nat) (s : storage) : bool =

In the case a RuleEngine has been defined, the validation workflow of a transfer involves a RuleEngine contract.

sequenceDiagram
    actor Alice
    Alice->>+CMTAT: transfer 10 to John
    CMTAT->>RULE_ENGINE: call view validateTransfer
    RULE_ENGINE-->>CMTAT: authorized ? unauthorized
    CMTAT->>CMTAT: update snapshots
    CMTAT->>-CMTAT: proceed transfer if authorized

Loading

Snapshots

The Snapshots module keeps track of total supply and account balance at certain point in time.

The Snapshots module provides the scheduleSnapshot function which allows to schedule snapshots (in the future).
When the Transfer entrypoint (or Mint Burn) is called it updates the total supply and account balances inside the current snapshot.

ATTENTION ! This update is done before the execution of the transfer, thus snapshots represents the balance before the transfer is done. This update is also done before mint and burn fonctions.

The Snapshots module provides the rescheduleSnapshot function to modify when a snapshot is scheduled (the scheduled snapshots cannot be re-ordered).

The Snapshots module provides the unscheduleSnapshot function to cancel the last scheduled snapshot.

The Snapshots module provides a view getNextSnapshots to retrieve the existing scheduled snapshot times (ones not yet done). So the first one is the current snapshot.

The Snapshots module also provides views (snapshotTotalsupply, snapshotBalanceOf) to query the total supply and account balances for a given snapshot time.

Library functions

Functions provided by the library for Single asset configuration.

function name	parameter	module
pause	bool	ADMINISTRATION
transfer	FA2.SingleAssetExtendable.TZIP12.transfer	FA2.SingleAssetExtendable
balance_of	FA2.SingleAssetExtendable.TZIP12.balance_of	FA2.SingleAssetExtendable
update_operators	FA2.SingleAssetExtendable.TZIP12.update_operators	FA2.SingleAssetExtendable
mint	mint_param	FA2.SingleAssetExtendable
burn	burn_param	FA2.SingleAssetExtendable
kill	unit	ADMINISTRATION
grantRole	address * AUTHORIZATIONS.role	AUTHORIZATIONS
revokeRole	address * AUTHORIZATIONS.role	AUTHORIZATIONS
scheduleSnapshot	timestamp	SNAPSHOTS
rescheduleSnapshot	timestamp * timestamp	SNAPSHOTS
unscheduleSnapshot	timestamp	SNAPSHOTS
setRuleEngine	address option	VALIDATION
validateTransfer	address * address * nat	VALIDATION
assert_validateTransfer	TZIP12.transfer	VALIDATION

Functions provided by the library for Multi asset configuration.

function name	parameter	module
pause	bool	ADMINISTRATION
transfer	TZIP12.transfer	FA2.MultiAssetExtendable
balance_of	TZIP12.balance_of	FA2.MultiAssetExtendable
update_operators	TZIP12.update_operators	FA2.MultiAssetExtendable
mint	mint_param	FA2.MultiAssetExtendable
burn	burn_param	FA2.MultiAssetExtendable
kill	unit	ADMINISTRATION
grantRole	address * nat option * AUTHORIZATIONS.role	AUTHORIZATIONS
revokeRole	address * nat option * AUTHORIZATIONS.role	AUTHORIZATIONS
scheduleSnapshot	timestamp	SNAPSHOTS
rescheduleSnapshot	timestamp * timestamp	SNAPSHOTS
unscheduleSnapshot	timestamp	SNAPSHOTS
setRuleEngine	address option	VALIDATION
validateTransfer	address * address * nat	VALIDATION
assert_validateTransfer	TZIP12.transfer	VALIDATION

Library Views

Views provided by the library for Single asset configuration.

view name	parameter	returned type	module
get_balance	address * nat	nat	FA2.SingleAssetExtendable
total_supply	nat	nat	FA2.SingleAssetExtendable
all_tokens	unit	nat set	FA2.SingleAssetExtendable
is_operator	FA2.SingleAssetExtendable.TZIP12.operator	bool	FA2.SingleAssetExtendable
token_metadata	nat	FA2.SingleAssetExtendable.TZIP12.tokenMetadataData	FA2.SingleAssetExtendable
hasRole	address * AUTHORIZATIONS.role	bool	AUTHORIZATIONS
getNextSnapshots	unit	timestamp list	SNAPSHOTS
snapshotTotalsupply	timestamp * nat	nat	SNAPSHOTS
snapshotBalanceOf	timestamp * address * nat	nat	SNAPSHOTS

Error messages

module	const	message code	Explanation	triggered by
ADMINISTRATION	not_admin	CMTAT_NOT_ADMIN	Not admin	kill
ADMINISTRATION	contract_in_pause	CMTAT_CONTRACT_PAUSED	The contract is paused	<all>
ADMINISTRATION	contract_killed	CMTAT_CONTRACT_KILLED	The contract is killed	<all>
TOTALSUPPLY	not_enough_supply	CMTAT_TOTALSUPPLY_INSUFFICIENT_BALANCE	Not enough supply	burn
SNAPSHOTS	schedule_in_past	CMTAT_SCHEDULE_IN_PAST	Cannot schedule in the past	scheduleSnapshot, rescheduleSnapshot
SNAPSHOTS	before_next_scheduled	CMTAT_SCHEDULE_BEFORE_NEXT	Proposed scheduled is before the next scheduled time	scheduleSnapshot
SNAPSHOTS	already_scheduled	CMTAT_SCHEDULE_ALREADY_SCHEDULED	This snapshot time is already scheduled	scheduleSnapshot
SNAPSHOTS	rescheduled_after_next	CMTAT_RESCHEDULE_AFTER_NEXT	New scheduled is after next scheduled	rescheduleSnapshot
SNAPSHOTS	rescheduled_before_previous	CMTAT_RESCHEDULE_BEFORE_PREVIOUS	New scheduled is before previous scheduled	rescheduleSnapshot
SNAPSHOTS	snapshot_already_done	CMTAT_SNAPSHOT_ALREADY_DONE	Snapshot already done	unscheduleSnapshot, rescheduleSnapshot
SNAPSHOTS	no_snapshot_scheduled	CMTAT_NO_SCHEDULED_SNAPSHOT	No scheduled snapshot	unscheduleSnapshot
SNAPSHOTS	snapshot_not_found	CMTAT_SNAPSHOT_UNKNOWN	Snapshot not found	unscheduleSnapshot
VALIDATION	undefined_rule_engine	CMTAT_RULE_ENGINE_UNDEFINED	Rule engine not defined	?
VALIDATION	refused_by_rule_engine	CMTAT_RULE_ENGINE_REFUSED	NOT_VALIDATED by rule engine	assert_validateTransfer
VALIDATION	invalid_rule_engine	CMTAT_RULE_ENGINE_INVALID	The pointed rule engine does not have an on-chain view validateTransfer	validateTransfer
AUTHORIZATIONS	unknown_user	CMTAT_ROLE_UNKNOWN_USER	Unknown user (no role)	revokeRole
AUTHORIZATIONS	missing_role	CMTAT_ROLE_MISSING	User do not have this role	revokeRole
AUTHORIZATIONS	not_ruler	CMTAT_ROLE_NOT_RULER	This user is not allowed to modify rules	grantRole, revokeRole
AUTHORIZATIONS	not_minter	CMTAT_ROLE_NOT_MINTER	This user is not allowed to mint assets	mint
AUTHORIZATIONS	not_burner	CMTAT_ROLE_NOT_BURNER	This user is not allowed to burn assets	burn
AUTHORIZATIONS	not_pauser	CMTAT_ROLE_NOT_PAUSER	This user is not allowed to pause the contract	pause
AUTHORIZATIONS	not_validator	CMTAT_ROLE_NOT_VALIDATOR	This user is not allowed to change rule engine contract address	setRuleEngine
AUTHORIZATIONS	not_snapshooter	CMTAT_ROLE_NOT_SNAPSHOOTER	This user is not allowed to schedule snapshots	scheduleSnapshot, rescheduleSnapshot,unscheduleSnapshot

Tests

An exemple of CMTA Token contract has been implemented for testing purposes. This extended_cmtat_single_asset illustrates

• how to implement a token contract based on cmtat library
• how to define entrypoints using the default behavior
• how to customize the storage of the token contract
• how to customize entrypoints while reusing sub-modules of the library

This token contract is used to originate a contract instance and to run test on related entrypoints. Tests of the extended_cmtat_single_asset contract illusrates how to execute entrypoints in predefined conditions and how to verify execution termination (success and failures).

These tests also ensures that the default implementation provided by the library is doing what is expected of it !

To run these tests, run the following commands

git clone https://github.com/ligolang/CMTAT-Ligo.git
cd CMTAT-Ligo
make install
make test

To run test only one file. The SUITE env var can be set to point the test file. For example, for the basic FA2 tests for a multi asset SUITE=cmtat/SUITE=cmtat/extended_cmtat_multi_asset.fa2 points to ./test/cmtat/SUITE=cmtat/extended_cmtat_multi_asset.fa2.test.mligo

make test SUITE=cmtat/extended_cmtat_multi_asset.fa2

To run tests on CMTAT features for a multi asset

make test SUITE=cmtat/extended_cmtat_multi_asset

To run tests on CMTAT features for a single asset

make test SUITE=cmtat/extended_cmtat_single_asset

To run tests on FA2 features for a single asset

make test SUITE=cmtat/extended_cmtat_single_asset.fa2

To run tests on CMTAT features for a NFT

make test SUITE=cmtat/extended_cmtat_nft_asset