@kub-chain/contracts 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# KUB Contracts
+
+A library of Solidity smart contracts implementing the **KAP token standards** and supporting access-control, KYC, and utility primitives for the [KUB](https://kubchain.com/) ecosystem.
+
+## Overview
+
+This repository provides reusable, abstract base contracts for building KAP-compliant tokens and applications on KUB:
+
+- **KAP token standards** - fungible (KAP-20, KAP-22), non-fungible (KAP-721), and multi-token (KAP-1155) implementations.
+- **Access control** — owner, committee, and project-router-based authorization models.
+- **KYC integration** — hooks into KUB's on-chain KYC registry to enforce KYC-level requirements.
+- **Utilities & libraries** — pausing, introspection (KAP-165), and gas-efficient enumerable data structures.
+
+All contracts target Solidity `^0.8.0` and are released under the MIT license.
+
+## Repository structure
+
+```
+contracts/
+├── token/
+│   ├── KAP-20/      Fungible token standard (ERC-20-like) with KYC + admin routing
+│   ├── KAP-22/      Period/stamp-based fungible token with transfer routing & whitelist
+│   ├── KAP-721/     Non-fungible token standard (ERC-721-like), enumerable + metadata
+│   └── KAP-1155/    Multi-token standard (ERC-1155-like), enumerable + metadata
+├── access/          Ownable, Committee, Authorization(KAP), AccessController(KAP)
+├── kyc/             KYCHandler — KYC level enforcement against the KUB KYC registry
+├── utils/           Pausable, Context, KAP-165 introspection
+├── libs/            Address, String, EnumerableSet (uint/address), EnumerableMap
+└── interfaces/      IAdminProjectRouter, IKYCBitkubChain
+```
+
+### Token standards
+
+| Standard | Type | Description |
+| --- | --- | --- |
+| **KAP-20** | Fungible | ERC-20-style token integrated with KYC, the admin project router, committee control, and a transfer router. |
+| **KAP-22** | Fungible | Period-based ("stamp") token tracking balances per period, with a transfer router and address whitelist. |
+| **KAP-721** | Non-fungible | ERC-721-style NFT with enumerable and metadata extensions. |
+| **KAP-1155** | Multi-token | ERC-1155-style token with enumerable and metadata extensions. |
+
+### Access & KYC
+
+- **Ownable / Committee** — single-owner and committee-governed roles.
+- **Authorization / AuthorizationKAP** — permissioning via an `AdminProjectRouter`.
+- **AccessController / AccessControllerKAP** — compose Ownable, Committee, Authorization, and KYCHandler, adding helpers such as `onlyOwnerOrCommittee` and transfer-router management.
+- **KYCHandler** — stores the accepted KYC level and toggles whether only KYC-verified addresses may interact, validating against `IKYCBitkubChain`.
+
+## Usage
+
+These are abstract base contracts intended to be inherited and configured by your concrete token. For example, a KAP-20 token is constructed with its name, symbol, project name, decimals, and the addresses of the KYC registry, admin project router, committee, and transfer router, along with the accepted KYC level:
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {KAP20} from "./contracts/token/KAP-20/KAP20.sol";
+
+contract MyToken is KAP20 {
+    constructor(
+        address kyc,
+        address adminProjectRouter,
+        address committee,
+        address transferRouter
+    )
+        KAP20(
+            "My Token",      // name
+            "MTK",           // symbol
+            "my-project",    // project name
+            18,              // decimals
+            kyc,
+            adminProjectRouter,
+            committee,
+            transferRouter,
+            4                // accepted KYC level
+        )
+    {}
+}
+```
+
+Use the contracts as provided rather than copying and modifying them, so deployments stay consistent with the KAP standards and KUB's KYC and admin-routing requirements. For more information, visit [KUB Docs](https://docs.kubchain.com).
+
+## Security
+
+These contracts integrate with privileged roles (owner, committee, admin project router) and an external KYC registry. Configure those addresses carefully, and review the access-control wiring before deploying to mainnet. Using this code is not a substitute for an independent security audit.
+
+## License
+
+Released under the [MIT License](https://opensource.org/licenses/MIT).

package/contracts/access/AccessController.sol

@@ -0,0 +1,96 @@
+//SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import {Authorization, IAdminProjectRouter} from "./Authorization.sol";
+import {IKYCBitkubChain} from "../interfaces/IKYCBitkubChain.sol";
+import {KYCHandler} from "../kyc/KYCHandler.sol";
+import {Ownable} from "./Ownable.sol";
+import {Committee} from "./Committee.sol";
+
+abstract contract AccessController is
+    Authorization,
+    KYCHandler,
+    Ownable,
+    Committee
+{
+    event TransferRouterSet(
+        address indexed oldTransferRouter,
+        address indexed newTransferRouter,
+        address indexed caller
+    );
+
+    address public transferRouter;
+
+    modifier onlyOwnerOrCommittee() {
+        require(
+            msg.sender == owner() || msg.sender == committee,
+            "AccessController: restricted only owner or committee"
+        );
+        _;
+    }
+
+    modifier onlySuperAdminOrTransferRouter() {
+        require(
+            adminProjectRouter.isSuperAdmin(msg.sender, PROJECT) ||
+                msg.sender == transferRouter,
+            "AccessController: restricted only super admin or transfer router"
+        );
+        _;
+    }
+
+    modifier onlySuperAdminOrCommittee() {
+        require(
+            adminProjectRouter.isSuperAdmin(msg.sender, PROJECT) ||
+                msg.sender == committee,
+            "AccessController: restricted only super admin or committee"
+        );
+        _;
+    }
+
+    modifier onlySuperAdminOrOwner() {
+        require(
+            adminProjectRouter.isSuperAdmin(msg.sender, PROJECT) ||
+                msg.sender == owner(),
+            "AccessController: restricted only super admin or owner"
+        );
+        _;
+    }
+
+    function activateOnlyKYCAddress() external onlyCommittee {
+        _activateOnlyKYCAddress();
+    }
+
+    function setKYC(address _kyc) external onlyCommittee {
+        _setKYC(IKYCBitkubChain(_kyc));
+    }
+
+    function setAcceptedKYCLevel(uint256 _kycLevel) external onlyCommittee {
+        _setAcceptedKYCLevel(_kycLevel);
+    }
+
+    function setTransferRouter(address _transferRouter)
+        external
+        onlyOwnerOrCommittee
+    {
+        emit TransferRouterSet(transferRouter, _transferRouter, msg.sender);
+        transferRouter = _transferRouter;
+    }
+
+    function setAdminProjectRouter(address _adminProjectRouter)
+        public
+        override
+        onlyOwnerOrCommittee
+    {
+        require(
+            _adminProjectRouter != address(0),
+            "Authorization: new admin project router is the zero address"
+        );
+        emit AdminProjectRouterSet(
+            address(adminProjectRouter),
+            _adminProjectRouter,
+            msg.sender
+        );
+        adminProjectRouter = IAdminProjectRouter(_adminProjectRouter);
+    }
+}

package/contracts/access/AccessControllerKAP.sol

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.0;
+
+import {WhitelistAddress} from "../token/KAP-22/utils/WhitelistAddress.sol";
+import {TransferRouter} from "../token/KAP-22/utils/TransferRouter.sol";
+// import {KYCHandler} from "../kyc/KYCHandler.sol";
+// import {IKYCBitkubChain} from "../interfaces/IKYCBitkubChain.sol";
+
+interface IKYCBitkubChain {
+    function kycsLevel(address _addr) external view returns (uint256);
+}
+
+abstract contract KYCHandler {
+    event OnlyKYCAddressActivated(address indexed caller);
+    event KYCSet(
+        address indexed oldKYC,
+        address indexed newKYC,
+        address indexed caller
+    );
+    event AcceptedKYCLevelSet(
+        uint256 indexed oldAcceptedKYCLevelSet,
+        uint256 indexed newAcceptedKYCLevelSet,
+        address indexed caller
+    );
+
+    IKYCBitkubChain public kyc;
+
+    uint256 public acceptedKycLevel;
+    bool public isActivatedOnlyKycAddress;
+
+    modifier onlyBitkubNext(address bitkubNext_) {
+        _onlyBitkubNext(bitkubNext_);
+        _;
+    }
+
+    constructor(address kyc_, uint256 acceptedKycLevel_) {
+        _setKyc(IKYCBitkubChain(kyc_));
+        _setAcceptedKycLevel(acceptedKycLevel_);
+    }
+
+    function _activateOnlyKycAddress() internal virtual {
+        isActivatedOnlyKycAddress = true;
+        emit OnlyKYCAddressActivated(msg.sender);
+    }
+
+    function _setKyc(IKYCBitkubChain _kyc) internal virtual {
+        emit KYCSet(address(kyc), address(_kyc), msg.sender);
+        kyc = _kyc;
+    }
+
+    function _setAcceptedKycLevel(uint256 _kycLevel) internal virtual {
+        emit AcceptedKYCLevelSet(acceptedKycLevel, _kycLevel, msg.sender);
+        acceptedKycLevel = _kycLevel;
+    }
+
+    function _onlyBitkubNext(address bitkubNext_) internal view {
+        require(
+            _isBitkubNext(bitkubNext_),
+            "KYCHandler: only Bitkub NEXT user"
+        );
+    }
+
+    function _isBitkubNext(address bitkubNext_) internal view returns (bool) {
+        return kyc.kycsLevel(bitkubNext_) >= acceptedKycLevel;
+    }
+}
+
+
+abstract contract AccessControllerKAP is WhitelistAddress, TransferRouter, KYCHandler {
+    address public owner;
+
+    event OwnerSet(address indexed oldOwner, address indexed newOwner, address indexed caller);
+
+    modifier onlyOwner() {
+        require(msg.sender == owner, "AccessControllerKAP: restricted only owner");
+        _;
+    }
+
+    constructor(
+        address owner_,
+        address transferRouter_,
+        address kyc_,
+        uint256 acceptedKycLevel_
+    ) TransferRouter(transferRouter_) KYCHandler(kyc_, acceptedKycLevel_) {
+        owner = owner_;
+    }
+
+    function setTransferRouter(address _transferRouter) public virtual {
+        _setTransferRouter(_transferRouter);
+    }
+
+    function setKyc(IKYCBitkubChain _kyc) public virtual {
+        _setKyc(_kyc);
+    }
+
+    function setAcceptedKycLevel(uint256 _kycLevel) public virtual {
+        _setAcceptedKycLevel(_kycLevel);
+    }
+
+    function activateOnlyKycAddress() public virtual {
+        _activateOnlyKycAddress();
+    }
+
+    function setOwner(address _owner) public virtual onlyOwner {
+        emit OwnerSet(owner, _owner, msg.sender);
+        owner = _owner;
+    }
+
+    function addWhitelistAddress(address _addr) public virtual override onlyOwner {
+        WhitelistAddress.addWhitelistAddress(_addr);
+    }
+
+    function revokeWhitelistAddress(address _addr) public virtual override onlyOwner {
+        WhitelistAddress.revokeWhitelistAddress(_addr);
+    }
+}

package/contracts/access/Authorization.sol

@@ -0,0 +1,36 @@
+//SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import "../interfaces/IAdminProjectRouter.sol";
+
+abstract contract Authorization {
+    IAdminProjectRouter public adminProjectRouter;
+    string public PROJECT;
+
+    event AdminProjectRouterSet(address indexed oldAdmin, address indexed newAdmin, address indexed caller);
+
+    modifier onlySuperAdmin() {
+        require(adminProjectRouter.isSuperAdmin(msg.sender, PROJECT), "Authorization: restricted only super admin");
+        _;
+    }
+
+    modifier onlyAdmin() {
+        require(adminProjectRouter.isAdmin(msg.sender, PROJECT), "Authorization: restricted only admin");
+        _;
+    }
+
+    modifier onlySuperAdminOrAdmin() {
+        require(
+            adminProjectRouter.isSuperAdmin(msg.sender, PROJECT) || adminProjectRouter.isAdmin(msg.sender, PROJECT),
+            "Authorization: restricted only super admin or admin"
+        );
+        _;
+    }
+
+    function setAdminProjectRouter(address _adminProjectRouter) public virtual onlySuperAdmin {
+        require(_adminProjectRouter != address(0), "Authorization: new admin project router is the zero address");
+        emit AdminProjectRouterSet(address(adminProjectRouter), _adminProjectRouter, msg.sender);
+        adminProjectRouter = IAdminProjectRouter(_adminProjectRouter);
+    }
+}

package/contracts/access/AuthorizationKAP.sol

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IAdminProjectRouter} from "../interfaces/IAdminProjectRouter.sol";
+
+abstract contract AuthorizationKAP {
+    IAdminProjectRouter public adminRouter;
+    string public constant PROJECT = "kap-token";
+    address public transferRouter;
+
+    address public committee;
+
+    event SetAdmin(address indexed oldAdmin, address indexed newAdmin, address indexed caller);
+    event SetCommittee(address indexed oldCommittee, address indexed newCommittee, address indexed caller);
+
+    modifier onlySuperAdmin() {
+        require(adminRouter.isSuperAdmin(msg.sender, PROJECT), "Restricted only super admin");
+        _;
+    }
+
+    modifier onlyAdmin() {
+        require(adminRouter.isAdmin(msg.sender, PROJECT), "Restricted only admin");
+        _;
+    }
+
+    modifier onlySuperAdminOrAdmin() {
+        require(
+            adminRouter.isSuperAdmin(msg.sender, PROJECT) || adminRouter.isAdmin(msg.sender, PROJECT),
+            "Restricted only super admin or admin"
+        );
+        _;
+    }
+
+    modifier onlySuperAdminOrTransferRouter() {
+        require(
+            adminRouter.isSuperAdmin(msg.sender, PROJECT) || msg.sender == transferRouter,
+            "Restricted only super admin ot transfer router"
+        );
+        _;
+    }
+
+    modifier onlyCommittee() {
+        require(msg.sender == committee, "Restricted only committee");
+        _;
+    }
+
+    function setAdmin(address _adminRouter) external onlySuperAdmin {
+        emit SetAdmin(address(adminRouter), _adminRouter, msg.sender);
+        adminRouter = IAdminProjectRouter(_adminRouter);
+    }
+
+    function setCommittee(address _committee) external onlyCommittee {
+        emit SetCommittee(committee, _committee, msg.sender);
+        committee = _committee;
+    }
+
+    function setTransferRouter(address _transferRouter) external onlySuperAdmin {
+        transferRouter = _transferRouter;
+    }
+}

package/contracts/access/Committee.sol

@@ -0,0 +1,26 @@
+//SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+abstract contract Committee {
+    address public committee;
+
+    event CommitteeSet(
+        address indexed oldCommittee,
+        address indexed newCommittee,
+        address indexed caller
+    );
+
+    modifier onlyCommittee() {
+        require(
+            msg.sender == committee,
+            "Committee: restricted only committee"
+        );
+        _;
+    }
+
+    function setCommittee(address _committee) public virtual onlyCommittee {
+        emit CommitteeSet(committee, _committee, msg.sender);
+        committee = _committee;
+    }
+}

package/contracts/access/Ownable.sol

@@ -0,0 +1,39 @@
+//SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import "../utils/Context.sol";
+
+abstract contract Ownable is Context {
+    address private _owner;
+
+    event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
+
+    constructor() {
+        _transferOwnership(_msgSender());
+    }
+
+    function owner() public view virtual returns (address) {
+        return _owner;
+    }
+
+    modifier onlyOwner() {
+        require(owner() == _msgSender(), "Ownable: caller is not the owner");
+        _;
+    }
+
+    function renounceOwnership() public virtual onlyOwner {
+        _transferOwnership(address(0));
+    }
+
+    function transferOwnership(address newOwner) public virtual onlyOwner {
+        require(newOwner != address(0), "Ownable: new owner is the zero address");
+        _transferOwnership(newOwner);
+    }
+
+    function _transferOwnership(address newOwner) internal virtual {
+        address oldOwner = _owner;
+        _owner = newOwner;
+        emit OwnershipTransferred(oldOwner, newOwner);
+    }
+}

package/contracts/interfaces/IAdminProjectRouter.sol

@@ -0,0 +1,9 @@
+//SPDX-License-Identifier: MIT
+
+pragma solidity >=0.6.0 <0.9.0;
+
+interface IAdminProjectRouter {
+    function isSuperAdmin(address _addr, string calldata _project) external view returns (bool);
+
+    function isAdmin(address _addr, string calldata _project) external view returns (bool);
+}

package/contracts/interfaces/IKYCBitkubChain.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+interface IKYCBitkubChain {
+    function kycsLevel(address _addr) external view returns (uint256);
+
+    function setKycCompleted(address _addr, uint256 _level) external;
+}

package/contracts/kyc/KYCHandler.sol

@@ -0,0 +1,24 @@
+//SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import {IKYCBitkubChain} from "../interfaces/IKYCBitkubChain.sol";
+
+abstract contract KYCHandler {
+    IKYCBitkubChain public kyc;
+
+    uint256 public acceptedKYCLevel;
+    bool public isActivatedOnlyKYCAddress;
+
+    function _activateOnlyKYCAddress() internal virtual {
+        isActivatedOnlyKYCAddress = true;
+    }
+
+    function _setKYC(IKYCBitkubChain _kyc) internal virtual {
+        kyc = _kyc;
+    }
+
+    function _setAcceptedKYCLevel(uint256 _kycLevel) internal virtual {
+        acceptedKYCLevel = _kycLevel;
+    }
+}

package/contracts/libs/Address.sol

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+library Address {
+    function isContract(address account) internal view returns (bool) {
+        // This method relies on extcodesize, which returns 0 for contracts in
+        // construction, since the code is only stored at the end of the
+        // constructor execution.
+
+        uint256 size;
+        assembly {
+            size := extcodesize(account)
+        }
+        return size > 0;
+    }
+}

package/contracts/libs/EnumerableSetAddress.sol

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+library EnumerableSetAddress {
+    struct AddressSet {
+        address[] _values;
+        mapping(address => uint256) _indexes;
+    }
+
+    function add(AddressSet storage set, address value) internal returns (bool) {
+        if (!contains(set, value)) {
+            set._values.push(value);
+            set._indexes[value] = set._values.length;
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    function remove(AddressSet storage set, address value) internal returns (bool) {
+        uint256 valueIndex = set._indexes[value];
+        if (valueIndex != 0) {
+            uint256 toDeleteIndex = valueIndex - 1;
+            uint256 lastIndex = set._values.length - 1;
+            address lastvalue = set._values[lastIndex];
+            set._values[toDeleteIndex] = lastvalue;
+            set._indexes[lastvalue] = toDeleteIndex + 1;
+            set._values.pop();
+            delete set._indexes[value];
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    function contains(AddressSet storage set, address value) internal view returns (bool) {
+        return set._indexes[value] != 0;
+    }
+
+    function length(AddressSet storage set) internal view returns (uint256) {
+        return set._values.length;
+    }
+
+    function at(AddressSet storage set, uint256 index) internal view returns (address) {
+        require(set._values.length > index, "EnumerableSet: index out of bounds");
+        return set._values[index];
+    }
+
+    function getAll(AddressSet storage set) internal view returns (address[] memory) {
+        return set._values;
+    }
+
+    function get(AddressSet storage set, uint256 _page, uint256 _limit) internal view returns (address[] memory) {
+        require(_page > 0 && _limit > 0);
+        uint256 tempLength = _limit;
+        uint256 cursor = (_page - 1) * _limit;
+        uint256 _addressLength = length(set);
+        if (cursor >= _addressLength) {
+            return new address[](0);
+        }
+        if (tempLength > _addressLength - cursor) {
+            tempLength = _addressLength - cursor;
+        }
+        address[] memory addresses = new address[](tempLength);
+        for (uint256 i = 0; i < tempLength; i++) {
+            addresses[i] = at(set, cursor + i);
+        }
+        return addresses;
+    }
+}

package/contracts/libs/EnumerableSetUint.sol

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.0;
+
+library EnumerableSetUint {
+    struct UintSet {
+        uint256[] _values;
+        mapping(uint256 => uint256) _indexes;
+    }
+
+    function add(UintSet storage set, uint256 value) internal returns (bool) {
+        if (!contains(set, value)) {
+            set._values.push(value);
+            set._indexes[value] = set._values.length;
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    function remove(UintSet storage set, uint256 value) internal returns (bool) {
+        uint256 valueIndex = set._indexes[value];
+        if (valueIndex != 0) {
+            uint256 toDeleteIndex = valueIndex - 1;
+            uint256 lastIndex = set._values.length - 1;
+            uint256 lastvalue = set._values[lastIndex];
+            set._values[toDeleteIndex] = lastvalue;
+            set._indexes[lastvalue] = toDeleteIndex + 1;
+            set._values.pop();
+            delete set._indexes[value];
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    function contains(UintSet storage set, uint256 value) internal view returns (bool) {
+        return set._indexes[value] != 0;
+    }
+
+    function length(UintSet storage set) internal view returns (uint256) {
+        return set._values.length;
+    }
+
+    function at(UintSet storage set, uint256 index) internal view returns (uint256) {
+        require(set._values.length > index, "EnumerableSet: index out of bounds");
+        return set._values[index];
+    }
+
+    function getAll(UintSet storage set) internal view returns (uint256[] memory) {
+        return set._values;
+    }
+
+    function get(
+        UintSet storage set,
+        uint256 _page,
+        uint256 _limit
+    ) internal view returns (uint256[] memory) {
+        require(_page > 0 && _limit > 0);
+        uint256 tempLength = _limit;
+        uint256 cursor = (_page - 1) * _limit;
+        uint256 _uintLength = length(set);
+        if (cursor >= _uintLength) {
+            return new uint256[](0);
+        }
+        if (tempLength > _uintLength - cursor) {
+            tempLength = _uintLength - cursor;
+        }
+        uint256[] memory uintList = new uint256[](tempLength);
+        for (uint256 i = 0; i < tempLength; i++) {
+            uintList[i] = at(set, cursor + i);
+        }
+        return uintList;
+    }
+}