solidity-checklist

Solidity Checklist

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.

Why This Skill Exists

Most on-chain operation failures come from skipping systematic verification. Instead of the reactive loop:

deploy -> fail -> paste error -> ask AI -> retry -> fail again -> ask again

This skill enforces a proactive verification flow:

check permissions -> check dependencies -> check params -> check security -> test locally -> execute -> capture knowledge

The 6-Layer Preflight Flow

Every on-chain operation MUST pass through these 6 layers in order before execution.

Layer 1: PERMISSIONS  — Do I have the right to do this?
Layer 2: DEPENDENCIES — Do I understand what this affects?
Layer 3: PARAMETERS   — Are my inputs correct?
Layer 4: SECURITY     — Is this safe to execute?
Layer 5: TESTING      — Have I verified locally first?
Layer 6: EXECUTE & CAPTURE — Do it, then record what I learned.

Layer 1: Permissions Check

Before any on-chain call, verify the caller has the required access.

Check	Command	Pass Condition
Contract owner	`cast call <CONTRACT> "owner()" --rpc-url <RPC>`	Returns expected deployer/admin address
Role-based access	`cast call <CONTRACT> "hasRole(bytes32,address)" <ROLE_HASH> <CALLER> --rpc-url <RPC>`	Returns `true`
Whitelist status	`cast call <CONTRACT> "isWhitelisted(address)" <CALLER> --rpc-url <RPC>`	Returns `true` (if applicable)
Token allowance	`cast call <TOKEN> "allowance(address,address)" <OWNER> <SPENDER> --rpc-url <RPC>`	Returns >= required amount
Paused state	`cast call <CONTRACT> "paused()" --rpc-url <RPC>`	Returns `false`

Decision Rule

Result	Action
All checks pass	Proceed to Layer 2
Missing permission	Fix permission first (grant role / approve / unpause), then re-check
Unsure which permissions are needed	Read contract source — find all `onlyOwner`, `onlyRole`, `require` in target function

Layer 2: Dependency Check

Understand the blast radius — what contracts and state does this operation touch?

Check	How
Direct dependencies	Read target function source — list all external calls (`IERC20(token).transfer(...)`, etc.)
Upstream contracts	Which contracts hold a reference to this contract's address?
Downstream effects	Will this state change trigger callbacks, events, or off-chain indexers?
Initialization state	`cast call <CONTRACT> "initialized()" --rpc-url <RPC>` — is the contract fully set up?
Linked addresses	Verify all addresses stored in contract state are correct and not zero

Dependency Map Template

Before operating on a multi-contract system, build a mental (or written) map:

ContractA (owner: deployer)
  ├── references: TokenB (ERC20), RouterC
  ├── authorized callers: deployer, ContractD
  └── state deps: must be initialized, TokenB must be approved

ContractD (owner: deployer)
  ├── references: ContractA, OracleE
  └── state deps: OracleE must have price feed set

Decision Rule

Result	Action
Dependencies clear	Proceed to Layer 3
Unknown dependency	Read contract source or ask — do NOT proceed blindly
Redeployment needed	Trace the full dependency graph to identify ALL contracts needing address updates

Layer 3: Parameter Validation

Verify every input before sending.

Check	Common Pitfall
Address format	Wrong network address, zero address, checksum mismatch
Token decimals	Using 18 decimals for a 6-decimal token (USDC/USDT)
Amount precision	`1e18` vs `1e6` — off by 12 orders of magnitude
Function selector	Calling wrong function or wrong overload
Enum values	Passing invalid enum index
Array length	Mismatched array lengths in batch operations
Deadline/timestamp	Expired deadline, wrong timezone, block.timestamp vs unix

Validation Commands

# Check token decimals before calculating amounts
cast call <TOKEN> "decimals()" --rpc-url <RPC>

# Verify address is a contract (not EOA)
cast code <ADDRESS> --rpc-url <RPC>
# Empty (0x) = EOA, non-empty = contract

# Decode your own calldata to double-check
cast calldata-decode "functionName(type1,type2)" <CALLDATA>

# Estimate gas before sending (catches obvious reverts)
cast estimate <CONTRACT> "functionName(args)" --from <CALLER> --rpc-url <RPC>

Decision Rule

Result	Action
All params verified	Proceed to Layer 4
Decimal mismatch found	Recalculate with correct decimals
Address is EOA, expected contract	Wrong address — verify deployment

Layer 4: Security Quick Check

Scan for common security risks before execution.

Risk	Check	Red Flag
Reentrancy	Does the function make external calls before updating state?	External call before state update
Front-running	Is this a price-sensitive operation (swap, liquidation)?	No slippage protection or deadline
Access control	Does the function restrict callers appropriately?	Missing `onlyOwner` / `onlyRole` on sensitive function
Value handling	Does the function handle msg.value correctly?	Accepts ETH but doesn't use it, or vice versa
Approval amount	Am I approving more than necessary?	`approve(spender, type(uint256).max)` on unknown contract
Private key exposure	Did the developer choose keystore or a gitignored `.env`?	Literal private key in a command, script, log, or committed file

Private Key Rule (MANDATORY)

# NEVER put a literal private key in the command
cast send ... --private-key 0xdead...

# Option A: Foundry Keystore (recommended)
cast send ... --account <KEYSTORE_NAME>

# Set up keystore if not done
cast wallet import <NAME> --interactive

# Option B: load PRIVATE_KEY from a gitignored .env
source .env
cast send ... --private-key "$PRIVATE_KEY"

Let the developer choose Option A or Option B before execution. Never read, print, or commit .env.

Decision Rule

Result	Action
No red flags	Proceed to Layer 5
Reentrancy risk found	Add ReentrancyGuard or fix CEI pattern before proceeding
Front-running risk	Add slippage/deadline params
Private key exposed	STOP — rotate the key, then use keystore or a gitignored `.env`

Layer 5: Local Testing

Never send a transaction that hasn't been verified locally or on a fork.

Method	Command	When to Use
Unit test	`forge test --match-test <testName> -vvvv`	New/modified contract functions
Fork test	`forge test --fork-url <RPC> --match-test <testName> -vvvv`	Testing against live state
Dry-run script	`forge script <Script> --rpc-url <RPC> -vvvv` (no `--broadcast`)	Deployment or complex operations
Gas estimation	`cast estimate <CONTRACT> "func(args)" --from <CALLER> --rpc-url <RPC>`	Before any cast send
Simulation	`cast call <CONTRACT> "func(args)" --from <CALLER> --rpc-url <RPC>`	Quick function call test

Testing Decision Tree

Is this a new or modified contract?
├── YES → Write forge test → Run test → Pass? → Proceed
│                                      → Fail? → Fix and re-test
└── NO (calling existing deployed contract)
    ├── Simple read? → cast call (Layer 3 already covers this)
    └── State-changing? → cast estimate first
        ├── Estimate succeeds → Proceed to Layer 6
        └── Estimate reverts → Debug with cast call + revert reason → Fix → Re-estimate

Decision Rule

Result	Action
Test passes / estimate succeeds	Proceed to Layer 6
Test fails	Fix the issue — do NOT deploy broken code
Estimate reverts	Likely a Layer 1 (permissions) or Layer 3 (params) issue — go back

Layer 6: Execute & Capture

Execute the operation, verify success, and capture knowledge.

Execute

# Option A: send transaction using Foundry Keystore (recommended)
cast send <CONTRACT> "functionName(type1,type2)" <arg1> <arg2> \
  --account <KEYSTORE_NAME> \
  --rpc-url <RPC>

# Option A: deploy using Foundry Keystore
forge script <Script> \
  --rpc-url <RPC> \
  --account <KEYSTORE_NAME> \
  --broadcast \
  --gas-limit <LIMIT> \
  -vvvv

# Option B: load PRIVATE_KEY from a gitignored .env, then send or deploy
source .env
cast send <CONTRACT> "functionName(type1,type2)" <arg1> <arg2> \
  --private-key "$PRIVATE_KEY" \
  --rpc-url <RPC>

forge script <Script> \
  --rpc-url <RPC> \
  --private-key "$PRIVATE_KEY" \
  --broadcast \
  --gas-limit <LIMIT> \
  -vvvv

Post-Execution Verification (MANDATORY)

Check	Command
TX status	Check `status` field in receipt: 1 = success, 0 = fail
State change	`cast call` to verify the expected state change happened
Events emitted	Check `logs` in receipt for expected events
Balance change	`cast balance` or `cast call balanceOf` to verify token movements

Knowledge Capture

After every successful (or failed) operation, capture what you learned:

What to Record	Where
Successful command with parameters	Personal command handbook (`.md` file)
New error encountered + solution	Debug notes
Contract address and its role	Project architecture doc
Permission/role requirements discovered	Contract dependency map
Gas cost of common operations	Gas reference table

Anti-Pattern: One-Time Consumption

The biggest leverage: turn every AI interaction into your own knowledge, not a one-time consumption.

If you asked AI for a command and it worked:

Understand WHY each parameter is what it is
Record it in your own words
Next time, write it yourself first — then verify with AI

Quick Reference: Preflight by Operation Type

Operation	Critical Layers	Most Common Failure
`approve`	L1 (owner), L3 (amount/decimals)	Wrong decimals
`transfer`	L1 (balance), L3 (amount/decimals)	Insufficient balance
`addLiquidity`	L1 (approve both tokens), L3 (amounts/ratio), L5 (estimate)	Missing approval
`removeLiquidity`	L1 (LP approve), L3 (minAmounts), L4 (slippage)	Slippage too tight
`stake`	L1 (approve + whitelist), L2 (staking contract state), L3 (amount)	Staking not active / not whitelisted
`unstake`	L1 (staker status), L2 (lock period), L3 (amount)	Lock period not expired
`deploy`	L3 (constructor args), L4 (full security check), L5 (fork test mandatory)	Constructor arg mismatch
`upgrade`	L1 (proxy admin), L2 (storage layout), L4 (storage collision), L5 (fork test mandatory)	Storage layout incompatible

Preflight Summary Card

Print this mental checklist before EVERY on-chain operation:

[ ] L1 PERMISSIONS  — Can I call this? (owner/role/approve/whitelist/paused)
[ ] L2 DEPENDENCIES — What does this touch? (contracts/state/events)
[ ] L3 PARAMETERS   — Are inputs correct? (address/decimals/amount/selector)
[ ] L4 SECURITY     — Is this safe? (reentrancy/frontrun/key exposure)
[ ] L5 TESTING      — Did I test locally? (forge test/estimate/dry-run)
[ ] L6 EXECUTE      — Send it, verify it, record what I learned.

6 layers, 2 minutes. Saves hours of debugging and wasted gas.

About this skill

Language Rule

Why This Skill Exists

The 6-Layer Preflight Flow

Layer 1: Permissions Check

Decision Rule

Layer 2: Dependency Check

Dependency Map Template

Decision Rule

Layer 3: Parameter Validation

Validation Commands

Decision Rule

Layer 4: Security Quick Check

Private Key Rule (MANDATORY)

Decision Rule

Layer 5: Local Testing

Testing Decision Tree

Decision Rule

Layer 6: Execute & Capture

Execute

Post-Execution Verification (MANDATORY)

Knowledge Capture

Anti-Pattern: One-Time Consumption

Quick Reference: Preflight by Operation Type

Preflight Summary Card