BuyOnlyToken - Advanced ERC-20 with Buy-Only Mechanics

⚠️ CRITICAL WARNING: This token implements a buy-only mechanism that blocks sells by default. This is visible on-chain and often perceived as a honeypot. Full disclosure to buyers is mandatory, and an independent security audit is strongly recommended before mainnet deployment.

Overview

BuyOnlyToken is a production-ready ERC-20 token implementation with advanced features including:

• Buy-Only Mechanism: Sells are blocked by default until explicitly enabled by governance
• Multi-Chain Support: Deployable on Base and BSC (Binance Smart Chain)
• Fee System: Configurable buy/sell fees with automatic distribution
• Anti-Bot Protection: Launch protection with transaction limits and cooldowns
• Governance: Timelock and multisig support for critical functions
• Vesting: Linear and cliff vesting schedules for team/investors
• Presale: Whitelist-based presale with contribution limits
• DeFi Integration: Uniswap V3 concentrated liquidity and DODO PMM support

Features

Core Token Features

• ERC-20 standard compliance
• EIP-2612 permit functionality
• Snapshot mechanism for governance voting
• Pausable transfers for emergencies
• Blacklist/whitelist functionality
• Fee exemptions for specific addresses

Buy-Only Mechanism

• Blocks transfers TO liquidity pools (sells) by default
• Allows transfers FROM liquidity pools (buys)
• Whitelist bypass for market makers and specific addresses
• Owner-controlled sell enabling through timelock

Fee Structure

• Buy Fee: 3% default (configurable)
• Sell Fee: 5% default (configurable)
• Distribution:
  • Treasury: 50%
  • Buyback: 30%
  • Burn: 20%

Security Features

• Anti-bot protection during launch
• Maximum transaction limits
• Maximum wallet limits
• Cooldown between transactions
• Gas price limits
• Timelock governance (2-day minimum delay)
• Multisig support

Installation

Prerequisites

• Foundry
• Node.js >= 16
• Git

Setup

# Clone the repository
git clone <repository-url>
cd buy-only-token

# Install dependencies
npm install

# Install Foundry dependencies
forge install

Environment Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Required environment variables:

• PRIVATE_KEY: Deployer wallet private key
• BASE_RPC_URL: Base network RPC endpoint
• BSC_RPC_URL: BSC network RPC endpoint
• BASESCAN_API_KEY: Basescan API key for verification
• BSCSCAN_API_KEY: BscScan API key for verification
• Token parameters (name, symbol, supply, etc.)
• Contract addresses (treasury, buyback, multisig)

Deployment

Local Testing

# Run tests
forge test

# Run tests with gas reporting
forge test --gas-report

# Run specific test
forge test --match-test testBuyOnlyMechanism -vvv

Deploy to Testnet

# Deploy to Base Sepolia
forge script script/Deploy.s.sol:Deploy --rpc-url base-sepolia --broadcast --verify

# Deploy to BSC Testnet
forge script script/Deploy.s.sol:Deploy --rpc-url bsc-testnet --broadcast --verify

Deploy to Mainnet

# Deploy to Base Mainnet
forge script script/Deploy.s.sol:Deploy --rpc-url base --broadcast --verify

# Deploy to BSC Mainnet
forge script script/Deploy.s.sol:Deploy --rpc-url bsc --broadcast --verify

Add Liquidity

After deployment, add liquidity using:

# Add liquidity (configure amounts in .env)
forge script script/AddLiquidity.s.sol:AddLiquidity --rpc-url <network> --broadcast

Initial Price Configuration

Uniswap V3 Strategy

1. Concentrated Liquidity: Deploy liquidity in a tight range (±5%) around target price
2. Capital Efficiency: Small amount of capital can maintain price stability
3. Example: For $0.001 initial price with $10,000 liquidity:

   Price Range: $0.00095 - $0.00105
   Token Amount: 10,000,000 MBOT
   USDC/ETH Amount: $10,000
   

DODO PMM Strategy

1. Set Initial Price (i parameter): Defines the initial price point
2. Set Slippage (k parameter): Controls price sensitivity (0.1-0.5 recommended)
3. Example Configuration:

   i = 0.001 * 10^18  // $0.001 per token
   k = 0.1 * 10^18    // 10% slippage parameter

Contract Interaction

Enable Selling (Governance Only)

// Through timelock (2-day delay)
1. Schedule: timelock.schedule(token, 0, setSellAllowed(true), ...)
2. Wait 2 days
3. Execute: timelock.execute(token, 0, setSellAllowed(true), ...)

Manage Liquidity Pools

// Mark address as liquidity pool
token.setLiquidityPool(poolAddress, true)

// Remove pool designation
token.setLiquidityPool(poolAddress, false)

Fee Management

// Update fees (max 20%)
token.setFees(300, 500) // 3% buy, 5% sell

// Update fee recipients
token.setFeeAddresses(treasury, buyback)

// Update distribution
token.setFeeShares(5000, 3000, 2000) // 50%, 30%, 20%

Security Considerations

Buy-Only Mechanism Risks

1. Honeypot Perception: Blocking sells creates honeypot appearance
2. Trust Issues: Requires strong community trust and transparency
3. Liquidity Risk: Limited sell-side liquidity until enabled
4. Regulatory Concerns: May face scrutiny in some jurisdictions

Mitigation Strategies

1. Full Disclosure: Clearly communicate buy-only period to all buyers
2. Timelock Governance: All critical functions behind 2-day timelock
3. Multisig Control: Use multisig wallet for ownership
4. Public Roadmap: Publish clear timeline for enabling sells
5. Third-Party Audit: Get professional security audit before launch
6. Renounce Carefully: Don't renounce ownership until fully tested

Gas Optimization

Approximate gas costs (Base/BSC):

Function	Gas Usage	Cost @ 30 Gwei
Transfer	~65,000	~$0.05
Transfer with fee	~95,000	~$0.08
Buy from pool	~110,000	~$0.10
Sell to pool	~115,000	~$0.10
Claim vesting	~85,000	~$0.07

Testing

Run comprehensive test suite:

# Unit tests
forge test --match-contract BuyOnlyTokenTest

# Integration tests
forge test --match-contract IntegrationTest

# Fuzz tests
forge test --match-test testFuzz

# Coverage report
forge coverage

Audit Preparation

Before audit, ensure:

1. ✅ All tests passing
2. ✅ 100% test coverage for critical paths
3. ✅ Deployment on testnet verified
4. ✅ Documentation complete
5. ✅ Known issues documented
6. ✅ Slither/Mythril analysis complete

See AUDIT_CHECKLIST.md for detailed audit requirements.

Deployment Checklist

See DEPLOY_CHECKLIST.md for step-by-step deployment guide.

Support Networks

Base

• Mainnet Chain ID: 8453
• Testnet (Sepolia): 84531
• Block Explorer: https://basescan.org

BSC (Binance Smart Chain)

• Mainnet Chain ID: 56
• Testnet Chain ID: 97
• Block Explorer: https://bscscan.com

Example Buyer Disclosure Message

⚠️ IMPORTANT NOTICE FOR BUYERS ⚠️

This token has a BUY-ONLY period active. This means:
- ✅ You CAN buy tokens from the liquidity pool
- ❌ You CANNOT sell tokens back to the pool yet
- 📅 Selling will be enabled on [DATE] via governance vote
- 🔒 This change requires a 48-hour timelock delay
- 👥 Decision made by multisig holders: [ADDRESSES]

This mechanism is designed to:
1. Prevent bot manipulation during launch
2. Build initial liquidity and price stability
3. Reward early supporters when selling enables

INVEST AT YOUR OWN RISK. This is visible on-chain and cannot be hidden.

License

MIT License - See LICENSE file for details

Disclaimer

This software is provided "as is", without warranty of any kind. The authors are not responsible for any losses or damages arising from its use. Always conduct your own research and get a professional audit before deploying to mainnet.

---

⚠️ FINAL WARNING: This project enables blocking sells by default. This is visible on-chain and often perceived as a honeypot — fully disclose to buyers and perform an independent security audit.