KAP-22

The following standard outlines a smart contract interface and logic for loyalty points tokens on KUB that behaves similarly to traditional loyalty points, enabling interoperability and composability within the decentralized ecosystem. By adhering to this standard, loyalty programs can leverage the benefits of blockchain technology, such as transparency, immutability, and programmability, while maintaining the familiar functionality of traditional loyalty points. It is proposed to derive the KAP-20 standard for KUB, with additional functions for periods and token expiration.

Token Interface

IAdminProjectRouter

isSuperAdmin

Check whether _addr is the Super Admin role in _project.

function isSuperAdmin(address _addr, string calldata _project) external view returns (bool)

isAdmin

Check whether _addr is the Admin role in _project.

function isAdmin(address _addr, string calldata _project) external view returns (bool)

IKYCBitkubChain

kycsLevel

Returns the KYC Level of _addr

function kycsLevel(address _addr) external view returns (uint256)

IKAP20

totalSupply

Returns the total token supply.

function totalSupply() external view returns (uint256)

decimals

Returns the number of decimals the token uses - e.g. 8, means to divide the token amount by 100000000 to get its user representation.

function decimals() external view returns (uint8)

NOTE: This method is optional in ERC-20. In KAP-20, this is a required method.

symbol

Returns the symbol of the token. E.g. "HIX".

function symbol() external view returns (string memory)

NOTE: This method is optional in ERC-20. In KAP-20, this is a required method.

name

Returns the name of the token - e.g."MyToken".

function name() external view returns (string memory)

NOTE: This method is optional in ERC-20. In KAP-20, this is a required method.

allowance

Returns the amount which spender is still allowed to withdraw from owner.

function allowance(address owner, address spender) external view returns (uint256)

approve

Allows spender to withdraw from your account multiple times, up to the amount amount. If this function is called again it overwrites the current allowance with amount.

function approve(address spender, uint256 amount) external returns (bool)

NOTE: To prevent attack vectors, clients SHOULD make sure to create user interfaces in such a way that they set the allowance first to 0 before setting it to another value for the same spender. THOUGH The contract itself shouldn't enforce it, to allow backwards compatibility with contracts deployed before

adminApprove

Allows spender to withdraw from owner account multiple times, up to the amount amount. If this function is called again it overwrites the current allowance with amount. This method works similar to the approve method.

function adminApprove(address owner, address spender, uint256 amount) external returns (bool)

NOTE: This function can only be called by the Admin and Super Admin. This function is designed to create transactions automatically on behalf of token holders if they have been a victim of a fraudulent transaction.

transferFrom

Transfers amount amount of tokens from address sender to address recipient, and MUST fire the Transfer event.

The transferFrom method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf. This can be used for example to allow a contract to transfer tokens on your behalf and/or to charge fees in sub-currencies. The function SHOULD throw unless the sender account has deliberately authorized the sender of the message via some mechanism.

function transferFrom(address sender, address recipient, uint256 amount) external returns (bool)

NOTE: Transfers of 0 values MUST be treated as normal transfers and fire the Transfer event.

adminTransfer

Transfers amount amount of tokens from address sender to address recipient, and MUST fire the Transfer event.

function adminTransfer(address sender, address recipient, uint256 amount) external returns (bool)

NOTE: This function can only be called by the Committee address required in the constructor. This function is designed to create transactions automatically on behalf of token holders if they have been a victim of a fraudulent transaction. This method works similar to the transferFrom method.

Events

Transfer

MUST trigger when tokens are transferred, including zero value transfers.

A token contract which creates new tokens SHOULD trigger a Transfer event with the from address set to 0x0 when tokens are created.

event Transfer(address indexed from, address indexed to, uint256 value)

Approval

MUST trigger on any successful call to approve(address spender, uint256 value).

event Approval(address indexed owner, address indexed spender, uint256 value)

IKAP22

mint

Mint amount amount of token to receiver address without period, and MUST fire the Mint event.

function mint(address receiver, uint256 amount) external returns (bool);

mintCurrentPeriod

Mint amount amount of token to receiver address with the current period.

function mintCurrentPeriod(address receiver, uint256 amount) external returns (bool);

mintCustomPeriod

Mint amount amount of token to receiver address with the customizable period period.

function mintCustomPeriod(address receiver, uint256 amount, uint256 period) external returns (bool);

transfer

Transfers amount amount of tokens to address recipient, and MUST fire the TransferPeriod event. The function SHOULD throw if the message caller's account balance does not have enough tokens to spend.

function transfer(address recipient, uint256 amount) external returns (bool)

NOTE: Tokens that are about to expired will be transferred first

transferNoPeriod

Transfer amount amount of token without period to recipient address.

function transferNoPeriod(address recipient, uint256 amount) external returns (bool);

transferStampPeriod

Transfer amount amount of token without period to recipient address and stamp the period period to the token, and MUST fire the TransferPeriod event. The function SHOULD throw if the message caller's account balance does not have enough tokens to spend.

function transferStampPeriod(address recipient, uint256 amount, uint256 period) external returns (bool);

transferCustomPeriod

Transfer amount amount of token within the desired period period to recipient address, and MUST fire the TransferPeriod event. The function SHOULD throw if the message caller's account balance does not have enough tokens to spend.

function transferCustomPeriod(address recipient, uint256 amount, uint256 period) external returns (bool);

balanceOf

Returns the balance of active tokens in every period of account address.

function balanceOf(address account) external view returns (uint256)

balanceOfAll

Returns the balance of tokens in every period of account address.

function balanceOfAll(address account) external view returns (uint256);

balanceOfPeriod

Returns the balance of tokens in the selected period period of account address.

function balanceOfPeriod(address account, uint256 period) external view returns (uint256);

balanceOfExpired

Returns the balance of expired tokens of account address.

function balanceOfExpired(address account) external view returns (uint256);

burn

Burns the amount amount of tokens, and MUST fire the Burn event.

function burn(uint256 amount) external returns (bool);

NOTE: Tokens that are about to expired will be burned first

burnCustomPeriod

Burns the amount amount of tokens in the selected period period.

function burnCustomPeriod(uint256 amount, uint256 period) external returns (bool);

pegToken

Returns the address of the token that is pegged with the loyalty token.

function pegToken() external view returns (address);

ratio

Returns the ratio of the loyalty token and the pegged token.

function ratio() external view returns (uint256);

currentIndex

Returns the index of the current period.

function currentIndex() external view returns (uint256);

currentPeriod

Returns the current period.

function currentPeriod() external view returns (uint256);

totalUnStampSupply

Returns the total amount of tokens without period.

function totalUnStampSupply() external view returns (uint256);

totalExpiredUserSupply

Returns the total amount of expired tokens.

function totalExpiredUserSupply() external view returns (uint256);

totalExpiredOwnerReceiverSupply

Returns the total amount of expired tokens of both Owner and Receiver.

function totalExpiredOwnerReceiverSupply() external view returns (uint256);

readPeriodTimestamp

Returns the number of seconds in the selected period.

function readPeriodTimestamp(uint256 page, uint256 limit) external view returns (uint256[] memory);

setPeriodTimeStamp

Sets the amount of seconds in the selected period.

function setPeriodTimeStamp(uint256[] calldata index, uint256[] calldata timestamp) external returns (bool);

KAP-22 Events

Mint

MUST trigger on any successful call to mint(address receiver, uint256 amount).

event Mint(uint256 indexed period, address indexed receiver, uint256 amount);

Burn

MUST trigger on any successful call to burn(uint256 amount).

event Burn(address indexed owner, uint256 amount);

TransferPeriod

MUST trigger on any successful call to transfer(address recipient, uint256 amount), transferStampPeriod(address recipient, uint256 amount, uint256 period), and transferCustomPeriod(address recipient, uint256 amount, uint256 period).

event TransferPeriod(address indexed sender, address indexed recipient, uint256 value, uint256 period);

IKToken

internalTransfer

Transfers amount amount of tokens to address recipient internally from sender, and MUST fire the Transfer event. The function SHOULD throw if the message caller's account balance does not have enough tokens to spend. Tokens can be transferred between internal addresses that have completed KYC for both the sender and the recipient using the internalTransfer function.

function internalTransfer(address sender, address recipient, uint256 amount) external returns (bool)

NOTE: This function can only be called by the Super Admin and the Transfer Router.

externalTransfer

Transfers amount amount of tokens to address recipient externally from sender, and MUST fire the Transfer event. The function SHOULD throw if the message caller's account balance does not have enough tokens to spend. The function externalTransfer allows tokens to be transferred between addresses that have only passed the sender's KYC verification process.

function externalTransfer(address sender, address recipient, uint256 amount) external returns (bool)

NOTE: This function can only be called by the Super Admin and the Transfer Router.