VKINHA Contract Documentation

Overview

The VKINHA contract is an ERC-20 token deployed on the BNB Chain Mainnet, designed to provide buying, transferring, staking, and administrative functionalities, with anti-bot mechanisms and fees to encourage legitimate use and deter abuse. The token, symbolized as VKINHA, has a maximum total supply of 15 million and integrates with decentralized exchanges (DEXs) such as PancakeSwap, Biswap, ApeSwap, and SushiSwap, supporting purchases with BNB, BUSD, and USDT via Chainlink oracles.

Main Features

• Name: VKINHA
• Symbol: VKINHA
• Decimals: 18
• Total Supply: 15,000,000 VKINHA
• Functionalities:
  • Token purchases with BNB, BUSD, or USDT using Chainlink oracles for pricing.
  • Progressive fees for repetitive purchases and fixed fees on transfers/sales.
  • Staking with rewards based on accumulated fees.
  • Administration with pause control, fund withdrawal, DEX configuration, and periodic token burning.
  • Anti-Bot Protections: Limit of one purchase per block and progressive fee for frequent purchases.

Contract Structure

Inheritances

• ERC20: Standard ERC-20 token implementation with functions such as transferFunction to send VKINHA to another address. Example: You send 10 VKINHA to a friend and pay a 3% fee (0.3 VKINHA)., approveFunction to allow a spender to transfer your VKINHA. Example: You approve 50 VKINHA for a DEX., and transferFromFunction to transfer VKINHA on behalf of another address. Example: A DEX transfers 20 VKINHA from your wallet..
• Ownable: Ownership control with two administrators (admin1 and admin2).
• ReentrancyGuard: Protection against reentrancy attacks in critical functions like buyTokensFunction to buy VKINHA tokens using BNB, BUSD, or USDT. Example: You send 0.1 BNB to receive VKINHA, paying an initial 0.25% fee. and unstakeTokensFunction to withdraw staked VKINHA. Example: You unstake 100 VKINHA after earning rewards..

Constants

The constants defined in the contract determine its behavior and operational limits. The table below lists the main constants:

Configurable Addresses (Mainnet)

Configurable addresses used in the contract for administrators, wallets, and DEX integration:

Chainlink Oracles (Mainnet)

Oracles used to fetch real-time prices for BNB, BUSD, and USDT:

Fee Logic

Fees on Purchase (buyTokensFunction to buy VKINHA tokens using BNB, BUSD, or USDT. Example: You send 0.1 BNB to receive VKINHA, paying an initial 0.25% fee that increases with frequent purchases.)

Base Fee: 0.25% (BASE_BUY_FEE_PERCENTAGE).

Progressive Fee:

• Condition: Applied to additional purchases within a 30-minute window (COOLDOWN_WINDOW).
• Increment: +1% per extra purchase (EXTRA_FEE_INCREMENT), up to a maximum of 20% (MAX_EXTRA_FEE_PERCENTAGE).
• Reset: After 1 hour without purchases (RESET_WINDOW), the extra fee resets to 0.25%.

Note: The progressive fee is designed to discourage automated trading bots and high-frequency trades, which can manipulate the price. This ensures a more stable and fair trading environment.

Calculation:

uint256 extraFee = purchaseCountInWindow[msg.sender] > 1 ? (purchaseCountInWindow[msg.sender] - 1) * EXTRA_FEE_INCREMENT : 0;
uint256 totalFeePercentage = BASE_BUY_FEE_PERCENTAGE + (extraFee > MAX_EXTRA_FEE_PERCENTAGE ? MAX_EXTRA_FEE_PERCENTAGE : extraFee);
uint256 buyFee = (amount * totalFeePercentage) / 10000;
uint256 amountAfterFee = amount - buyFee;

Destination: buyFee is transferred to tokenWallet and added to accumulatedFeePool.

Fees on Transfer (transferFunction to send VKINHA to another address. Example: You send 10 VKINHA to a friend and pay a 3% fee (0.3 VKINHA). If it's a sale on DEX, you pay an additional 0.5%.)

Transfer Fee: 3% (TRANSFER_FEE_PERCENTAGE) on all transfers.

Sale Fee: 0.5% (SELL_FEE_PERCENTAGE) additional only when the recipient is dexRouter (sale on DEX).

Calculation:

uint256 transferFee = (amount * TRANSFER_FEE_PERCENTAGE) / 10000;
uint256 sellFee = (to == dexRouter) ? (amount * SELL_FEE_PERCENTAGE) / 10000 : 0;
uint256 totalFee = transferFee + sellFee;
uint256 amountAfterFee = amount - totalFee;

Destination: totalFee is transferred to tokenWallet and added to accumulatedFeePool.

Reward Logic

Staking (stakeTokensFunction to stake your VKINHA and earn rewards. Example: You stake 100 VKINHA for 30 days and receive a portion of the collected fees as a reward.)

Operation: Users stake VKINHA to earn rewards based on accumulated fees.

Rewards: Calculated in calculateRewards based on:

• Base Rate: 0.002% per day (BASE_REWARD_RATE) on the staked amount.
• Extra Rate: 0.001% per day for every 1000 VKINHA above 0.01 (EXTRA_REWARD_RATE), up to a maximum of 0.1% (MAX_REWARD_RATE).
• Fee Pool: 0.002% per day (FEE_POOL_REWARD_RATE) of accumulatedFeePool, proportional to the user's stake.

Calculation:

uint256 baseReward = (staker.amount * BASE_REWARD_RATE * timeElapsed) / (10000 * 1 days);
uint256 extraReward = (extraTokens / (1000 * 1e18)) * EXTRA_REWARD_RATE * timeElapsed / (10000 * 1 days);
uint256 fixedReward = baseReward + extraReward > maxReward ? maxReward : baseReward + extraReward;
uint256 feePoolReward = (feePoolDelta * FEE_POOL_REWARD_RATE * timeElapsed) / (10000 * 1 days);
uint256 proportionalReward = totalStaked > 0 ? (staker.amount * feePoolReward) / totalStaked : 0;
return staker.accumulatedRewards + fixedReward + proportionalReward;

Payment: Rewards are transferred from tokenWallet when calling claimRewardsFunction to claim your staking rewards. Example: After staking 100 VKINHA, you claim 0.5 VKINHA in rewards..

Administrative Functions

Administrators

admin1: Initial owner with permission for all administrative functions.

admin2: Secondary administrator with permission for specific functions (e.g., replaceTokenWallet).

Main Functions

• replaceTokenWallet(address newTokenWallet)Replaces the token storage wallet with a new address. Example: The admin changes to a more secure wallet.: Permission: Only admin1 or admin2. Description: Replaces tokenWallet with a new address.
• withdrawFunds(uint256 amount)Allows the admin to withdraw tokens from the contract. Example: The admin withdraws 100 VKINHA for other uses.: Permission: Only admin1 or admin2. Description: Withdraws amount of VKINHA from tokenWallet.
• setDexRouter(address newRouter)Sets the DEX router address for trading. Example: Configures PancakeSwap as the trading platform.: Permission: Only admin1 or admin2. Description: Configures the DEX router.
• pause()Pauses the contract in emergencies. Example: If there's an issue, the admin temporarily stops operations.: Permission: Only admin1 or admin2. Description: Pauses contract operations.
• unpause()Resumes the contract after a pause. Example: After resolving an issue, the admin restarts operations.: Permission: Only admin1 or admin2. Description: Resumes contract operations.
• burnPeriodic()Burns tokens periodically to reduce supply. Example: Every month, 50 VKINHA are destroyed.: Permission: Anyone (when not paused). Description: Burns BURN_AMOUNT tokens every BURN_INTERVAL until reaching BURN_SUPPLY_TARGET.
• checkAndUnlockTokens()Unlocks locked tokens after 365 days. Example: After 1 year, 1000 VKINHA become available.: Permission: Anyone. Description: Unlocks LOCKED_SUPPLY after 365 days from the first transfer.

Interaction Examples

Using Remix

Buying VKINHA with BNB:

• Function: buyTokens(uint256 amount, address paymentToken)
• Parameters:
  • amount: 1000000000000000 (0.001 VKINHA)
  • paymentToken: "0x0000000000000000000000000000000000000000"
  • "Value": 1000000000000000 (0.001 BNB)
• Steps:
  1. Connect to Remix with MetaMask (Mainnet).
  2. Deploy the contract and call buyTokens.
  3. Confirm the transaction.

Transferring VKINHA:

• Function: transfer(address to, uint256 amount)
• Parameters:
  • to: "0xOtherAddress"
  • amount: 1000000000000000 (0.001 VKINHA)
• Steps:
  1. Call transfer in Remix and confirm.

Using Web3.js

const Web3 = require('web3');
const web3 = new Web3('https://bsc-dataseed.binance.org/');
const contractABI = [/* Contract ABI */];
const contractAddress = '0xContract';
const contract = new web3.eth.Contract(contractABI, contractAddress);

async function buyTokens(account, amount) {
    const tx = await contract.methods.buyTokens(amount, "0x0000000000000000000000000000000000000000")
        .send({ from: account, value: web3.utils.toWei('0.001', 'ether') });
    console.log('Purchase completed:', tx.transactionHash);
}

buyTokens('0xYourAddress', '1000000000000000');

Security Considerations

Attack Vectors and Mitigations

• Reentrancy:
  • Risk: Malicious contracts could repeatedly call buyTokens or unstakeTokens.
  • Mitigation: Use of the nonReentrant modifier.
• Frontrunning:
  • Risk: Bots buying before legitimate users in the same block.
  • Mitigation: Limit of one purchase per block (lastPurchaseBlock).
• Transaction Spam:
  • Risk: Bots flooding the contract with small purchases.
  • Mitigation: Progressive fee (up to 20.25%) for frequent purchases.
• Oracle Manipulation:
  • Risk: Manipulated prices in Chainlink oracles.
  • Mitigation: Use of reliable oracles with fallback to a fixed price (0.01 BNB) in case of failure.
• Administrative Access:
  • Risk: admin1 or admin2 abusing powers (e.g., withdrawFunds).
  • Mitigation: Two administrators with separate permissions; audit recommended.

Recommendations

• Audit the contract using tools like MythX or Slither before deployment.
• Thoroughly test on the Testnet to validate anti-bot mechanisms and fees.

Testing

Test Strategy

• Functionalities: Test buyTokens, transfer, stakeTokens, unstakeTokens, claimRewards.
• Anti-Bot: Simulate repetitive purchases to validate progressive fees and per-block limits.
• Rewards: Verify calculations across different staking scenarios.
• Administration: Test withdrawFunds, pause, setDexRouter, burnPeriodic.

Recommended Tools

Hardhat:

Setup:

const { ethers } = require("hardhat");

async function main() {
    const VKINHA = await ethers.getContractFactory("VKINHA");
    const vkinha = await VKINHA.deploy();
    await vkinha.deployed();
    console.log("Contract deployed to:", vkinha.address);
}

Tests:

it("should apply progressive buy fee", async function () {
    const [owner] = await ethers.getSigners();
    await vkinha.buyTokens(ethers.utils.parseEther("0.001"), "0x0", { value: ethers.utils.parseEther("0.001") });
    await vkinha.buyTokens(ethers.utils.parseEther("0.001"), "0x0", { value: ethers.utils.parseEther("0.001") });
    // Verify fee > 0.25%
});

Foundry:

Setup: Use forge init and add the contract.

Test: Write in Solidity to simulate interactions.

Steps

• Deploy on Testnet (Chain ID: 97).
• Use Remix or scripts to execute test scenarios.

Gas Optimization

Current Optimizations

• Use of unchecked in safe operations (e.g., subtractions in _transferWithoutFee).
• Efficient storage of variables like lastPurchaseBlock.

Possible Improvements

• Reduce Storage Operations:
  • Problem: Mappings like lastPurchaseTime and purchaseCountInWindow incur gas costs per write.
  • Solution: Combine into a structure:

    struct PurchaseInfo {
        uint256 lastBlock;
        uint256 lastTime;
        uint256 countInWindow;
    }
    mapping(address => PurchaseInfo) public purchaseData;

• Variable Caching:
  • Problem: Repeated reads of tokenWallet or dexRouter.
  • Solution: Store in local variables in buyTokens and transfer.
• Remove Redundant Checks:
  • Problem: require in _transfer already checks balance, duplicated in transfer.
  • Solution: Eliminate redundancies where possible.

Impact

Estimated reduction: 5-10% in gas cost per transaction.