Skip to content

codyfight/token-contract

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

14 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Codyfight Token $CTOK

footer-logo

Visit the official Codyfight website for more information.

Codyfight Token $CTOK - Project Documentation

Functional Requirements

Project Purpose

CTOK fuels Codyfight's in-game economy, facilitating asset exchange and rewarding players. It operates on the Arbitrum blockchain for in-game transactions and broader crypto use.

Project Features

CTOK is a LERC-20 Burnable token, this protocol created and maintained by Lossless.io is an ERC-20 implementation that is capable of freezing any fraudulent transaction based on a set of fraud identification parameters.

References:

Project Business Logic

CTOK smart contract establishes a burnable ERC-20 token with additional features for recovery administration and lossless functionality. It inherits from LERC20Burnable, implementing functions for transfers, approvals, and allowance management. Key features include:

  • Lossless Functionality: Control mechanisms are in place to toggle lossless functionality, enabling additional checks for transfers and approvals via the Lossless Controller.

  • Recovery Administration: The contract facilitates the transfer of recovery admin ownership and the proposal and execution of lossless functionality turn-off.

  • ERC20 Compliance: Standard ERC-20 functions such as transfer, transferFrom, approve, increaseAllowance, and decreaseAllowance are implemented, along with events to track token transfers and approvals.

  • Token Minting and Burning: Functions for minting and burning tokens are provided, with appropriate checks for balance and allowance. The minting function is only available at contract deployment.

Use Cases

CTOK has plenty of utilities and serves not only as a way to reward players but also as a system to value users’ tasks in-game.

Codyfight is a competitive game and Codyfighters will need to showcase their skills and think efficiently about how to win tokens.

Use cases are community incentives, rewards, in-game asset purchases, governance and more:

  • Lower costs of in-game transaction fees, keeping them at the bare minimum.
  • Reward external project contributors and motivate them to get involved in the success of the project.
  • Reward players’ efforts in the gameplay and further their motivation to purchase assets.
  • Benefit players who create in-game assets (Codyfighters & AI code).
  • Create a valuable system of rewards based on the player's performance.
  • Reward for competitive players, team members, and e-sport investors.

These use cases demonstrate the versatile applications of the CodyfightToken smart contract within the gaming ecosystem and beyond, leveraging blockchain technology to enhance user experiences, incentivize participation, and facilitate economic interactions.

References:

Roles and Authorizations

  • Admin Role:

    • Role Description: The admin role represents the project owner's administrative wallet address, used for Lossless governance decisions and initial token holder.

    • Permissions:

      • Interact with the Lossless protocol for governance decisions.
      • Tokens are minted to the administrative wallet address.
  • Recovery Admin Role:

    • Role Description: The Recovery Admin role is responsible for managing administrative changes and facilitating recovery procedures within the CodyfightToken (CTOK) contract.

    • Permissions:

      • Transfer Ownership: The Recovery Admin can transfer ownership of the Recovery Admin role to another address by proposing a new candidate.
      • Accept Ownership: Upon the proposal of a new candidate, the Recovery Admin can accept ownership of the Recovery Admin role by providing the correct key.
      • Proposal for Lossless Functionality: The Recovery Admin can propose turning off the lossless functionality, and initiating a governance decision process within the contract.

These permissions empower the Recovery Admin to oversee critical administrative tasks, ensuring the contract's smooth operation and security.

References:

Technical Requirements

Project Components

CodyfightToken (CTOK) is a LERC20Burnable contract. Deploying it requires these parameters:

  • totalSupply: amount of tokens to be minted (18 decimals);

  • name: token title;

  • symbol: token symbol;

  • admin: project owner’s administrative wallet address, this will be used in Lossless governance decisions. Token creators should set up a wallet that they are planning on using to interact with the Lossless protocol. Tokens are initially minted to this wallet;

  • recoveryAdmin: project owner’s wallet that is used to change admin. Token creators should use multi-sig for this and keep it as secure as possible as this wallet allows changing the admin wallet;

  • timelockPeriod: timelock period in seconds dedicated for turning Lossless turn off. In case the project decides to turn off Lossless they would have to wait for this period after initially proposing to turn the Lossless functionality off. Recommended timelockPeriod is 24 hours or 86400 seconds. Any lower timelockPeriod will be considered unsafe and will be marked as such in Lossless platform;

  • lossless: Lossless protocol controller address. It should be set to Lossless Controller address. Lossless Controller address is different on different chains. Any other address will not allow the token to function properly. You can find the appropriate controller address here.

References:

Technologies Used

The CodyfightToken (CTOK) project employs a diverse set of technologies to build and operate its ecosystem. Here's a breakdown of the key technologies used:

CodyfightToken project aims to build a secure, scalable, and feature-rich token ecosystem on the Arbitrum blockchain, providing users with a seamless and rewarding experience.

Architectural Design

Smart Contracts

  • LERC20Burnable: Implements core token functionalities including minting, burning, transferring, and allowance management. Integrates lossless functionality through modifiers and events.
  • CodyfightToken: Main token contract inheriting functionality from LERC20Burnable. Initializes token parameters and interacts with lossless controller.

Interfaces

  • ILssController: Interface defining functions for lossless functionality such as beforeTransfer, beforeApprove, beforeBurn, etc.

Admin and Recovery Admin

  • Administrative wallet address (admin) and recovery admin wallet address (recoveryAdmin) specified during contract deployment. Recovery admin proposes and executes changes related to lossless functionality and ownership transfer. Admin holds minted tokens and governs the contract, interacting with the lossless protocol for governance decisions.

Lossless Functionality

  • CTOK includes lossless functionality with additional checks and safeguards during token transfers and operations. Toggled on or off by recovery admin for flexibility and security enhancements.

Events

  • Various events emitted during contract execution to provide visibility into important state changes. Events include Transfer, Approval, NewAdmin, NewRecoveryAdminProposal, NewRecoveryAdmin, LosslessTurnOffProposal, LosslessOff, and LosslessOn.

Modifiers

  • Modifiers enforce additional checks and interactions with the lossless controller before executing certain functions. Modifiers such as lssTransfer, lssApprove, lssBurn, etc., ensure secure and efficient contract operations.

Overall, the architecture of the CTOK project revolves around secure and efficient smart contracts, with a focus on implementing lossless functionality and providing flexibility for contract administration and ownership. The interaction between the main token contract, lossless controller, admin, and recovery admin ensures robust governance and security for the CTOK ecosystem.

Testing

The CodyfightToken (CTOK) project includes comprehensive testing to ensure the functionality, security, and reliability of the smart contracts. The testing suite covers various scenarios and edge cases to validate the contract's behavior under different conditions.

Deployment

The deployment process involves deploying the CTOK smart contract on the Arbitrum blockchain with the specified parameters, including total supply, token name, symbol, admin, recovery admin, timelock period, and lossless controller address. Once deployed, the contract is ready to interact with users and other components of the Codyfight ecosystem.

References:

Non-Functional Requirements

Security Considerations, Compliance and Governance

The CodyfightToken (CTOK) project incorporates several security measures, compliance standards, and governance practices to ensure the safety and integrity of the token ecosystem. Key security features and practices include:

  • ERC-20 Standard: CTOK follows the ERC-20 token standard, ensuring interoperability with other Ethereum-based tokens and platforms, and compliance with industry norms and guidelines.

  • Lossless Functionality: The lossless protocol adds an additional layer of security by preventing fraudulent transactions and ensuring the integrity of token transfers and operations.

  • Role-Based Permissions: The admin and recovery admin roles are carefully defined to manage critical contract functions such as ownership transfer, lossless functionality, and recovery procedures.

  • Timelock Period: The timelock period for turning off lossless functionality provides a grace period for governance decisions, allowing stakeholders to review and confirm changes before they take effect.

  • Event Logging: Events are emitted during contract execution to provide visibility into important state changes and transactions, enabling users to monitor contract activities and detect anomalies.

  • Modifiers and Checks: Modifiers enforce additional checks and interactions with the lossless controller before executing certain functions, ensuring that only authorized transactions are processed.

  • Testing and Auditing: Comprehensive testing and auditing processes are conducted to validate the contract's functionality, security, and compliance with best practices, minimizing the risk of vulnerabilities and exploits.

By incorporating these security measures and best practices, the CodyfightToken (CTOK) project aims to create a secure and reliable token ecosystem that safeguards user assets and transactions on the Arbitrum blockchain.

Scalability and Performance

The CodyfightToken (CTOK) project leverages the Arbitrum blockchain as a layer 2 scaling solution to enhance scalability and performance for in-game transactions and broader crypto use. By operating on Arbitrum, CTOK benefits from:

  • Low Transaction Fees: Arbitrum offers low transaction fees, making it cost-effective for users to perform token transfers, asset exchanges, and other operations within the Codyfight ecosystem.

  • Fast Transaction Speeds: Arbitrum provides fast transaction speeds, enabling near-instant confirmation times for token transfers and operations, enhancing the user experience and gameplay efficiency.

  • Scalable Architecture: The Arbitrum blockchain is designed for scalability, supporting a high throughput of transactions and smart contract interactions, making it suitable for the growing demands of the Codyfight ecosystem.

  • Layer 2 Solutions: By utilizing layer 2 solutions like Arbitrum, CTOK can offload transaction processing and data storage from the Ethereum mainnet, reducing congestion and improving overall performance for users.

The scalability and performance benefits of operating on Arbitrum enable the CodyfightToken (CTOK) project to deliver a seamless and efficient token ecosystem that meets the needs of players, developers, and stakeholders within the gaming community.

References:

Usability and User Experience

The CodyfightToken (CTOK) project focuses on usability and user experience to provide a seamless and rewarding interaction for players, developers, and stakeholders within the gaming ecosystem. Key usability features and enhancements include:

  • Intuitive Token Operations: CTOK offers intuitive token operations such as transfers, approvals, and burning, enabling users to interact with the token contract easily and efficiently.

  • NatSpec Documentation: Human-readable documentation is provided for the smart contract functions, events, and modifiers, making it easier for developers and users to understand the contract's behavior and usage.

By focusing on usability and user experience, the CodyfightToken (CTOK) project aims to create a user-friendly and engaging token ecosystem that empowers players, developers, and stakeholders to participate in the gaming community and benefit from the rewards and incentives offered by CTOK.

Codyfight Token $CTOK - Contract Documentation

Context Contract

Context provides information about the transaction sender.

Context library from OpenZeppelin contracts.

_msgSender

function _msgSender() internal view virtual returns (address)

Returns the transaction sender address.

Return Values

Name Type Description
[0] address sender_ The transaction sender address.

_msgData

function _msgData() internal view virtual returns (bytes)

Returns the transaction data.

Return Values

Name Type Description
[0] bytes data_ The transaction data.

ILssController

LssController is a contract that implements the lossless feature. It is used to control the lossless feature of the LERC20Burnable contract. The LssController contract must implement the beforeTransfer, beforeTransferFrom, beforeApprove, beforeIncreaseAllowance, beforeDecreaseAllowance, and beforeBurn functions. The LssController contract must be set in the LERC20Burnable contract.

Interface of the LssController.

beforeTransfer

function beforeTransfer(address sender, address recipient, uint256 amount) external

Function to be called before a transfer.

Parameters

Name Type Description
sender address The sender address.
recipient address The recipient address.
amount uint256 The transfer amount.

beforeTransferFrom

function beforeTransferFrom(address msgSender, address sender, address recipient, uint256 amount) external

Function to be called before a transfer from.

Parameters

Name Type Description
msgSender address The transaction sender address.
sender address The sender address.
recipient address The recipient address.
amount uint256 The transfer amount.

beforeApprove

function beforeApprove(address sender, address spender, uint256 amount) external

Function to be called before an approve.

Parameters

Name Type Description
sender address The sender address.
spender address The spender address.
amount uint256 The approve amount.

beforeIncreaseAllowance

function beforeIncreaseAllowance(address msgSender, address spender, uint256 addedValue) external

Function to be called before an increase allowance.

Parameters

Name Type Description
msgSender address The transaction sender address.
spender address The spender address.
addedValue uint256 The added allowance amount.

beforeDecreaseAllowance

function beforeDecreaseAllowance(address msgSender, address spender, uint256 subtractedValue) external

Function to be called before a decrease allowance.

Parameters

Name Type Description
msgSender address The transaction sender address.
spender address The spender address.
subtractedValue uint256 The subtracted allowance amount.

beforeBurn

function beforeBurn(address account, uint256 amount) external

Function to be called before a burn.

Parameters

Name Type Description
account address The account address.
amount uint256 The burn amount.

LERC20Burnable Contract

LERC20Burnable is a contract that implements the ERC20 standard with burn and lossless features. The LERC20Burnable contract is based on the OpenZeppelin Context contract.

LERC20Burnable contract from Lossless.io. Extends the Context contract.

recoveryAdmin

address recoveryAdmin

recoveryAdmin is the address of the recovery admin, who can change the admin and turn off the lossless feature.

Recovery admin variable.

admin

address admin

admin is the address of the admin, who will hold the minted tokens and have governance rights.

Admin variable.

timelockPeriod

uint256 timelockPeriod

timelockPeriod is the period in seconds that the recovery admin must wait to turn off the lossless feature.

Timelock period variable.

losslessTurnOffTimestamp

uint256 losslessTurnOffTimestamp

losslessTurnOffTimestamp is the timestamp when the lossless feature will be turned off.

Lossless turn off timestamp variable.

isLosslessOn

bool isLosslessOn

isLosslessOn is a boolean that indicates if the lossless feature is on.

Lossless on variable.

lossless

contract ILssController lossless

lossless is the address of the LssController contract, which implements the lossless feature.

Lossless controller variable.

constructor

constructor(uint256 totalSupply_, string name_, string symbol_, address admin_, address recoveryAdmin_, uint256 timelockPeriod_, address lossless_) public

Constructor sets the initial values of the contract. It mints the total supply to the admin address.

Constructor function.

Parameters

Name Type Description
totalSupply_ uint256 The total supply of the token.
name_ string The name of the token.
symbol_ string The symbol of the token.
admin_ address The address of the admin.
recoveryAdmin_ address The address of the recovery admin.
timelockPeriod_ uint256 The timelock period in seconds.
lossless_ address The address of the LssController contract.

Transfer

event Transfer(address _from, address _to, uint256 _value)

Transfer event.

Parameters

Name Type Description
_from address The sender address.
_to address The recipient address.
_value uint256 The transfer amount.

Approval

event Approval(address _owner, address _spender, uint256 _value)

Approval event.

Parameters

Name Type Description
_owner address The owner address.
_spender address The spender address.
_value uint256 The approve amount.

NewAdmin

event NewAdmin(address _newAdmin)

New admin event.

Parameters

Name Type Description
_newAdmin address The new admin address.

NewRecoveryAdminProposal

event NewRecoveryAdminProposal(address _candidate)

New recovery admin proposal event.

Parameters

Name Type Description
_candidate address The candidate address.

NewRecoveryAdmin

event NewRecoveryAdmin(address _newAdmin)

New recovery admin event.

Parameters

Name Type Description
_newAdmin address The new recovery admin address.

LosslessTurnOffProposal

event LosslessTurnOffProposal(uint256 _turnOffDate)

Lossless turn off proposal event.

Parameters

Name Type Description
_turnOffDate uint256 The turn off date timestamp.

LosslessOff

event LosslessOff()

Lossless off event.

LosslessOn

event LosslessOn()

Lossless on event.

lssAprove

modifier lssAprove(address spender, uint256 amount)

The lssAprove modifier calls the beforeApprove function of the lossless contract.

Lossless approve modifier.

Parameters

Name Type Description
spender address The spender address.
amount uint256 The approve amount.

lssTransfer

modifier lssTransfer(address recipient, uint256 amount)

The lssTransfer modifier calls the beforeTransfer function of the lossless contract.

Lossless transfer modifier.

Parameters

Name Type Description
recipient address The recipient address.
amount uint256 The transfer amount.

lssTransferFrom

modifier lssTransferFrom(address sender, address recipient, uint256 amount)

The lssTransferFrom modifier calls the beforeTransferFrom function of the lossless contract.

Lossless transfer from modifier.

Parameters

Name Type Description
sender address The sender address.
recipient address The recipient address.
amount uint256 The transfer amount.

lssBurn

modifier lssBurn(address account, uint256 amount)

The lssBurn modifier calls the beforeBurn function of the lossless contract.

Lossless burn modifier.

Parameters

Name Type Description
account address The account address.
amount uint256 The burn amount.

lssIncreaseAllowance

modifier lssIncreaseAllowance(address spender, uint256 addedValue)

The lssIncreaseAllowance modifier calls the beforeIncreaseAllowance function of the lossless contract.

Lossless increase allowance modifier.

Parameters

Name Type Description
spender address The spender address.
addedValue uint256 The added allowance amount.

lssDecreaseAllowance

modifier lssDecreaseAllowance(address spender, uint256 subtractedValue)

The lssDecreaseAllowance modifier calls the beforeDecreaseAllowance function of the lossless contract.

Lossless decrease allowance modifier.

Parameters

Name Type Description
spender address The spender address.
subtractedValue uint256 The subtracted allowance amount.

onlyRecoveryAdmin

modifier onlyRecoveryAdmin()

The onlyRecoveryAdmin modifier restricts access to the recovery admin.

Recovery admin modifier.

transferOutBlacklistedFunds

function transferOutBlacklistedFunds(address[] from) external

This function allows the lossless contract to transfer out blacklisted funds.

Function to transfer out blacklisted funds.

Parameters

Name Type Description
from address[] The array of addresses from which the funds will be transferred.

setLosslessAdmin

function setLosslessAdmin(address newAdmin) external

This function allows the recovery admin to set a new admin.

Function to set new admin.

Parameters

Name Type Description
newAdmin address The new admin address.

transferRecoveryAdminOwnership

function transferRecoveryAdminOwnership(address candidate, bytes32 keyHash) external

This function allows the recovery admin to transfer the recovery admin ownership to a candidate address.

Function to transfer recovery admin ownership.

Parameters

Name Type Description
candidate address The candidate address.
keyHash bytes32 The key hash.

acceptRecoveryAdminOwnership

function acceptRecoveryAdminOwnership(bytes key) external

This function allows the candidate address to accept the recovery admin ownership.

Function to accept recovery admin ownership.

Parameters

Name Type Description
key bytes The key.

proposeLosslessTurnOff

function proposeLosslessTurnOff() external

This function allows the recovery admin to propose to turn off the lossless features.

Function to propose lossless turn off.

executeLosslessTurnOff

function executeLosslessTurnOff() external

This function allows the recovery admin to execute the lossless turn off, when the timelock period has passed.

Function to execute lossless turn off.

executeLosslessTurnOn

function executeLosslessTurnOn() external

This function allows the recovery admin to execute the lossless turn on.

Function to execute lossless turn on.

getAdmin

function getAdmin() public view virtual returns (address)

Function to get the admin address.

Return Values

Name Type Description
[0] address The admin address.

name

function name() public view virtual returns (string)

Function to get the name of the token.

Return Values

Name Type Description
[0] string The name of the token.

symbol

function symbol() public view virtual returns (string)

Function to get the symbol of the token.

Return Values

Name Type Description
[0] string The symbol of the token.

decimals

function decimals() public view virtual returns (uint8)

Function to get the decimals of the token.

Return Values

Name Type Description
[0] uint8 The decimals of the token.

totalSupply

function totalSupply() public view virtual returns (uint256)

Function to get the total supply of the token.

Return Values

Name Type Description
[0] uint256 The total supply of the token.

balanceOf

function balanceOf(address account) public view virtual returns (uint256)

Function to get the balance of an account.

Parameters

Name Type Description
account address The account address.

Return Values

Name Type Description
[0] uint256 The balance of the account.

transfer

function transfer(address recipient, uint256 amount) public virtual returns (bool)

Function to transfer tokens. Uses the lssTransfer modifier to call the beforeTransfer function of the lossless contract.

Parameters

Name Type Description
recipient address The recipient address.
amount uint256 The transfer amount.

Return Values

Name Type Description
[0] bool A boolean that indicates if the operation was successful.

allowance

function allowance(address owner, address spender) public view virtual returns (uint256)

Function to get the allowance of a spender on an owner's tokens.

Parameters

Name Type Description
owner address The owner address.
spender address The spender address.

Return Values

Name Type Description
[0] uint256 The allowance of the spender on the owner's tokens.

approve

function approve(address spender, uint256 amount) public virtual returns (bool)

Function to approve a spender to spend an amount of tokens. Uses the lssAprove modifier to call the beforeApprove function of the lossless contract.

Parameters

Name Type Description
spender address The spender address.
amount uint256 The approve amount.

Return Values

Name Type Description
[0] bool A boolean that indicates if the operation was successful.

transferFrom

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

Function to transfer tokens from an owner to a recipient. Uses the lssTransferFrom modifier to call the beforeTransferFrom function of the lossless contract.

Parameters

Name Type Description
sender address The sender address.
recipient address The recipient address.
amount uint256 The transfer amount.

Return Values

Name Type Description
[0] bool A boolean that indicates if the operation was successful.

increaseAllowance

function increaseAllowance(address spender, uint256 addedValue) public virtual returns (bool)

Function to increase the allowance of a spender. Uses the lssIncreaseAllowance modifier to call the beforeIncreaseAllowance function of the lossless contract.

Parameters

Name Type Description
spender address The spender address.
addedValue uint256 The added allowance amount.

Return Values

Name Type Description
[0] bool A boolean that indicates if the operation was successful.

decreaseAllowance

function decreaseAllowance(address spender, uint256 subtractedValue) public virtual returns (bool)

Function to decrease the allowance of a spender. Uses the lssDecreaseAllowance modifier to call the beforeDecreaseAllowance function of the lossless contract.

Parameters

Name Type Description
spender address The spender address.
subtractedValue uint256 The subtracted allowance amount.

Return Values

Name Type Description
[0] bool A boolean that indicates if the operation was successful.

_transfer

function _transfer(address sender, address recipient, uint256 amount) internal virtual

Internal function to transfer tokens. Overrides the _transfer function of the Context contract to enforce specific conditions.

Parameters

Name Type Description
sender address The sender address.
recipient address The recipient address.
amount uint256 The transfer amount.

_mint

function _mint(address account, uint256 amount) internal virtual

Mint function is only executed at contract deployment. No mint function is available after deployment.

Internal function to mint tokens. Overrides the _mint function of the Context contract to enforce specific conditions.

Parameters

Name Type Description
account address The account address.
amount uint256 The mint amount.

_burn

function _burn(address account, uint256 amount) internal virtual

Internal function to burn tokens. Overrides the _burn function of the Context contract to enforce specific conditions.

Parameters

Name Type Description
account address The account address.
amount uint256 The burn amount.

_approve

function _approve(address owner, address spender, uint256 amount) internal virtual

Internal function to approve a spender to spend an amount of tokens.

Parameters

Name Type Description
owner address The owner address.
spender address The spender address.
amount uint256 The approve amount.

burn

function burn(uint256 amount) public virtual

Burn function may not be allowed if the lossless feature is on, Lossless controller may block the burn.

Function to burn tokens. Uses the lssBurn modifier to call the beforeBurn function of the lossless contract.

Parameters

Name Type Description
amount uint256 The burn amount.

burnFrom

function burnFrom(address account, uint256 amount) public virtual

Burn function may not be allowed if the lossless feature is on, Lossless controller may block the burn.

Function to burn tokens from an account. Uses the lssBurn modifier to call the beforeBurn function of the lossless contract.

Parameters

Name Type Description
account address The account address.
amount uint256 The burn amount.

CodyfightToken Contract

CodyfightToken is the official token of Codyfight. Tokens are only minted at contract deployment. No mint function is available after deployment. Tokens can be burned.

CodyfightToken fully inherits the LERC20Burnable contract, which implements the ERC20 standard with burn and lossless features.

constructor

constructor(uint256 totalSupply_, string name_, string symbol_, address admin_, address recoveryAdmin_, uint256 timelockPeriod_, address lossless_) public

Constructor sets the initial values of the contract. It mints the total supply to the admin address.

Constructor function.

Parameters

Name Type Description
totalSupply_ uint256 The total supply of the token.
name_ string The name of the token.
symbol_ string The symbol of the token.
admin_ address The address of the admin.
recoveryAdmin_ address The address of the recovery admin.
timelockPeriod_ uint256 The timelock period in seconds.
lossless_ address The address of the LssController contract.