docs: add line highlights to guides

Author: onbjerg

src/pages/guides/deploying-contracts.mdx

@@ -145,12 +145,12 @@ import {Counter} from "../src/Counter.sol";
 
 contract DeployScript is Script {
     function run() public {
-        vm.startBroadcast();
+        vm.startBroadcast(); // [!code hl]
         
         Counter counter = new Counter();
         console.log("Counter deployed at:", address(counter));
         
-        vm.stopBroadcast();
+        vm.stopBroadcast(); // [!code hl]
     }
 }
 ```

src/pages/guides/invariant-testing.mdx

@@ -141,19 +141,19 @@ contract TokenHandler is Test {
     Token public token;
     
     // Track all mints and burns
-    uint256 public ghost_mintedSum;
-    uint256 public ghost_burnedSum;
+    uint256 public ghost_mintedSum; // [!code hl]
+    uint256 public ghost_burnedSum; // [!code hl]
     
     // Track per-address deltas
-    mapping(address => int256) public ghost_balanceDeltas;
+    mapping(address => int256) public ghost_balanceDeltas; // [!code hl]
 
     function mint(address to, uint256 amount) external {
         amount = bound(amount, 1, 1000 ether);
         
         token.mint(to, amount);
         
-        ghost_mintedSum += amount;
-        ghost_balanceDeltas[to] += int256(amount);
+        ghost_mintedSum += amount; // [!code hl]
+        ghost_balanceDeltas[to] += int256(amount); // [!code hl]
     }
 
     function burn(address from, uint256 amount) external {
@@ -165,16 +165,16 @@ contract TokenHandler is Test {
         vm.prank(from);
         token.burn(amount);
         
-        ghost_burnedSum += amount;
-        ghost_balanceDeltas[from] -= int256(amount);
+        ghost_burnedSum += amount; // [!code hl]
+        ghost_balanceDeltas[from] -= int256(amount); // [!code hl]
     }
 }
 
 contract TokenInvariantTest is Test {
     function invariant_TotalSupplyMatchesGhosts() public view {
         assertEq(
             token.totalSupply(),
-            handler.ghost_mintedSum() - handler.ghost_burnedSum()
+            handler.ghost_mintedSum() - handler.ghost_burnedSum() // [!code hl]
         );
     }
 }
@@ -201,12 +201,12 @@ function setUp() public {
     
     // Only call these functions
     bytes4[] memory selectors = new bytes4[](2);
-    selectors[0] = VaultHandler.deposit.selector;
-    selectors[1] = VaultHandler.withdraw.selector;
-    targetSelector(FuzzSelector({
-        addr: address(handler),
-        selectors: selectors
-    }));
+    selectors[0] = VaultHandler.deposit.selector; // [!code hl]
+    selectors[1] = VaultHandler.withdraw.selector; // [!code hl]
+    targetSelector(FuzzSelector({ // [!code hl]
+        addr: address(handler), // [!code hl]
+        selectors: selectors // [!code hl]
+    })); // [!code hl]
 }
 ```
 
@@ -217,10 +217,10 @@ function setUp() public {
     targetContract(address(handler));
     
     // Exclude specific functions
-    excludeSelector(FuzzSelector({
-        addr: address(handler),
-        selectors: toSelectors(VaultHandler.debugFunction.selector)
-    }));
+    excludeSelector(FuzzSelector({ // [!code hl]
+        addr: address(handler), // [!code hl]
+        selectors: toSelectors(VaultHandler.debugFunction.selector) // [!code hl]
+    })); // [!code hl]
 }
 
 function toSelectors(bytes4 selector) internal pure returns (bytes4[] memory) {
@@ -237,27 +237,27 @@ Add a summary function to understand test coverage:
 ```solidity
 contract VaultHandler is Test {
     // Call counters
-    mapping(bytes4 => uint256) public calls;
+    mapping(bytes4 => uint256) public calls; // [!code hl]
 
     function deposit(uint256 amount) external {
-        calls[this.deposit.selector]++;
+        calls[this.deposit.selector]++; // [!code hl]
         // ...
     }
 
     function withdraw(uint256 amount) external {
-        calls[this.withdraw.selector]++;
+        calls[this.withdraw.selector]++; // [!code hl]
         // ...
     }
 
-    function callSummary() external view {
-        console.log("deposit calls:", calls[this.deposit.selector]);
-        console.log("withdraw calls:", calls[this.withdraw.selector]);
-    }
+    function callSummary() external view { // [!code hl]
+        console.log("deposit calls:", calls[this.deposit.selector]); // [!code hl]
+        console.log("withdraw calls:", calls[this.withdraw.selector]); // [!code hl]
+    } // [!code hl]
 }
 
 contract VaultInvariantTest is Test {
     function invariant_CallSummary() public view {
-        handler.callSummary();
+        handler.callSummary(); // [!code hl]
     }
 }
 ```

src/pages/guides/multi-chain-deployments.mdx

@@ -56,19 +56,19 @@ contract DeployScript is Script {
     }
 
     function getConfig() internal view returns (Config memory) {
-        if (block.chainid == 1) {
+        if (block.chainid == 1) { // [!code hl]
             return Config({
                 admin: 0x1234567890123456789012345678901234567890,
                 initialSupply: 1_000_000 ether,
                 weth: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
             });
-        } else if (block.chainid == 10) {
+        } else if (block.chainid == 10) { // [!code hl]
             return Config({
                 admin: 0x1234567890123456789012345678901234567890,
                 initialSupply: 500_000 ether,
                 weth: 0x4200000000000000000000000000000000000006
             });
-        } else if (block.chainid == 42161) {
+        } else if (block.chainid == 42161) { // [!code hl]
             return Config({
                 admin: 0x1234567890123456789012345678901234567890,
                 initialSupply: 500_000 ether,
@@ -178,12 +178,12 @@ contract DeployScript is Script {
         vm.stopBroadcast();
 
         // Write deployment to JSON
-        string memory json = vm.serializeAddress("deployment", "token", address(token));
-        json = vm.serializeUint("deployment", "chainId", block.chainid);
-        json = vm.serializeUint("deployment", "blockNumber", block.number);
+        string memory json = vm.serializeAddress("deployment", "token", address(token)); // [!code hl]
+        json = vm.serializeUint("deployment", "chainId", block.chainid); // [!code hl]
+        json = vm.serializeUint("deployment", "blockNumber", block.number); // [!code hl]
         
-        string memory path = string.concat("deployments/", vm.toString(block.chainid), ".json");
-        vm.writeJson(json, path);
+        string memory path = string.concat("deployments/", vm.toString(block.chainid), ".json"); // [!code hl]
+        vm.writeJson(json, path); // [!code hl]
     }
 }
 ```

src/pages/guides/stack-too-deep.mdx

@@ -74,7 +74,7 @@ struct Signature {
     bytes32 s;
 }
 
-function processOrder(Order calldata order, Signature calldata sig) external {
+function processOrder(Order calldata order, Signature calldata sig) external { // [!code hl]
     // Works fine
 }
 ```
@@ -113,7 +113,7 @@ struct CalcVars {
 }
 
 function calculate() external view returns (uint256) {
-    CalcVars memory vars;
+    CalcVars memory vars; // [!code hl]
     vars.a = getValue1();
     vars.b = getValue2();
     vars.c = getValue3();
@@ -202,19 +202,19 @@ Solidity supports block scoping with curly braces. Variables declared in a block
 function process() external {
     uint256 result;
 
-    {
+    { // [!code hl]
         uint256 temp1 = getValue1();
         uint256 temp2 = getValue2();
         result = temp1 + temp2;
         // temp1 and temp2 go out of scope here
-    }
+    } // [!code hl]
 
-    {
+    { // [!code hl]
         uint256 temp3 = getValue3();
         uint256 temp4 = getValue4();
         result += temp3 * temp4;
         // temp3 and temp4 go out of scope here
-    }
+    } // [!code hl]
 }
 ```
 

src/pages/guides/upgrading-contracts.mdx

@@ -16,10 +16,14 @@ This guide covers deploying and upgrading proxy contracts with Forge, including
 
 ### UUPS proxy deployment
 
+In the UUPS pattern, the proxy is a thin contract that delegates all calls to an implementation contract. The implementation holds both the business logic and the upgrade logic. Because the proxy uses `delegatecall`, all state is stored on the proxy - the implementation is just code.
+
 ::::steps
 
 #### Create the implementation
 
+Upgradeable contracts replace constructors with `initialize` functions, since constructor logic runs in the implementation's context, not the proxy's. `_disableInitializers()` in the constructor prevents anyone from calling `initialize` directly on the implementation, which could let an attacker take ownership of it.
+
 ```solidity [src/TokenV1.sol]
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
@@ -52,6 +56,8 @@ contract TokenV1 is UUPSUpgradeable, OwnableUpgradeable {
 
 #### Deploy the proxy
 
+Deployment is a two-step process: deploy the implementation, then deploy an ERC1967 proxy pointing to it. The proxy constructor accepts initialization calldata, so the `initialize` function is called atomically during deployment.
+
 ```solidity [script/DeployToken.s.sol]
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
@@ -87,6 +93,8 @@ contract DeployToken is Script {
 
 #### Create the new implementation
 
+The new implementation inherits from V1 and adds state variables **at the end** of the storage layout. Inserting or reordering variables would corrupt existing proxy state.
+
 ```solidity [src/TokenV2.sol]
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
@@ -95,7 +103,7 @@ import {TokenV1} from "./TokenV1.sol";
 
 contract TokenV2 is TokenV1 {
     // New state variables must be added at the end
-    mapping(address => bool) public frozen;
+    mapping(address => bool) public frozen; // [!code ++]
 
     function freeze(address account) external onlyOwner {
         frozen[account] = true;
@@ -109,6 +117,8 @@ contract TokenV2 is TokenV1 {
 
 #### Deploy and upgrade
 
+To upgrade, deploy the new implementation and call `upgradeToAndCall` on the proxy. This updates the implementation address stored in the proxy's ERC1967 slot. The second argument is optional calldata for a migration function - pass empty bytes if no re-initialization is needed.
+
 ```solidity [script/UpgradeToken.s.sol]
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
@@ -145,7 +155,7 @@ contract UpgradeToken is Script {
 
 ### Storage layout verification
 
-Foundry can check storage layout compatibility between implementations:
+Since the proxy stores all state, the new implementation's storage layout must be compatible with the old one. Foundry can export and diff storage layouts to catch breaking changes before deployment:
 
 ```bash
 $ forge inspect src/TokenV1.sol:TokenV1 storage-layout --pretty > v1-layout.txt
@@ -165,26 +175,30 @@ $ diff v1-layout.txt v2-layout.txt
 
 #### Using storage gaps
 
+Storage gaps are fixed-size arrays that reserve empty storage slots in a base contract. When you add new state variables in an upgrade, you reduce the gap size by the same number of slots, keeping the total storage layout unchanged and preventing slot collisions with inherited contracts.
+
 ```solidity
 contract TokenV1 is UUPSUpgradeable, OwnableUpgradeable {
     mapping(address => uint256) public balances;
     uint256 public totalSupply;
     
     // Reserve 50 slots for future variables
-    uint256[50] private __gap;
+    uint256[50] private __gap; // [!code hl]
 }
 
 contract TokenV2 is TokenV1 {
     // Uses one slot from the gap
-    mapping(address => bool) public frozen;
+    mapping(address => bool) public frozen; // [!code hl]
     
     // Update gap to maintain total slot count
-    uint256[49] private __gap;
+    uint256[49] private __gap; // [!code hl]
 }
 ```
 
 ### Transparent proxy deployment
 
+In the transparent proxy pattern, the proxy itself contains the upgrade logic and a separate admin address. Only the admin can call upgrade functions; all other callers are transparently delegated to the implementation. This avoids function selector clashes between the proxy and implementation but costs more gas per call due to the admin check.
+
 ```solidity [script/DeployTransparent.s.sol]
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
@@ -221,6 +235,8 @@ contract DeployTransparent is Script {
 
 ### Testing upgrades
 
+Upgrade tests should verify three things: state is preserved across the upgrade, new functionality works, and only authorized accounts can trigger upgrades.
+
 ```solidity [test/TokenUpgrade.t.sol]
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
@@ -242,16 +258,16 @@ contract TokenUpgradeTest is Test {
 
     function test_UpgradePreservesState() public {
         // Set state in V1
-        proxy.mint(address(0x1), 1000);
+        proxy.mint(address(0x1), 1000); // [!code hl]
         assertEq(proxy.balances(address(0x1)), 1000);
 
         // Upgrade to V2
         TokenV2 newImpl = new TokenV2();
-        proxy.upgradeToAndCall(address(newImpl), "");
+        proxy.upgradeToAndCall(address(newImpl), ""); // [!code hl]
 
         // State is preserved
         TokenV2 proxyV2 = TokenV2(address(proxy));
-        assertEq(proxyV2.balances(address(0x1)), 1000);
+        assertEq(proxyV2.balances(address(0x1)), 1000); // [!code hl]
         assertEq(proxyV2.version(), 2);
     }