Solidity Coding

Solidity Coding Standards

Language Rule

• Always respond in the same language the user is using. If the user asks in Chinese, respond in Chinese. If in English, respond in English.

Coding Principles

• Pragma: Use pragma solidity ^0.8.19; — keep consistent across all files in the project
• Dependencies: OpenZeppelin Contracts 4.9.x, manage imports via remappings.txt
• Error Handling: Prefer custom errors over require strings — saves gas and is more expressive
• Define: error InsufficientBalance(uint256 available, uint256 required);
• Use: if (balance .sol, separate from implementation |

| Simple on-chain queries | Use Foundry cast CLI (call / send) | | Complex multi-step operations | Use Foundry script (*.s.sol) | | Import style | Use named imports: import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol"; |

Project Directory Structure

src/              — Contract source code
  interfaces/     — Interface definitions (I*.sol)
  common/         — Shared constants, types, errors (Const.sol, Types.sol)
test/             — Test files (*.t.sol)
script/           — Deployment & interaction scripts (*.s.sol)
config/           — Network config, parameters (*.json)
deployments/      — Deployment records (latest.env)
docs/             — Documentation, changelogs
lib/              — Dependencies (managed by Foundry)

Configuration Management

• config/*.json — network RPC URLs, contract addresses, business parameters
• deployments/latest.env — latest deployed contract addresses, must update after each deployment
• foundry.toml — compiler version, optimizer settings, remappings
• Important config changes must be documented in the PR description

OpenZeppelin Library Selection Standards

When writing Solidity contracts, prioritize using battle-tested OpenZeppelin libraries over custom implementations. Select the appropriate library based on the scenario:

Access Control

| Scenario | Library | Import Path | |----------|---------|-------------| | Single owner management | Ownable | @openzeppelin/contracts/access/Ownable.sol | | Owner transfer needs safety | Ownable2Step | @openzeppelin/contracts/access/Ownable2Step.sol | | Multi-role permission (admin/operator/minter) | AccessControl | @openzeppelin/contracts/access/AccessControl.sol | | Need to enumerate role members | AccessControlEnumerable | @openzeppelin/contracts/access/AccessControlEnumerable.sol | | Governance with timelock delay | TimelockController | @openzeppelin/contracts/governance/TimelockController.sol |

Rule: Single owner → Ownable2Step; 2+ roles → AccessControl; governance/DAO → TimelockController

Security Protection

| Scenario | Library | Usage | |----------|---------|-------| | External call / token transfer | ReentrancyGuard | Add nonReentrant modifier | | Emergency pause needed | Pausable | Add whenNotPaused to user-facing functions; keep admin functions unpaused | | ERC20 token interaction | SafeERC20 | Use safeTransfer / safeTransferFrom / safeApprove instead of raw calls |

Rule: Any contract that transfers tokens or ETH MUST use ReentrancyGuard + SafeERC20

Token Standards

| Scenario | Library | Notes | |----------|---------|-------| | Fungible token | ERC20 | Base standard | | Token with burn mechanism | ERC20Burnable | Adds burn() and burnFrom() | | Token with max supply cap | ERC20Capped | Enforces `totalSupply = 0.8.0 — overflow checks are built-in

• Do NOT use require(token.transfer(...)) — use token.safeTransfer(...) via SafeERC20
• Do NOT use tx.origin for auth — use msg.sender with Ownable / AccessControl

MCP-Assisted Contract Generation (if available)

When OpenZeppelinContracts MCP is configured, prefer using it to generate base contracts instead of writing from scratch:

| Contract Type | MCP Tool | When to Use | |---|---|---| | Fungible token | solidity-erc20 | Any new ERC20 token contract | | NFT | solidity-erc721 | Any new NFT contract | | Multi-token | solidity-erc1155 | Game items, batch operations | | Stablecoin | solidity-stablecoin | Stablecoin with ERC20 compliance | | Real-world assets | solidity-rwa | Asset tokenization | | Smart account | solidity-account | ERC-4337 account abstraction | | Governance | solidity-governor | DAO voting and proposals | | Custom | solidity-custom | Non-standard contracts with OZ patterns |

Workflow: MCP generates base → apply this skill's naming/structure rules → customize business logic → apply /solidity-security rules

Why MCP over manual: MCP output is validated against the same rule-set as OZ Contracts Wizard — imports, modifiers, security checks are guaranteed correct. Manual coding risks missing imports or using wrong OZ versions.

When NOT to use MCP: Heavily custom contracts with non-standard patterns, contracts that don't fit any OZ template, or when you need fine-grained control from line 1.

Graceful degradation: If MCP is not configured, fall back to the Library Selection Standards above and write contracts manually following all rules in this skill.

Foundry Quick Reference

| Operation | Command | |-----------|---------| | Create new project | forge init | | Install dependency | forge install openzeppelin-contracts | | Build contracts | forge build | | Format code | forge fmt | | Update remappings | forge remappings |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ComeOnOliver
• Source: ComeOnOliver/skillshub
• License: MIT
• Homepage: https://skillshub.wtf

Install and usage instructions live in the source repository linked above.