---
tags: Blockchain
---

# 白名單 (Whitelist) 介紹與探討
contributed by < [steven1lung](https://github.com/steven1lung) >

## 什麼是白名單
白名單，顧名思義就是一份寫滿被准許的使用者的名單。使用者可以是公司、企業、電腦程式、一個人、或是一個錢包位址。通常來說，我們會把白名單使用在一些特定的場合或是我們想提供的服務裡。

舉例來說，我們訂閱一個經濟平台的日報時，都會被提醒要將此平台的信箱位址加到白名單裡，不然我們的信箱很可能就將我們想收到的信直接丟到垃圾桶裡。或者是有些企業會付錢給一些的網際網路提供者，讓他們企業寄出去的信件不會被標示成垃圾郵件。

所以說在電子信箱使用白名單可以讓我們順利地收到我們需要的資訊，也可以過濾掉我們不想要的資料。

## 白名單在區塊鏈裡的使用
在區塊鏈跟加密貨幣的領域裡，白名單最常被使用在 ICO (首次發售) 場合或是提領時。

舉例來說，A 公司想要發行一個新幣，所以開放用戶去到他們的 telegram 群組填白名單的表單。接下來在開賣時，只有位址有在白名單裡面的錢包才可以進行購買。通常都會搭配 KYC (know your customer) 來認證同一個使用者有沒有註冊超過兩個位址，如果有的話，那兩個位址都會被移除。
> KYC 就是我們常說的實名認證

## 為什麼會需要白名單
你可能會想說，如果都是以募資的前提下去發幣或是發 NFT，那為什麼要設立白名單過濾購買的人？
在沒有白名單這個機制前，NFT 的購買會有兩種問題：
#### 1. NFT 常常會在你有機會買之前就賣完
NFT 的世界正在急速發展，好的專案通常都會吸引許多人在發行的當下去購買。這樣你要在這麼多人前面買到你想要的 NFT 機會就很小。
#### 2. 有機會出現 gas fee 戰爭
因為 gas fee 的機制，所以你願意付出的 gas fee 越多，你的交易速度就會越快被確認。所以為了要在如此多的 mint 中脫穎而出，很多人都增加他們願意付的 gas fee，導致每一筆交易紀錄的 gas fee 都超級貴。

#### 有了白名單之後
有了白名單的機制，很明顯可以解決問題一，因為要跟你搶的人數會被白名單限制，所以不用擔心會有太多人一起搶。

有些企劃也會設定白名單的購買者有早鳥優惠，可以用較低的價格鑄造一顆 NFT，甚至可以免費領。

當你被加入白名單，你就可以找一個交易數量比較少的時候去鑄造 NFT，達到省 gas fee 的效果。

## 白名單的實作
要學習如何寫一個好的白名單，我們可以參考一些有名的 NFT 專案，這裡我們參考 [Doodles](https://doodles.app/) 如何實作出他們的白名單。

### 前提
要看懂白名單的實作，要先了解 NFT 的機制、加密貨幣、Solidity 這些東西，如果還不知道可以點下方連結先學習一下。
1. [NFT、智能合約介紹](https://hackmd.io/6qX8nZXcSKCrOx2IXKkpow)
2. [NFT 合約 ERC721A](https://hackmd.io/bd_KYpB4QvOf8YXR6Gvc8Q)
3. [同質化代幣介紹](https://hackmd.io/X7iSrbQ9TZihmyx-oYitTg)

### 概念
白名單的概念很簡單，只要把我們想要白名單的錢包位址儲存起來就好了。那如何實作出一個好的（省 gas fee）白名單機制就是每個專案孰優孰劣的地方了。

在 Doodles 裡面，使用到資料結構裡的 mapping，可以想成我們一般所說的 hashing。

我們在 [etherscan](https://etherscan.io/address/0x8a90CAb2b38dba80c64b7734e58Ee1dB38B8992e#code) 裡面可以看到一個 `mapping` 的函式，這邊的 `_allowList` 就是他們的白名單。

mapping(address => uint8) private _allowList;

上述的函式就是建立一個 mapping 的資料結構。

#### 將用戶加入白名單

function setAllowList(address[] calldata addresses, uint8 numAllowedToMint) external onlyOwner {
    for (uint256 i = 0; i < addresses.length; i++) {
        _allowList[addresses[i]] = numAllowedToMint;
    }
}

我們將一組位址錢包傳進去函式，並附帶上每個位址可以鑄造的數量。然後就透過 `for` 迴圈，將每個錢包位址加入白名單中。

這邊我們可能會好奇的點是一些關鍵字，像是 `calldata`、`external`、`onlyOwner`。

##### `onlyOwner`
這個關鍵字是從 OZ library 匯入的，他們提供這個關鍵字的用意在智能合約上建立出擁有者的身份。如果在你的函式前加入這個關鍵字，那這個憾函式就只能被一個特定的位址呼叫，而這個特定的位置預設就是合約的位址。

import "@openzeppelin/contracts/access/Ownable.sol";


function setAllowList() external {
    // 大家都可以呼叫這個 function
}

function setAllowList() external onlyOwner {
    // 只有擁有者可以呼叫這個 function
}

##### 函式的四種形態
Solidity 裡提供的函式型態總共有四種：`external`、`internal`、`public`、`private`。

* private 函式只能在合約裡被呼叫。
* internal 函式可以在合約裡被呼叫，也可以在被繼承的合約中被呼叫。
* external 函式只能被從外部呼叫。
* public 函式可以在任何地方被呼叫。

那在上面的加入白名單中，為何我們使用的是 `external`，而不是 `public`。

因為 `external` 在處理大量的陣列資料時會比 `public` 更有效率。
>The difference is because in public functions, Solidity immediately copies array arguments to memory, while external functions can read directly from calldata. Memory allocation is expensive, whereas reading from calldata is cheap.

##### 資料位置

變數在 Solidity 可以被處存在不同位置：`storage`、`memory`、`calldata`。
* storage 變數會被直接存在區塊鏈上。
* memory 變數會被存在記憶體而且只會在 function 被呼叫時存在。
* calldata 變數是比較特別（也較有效率），他們會被存在一個只存函式參數的地方，並且只能被 `external` 函式存取。

因為一個白名單的位址陣列可能會很大，所以使用 `calldata` 來存位址陣列會比較有效率。

### 用戶如何鑄造

function mintAllowList(uint8 numberOfTokens) external payable {
    uint256 ts = totalSupply();
    require(isAllowListActive, "Allow list is not active");
    require(numberOfTokens <= _allowList[msg.sender], "Exceeded max available to purchase");
    require(ts + numberOfTokens <= MAX_SUPPLY, "Purchase would exceed max tokens");
    require(PRICE_PER_TOKEN * numberOfTokens <= msg.value, "Ether value sent is not correct");

    _allowList[msg.sender] -= numberOfTokens;
    for (uint256 i = 0; i < numberOfTokens; i++) {
        _safeMint(msg.sender, ts + i);
    }
}

這個函式就是鑄造一顆 NFT 所呼叫的，第四行就是白名單的確認。如果在 `_allowList[address]` 裡所可以鑄造數量小於現在要鑄造的數量，就會丟出一個例外，並且終止操作。

###### 參考資料
[Create a whitelist for your NFT project](https://dev.to/lilcoderman/create-a-whitelist-for-your-nft-project-1g55)