Solidity

What this skill does

<!-- SOLIDITY:START -->
# Solidity Project Rules

## Agent Automation Commands

**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).

```bash
# Complete quality check sequence (Hardhat):
npx hardhat compile       # Compilation check
npx hardhat test          # All tests (100% pass)
npx hardhat coverage      # Coverage check
npx slither .             # Security analysis

# Or with Foundry:
forge build               # Compilation
forge test                # All tests
forge coverage            # Coverage
slither .                 # Security scan

# Gas optimization check:
npx hardhat test --gas
```

## Solidity Configuration

**CRITICAL**: Use Solidity 0.8.20+ with strict compiler settings and comprehensive testing.

- **Version**: Solidity 0.8.20+
- **Recommended**: Solidity 0.8.26+
- **Framework**: Hardhat or Foundry
- **Testing**: Hardhat tests or Foundry tests
- **Linter**: Solhint
- **Formatter**: Prettier with prettier-plugin-solidity
- **Security**: Slither, Mythril for static analysis

### hardhat.config.js Requirements

```javascript
require("@nomicfoundation/hardhat-toolbox");
require("hardhat-gas-reporter");
require("solidity-coverage");

module.exports = {
  solidity: {
    version: "0.8.26",
    settings: {
      optimizer: {
        enabled: true,
        runs: 200
      },
      viaIR: true,
      outputSelection: {
        "*": {
          "*": ["storageLayout"]
        }
      }
    }
  },
  networks: {
    hardhat: {
      chainId: 31337
    },
    localhost: {
      url: "http://127.0.0.1:8545"
    }
  },
  gasReporter: {
    enabled: true,
    currency: "USD",
    outputFile: "gas-report.txt"
  },
  paths: {
    sources: "./contracts",
    tests: "./test",
    cache: "./cache",
    artifacts: "./artifacts"
  }
};
```

### foundry.toml Requirements (Alternative)

```toml
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc = "0.8.26"
optimizer = true
optimizer_runs = 200
via_ir = true
verbosity = 3

[profile.ci]
fuzz = { runs = 10000 }
invariant = { runs = 1000 }

[fmt]
line_length = 100
tab_width = 4
bracket_spacing = true
int_types = "long"
quote_style = "double"
number_underscore = "thousands"
```

## Code Quality Standards

### Mandatory Quality Checks

**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.

**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!

```bash
# Pre-Commit Checklist - Hardhat (MUST match .github/workflows/*.yml)

# 1. Format check (matches workflow)
npx prettier --check 'contracts/**/*.sol' 'test/**/*.js'

# 2. Lint (MUST pass with no warnings - matches workflow)
npx solhint 'contracts/**/*.sol'

# 3. Compile (matches workflow)
npx hardhat compile

# 4. Run all tests (MUST pass 100% - matches workflow)
npx hardhat test

# 5. Gas report (matches workflow)
REPORT_GAS=true npx hardhat test

# 6. Coverage (MUST meet threshold - matches workflow)
npx hardhat coverage

# 7. Security analysis (matches workflow)
slither .
# or: mythril analyze contracts/MyContract.sol

# Pre-Commit Checklist - Foundry (MUST match .github/workflows/*.yml)

# 1. Format check (matches workflow)
forge fmt --check

# 2. Build (matches workflow)
forge build

# 3. Run all tests (MUST pass 100% - matches workflow)
forge test -vvv

# 4. Coverage (matches workflow)
forge coverage

# 5. Gas snapshot (matches workflow)
forge snapshot --check

# 6. Security analysis (matches workflow)
slither .

# If ANY fails: ❌ DO NOT COMMIT - Fix first!
```

**If ANY of these fail, you MUST fix the issues before committing.**

**Why This Matters:**
- Running different commands locally than in CI causes deployment failures
- Smart contract bugs can lead to financial losses
- Example: Using `prettier --write` locally but `prettier --check` in CI = failure
- Example: Skipping security analysis locally = vulnerabilities deployed to mainnet
- Example: Missing gas optimization = expensive contract operations

### Security Best Practices

**CRITICAL**: Smart contracts handle real value - security is paramount!

```solidity
// ✅ GOOD: Secure patterns
pragma solidity 0.8.26;

import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract SecureVault is ReentrancyGuard, Ownable {
    mapping(address => uint256) private balances;
    
    event Deposit(address indexed user, uint256 amount);
    event Withdrawal(address indexed user, uint256 amount);
    
    // Checks-Effects-Interactions pattern
    function withdraw(uint256 amount) external nonReentrant {
        // Checks
        require(amount > 0, "Amount must be positive");
        require(balances[msg.sender] >= amount, "Insufficient balance");
        
        // Effects
        balances[msg.sender] -= amount;
        emit Withdrawal(msg.sender, amount);
        
        // Interactions
        (bool success, ) = msg.sender.call{value: amount}("");
        require(success, "Transfer failed");
    }
    
    function deposit() external payable {
        require(msg.value > 0, "Must deposit positive amount");
        balances[msg.sender] += msg.value;
        emit Deposit(msg.sender, msg.value);
    }
    
    function getBalance(address user) external view returns (uint256) {
        return balances[user];
    }
}

// ❌ BAD: Vulnerable to reentrancy
contract InsecureVault {
    mapping(address => uint256) public balances;
    
    function withdraw(uint256 amount) external {
        require(balances[msg.sender] >= amount);
        
        // DANGER: External call before state update!
        (bool success, ) = msg.sender.call{value: amount}("");
        require(success);
        
        balances[msg.sender] -= amount;  // TOO LATE - already reentered!
    }
}
```

### Testing

- **Framework**: Hardhat (Mocha/Chai) or Foundry (Forge)
- **Location**: `/test` directory
- **Coverage**: Must meet threshold (90%+)
- **Invariant Testing**: Use property-based testing
- **Fork Testing**: Test against mainnet forks

Example Hardhat test:
```javascript
const { expect } = require("chai");
const { ethers } = require("hardhat");

describe("SecureVault", function () {
  let vault;
  let owner;
  let addr1;
  let addr2;
  
  beforeEach(async function () {
    [owner, addr1, addr2] = await ethers.getSigners();
    
    const Vault = await ethers.getContractFactory("SecureVault");
    vault = await Vault.deploy();
    await vault.deployed();
  });
  
  describe("Deployment", function () {
    it("Should set the right owner", async function () {
      expect(await vault.owner()).to.equal(owner.address);
    });
  });
  
  describe("Deposits", function () {
    it("Should accept deposits", async function () {
      const depositAmount = ethers.utils.parseEther("1.0");
      
      await expect(vault.connect(addr1).deposit({ value: depositAmount }))
        .to.emit(vault, "Deposit")
        .withArgs(addr1.address, depositAmount);
      
      expect(await vault.getBalance(addr1.address)).to.equal(depositAmount);
    });
    
    it("Should reject zero deposits", async function () {
      await expect(
        vault.connect(addr1).deposit({ value: 0 })
      ).to.be.revertedWith("Must deposit positive amount");
    });
  });
  
  describe("Withdrawals", function () {
    beforeEach(async function () {
      await vault.connect(addr1).deposit({ value: ethers.utils.parseEther("2.0") });
    });
    
    it("Should allow withdrawals", async function () {
      const withdrawAmount = ethers.utils.parseEther("1.0");
      
      await expect(vault.connect(addr1).withdraw(withdrawAmount))
        .to.emit(vault, "Withdrawal")
        .withArgs(addr1.address, withdrawAmount);
      
      expect(await vault.getBalance(addr1.address))
        .to.equal(ethers.utils.parseEther("1.0"));
    });
    
    it("Should prevent withdrawal of more than balance", async function () {
      await expect(
        vault.connect(addr1).withdraw(e