Ctrlk
Nomadic LabsTezos Developer PortalTezos stack exchangeTezos Agora
For the complete documentation index, see llms.txt. This page is also available as Markdown.

โ˜‘๏ธWhitelist smart contract

๐ŸŒŠ Intro

This repository provides an implementation of Whitelist interface proposed in the TZIP-15 written in SmartPy: Python library for constructing Tezos SC and compiled to Michelson code. The contract is migrated from the Lorentz whitelisting contract.

๐Ÿ’ก Why a whitelist contract?

The purpose of the Whitelist contract is to validate transfers so the token's contract holder can control which users can perform such operations. The Whitelist contract contains a list of users and entities that have satisfied the euroTz KYC/AML compliance procedures and thus are eligible to hold euroTz Tokens.

๐Ÿ”” Specifications

UserID

As userID, we use the user's public key hash, e.g. a tz1 address.

Storage

โ€ข whitelists:

big_map (
         key = whitelistID: Nat,
         value = {
         unrestricted: Bool,
         allowedWhitelists: set(whitelistID)
        })

โ€ข users:

โ€ข admin: address

โ€ข issuer: address

๐Ÿš€ We use the interface as an on-chain wrapper:

  1. The whitelist contract is deployed separately from our euroTz contract.

  2. The assertion entrypoints are called from euroTz contract, without requiring callbacks since they call FAILWITH when they fail.

How does our wrapper whitelist SC work?

๐ŸŽฅ Main scenarios:

  1. Issuer may transfer to bob ONLY if bob's is an asserted receiver, in other words, bob must be added to the users big_map and his whitelistID must be set and unrestricted in the whitelists big_map.

  2. Alice may transfer to Bob ONLY if bob and Alice are asserted users AND Bob's whitelistID is in Alice's allowedWhitelists.

โฌ‡๏ธ Get the Project:

  1. Clone the project & cd to the directory;

  2. Install the packages with yarn install.

๐Ÿ” EntryPoints (SC methods):

EntryPoint

Params (type / desc.)

Permission

Type

addUser

address (address) / whitelistID (option(nat))

Admin

Management

setWhitelistOutbound

whitelistID (nat) / option(allowed_whitelists (set) / unrestricted (bool))

Admin

Management

setAdmin

address (address)

Admin

Management

setIssuer

address (address)

Admin

Management

getAdmin

address (address / KT1 view contractAddress)

Any

Informative

getIssuer

address (address / KT1 view contractAddress)

Any

Informative

getWhitelist

address (address / KT1 view contractAddress) / whitelistID (nat)

Any

Informative

getUser

address (address / KT1 view contractAddress) / address (address / userAddress)

Any

Informative

assertReceiver

address (address)

Any

Assertion

assertReceivers

set (set(address))

Any

Assertion

assertTransfer

from_ (address) / to_ (address)

Any

Assertion

assertTransfers

set (set({from_: address, to_: address}))

Any

Assertion

Visit TZIP-15 to get a more developed description of the whitelist contract entrypoints.

๐Ÿ‘€ Tests Cases

The smartContract tests are written in smartPy and in JS (with Taquito, Mocha and Chai)

To launch tests, you have to:

  1. Originate the whitelist contract with:

  2. Paste the address of the originated whitelist SC in the conf file under /conf as following:

  1. Originate the euroTz contract with:

  2. Paste the address of the originated euroTz SC in the same conf file as follows:

๐ŸŽ‰ You're ready to launch tests now...

The following tests use as

โ€ข whitelist contract address: KT1PFj9vshZKrHYLCswxUXKtY89SDYkXThDC

โ€ข euroTz contract address: KT1WcxYBrh9WwRo1vkbSJxAqr6ZVAUqDEiFg

Management entrypoints

Test Output:

Test Output:

Test Output:

Test Output:

Informative entrypoints

Test Output:

Assertion entrypoints

โš ๏ธ In order to mint some euroTz tokens to the Issuer, you must launch the assertReceiver test before the assertTrasnfer one.

Test Output:

Test Output:

Test Output:

Test Output:

๐Ÿ‘ฎ Roles:

  1. Admin: the contract's owner and manager, he can:

    โ€ข Set a new contract's admin;

    โ€ข Set a new contract's issuer;

    โ€ข Add / Update / Delete any user in the users big_map;

    โ€ข Add / Update / Delete any whitelist in the whitelists big_map.

  2. Issuer:

    โ€ข Can't be explicitly added to users;

    โ€ข Is always unrestricted;

    โ€ข Whose allowedWhitelists is the set of ALL whitelistId's

๐Ÿ”— Implementations

  • An implementation of wrapping and non-wrapping forms in Lorentz may be found here

  • A partial implementation of the compile-time wrapping form in LIGO may be found here

PreviousEuroTzNextRarible

Last updated

Was this helpful?