agentleFS
SperaxSperax/sperax-skills/skills/smart-contract-reading-guide/SKILL.md

smart-contract-reading-guide

Skill8 starsChanged 9 months agoMITView on GitHub

How to read and understand smart contracts — navigating Etherscan, reading Solidity code, understanding ABIs, decoding transactions, and spotting common patterns. Use when helping users verify contracts, understand DeFi protocol mechanics, or decode on-chain activity.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Look for the green checkmark ("Contract Source Code Verified")

    line 27
  2. Distinctive:

    If not verified → RED FLAG — don't interact with unverified contracts

    line 28
  3. Distinctive:

    Every transaction emits events (in the "Logs" tab):

    line 151
  4. Distinctive:

    On Etherscan: Look for "Read as Proxy" / "Write as Proxy" tabs.

    line 231

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Smart Contract Reading Guide

You don't need to be a Solidity developer to read smart contracts. This guide teaches you to understand what contracts do by reading their code on block explorers.

Finding Contract Code

Block Explorers

ChainExplorerURL
EthereumEtherscanetherscan.io
ArbitrumArbiscanarbiscan.io
BaseBaseScanbasescan.org
OptimismOptimistic Etherscanoptimistic.etherscan.io
PolygonPolygonScanpolygonscan.com

Steps to Read a Contract

  1. Go to the explorer → Enter contract address
  2. Click "Contract" tab
  3. Look for the green checkmark ("Contract Source Code Verified")
  4. If not verified → RED FLAG — don't interact with unverified contracts

Understanding Contract Structure

Solidity 101 for Readers

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

// Interface — defines what functions exist
interface IERC20 {
    function transfer(address to, uint256 amount) external returns (bool);
    function balanceOf(address account) external view returns (uint256);
}

// Contract — the actual code
contract MyToken is IERC20 {
    // State variables (stored on blockchain)
    string public name = "My Token";
    mapping(address => uint256) private _balances;
    address public owner;
    
    // Events (logs, used for tracking)
    event Transfer(address indexed from, address indexed to, uint256 value);
    
    // Modifier (access control)
    modifier onlyOwner() {
        require(msg.sender == owner, "Not owner");
        _;
    }
    
    // View function (read-only, free to call)
    function balanceOf(address account) external view returns (uint256) {
        return _balances[account];
    }
    
    // State-changing function (costs gas)
    function transfer(address to, uint256 amount) external returns (bool) {
        _balances[msg.sender] -= amount;
        _balances[to] += amount;
        emit Transfer(msg.sender, to, amount);
        return true;
    }
    
    // Owner-only function (⚠️ check these carefully)
    function mint(address to, uint256 amount) external onlyOwner {
        _balances[to] += amount;
    }
}

Key Solidity Concepts

ConceptMeaningWhy It Matters
publicAnyone can call/readNormal, expected
externalOnly callable from outsideNormal for functions
view / pureRead-only (free to call)Safe — no state changes
onlyOwnerOnly the owner can callCheck what owner can do
payableCan receive ETHMay collect fees
mappingKey-value storageStores balances, approvals
requireValidation checkIf false, transaction reverts
emitLogs an eventUsed for tracking

Reading on Etherscan

"Read Contract" Tab

Free queries — anyone can call these:

FunctionWhat It Returns
name()Token name
symbol()Token symbol (e.g., "USDC")
decimals()Decimal places (6 for USDC, 18 for most tokens)
totalSupply()Total tokens in existence
balanceOf(address)How many tokens an address holds
owner()Who controls the contract
paused()Whether the contract is paused

"Write Contract" Tab

Requires wallet connection and gas:

FunctionWhat It DoesRisk Level
transfer()Send tokensNormal
approve()Grant spending permissionMedium (check amount)
stake()Lock tokens for rewardsNormal
mint()Create new tokensCheck who can call

Decoding Transactions

Transaction Overview

On any transaction page:

FieldWhat It Shows
StatusSuccess or Failed
FromSender address
ToContract called
ValueETH sent
Input DataFunction call + parameters
Gas UsedActual gas consumed

Reading Input Data

Raw input data looks like:

0xa9059cbb000000000000000000000000abcdef...00000000000000000000000000000000000000000000000000000002540be400

Decoded (Etherscan does this automatically for verified contracts):

Function: transfer(address, uint256)
  to: 0xabcdef...
  amount: 10000000000 (10,000 USDC with 6 decimals)

Event Logs

Every transaction emits events (in the "Logs" tab):

Transfer(
  from: 0x1234...,
  to: 0x5678...,
  value: 1000000000000000000  (1 ETH in wei)
)

Common DeFi Contract Patterns

ERC-20 Token

FunctionWhat to Check
mint()Who can call? If unrestricted → inflation risk
burn()Deflationary mechanism
pause()Can transfers be frozen?
blacklist()Can addresses be blocked?
setFee()Can transfer tax be changed?

Lending Protocol (Aave-style)

FunctionWhat It Does
supply()Deposit collateral
borrow()Take a loan
repay()Pay back loan
liquidationCall()Liquidate unhealthy position
getReserveData()Read pool stats (APY, utilization)

DEX (Uniswap-style)

FunctionWhat It Does
swap()Execute a token swap
mint() / addLiquidity()Provide liquidity
burn() / removeLiquidity()Remove liquidity
getReserves()Current pool balances (determines price)

Stablecoin (like USDs)

FunctionWhat to Check
mint()How is new supply created? What collateral is accepted?
redeem()Can you always redeem for underlying?
rebase()How yield is distributed (USDs auto-rebases)
collateralRatio()Is it fully backed?

ABI (Application Binary Interface)

The ABI defines how to interact with a contract programmatically:

[
  {
    "name": "balanceOf",
    "type": "function",
    "inputs": [{ "name": "account", "type": "address" }],
    "outputs": [{ "name": "", "type": "uint256" }],
    "stateMutability": "view"
  }
]

Where to get ABIs:

  1. Etherscan → Contract tab → "Contract ABI" section
  2. Protocol documentation
  3. GitHub repositories

Proxy Contracts

Many DeFi protocols use proxies (upgradeable contracts):

User → Proxy Contract → Implementation Contract
       (fixed address)   (logic, can be upgraded)

On Etherscan: Look for "Read as Proxy" / "Write as Proxy" tabs. If you see a proxy, click through to read the implementation contract.

Security Checklist for Contract Review

CheckHowRisk If Failed
✅ Contract verifiedGreen checkmark on explorerCan't see what code does
✅ Check owner functionsSearch for onlyOwner, onlyAdminOwner could rug
✅ Check mint capabilitySearch for mint functionInfinite inflation
✅ Check pause/blacklistSearch for pause, blacklistFunds could be frozen
✅ Check fee functionsSearch for fee, taxFees could be raised to 100%
✅ Audit reportCheck project websiteUnaudited = higher risk
✅ Timelock on upgradesCheck if proxy has a timelockInstant upgrade = rug risk

Agent Tips

  1. Verified contract is non-negotiable — never recommend interacting with unverified contracts
  2. "Read as Proxy" — always check for proxy implementation for the real logic
  3. Owner functions are key — what the owner can do defines the trust assumptions
  4. View functions are free — encourage users to read contract state before transacting
  5. Etherscan does the heavy lifting — auto-decodes transactions, ABI, and events
  6. Sperax contracts are verified — USDs, SPA, and Farms contracts on Arbiscan are fully verified and audited

Links

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.