Merge pull request #958 from EYBlockchain/westlad/kyc

KYC backend functionality

.eslintignore

@@ -4,7 +4,9 @@ node_modules/*
 **/doc/*
 cli/build/*
 wallet/cli/*
+wallet/src/components/Assets/
 test/adversary/nightfall-adversary/*
 /**/*.d.ts
 **/build/*
 hardhat.*
+typechain-types/

.github/workflows/check-PRs.yml

@@ -43,6 +43,21 @@ jobs:
           npm ci
           npm run test
 
+  unit-tests:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v1
+        with:
+          node-version: '16.17.0'
+      - name: Unit Tests
+        run: |
+          npm ci
+          cd common-files
+          npm ci
+          cd ../
+          npm run unit-test
+
   circuits-test:
     runs-on: ubuntu-20.04
     env:
@@ -136,6 +151,52 @@ jobs:
           name: ganache-test-logs
           path: ./ganache-test.log
 
+  kyc-test:
+    env:
+      WHITELISTING: enable
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v1
+        with:
+          node-version: '16.17.0'
+
+      - name: Start Containers
+        run: |
+          ./setup-nightfall
+          ./start-nightfall -g -d &> kyc-test.log &disown
+
+      - name: Wait for images to be ready
+        uses: Wandalen/[email protected]
+        with:
+          command: |
+            docker wait nightfall_3_deployer_1
+          attempt_limit: 100
+          attempt_delay: 20000
+
+      - name: Debug logs - after image builds
+        if: always()
+        run: cat kyc-test.log
+
+      - name: Run integration test
+        run: npm run test-kyc
+
+      - name: Debug logs - after integration test run
+        if: always()
+        run: cat kyc-test.log
+
+      - name: If integration test failed, shutdown the Containers
+        if: failure()
+        run: docker-compose -f docker-compose.yml -f docker-compose.ganache.yml down -v
+
+      - name: If integration test failed, upload logs files as artifacts
+        if: failure()
+        uses: actions/upload-artifact@master
+        with:
+          name: kyc-test-logs
+          path: ./ganackyche-test.log
+
+
   optimist-sync-test:
     runs-on: ubuntu-18.04
     steps:

.gitignore

@@ -11,3 +11,7 @@ __pycache__
 test/adversary/nightfall-adversary
 wallet/tests/e2e/videos
 wallet/tests/e2e/screenshots
+typechain-types/
+artifacts/
+cache/
+

cli/lib/nf3.mjs

@@ -278,7 +278,7 @@ class Nf3 {
       gas,
       gasPrice,
     };
-
+    // logger.debug(`submitting tx, ${JSON.stringify(tx, null, 2)}`);
     if (this.ethereumSigningKey) {
       const signed = await this.web3.eth.accounts.signTransaction(tx, this.ethereumSigningKey);
       const promiseTest = new Promise((resolve, reject) => {
@@ -1247,6 +1247,40 @@ class Nf3 {
   getNetworkId() {
     return this.web3.eth.net.getId();
   }
+
+  /**
+   Adds a user to a whitelist (only works of the calling address is that of a Whitelist Manager)
+  */
+  async addUserToWhitelist(groupId, address) {
+    const res = await axios.post(`${this.clientBaseUrl}/whitelist/add`, {
+      address,
+    });
+    const txDataToSign = res.data;
+    return this.submitTransaction(txDataToSign);
+  }
+
+  /**
+   Removes a user from a whitelist (only works of the calling address is that of a Whitelist Manager)
+  */
+  async removeUserFromWhitelist(address) {
+    const res = await axios.post(`${this.clientBaseUrl}/whitelist/remove`, {
+      address,
+    });
+    const txDataToSign = res.data;
+    return this.submitTransaction(txDataToSign);
+  }
+
+  /**
+   checks if a user is whitelisted
+  */
+  async isWhitelisted(address) {
+    const res = await axios.get(`${this.clientBaseUrl}/whitelist/check`, {
+      params: {
+        address,
+      },
+    });
+    return res.data.isWhitelisted;
+  }
 }
 
 export default Nf3;

config/default.js

@@ -49,6 +49,12 @@ module.exports = {
           '0x4789FD18D5d71982045d85d5218493fD69F55AC4',
         ],
   },
+  WHITELIST_MANAGERS: [
+    { address: '0x9C8B2276D490141Ae1440Da660E470E7C0349C63', groupId: 1 },
+    { address: '0xfeEDA3882Dd44aeb394caEEf941386E7ed88e0E0', groupId: 1 },
+    { address: '0xfCb059A4dB5B961d3e48706fAC91a55Bad0035C9', groupId: 2 },
+    { address: '0x4789FD18D5d71982045d85d5218493fD69F55AC4', groupId: 2 },
+  ],
   BLOCKCHAIN_URL:
     process.env.BLOCKCHAIN_URL ||
     `ws://${process.env.BLOCKCHAIN_WS_HOST}:${process.env.BLOCKCHAIN_PORT}${

doc/kyc.md

@@ -0,0 +1,19 @@
+# Nightfall KYC adaptions
+
+Nightfall now incorporates the ability to manage a whitelist of accounts in support of KYC (Know Your Customer). When whitelisting is enabled, only accounts that are added to the whitelist are able to move funds from Layer 1 to Layer 2 and to withdraw Layer 1 funds from the Shield contract.
+
+Whitelisting can be controlled either externally to the blockchain or via a smart contract.  Nightfall is agnostic about how KYC is applied.
+
+## Enabling Whitelisting
+
+To enable whitelisting, the deployer container should have its `WHITELISTING` environment variable set to `enable`. Setting the `WHITELISTING` variable to anything else will desable whitlisting.
+
+## Operating Whitelisting
+
+The KYC adaptions have recognise a new actor, the whitelist manager. A whitelist manager is able to whitelist users and to remove them from the whitelist. Each whitelist manager manager has a group ID associated with them, and users are added to the whitelist managers group ID when they are whitelisted. In practice, the group ID currently has little effect, other than acting as a grouping variable; all whitelisted users can interact, regardless of their group ID.
+
+Whitelist managers are created/removed by the contract owner (multisig). They can also operate as normal Nightfall users, thus they are able to whitelist themselves.
+
+All whitelisting functionality is managed by the contract `KYC.sol`, the functions therein are self-explanatory.
+
+Note that all users are, by default members of the null group (group ID = 0). Members of this group are NOT whitelisted when whitelisting is enabled. Memebership of any other group confirs whitlisted status.

docker/docker-compose.yml

@@ -68,6 +68,7 @@ services:
       BLOCKCHAIN_PORT: 8546
       ZOKRATES_WORKER_HOST: worker
       USE_STUBS: 'false'
+      WHITELISTING: ${WHITELISTING}
 
   hosted-utils-api-server:
     build:

hardhat.config.ts

@@ -1,9 +1,18 @@
 import { HardhatUserConfig } from 'hardhat/config';
 import '@nomiclabs/hardhat-truffle5';
 import '@nomicfoundation/hardhat-toolbox';
+import 'hardhat-contract-sizer';
 
 const config: HardhatUserConfig = {
-  solidity: '0.8.9',
+  solidity: {
+    version: '0.8.3',
+    settings: {
+      optimizer: {
+        enabled: true,
+        runs: 200
+      }
+    }
+  },
   paths: {
     sources: './nightfall-deployer/contracts',
     tests: './test/e2e',

nightfall-client/src/app.mjs

@@ -14,6 +14,7 @@ import {
   incomingViewingKey,
   setInstantWithdrawl,
   generateZkpKeys,
+  kyc,
 } from './routes/index.mjs';
 
 const app = express();
@@ -32,6 +33,7 @@ setupHttpDefaults(
     app.use('/incoming-viewing-key', incomingViewingKey);
     app.use('/set-instant-withdrawal', setInstantWithdrawl);
     app.use('/generate-zkp-keys', generateZkpKeys);
+    app.use('/whitelist', kyc);
   },
   true,
   false,

nightfall-client/src/routes/index.mjs

@@ -9,6 +9,7 @@ import commitment from './commitment.mjs';
 import incomingViewingKey from './incoming-viewing-key.mjs';
 import setInstantWithdrawl from './instant-withdrawal.mjs';
 import generateZkpKeys from './generate-zkp-keys.mjs';
+import kyc from './kyc.mjs';
 
 export {
   transfer,
@@ -22,4 +23,5 @@ export {
   incomingViewingKey,
   setInstantWithdrawl,
   generateZkpKeys,
+  kyc,
 };

nightfall-client/src/routes/kyc.mjs

@@ -0,0 +1,48 @@
+/**
+ Routes to perform whitelist manager KYC work
+ */
+
+import express from 'express';
+import logger from 'common-files/utils/logger.mjs';
+import { addUserToWhitelist, removeUserFromWhitelist, isWhitelisted } from '../services/kyc.mjs';
+
+const router = express.Router();
+
+router.get('/check', async (req, res, next) => {
+  try {
+    const { address } = req.query;
+    logger.debug(`Details requested with address ${address}`);
+    const whitelisted = await isWhitelisted(address);
+    res.json({ isWhitelisted: whitelisted });
+  } catch (err) {
+    next(err);
+  }
+});
+
+/**
+ Add a use to a KYC whitelist (only works if user is a whitelist manager, otherwise just wastes gas)
+ */
+router.post('/add', async (req, res, next) => {
+  const { address } = req.body;
+  try {
+    const response = await addUserToWhitelist(address);
+    res.json(response);
+  } catch (err) {
+    next(err);
+  }
+});
+
+/**
+ Add a use to a KYC whitelist (only works if user is a relevant (to the group) whitelist manager, otherwise just wastes gas)
+ */
+router.post('/remove', async (req, res, next) => {
+  const { address } = req.body;
+  try {
+    const response = await removeUserFromWhitelist(address);
+    res.json(response);
+  } catch (err) {
+    next(err);
+  }
+});
+
+export default router;

nightfall-client/src/services/kyc.mjs

@@ -0,0 +1,23 @@
+/**
+ This module creates blockchain transactions to interact with the KYC smart contract
+*/
+
+import constants from 'common-files/constants/index.mjs';
+import { waitForContract } from 'common-files/utils/contract.mjs';
+
+const { SHIELD_CONTRACT_NAME } = constants;
+
+export async function isWhitelisted(address) {
+  const shieldContractInstance = await waitForContract(SHIELD_CONTRACT_NAME);
+  return shieldContractInstance.methods.isWhitelisted(address).call();
+}
+
+export async function addUserToWhitelist(address) {
+  const shieldContractInstance = await waitForContract(SHIELD_CONTRACT_NAME);
+  return shieldContractInstance.methods.addUserToWhitelist(address).encodeABI();
+}
+
+export async function removeUserFromWhitelist(address) {
+  const shieldContractInstance = await waitForContract(SHIELD_CONTRACT_NAME);
+  return shieldContractInstance.methods.removeUserFromWhitelist(address).encodeABI();
+}

nightfall-deployer/contracts/Config.sol

@@ -23,7 +23,7 @@ contract Config is Ownable, Structures {
     address maticAddress;
     mapping(address => uint256[2]) erc20limit;
 
-    function initialize() public virtual override initializer {
+    function initialize() public virtual override onlyInitializing {
         Ownable.initialize();
     }
 

nightfall-deployer/contracts/KYC.sol

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: CC0-1.0
+import './Ownable.sol';
+
+pragma solidity ^0.8.0;
+
+contract KYC is Ownable {
+
+    bool public whitelisting;
+    mapping(address => uint256) public users;
+    mapping(address => uint256) public managers;
+
+    // groupIds cannot be zero, although we don't specifcally chack for this because assigning a groupId of zero has
+    // no effect other than wasting gas.
+
+    function initialize() override virtual public onlyInitializing {
+        whitelisting = false;
+        Ownable.initialize();
+    }
+
+    function addUserToWhitelist(address _user) external {
+        // if a non-manager calls this, they will just assign someone to the zero group, which is the null value and has no effect
+        users[_user] = managers[msg.sender];
+    }
+
+    function removeUserFromWhitelist(address _user) external {
+        require(users[_user] != 0, 'This user is not whitelisted, so cannot be delisted');
+        require (managers[msg.sender] == users[_user], 'You are not the manager of this group' );
+        delete users[_user];
+    }
+
+    function createWhitelistManager(uint256 _groupId, address _manager) external onlyOwner {
+        managers[_manager] = _groupId;
+    }
+
+    function removeWhitelistManager(address _manager) external onlyOwner {
+        delete managers[_manager];
+    }
+
+    function enableWhitelisting(bool _whitelisting) external onlyOwner {
+        whitelisting = _whitelisting;
+    }
+
+    function isWhitelisted(address _user) public view returns (bool) {
+        if (whitelisting == false ) return true; // whitelisting is turned off
+        if (users[_user] != 0) return true;
+        return false;
+    }
+
+    function isWhitelistManager(address _manager) public view returns (uint) {
+        return managers[_manager];
+    }
+}

nightfall-deployer/contracts/Key_Registry.sol

@@ -11,7 +11,7 @@ contract Key_Registry is Ownable, Structures {
 
   mapping(TransactionTypes => uint256[]) public vks;
 
-  function initialize() override virtual public initializer {
+  function initialize() override virtual public onlyInitializing {
     Ownable.initialize();
   }
   /**

nightfall-deployer/contracts/Ownable.sol

@@ -30,7 +30,7 @@ contract Ownable is Initializable {
   /**
    * @dev The constructor sets the original owner of the contract to the sender account.
    */
-  function initialize() virtual public initializer {
+  function initialize() virtual public onlyInitializing {
     setOwner(msg.sender);
   }
 

nightfall-deployer/contracts/Pausable.sol

@@ -7,7 +7,7 @@ pragma solidity ^0.8.0;
 
 abstract contract Pausable is PausableUpgradeable, Ownable {
 
-  function initialize() public override(Ownable) virtual initializer {
+  function initialize() public override(Ownable) virtual onlyInitializing {
     Ownable.initialize();
     PausableUpgradeable.__Pausable_init();
   }