Building Your First Solidity Contract: Storage Layout, Gas Traps, and the Decisions That Compound

Most "first contract" guides start with pragma and end with Remix's deploy button. The result: developers internalize a workflow where storage layout is an afterthought and gas behavior is a surprise. The compounding mistake is that storage slot ordering is the single largest gas lever in a basic contract, and it's decided the moment you declare your state variables.

Solidity packs state variables into 32-byte storage slots sequentially. Two adjacent uint128 variables share one slot; a uint128 followed by a uint256 followed by another uint128 wastes a full slot because the uint256 forces a new slot boundary and the second uint128 occupies a third. Reordering those three declarations from uint128, uint128, uint256 saves one SSTORE cold-slot allocation — 20,000 gas on first write. In a contract with dozens of state variables, sloppy ordering can cost deployers and users tens of thousands of gas per transaction, permanently.

The takeaway: sketch your state variable types, sort them by size descending within each 32-byte boundary, then write the rest of the contract. This is the correct first step, not pragma selection.

Pin the compiler version with an exact pragma (e.g., pragma solidity 0.8.26) rather than a caret range. Caret ranges introduce nondeterminism in bytecode verification — if Etherscan's compiler auto-selection picks a different patch version than your local build, verification fails silently or produces a mismatch. The SPDX license identifier (MIT, GPL-3.0, UNLICENSED) is enforced at the metadata level and emitted into the contract's CBOR-encoded tail bytes. Omitting it triggers a compiler warning and makes Etherscan verification noisier.

• Exact pragma eliminates bytecode drift across environments, which matters the moment you add CI or a second developer
• The compiler's default optimization run count is 200; changing it alters deployed bytecode and must match during verification
• Metadata hash (the last ~43 bytes of deployed bytecode) includes source paths — building from different directories produces different bytecode unless you strip or standardize metadata

Visibility modifiers on state variables control getter generation and access scope, but the gas implications are asymmetric and under-documented.

• Declaring a variable as public auto-generates an external getter. This getter costs ~2,100 gas for a cold SLOAD, same as any manual getter you'd write — there is no overhead from the auto-generation itself
• internal (the default) exposes the variable to derived contracts via direct storage access. No getter is generated; reading from an inheriting contract compiles to an SLOAD, not a CALL
• private variables are still readable by anyone inspecting storage slots directly (eth_getStorageAt). The modifier prevents Solidity-level access from derived contracts; it provides zero on-chain confidentiality
• Constant and immutable variables do not occupy storage slots. Constants are inlined at compile time into the bytecode. Immutables are written into the deployed bytecode during constructor execution, which means they cost zero SLOAD at runtime — a meaningful gas saving for values set once

Function bodies should follow the checks-effects-interactions (CEI) pattern not because it's convention but because any deviation creates a reentrancy surface.

The Mechanics

A require statement at the top (checks) reverts cheaply before state mutation. State variable writes (effects) happen next, updating balances or flags before any external call. External calls (interactions) go last. If an external call re-enters the function, the state already reflects the updated values, so the reentrant call's require checks against post-mutation state.

Violating CEI — e.g., sending ETH before decrementing a balance mapping — is the exact pattern exploited in the 2016 DAO hack and hundreds of subsequent exploits. Solidity 0.8.x's built-in overflow checks do not protect against reentrancy; they are orthogonal concerns.

• A nonReentrant modifier (as in OpenZeppelin's ReentrancyGuard) uses a storage-based mutex. It costs ~5,000 gas overhead per guarded call (one SLOAD + one SSTORE for the lock toggle). For functions that already follow strict CEI with no external calls, the modifier is pure cost
• receive() and fallback() functions are called on plain ETH transfers. If your contract holds ETH and calls addr.call with value, the target's receive() executes in the caller's gas context — this is the reentrancy entry point

A constructor runs once, during deployment, and its code is not included in the deployed bytecode. For a standalone contract, this is the correct initialization point — set immutable values, validate constructor arguments, assign ownership.

If you ever intend to use a proxy pattern (ERC-1967 or similar), the constructor is useless: proxies delegatecall into the implementation's logic, but the implementation's constructor ran in the implementation's own storage context, not the proxy's. This is why upgradeable contracts use an initializer function with a one-shot guard instead. For a first contract with no upgrade path, use the constructor; just know why the alternative exists.

• Constructor arguments are ABI-encoded and appended to the deployment bytecode. Etherscan verification requires you to provide these separately if not auto-detected
• Forgetting to set ownership in the constructor is a permanent lockout if the contract has onlyOwner functions — there is no recovery path

• Uninitialized storage: Solidity 0.8.x zero-initializes all state variables, but structs in mappings are not "uninitialized" in the sense a developer might expect — they exist at their deterministic slot with all-zero values. Checking mapping(address => bool) for a "nonexistent" key returns false, which is semantically identical to "exists and is false." This ambiguity causes real bugs in access-control patterns
• tx.origin authentication: Using tx.origin instead of msg.sender allows any contract called by the owner to impersonate the owner. This is a phishing vector, not an edge case
• Integer overflow/underflow: Solidity >=0.8.0 reverts on overflow by default. Wrapping in an unchecked block re-enables overflow — this is an intentional gas optimization tool (saves ~30–80 gas per arithmetic operation) but must be applied only where overflow is provably impossible
• Self-destruct deprecation: selfdestruct is deprecated per EIP-6049 and its ETH-forwarding behavior may change post-Cancun. Do not use it as a withdrawal mechanism in new contracts
• Block timestamp manipulation: block.timestamp is set by the block proposer. Under proof-of-stake, the proposer can adjust it within the 12-second slot window. Using it for randomness or tight time bounds (sub-minute) is unreliable

The ordering here is not arbitrary — each step validates the output of the previous one, catching errors before they become permanent on-chain artifacts.

Compile with a pinned compiler version and explicit optimization settings. Inspect the ABI output to confirm that only intended functions are externally callable — unexpected public functions are a real attack surface. Run the test suite against a local fork (Foundry's forge test with --fork-url, or Hardhat's forking mode) to exercise state transitions against real chain state.

Deploy to a testnet (Sepolia, not Goerli — Goerli is deprecated) first. Record the deployer nonce and transaction hash. Then deploy to mainnet with the same compiled artifact.

Verify on Etherscan using the exact compiler version, optimization run count, and EVM version (default is currently shanghai for 0.8.24+). If you used constructor arguments, ABI-encode them and submit them during verification. A verified contract with a green checkmark is the minimum standard for any contract that handles value — unverified contracts hemorrhage user trust and cannot be audited publicly.

• Solidity documentation on storage layout: docs.soliditylang.org/en/latest/internals/layout_in_storage.html
• EVM Codes interactive opcode reference: evm.codes — trace SLOAD/SSTORE gas costs under Berlin and Shanghai pricing
• OpenZeppelin Contracts library (audited base contracts): github.com/OpenZeppelin/openzeppelin-contracts
• Etherscan contract verification guide: docs.etherscan.io/tutorials/verifying-contracts-programmatically
• Foundry book (forge, cast, anvil documentation): book.getfoundry.sh
• EIP-6049 (selfdestruct deprecation): eips.ethereum.org/EIPS/eip-6049
• Storage slot inspector: cast storage
  via Foundry's cast CLI tool queries live on-chain storage directly