Skip to content

Latest commit

 

History

History
274 lines (221 loc) · 9.63 KB

solidity.md

File metadata and controls

274 lines (221 loc) · 9.63 KB

Solidity Development Standards

This document outlines the standards and best practices for Solidity development at Bayat.

Code Style and Formatting

General Guidelines

  • Follow the Solidity Style Guide
  • Use a consistent version pragma statement at the top of each file
  • Maximum line length should be 120 characters
  • Use 4 spaces for indentation, not tabs
  • Files should be encoded in UTF-8
  • Files should end with a newline
  • Use spaces around operators
  • No trailing whitespace
  • Use // SPDX-License-Identifier: <LICENSE> at the top of each file

Naming Conventions

  1. Contracts and Libraries:

    • Use PascalCase for contract, library, and interface names (e.g., ERC20Token, SafeMath)
    • Be descriptive and avoid abbreviations
    • Interfaces should be prefixed with "I" (e.g., IERC20)

  2. Functions:

    • Use camelCase for function names (e.g., transferFrom, balanceOf)
    • Use descriptive names that accurately reflect behavior
    • Private/internal functions should be prefixed with an underscore (e.g., _transfer)
    • Event functions should use PascalCase (e.g., Transfer, Approval)

  3. Variables:

    • Use camelCase for variable names (e.g., tokenBalance, ownerAddress)
    • Use meaningful names that reflect the purpose or meaning
    • Constants should use SNAKE_CASE (e.g., MAX_UINT, TOKEN_DECIMALS)
    • Private/internal state variables should be prefixed with an underscore (e.g., _balances)

  4. Modifiers:

    • Use camelCase for modifier names (e.g., onlyOwner, nonReentrant)
    • Modifier names should describe the restriction or behavior they enforce

  5. Events:

    • Use PascalCase for event names (e.g., Transfer, OwnershipTransferred)
    • Event names should typically be verbs in past tense as they record actions that have occurred

  6. Enums and Structs:

    • Use PascalCase for enum and struct names
    • Enum values should be in ALL_CAPS

Code Organization

  1. File Structure:

    • One contract/library per file, unless closely related
    • Follow a standard order for contract elements:
      1. Pragma statements
      2. Import statements
      3. Interfaces
      4. Libraries
      5. Contracts (ordered from base to most derived)
    • Within a contract, follow this order:
      1. Type declarations (structs, enums)
      2. State variables
      3. Events
      4. Modifiers
      5. Constructor
      6. Fallback and receive functions
      7. External functions
      8. Public functions
      9. Internal functions
      10. Private functions

  2. Import Statements:

    • Group imports by source (e.g., standard libraries, external libraries, local imports)
    • Use explicit imports (e.g., import {Symbol} from "filename") when only importing specific symbols

Smart Contract Security

Best Practices

  1. Access Control:

    • Implement proper access control with modifiers
    • Use OpenZeppelin's Ownable or role-based access control when appropriate
    • Always check authorization before executing sensitive operations

  2. Reentrancy Protection:

    • Implement reentrancy guards for external calls
    • Follow the checks-effects-interactions pattern
    • Consider using OpenZeppelin's ReentrancyGuard

  3. Integer Arithmetic:

    • Use SafeMath or Solidity 0.8.x built-in overflow/underflow protection
    • Be aware of potential overflow/underflow in arithmetic operations
    • Consider using OpenZeppelin's SafeMath for Solidity < 0.8.0

  4. Gas Optimization:

    • Be mindful of gas costs in loops and data storage
    • Use memory instead of storage when appropriate
    • Prefer calldata for function parameters in external functions

  5. Avoid Common Vulnerabilities:

    • Protect against front-running and transaction ordering attacks
    • Be cautious with delegatecall and understand its security implications
    • Avoid timestamp manipulation vulnerabilities

  6. Error Handling:

    • Use custom errors (Solidity 0.8.4+) or revert with clear error messages
    • Fail early and loudly
    • Validate all inputs and preconditions

Contract Implementation

  1. Contract Upgradeability:

    • If using upgradeable contracts, follow a well-established pattern (e.g., proxy patterns)
    • Document upgradeability intentions and mechanisms
    • Consider using OpenZeppelin Upgrades library

  2. External Calls:

    • Always check return values from external calls
    • Implement proper error handling for external calls
    • Be aware of potential callback issues
    • Use try/catch for external calls in Solidity 0.6.0+

  3. Function Visibility:

    • Use the most restrictive visibility possible
    • Mark functions as external when they are only called from outside the contract
    • Mark functions as internal or private when they are only called from within the contract

Documentation

  1. Code Comments:

    • Use NatSpec format for function and contract documentation
    • Document all public and external functions
    • Example format: 
      /// @title A title that should describe the contract/interface
/// @author The name of the author
/// @notice Explain to an end user what this does
/// @dev Explain to a developer any extra details
contract MyContract {
    /// @notice Explain to an end user what this function does
    /// @dev Explain to a developer any extra details
    /// @param user The address of the user
    /// @return balances The token balance of the user
    function getBalance(address user) external view returns (uint256 balances) {
        // Implementation
    }
}

  2. Contract Documentation:

    • Document the purpose of each contract
    • Document inheritance relationships
    • Document the expected behavior and assumptions
    • Document any known limitations or risks

Testing

  1. Unit Testing:

    • Write comprehensive unit tests for all contract functionality
    • Use a framework such as Hardhat, Truffle, or Foundry
    • Test both success and failure scenarios
    • Ensure code coverage of at least 95%

  2. Integration Testing:

    • Test interactions between different contracts
    • Test the contract in realistic scenarios
    • Simulate real-world usage patterns

  3. Gas Optimization Testing:

    • Monitor gas usage for all functions
    • Establish gas usage baselines and track changes
    • Create gas usage reports for key functions

Deployment

  1. Deployment Process:

    • Document the deployment procedure for each contract
    • Create deployment scripts for reproducible deployments
    • Verify contract source code on block explorers

  2. Environment Management:

    • Maintain separate configurations for different environments (testnet, mainnet)
    • Use environment-specific addresses and parameters
    • Document the addresses of deployed contracts

Auditing and Review

  1. Code Review Process:

    • All code should undergo peer review before deployment
    • Use a consistent code review checklist
    • Consider formal verification for critical contracts

  2. External Audits:

    • Engage external auditors for critical contracts
    • Address all identified issues
    • Document the audit process and results

Versioning and Updates

  1. Version Management:

    • Use semantic versioning for contract releases
    • Document changes between versions
    • Maintain backward compatibility when possible

  2. Contract Updates:

    • Document the upgrade strategy (proxy pattern, new deployment, etc.)
    • Ensure proper testing of upgrade procedures
    • Have a roll-back plan for failed upgrades

Dependencies

  1. Library Usage:

    • Prefer established, audited libraries (e.g., OpenZeppelin)
    • Document all external dependencies
    • Specify exact versions for dependencies
    • Understand the code you're importing

  2. Version Pinning:

    • Pin compiler versions to specific releases
    • Specify exact versions for imported contracts
    • Update dependencies to fix known vulnerabilities

Development Environment

  1. Recommended Tools:

    • Development Framework: Hardhat, Foundry, or Truffle
    • Linting: Solhint or Ethlint
    • Testing: Mocha, Chai, Waffle
    • Static Analysis: Slither, MythX
    • Gas Analysis: Hardhat Gas Reporter

  2. Local Development:

    • Use a local blockchain (e.g., Hardhat Network, Ganache)
    • Set up a consistent development environment
    • Use automated deployment scripts

Blockchain-Specific Considerations

  1. Network Selection:

    • Consider gas costs, transaction speed, and security when selecting a blockchain
    • Document supported networks
    • Handle network-specific quirks and limitations

  2. Gas Optimization:

    • Optimize contracts for the target blockchain's gas model
    • Be aware of network-specific gas pricing mechanisms
    • Document expected gas costs for key operations

Continuous Integration

  1. Automated Testing:

    • Run tests on every commit
    • Run gas usage analysis on every commit
    • Run static analysis tools automatically

  2. Deployment Automation:

    • Automate deployments to test networks
    • Create verification scripts for deployed contracts

Emergency Response

  1. Emergency Plans:

    • Have a documented plan for responding to vulnerabilities
    • Implement circuit breakers or pause mechanisms for critical functions
    • Define roles and responsibilities during emergencies

  2. Monitoring:

    • Monitor contract activity for unusual patterns
    • Set up alerts for critical events
    • Regularly check contract balances and state