| name | "algo-blockchain-smart-contract" |
| description | "Design and implement smart contracts as self-executing programmatic agreements on blockchain. Use this skill when the user needs to build automated on-chain logic, evaluate smart contract security, or design tokenized business rules — even if they say 'smart contract development', 'automated agreement', or 'on-chain logic'.". |
| allowed-tools | Read, Glob, Grep |
Smart Contracts
Overview
Smart contracts are self-executing programs stored on a blockchain that automatically enforce agreement terms when conditions are met. Primarily written in Solidity (Ethereum/EVM) or Rust (Solana). Once deployed, code is immutable — bugs cannot be patched without migration. Security is critical as exploits are irreversible.
When to Use
Trigger conditions:
- Automating multi-party agreements that execute without intermediaries
- Building token-based systems (NFTs, DeFi, governance)
- Creating transparent, auditable business logic on-chain
When NOT to use:
- For simple CRUD operations (use a database)
- When business logic changes frequently (immutability makes updates costly)
- When off-chain data is the primary input (oracle dependency is risky)
Algorithm
IRON LAW: Deployed Smart Contracts Are IMMUTABLE — Bugs Are Permanent
Once deployed, contract code cannot be changed. A bug that loses funds
is IRREVERSIBLE. There is no "hotfix" or "rollback" (unless the
contract includes an upgrade proxy pattern). Security audit BEFORE
deployment is not optional — it is the only protection.
Phase 1: Input Validation
Define: contract purpose, participants, conditions, state variables, access controls. Determine: which logic MUST be on-chain vs which can be off-chain.
Gate: Business logic specified, on-chain necessity justified.
Phase 2: Core Algorithm
Design:
- Define state variables (stored on-chain, costs gas)
- Define functions: external (callable by users), internal (helper logic)
- Implement access control (onlyOwner, role-based, multisig)
- Handle edge cases: reentrancy guards, integer overflow checks, gas limits
Security patterns:
- Checks-Effects-Interactions (prevent reentrancy)
- Pull over push (for payments)
- Minimal on-chain data (store hashes, not full data)
- Upgradeable proxy pattern (if mutability needed)
Phase 3: Verification
Test: unit tests covering all paths, edge cases, access control violations. Security audit: automated (Slither, Mythril) + manual review. Deploy to testnet first.
Gate: All tests pass, automated security scan clean, testnet deployment successful.
Phase 4: Output
Return contract design with security analysis.
Output Format
{
"contract": {"name": "Escrow", "functions": 5, "state_variables": 4, "access_roles": ["buyer", "seller", "arbiter"]},
"security": {"audit_status": "passed", "patterns_used": ["checks_effects_interactions", "pull_payment"], "known_risks": ["oracle_dependency"]},
"metadata": {"platform": "ethereum", "language": "solidity", "estimated_gas": 250000}
}
Examples
Sample I/O
Input: Escrow contract: buyer deposits, seller delivers, arbiter resolves disputes
Expected: Contract with: deposit(), confirmDelivery(), dispute(), withdraw() functions. Funds held until conditions met.
Edge Cases
| Input | Expected | Why |
|---|
| Gas price spike | Transaction may fail or cost more | Always set gas limits and handle failures |
| Reentrant call | Must be blocked | Reentrancy is the #1 smart contract vulnerability |
| Contract upgrade needed | Use proxy pattern or migrate | Immutability by default |
Gotchas
- Reentrancy attacks: The DAO hack ($60M) exploited reentrancy. Always use the Checks-Effects-Interactions pattern and/or ReentrancyGuard.
- Integer overflow/underflow: Solidity 0.8+ has built-in overflow checks. Earlier versions require SafeMath library. Never assume arithmetic is safe.
- Front-running: Miners/validators can see pending transactions and insert their own first (MEV). Sensitive operations need commit-reveal schemes.
- Gas optimization: Every operation costs gas. Minimize storage writes (most expensive), use events for data that doesn't need on-chain querying, pack variables.
- Upgradeability vs immutability: Proxy patterns allow upgrades but add complexity and trust assumptions (who can upgrade?). Choose based on trust model.
- Oracle dependency: Smart contracts can't access off-chain data directly. Oracles (Chainlink, etc.) introduce trust assumptions. A compromised oracle compromises the contract.
References
- For common vulnerability patterns, see
references/vulnerability-patterns.md
- For gas optimization techniques, see
references/gas-optimization.md
