solidity-argus 0.1.0

package/skills/vulnerability-patterns/shadowing-state-variables/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: shadowing-state-variables
+description: - Contract inherits from one or more parent contracts
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Shadowing State Variables
+
+## Preconditions
+- Contract inherits from one or more parent contracts
+- A state variable in the child contract has the same name as a state variable in a parent contract
+- Solidity version <0.6.0 (>=0.6.0 disallows state variable shadowing with a compiler error)
+- OR: function parameters or local variables shadow state variables (any Solidity version)
+
+## Vulnerable Pattern
+```solidity
+contract Base {
+    address public owner;
+
+    constructor() {
+        owner = msg.sender;
+    }
+}
+
+// Solidity <0.6.0: this compiles without error
+contract Child is Base {
+    address public owner; // Shadows Base.owner — creates a NEW variable
+
+    function setOwner(address _owner) external {
+        owner = _owner; // Sets Child.owner, NOT Base.owner
+    }
+
+    // Base's functions still read Base.owner (the original)
+    // Child's functions read Child.owner (the shadow)
+    // These are two different storage variables!
+}
+
+// Local variable shadowing (any version)
+contract Example {
+    uint256 public value = 100;
+
+    function getValue() public view returns (uint256) {
+        uint256 value = 0; // Shadows state variable
+        return value; // Returns 0, not 100
+    }
+}
+```
+
+## Detection Heuristics
+1. Check Solidity version: if <0.6.0, search for state variables in child contracts that share names with parent contract variables
+2. For any version, search for function parameters and local variables that share names with state variables
+3. Check compiler warnings — modern Solidity warns about local shadowing even if it allows it
+4. For each shadowed variable, trace which version (parent's or child's) each function reads/writes — inconsistency indicates a bug
+5. Pay special attention to `owner`, `admin`, and other access-control variables being shadowed
+
+## False Positives
+- Solidity >=0.6.0: state variable shadowing is a compiler error, so it can't happen
+- Local variable shadowing where the intent is clear and the state variable is not needed in that scope (still bad practice but not exploitable)
+- The shadowing is in a test file or non-production code
+
+## Remediation
+- Upgrade to Solidity >=0.6.0 where state variable shadowing is a compiler error
+- For local variable shadowing, use distinct names (e.g., prefix with `_` for parameters)
+- Rename conflicting variables to be unique across the inheritance chain
+```solidity
+contract Child is Base {
+    // Don't redeclare — use Base.owner directly
+    function setOwner(address _newOwner) external {
+        owner = _newOwner; // Modifies Base.owner
+    }
+}
+```

package/skills/vulnerability-patterns/signature-malleability/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: signature-malleability
+description: - Contract uses ECDSA signatures for authorization or deduplication
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Signature Malleability
+
+## Preconditions
+- Contract uses ECDSA signatures for authorization or deduplication
+- Signatures are tracked by their raw bytes (e.g., `mapping(bytes => bool)`) to prevent replay
+- No enforcement that the `s` value is in the lower half of the curve order
+
+## Vulnerable Pattern
+```solidity
+mapping(bytes => bool) public usedSignatures;
+
+function claimReward(bytes memory signature, uint256 amount) external {
+    // Deduplication by raw signature bytes
+    require(!usedSignatures[signature], "already used");
+
+    bytes32 hash = keccak256(abi.encodePacked(msg.sender, amount));
+    address signer = ecrecover(hash, v, r, s);
+    require(signer == trustedSigner);
+
+    usedSignatures[signature] = true; // Attacker submits (r, n-s, flipped_v)
+    // to bypass this check with a valid but different signature
+    _payout(msg.sender, amount);
+}
+```
+
+## Detection Heuristics
+1. Search for `mapping(bytes => bool)` or any mapping keyed by raw signature bytes
+2. If signatures are used as mapping keys for deduplication, flag it — an attacker can compute the complementary `(r, n-s)` signature
+3. Check if `ecrecover` is called directly without an `s`-value range check
+4. Check if OpenZeppelin's ECDSA library is used (it enforces lower-s normalization)
+5. If neither a library nor a manual `s < secp256k1n/2` check is present, flag it
+
+## False Positives
+- Signatures are deduplicated by message hash or nonce, not by raw signature bytes
+- OpenZeppelin's `ECDSA.recover` is used, which rejects high-s signatures
+- Manual check enforces `s <= 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0`
+
+## Remediation
+- Track used signatures by message hash or nonce, not by raw signature bytes
+- Use OpenZeppelin's `ECDSA.recover` which enforces `s` in the lower half of the curve order
+- If using raw `ecrecover`, add a manual `s`-value check
+```solidity
+// Use nonce-based deduplication instead of signature bytes
+mapping(address => uint256) public nonces;
+
+function claimReward(uint8 v, bytes32 r, bytes32 s, uint256 amount) external {
+    uint256 nonce = nonces[msg.sender]++;
+    bytes32 hash = keccak256(abi.encodePacked(msg.sender, amount, nonce));
+    address signer = ECDSA.recover(hash, v, r, s); // Rejects malleable sigs
+    require(signer == trustedSigner);
+    _payout(msg.sender, amount);
+}
+```

package/skills/vulnerability-patterns/unbounded-return-data/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: unbounded-return-data
+description: - Contract makes a low-level `.call()` to an untrusted or user-specified address
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Unbounded Return Data
+
+## Preconditions
+- Contract makes a low-level `.call()` to an untrusted or user-specified address
+- Solidity's automatic return data copying is used (default behavior up to at least v0.8.26)
+- No assembly-level restriction on `returndatacopy` size
+- The function is on a critical path where revert would lock funds (withdrawals, undelegation)
+
+## Vulnerable Pattern
+```solidity
+function unstake(address callback) external {
+    uint256 amount = stakes[msg.sender];
+    stakes[msg.sender] = 0;
+
+    // Solidity automatically copies ALL return data into memory
+    // Attacker's callback contract returns megabytes of data
+    // Memory expansion cost grows quadratically — causes out-of-gas
+    (bool success,) = callback.call(
+        abi.encodeWithSignature("onUnstake(uint256)", amount)
+    );
+    // Even with limited gas stipend, the return data copy
+    // happens in the CALLER's gas context
+    require(success, "callback failed");
+}
+```
+
+## Detection Heuristics
+1. Search for `.call(`, `.delegatecall(`, `.staticcall(` to addresses that could be attacker-controlled
+2. Check if the return data is handled by Solidity's default (captured as `bytes memory` or discarded but still copied)
+3. If the call target is untrusted and no assembly-level return data size limit is used, flag it
+4. Check if the function is on a critical path — can a revert here lock user funds?
+5. Look for callback patterns (delegation hooks, unstaking callbacks, flash loan callbacks) where the callee is attacker-controlled
+
+## False Positives
+- The call target is a trusted, known contract (not user-controlled)
+- Assembly is used to limit `returndatacopy` to a bounded size (e.g., max 32 bytes)
+- `ExcessivelySafeCall` or similar library is used for bounded return data
+- The function doesn't revert on call failure (uses try/catch or ignores success)
+
+## Remediation
+- Use assembly to limit return data size instead of Solidity's automatic copy
+- Use Nomad's `ExcessivelySafeCall` library for calls to untrusted addresses
+- Bound `returndatacopy` to only the bytes you need (typically 0 or 32)
+```solidity
+// Assembly-bounded return data copy
+function safeCall(address target, bytes memory data) internal returns (bool success) {
+    assembly {
+        success := call(gas(), target, 0, add(data, 0x20), mload(data), 0, 0)
+        // Only copy up to 32 bytes of return data
+        let rdsize := returndatasize()
+        if gt(rdsize, 0) {
+            if gt(rdsize, 32) { rdsize := 32 }
+            returndatacopy(0, 0, rdsize)
+        }
+    }
+}
+```

package/skills/vulnerability-patterns/unchecked-return-values/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: unchecked-return-values
+description: - Contract uses low-level calls: `.call()`, `.send()`, or `.delegatecall()`
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Unchecked Return Values
+
+## Preconditions
+- Contract uses low-level calls: `.call()`, `.send()`, or `.delegatecall()`
+- The boolean return value indicating success/failure is not checked
+- State changes occur after the unchecked call, assuming it succeeded
+
+## Vulnerable Pattern
+```solidity
+function withdraw(uint256 amount) external {
+    // .send() returns false on failure but does NOT revert
+    msg.sender.send(amount); // Return value ignored
+    balances[msg.sender] -= amount; // State updated even if send failed
+}
+
+function payout(address to, uint256 amount) external {
+    // .call() return value captured but never checked
+    (bool success,) = to.call{value: amount}("");
+    // success could be false, but execution continues
+    totalPaid += amount;
+}
+```
+
+## Detection Heuristics
+1. Search for all `.call(`, `.send(`, `.delegatecall(` invocations
+2. For each, check whether the returned boolean is captured AND checked (e.g., `require(success)`, `if (!success) revert`)
+3. If the return value is captured but never referenced again, flag it
+4. If the return value is not captured at all (e.g., bare `addr.send(amount);`), flag it
+5. Check for state changes after unchecked calls — these create inconsistent state on silent failure
+
+## False Positives
+- Return value is checked with `require(success)` or equivalent
+- The call is intentionally fire-and-forget (documented, no state depends on success) — rare but valid
+- Using Solidity's high-level function calls (e.g., `IERC20(token).transfer(...)`) which auto-revert on failure
+
+## Remediation
+- Always check the return value: `require(success, "call failed")`
+- For ETH transfers to untrusted recipients, consider a pull-payment pattern to avoid DoS if the recipient deliberately reverts
+- Prefer high-level Solidity calls when interacting with known interfaces
+```solidity
+function withdraw(uint256 amount) external {
+    balances[msg.sender] -= amount;
+    (bool success,) = msg.sender.call{value: amount}("");
+    require(success, "ETH transfer failed");
+}
+```

package/skills/vulnerability-patterns/unencrypted-private-data-on-chain/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: unencrypted-private-data-on-chain
+description: - Sensitive data (passwords, secrets, private keys, game answers) is stored in contract storage
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Unencrypted Private Data On-Chain
+
+## Preconditions
+- Sensitive data (passwords, secrets, private keys, game answers) is stored in contract storage
+- The developer relies on the `private` visibility modifier for confidentiality
+- OR: sensitive data is passed as transaction calldata (publicly visible)
+
+## Vulnerable Pattern
+```solidity
+contract SecretGame {
+    // `private` only prevents OTHER CONTRACTS from reading
+    // Anyone can read this via eth_getStorageAt(address, slot)
+    bytes32 private secretAnswer;
+    string private password;
+
+    constructor(bytes32 _answer, string memory _pwd) {
+        secretAnswer = _answer; // Visible in deployment tx calldata
+        password = _pwd;        // Readable from storage slot
+    }
+
+    function guess(bytes32 _guess) external {
+        // Attacker reads secretAnswer from storage first
+        require(_guess == secretAnswer, "wrong");
+        _reward(msg.sender);
+    }
+}
+```
+
+## Detection Heuristics
+1. Search for state variables storing passwords, secrets, keys, answers, or seeds — regardless of visibility modifier
+2. Check if any `private` variable is relied upon for confidentiality (not just access control)
+3. Look for game/lottery logic where hidden information is stored on-chain before a reveal phase
+4. Check constructor parameters and transaction calldata for sensitive values — these are publicly visible on block explorers
+5. Search for comments like "secret", "hidden", "private key", "password" near storage declarations
+
+## False Positives
+- Data is encrypted or hashed before storage (e.g., commitment hash in a commit-reveal scheme)
+- The `private` modifier is used correctly for access control between contracts, not for data confidentiality
+- The "sensitive" data is actually public information (e.g., a contract address)
+
+## Remediation
+- Never store plaintext secrets on-chain — all storage is publicly readable
+- Use commit-reveal schemes for hidden inputs: store `keccak256(secret || salt)` first, reveal later
+- For truly private data, keep it off-chain and only store hashes/commitments on-chain
+- Consider zero-knowledge proofs for verifiable computation on private data
+```solidity
+// Commit-reveal scheme
+mapping(address => bytes32) public commitments;
+
+function commit(bytes32 hash) external {
+    // User submits keccak256(answer, salt) — answer stays private
+    commitments[msg.sender] = hash;
+}
+
+function reveal(bytes32 answer, bytes32 salt) external {
+    require(commitments[msg.sender] == keccak256(abi.encodePacked(answer, salt)));
+    _processAnswer(msg.sender, answer);
+}
+```

package/skills/vulnerability-patterns/unexpected-ecrecover-null-address/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: unexpected-ecrecover-null-address
+description: - Contract uses `ecrecover` directly (not via OpenZeppelin's ECDSA library)
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Unexpected ecrecover Null Address
+
+## Preconditions
+- Contract uses `ecrecover` directly (not via OpenZeppelin's ECDSA library)
+- The recovered address is not checked against `address(0)`
+- The expected signer variable could be uninitialized (defaults to `address(0)`)
+
+## Vulnerable Pattern
+```solidity
+contract Vault {
+    address public signer; // Uninitialized — defaults to address(0)
+
+    function withdrawWithSig(uint256 amount, uint8 v, bytes32 r, bytes32 s) external {
+        bytes32 hash = keccak256(abi.encodePacked(msg.sender, amount));
+
+        // ecrecover returns address(0) for invalid signatures
+        // (e.g., v != 27 && v != 28)
+        address recovered = ecrecover(hash, v, r, s);
+
+        // If signer is uninitialized (address(0)) and recovered is address(0),
+        // this check passes — anyone can withdraw
+        require(recovered == signer, "invalid signature");
+
+        _withdraw(msg.sender, amount);
+    }
+}
+```
+
+## Detection Heuristics
+1. Search for `ecrecover(` calls in the codebase
+2. Check if the returned address is validated against `address(0)` — flag if not
+3. Check the variable that the recovered address is compared against — can it ever be `address(0)`? (uninitialized, never set, cleared by admin)
+4. Check if OpenZeppelin's `ECDSA.recover` is used instead — it reverts on null recovery automatically
+5. In upgradeable contracts, check if the signer is set during `initialize()` — if `initialize` is never called, signer remains `address(0)`
+
+## False Positives
+- `require(recovered != address(0))` check is present after `ecrecover`
+- OpenZeppelin's `ECDSA.recover` is used (handles null address internally)
+- The expected signer is set in the constructor or initializer and can never be `address(0)` (validated on set)
+
+## Remediation
+- Always check `require(recovered != address(0), "invalid signature")` after `ecrecover`
+- Use OpenZeppelin's `ECDSA.recover` which reverts on invalid signatures and null recovery
+- Validate that signer variables cannot be `address(0)` at any point
+```solidity
+import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+
+function withdrawWithSig(uint256 amount, bytes memory sig) external {
+    bytes32 hash = keccak256(abi.encodePacked(msg.sender, amount));
+    bytes32 ethHash = ECDSA.toEthSignedMessageHash(hash);
+    address recovered = ECDSA.recover(ethHash, sig); // Reverts if address(0)
+    require(recovered == signer, "invalid signature");
+    _withdraw(msg.sender, amount);
+}
+```

package/skills/vulnerability-patterns/uninitialized-storage-pointer/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: uninitialized-storage-pointer
+description: - Solidity version <0.5.0
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Uninitialized Storage Pointer
+
+## Preconditions
+- Solidity version <0.5.0
+- Local variables of complex types (structs, arrays) are declared without an explicit `storage` or `memory` data location
+- The variable defaults to `storage`, pointing to slot 0
+
+## Vulnerable Pattern
+```solidity
+// Solidity <0.5.0 only
+pragma solidity ^0.4.24;
+
+contract Registry {
+    address public owner;      // Stored in slot 0
+    uint256 public totalUsers; // Stored in slot 1
+
+    struct User {
+        address addr;
+        uint256 balance;
+    }
+
+    User[] public users;
+
+    function addUser(address _addr, uint256 _balance) external {
+        // No data location specified — defaults to storage
+        // Points to slot 0 (owner) and slot 1 (totalUsers)
+        User u;        // u.addr aliases slot 0 (owner)
+        u.addr = _addr;    // Overwrites owner!
+        u.balance = _balance; // Overwrites totalUsers!
+        users.push(u);
+    }
+}
+```
+
+## Detection Heuristics
+1. Check the Solidity version: if >=0.5.0, this vulnerability is impossible (compiler requires explicit data location)
+2. For <0.5.0: search for local struct or array variable declarations without `storage` or `memory` keyword
+3. If a local variable of a complex type has no data location, it defaults to `storage` at slot 0 — writes to it overwrite the first state variables
+4. Check which state variables occupy slots 0, 1, 2, etc. — these are the ones at risk of overwrite
+5. Look for struct field assignments on local variables that could alias storage
+
+## False Positives
+- Solidity >=0.5.0 (compiler enforces explicit data location — this can't happen)
+- The variable is explicitly declared as `memory` (e.g., `User memory u`)
+- The variable is explicitly declared as `storage` and intentionally points to a known storage location
+
+## Remediation
+- Upgrade to Solidity >=0.5.0 where explicit data locations are compiler-enforced
+- For legacy contracts, add explicit `memory` or `storage` to all local complex-type declarations
+```solidity
+function addUser(address _addr, uint256 _balance) external {
+    User memory u;         // Explicit memory — no storage aliasing
+    u.addr = _addr;
+    u.balance = _balance;
+    users.push(u);
+}
+```

package/skills/vulnerability-patterns/unsafe-low-level-call/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: unsafe-low-level-call
+description: - Contract uses `.call()`, `.delegatecall()`, `.staticcall()`, or `.send()` for external interactions
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Unsafe Low-Level Call
+
+## Preconditions
+- Contract uses `.call()`, `.delegatecall()`, `.staticcall()`, or `.send()` for external interactions
+- The return value is not checked, OR
+- The target address may not have deployed code (user-provided, destroyed, or never deployed)
+
+## Vulnerable Pattern
+```solidity
+function payout(address to, uint256 amount) external {
+    // Unchecked return value — silent failure
+    to.call{value: amount}("");
+    totalPaid += amount; // Updated even if call failed
+}
+
+function interact(address target, bytes calldata data) external {
+    // Call to non-existent contract "succeeds" silently
+    // EVM treats call to codeless address as successful
+    (bool success,) = target.call(data);
+    require(success); // Passes even if target has no code!
+    _markComplete();
+}
+```
+
+## Detection Heuristics
+1. Search for `.call(`, `.send(`, `.delegatecall(`, `.staticcall(` in the codebase
+2. For each, check if the returned `bool` is captured AND checked (e.g., `require(success)`)
+3. If the return value is not captured or not checked, flag it — execution continues after failure
+4. For calls to user-supplied addresses, check if `target.code.length > 0` is verified before the call — the EVM silently succeeds on calls to addresses with no code
+5. Note: `address.code.length` check can be bypassed during constructor execution (code size is 0)
+6. Check if state changes after the call assume it succeeded
+
+## False Positives
+- Return value is properly checked with `require(success)`
+- High-level Solidity calls are used (e.g., `IERC20(token).transfer(...)`) which include automatic `extcodesize` checks and revert on failure
+- The call is intentionally fire-and-forget with no state depending on success (rare, must be documented)
+
+## Remediation
+- Always check return values: `require(success, "call failed")`
+- Verify target has code before low-level calls: `require(target.code.length > 0)`
+- Prefer high-level Solidity calls for known interfaces — they include automatic code existence checks
+- For critical integrations, combine both checks
+```solidity
+function payout(address to, uint256 amount) external {
+    require(to.code.length > 0 || to == tx.origin, "no code at target");
+    (bool success,) = to.call{value: amount}("");
+    require(success, "transfer failed");
+    totalPaid += amount;
+}
+```

package/skills/vulnerability-patterns/unsecure-signatures/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: unsecure-signatures
+description: - Contract uses ECDSA signatures for authorization, authentication, or message verification
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Unsecure Signatures
+
+## Preconditions
+- Contract uses ECDSA signatures for authorization, authentication, or message verification
+- One or more of the following sub-vulnerabilities are present:
+  - Signature malleability (tracking by raw bytes)
+  - Missing replay protection (no nonce, chainId, or contract address)
+  - Unchecked ecrecover null address return
+  - Hash collisions from `abi.encodePacked` with multiple dynamic types
+  - No EIP-712 structured data signing
+
+## Vulnerable Pattern
+```solidity
+// Combines multiple signature anti-patterns
+function execute(bytes memory sig, address to, uint256 amount) external {
+    // 1. No nonce — replay attack
+    // 2. No address(this) — cross-contract replay
+    // 3. No block.chainid — cross-chain replay
+    bytes32 hash = keccak256(abi.encodePacked(to, amount));
+
+    // 4. Raw ecrecover — no null address check
+    address recovered = ecrecover(hash, v, r, s);
+    // 5. No s-value malleability check
+    require(recovered == signer);
+
+    // 6. Signature tracked by bytes — malleable bypass
+    require(!used[sig]);
+    used[sig] = true;
+
+    _transfer(to, amount);
+}
+```
+
+## Detection Heuristics
+1. Search for `ecrecover` or `ECDSA.recover` — this indicates signature usage
+2. Check each sub-vulnerability in order:
+   - **Malleability**: is deduplication done by raw signature bytes? Flag if yes
+   - **Replay**: does the signed hash include nonce + `address(this)` + `block.chainid`? Flag any missing
+   - **Null address**: is the recovered address checked against `address(0)`? Flag if not
+   - **Hash collision**: is `abi.encodePacked` used with multiple dynamic types? Flag if yes
+   - **EIP-712**: is structured typed data signing used? Flag if not (lower severity)
+3. Check if OpenZeppelin's ECDSA library is used — it handles malleability and null address automatically
+4. Check for front-running risk: can a signed message be observed in the mempool and submitted by someone else?
+
+## False Positives
+- OpenZeppelin's ECDSA library is used with EIP-712 domain separator, nonce tracking, and proper hash construction — all sub-vulnerabilities are addressed
+- EIP-2612 permit pattern is used correctly (includes nonce, deadline, domain separator)
+- The contract is a simple forwarder where signature security is handled by a downstream contract
+
+## Remediation
+- Use OpenZeppelin's ECDSA library for signature recovery (handles malleability + null address)
+- Implement EIP-712 structured data signing with domain separator (covers chainId + contract address)
+- Track nonces per signer to prevent replay
+- Use `abi.encode` instead of `abi.encodePacked` for hash construction
+```solidity
+import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
+
+contract SecureSig is EIP712("SecureSig", "1") {
+    mapping(address => uint256) public nonces;
+
+    bytes32 constant EXECUTE_TYPEHASH =
+        keccak256("Execute(address to,uint256 amount,uint256 nonce)");
+
+    function execute(address to, uint256 amount, bytes memory sig) external {
+        uint256 nonce = nonces[msg.sender]++;
+        bytes32 structHash = keccak256(abi.encode(EXECUTE_TYPEHASH, to, amount, nonce));
+        bytes32 hash = _hashTypedDataV4(structHash);
+        address recovered = ECDSA.recover(hash, sig);
+        require(recovered == signer, "invalid sig");
+        _transfer(to, amount);
+    }
+}
+```

package/skills/vulnerability-patterns/unsupported-opcodes/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: unsupported-opcodes
+description: - Contract is intended for deployment on an EVM-compatible chain other than Ethereum mainnet (zkSync Era, Arbitrum, Optimism, Polygon, BNB Chain, etc.)
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Unsupported Opcodes on EVM-Compatible Chains
+
+## Preconditions
+- Contract is intended for deployment on an EVM-compatible chain other than Ethereum mainnet (zkSync Era, Arbitrum, Optimism, Polygon, BNB Chain, etc.)
+- The contract uses opcodes or patterns that are not supported or behave differently on the target chain
+
+## Vulnerable Pattern
+```solidity
+// PUSH0 opcode: Solidity >=0.8.20 emits PUSH0
+// Not supported on all chains — contract fails to deploy
+pragma solidity 0.8.20;
+
+contract Token {
+    // Compiled bytecode contains PUSH0 — reverts on chains without support
+}
+
+// .transfer() on zkSync Era — 2300 gas stipend insufficient
+function withdraw() external {
+    // transfer() forwards only 2300 gas
+    // On zkSync Era, basic operations cost more — this always reverts
+    // Gemholic lost 921 ETH to this exact issue
+    payable(msg.sender).transfer(amount);
+}
+
+// Dynamic create on zkSync Era
+function deploy(bytes memory bytecode) external {
+    assembly {
+        // zkSync requires bytecode known at compile time
+        // Runtime create from arbitrary bytecode fails
+        let addr := create(0, add(bytecode, 0x20), mload(bytecode))
+    }
+}
+```
+
+## Detection Heuristics
+1. Check the Solidity version: if >=0.8.20, verify the target chain supports the PUSH0 opcode
+2. Search for `.transfer()` and `.send()` — these use a 2300 gas stipend that may be insufficient on chains with different gas cost structures (especially zkSync Era)
+3. Search for assembly `create` / `create2` with runtime-supplied bytecode — this fails on zkSync Era
+4. Search for `selfdestruct` — deprecated and non-functional on some chains post-Dencun
+5. If the project targets multiple chains, cross-reference all opcodes used against each target chain's compatibility (use evmdiff.com)
+
+## False Positives
+- Contract is only deployed on Ethereum mainnet
+- Solidity version is <0.8.20 (no PUSH0 emitted)
+- `.call{value: amount}("")` is used instead of `.transfer()` (forwards all available gas)
+- The project explicitly documents which chains are supported and tests against them
+
+## Remediation
+- Use `.call{value: amount}("")` instead of `.transfer()` or `.send()` for ETH transfers
+- For multi-chain deployments, compile with Solidity <0.8.20 or use `--evm-version paris` to avoid PUSH0
+- On zkSync Era, use compile-time known bytecode for contract creation
+- Test deployments on each target chain before mainnet launch
+- Use evmdiff.com to verify opcode compatibility per chain
+```solidity
+// Safe ETH transfer for all EVM chains
+function withdraw(uint256 amount) external {
+    (bool success,) = msg.sender.call{value: amount}("");
+    require(success, "transfer failed");
+}
+
+// Avoid PUSH0: compile with Paris EVM target
+// solc --evm-version paris
+```