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

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