algo-blockchain-smart-contract

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:

1. Define state variables (stored on-chain, costs gas)
2. Define functions: external (callable by users), internal (helper logic)
3. Implement access control (onlyOwner, role-based, multisig)
4. 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