0x-shashi/skills/starknet-scanner

Starknet Specialized Scanner

Specialized security scanner for Starknet Cairo contracts. Extends the general Cairo Scanner with Starknet-specific patterns: account abstraction, contract upgrades via replace_class, component architecture, and the L1-L2 messaging bridge.

---

Why a Separate Starknet Scanner?

While the Cairo Scanner covers language-level patterns (felt arithmetic, Sierra safety), Starknet-specific features create unique attack surfaces:

| Feature | Security Impact | |---------|----------------| | Account Abstraction | Custom validation logic = custom attack surface | | replace_class_syscall | Contract upgrade mechanism — must be protected | | Components (like Solidity libraries) | Storage collision between components | | L1-L2 Messaging | Cross-chain replay, message validation | | Sequencer | Centralized sequencer = MEV, censorship risks | | Fee market | STRK token fees, gas estimation |

---

Detection Capabilities

| Category | Detection | Severity | |----------|-----------|----------| | Account | __validate__ missing signature check | Critical | | Account | __execute__ allows arbitrary call without validation | Critical | | Account | Signature replay across chains (no chain_id in hash) | High | | Upgrade | replace_class_syscall callable by unauthorized party | Critical | | Upgrade | No upgrade delay/timelock | High | | Upgrade | Storage layout incompatibility after upgrade | High | | Components | Storage collision between components | High | | Components | Component events shadowing contract events | Medium | | L1-L2 | Message replay (consumed message not tracked) | Critical | | L1-L2 | Missing sender validation on L1 handler | Critical | | L1-L2 | Message not consumed (stuck funds) | High | | Felt | Felt arithmetic wrapping (p = 2^251 + 17*2^192 + 1) | High | | Storage | Storage address collision (Pedersen hash) | Medium | | Access | Missing caller validation on external function | Critical | | Access | Ownable component not initialized | High |

---

Starknet Account Abstraction

Every account on Starknet is a smart contract. This means custom validation logic:

#[starknet::contract(account)]
mod MyAccount {
    // REQUIRED: Validates transaction signature
    // If this returns successfully, the tx is considered valid
    #[external(v0)]
    fn __validate__(
        ref self: ContractState,
        calls: Array<Call>
    ) -> felt252 {
        // CRITICAL: Must verify the transaction signature
        // If this blindly returns VALIDATED, anyone can submit txs as this account
        let tx_hash = get_tx_info().unbox().transaction_hash;
        let signature = get_tx_info().unbox().signature;
        
        // Verify signature against stored public key
        assert(check_ecdsa_signature(tx_hash, self.public_key.read(), *signature.at(0), *signature.at(1)), 'invalid sig');
        
        starknet::VALIDATED
    }
    
    // REQUIRED: Executes the validated transaction
    #[external(v0)]
    fn __execute__(
        ref self: ContractState,
        calls: Array<Call>
    ) -> Array<Span<felt252>> {
        // Execute each call
        // Typically a loop over calls with call_contract_syscall
    }
}

Account Security Checklist

• [ ] __validate__ verifies transaction hash signature
• [ ] __validate__ uses stored public key (not hardcoded)
• [ ] Signature cannot be replayed (nonce handled by protocol)
• [ ] chain_id included in signature verification (cross-chain replay)
• [ ] Key rotation mechanism exists and is secure
• [ ] Multicall execution handles failures correctly (atomicity)

---

Contract Upgrade via replace_class_syscall

Starknet contracts can upgrade their logic using replace_class_syscall:

use starknet::replace_class_syscall;
use starknet::ClassHash;

#[external(v0)]
fn upgrade(ref self: ContractState, new_class_hash: ClassHash) {
    // CRITICAL: WHO can call this?
    self.ownable.assert_only_owner();
    
    // Replace the contract's class (logic) with new implementation
    replace_class_syscall(new_class_hash).unwrap();
    
    // Emit upgrade event
    self.emit(Upgraded { new_class_hash });
}

Upgrade Security

| Risk | Description | |------|-------------| | Unauthorized upgrade | Anyone calling replace_class_syscall can change contract logic | | No timelock | Instant upgrade = no time for users to exit | | Storage incompatibility | New class may interpret storage differently | | Proxy pattern | If using proxy, verify replace_class on implementation, not just proxy |

• [ ] replace_class_syscall protected by access control (owner, governance)
• [ ] Upgrade delay (timelock) implemented for critical contracts
• [ ] Storage layout documented and verified compatible across versions
• [ ] Upgrade event emitted

---

Component Architecture

Starknet components are reusable modules (similar to Solidity libraries with storage):

// Using OpenZeppelin components
#[starknet::contract]
mod MyContract {
    use openzeppelin::access::ownable::OwnableComponent;
    use openzeppelin::token::erc20::ERC20Component;
    
    component!(path: OwnableComponent, storage: ownable, event: OwnableEvent);
    component!(path: ERC20Component, storage: erc20, event: ERC20Event);
    
    #[storage]
    struct Storage {
        #[substorage(v0)]
        ownable: OwnableComponent::Storage,
        #[substorage(v0)]
        erc20: ERC20Component::Storage,
        // Custom storage
        my_value: felt252,
    }
}

Component Security

| Risk | Description | |------|-------------| | Storage collision | Two components writing to same storage address | | Uninitialized component | Ownable without initializer() = no owner set | | Event shadowing | Component events with same name as contract events | | Version mismatch | Component version incompatible with contract |

• [ ] All components initialized in constructor
• [ ] #[substorage(v0)] used correctly (automatic storage isolation)
• [ ] No manual storage access that could collide with component storage
• [ ] Component versions compatible with each other

---

L1-L2 Messaging

Starknet communicates with Ethereum L1 via asynchronous messaging:

| Direction | Mechanism | Latency | |-----------|-----------|----------| | L1 → L2 | send_message_to_l2() on Starknet Core contract | ~minutes (L2 block time) | | L2 → L1 | send_message_to_l1_syscall() in Cairo | ~hours (proof verification) |

L1-L2 Security Checklist

• [ ] L2 handler validates L1 sender (from_address in L1Handler)
• [ ] L1 handler validates L2 sender (message origin)
• [ ] Messages consumed exactly once (replay protection)
• [ ] Message format matches between L1 and L2 contracts
• [ ] Stuck message handling (cancellation mechanism exists)
• [ ] Fee handling on L1→L2 messages correct

---

Resources

• Starknet Patterns

Workflows

• Starknet Audit

See Also

• Cairo Scanner for Cairo language patterns
• Chain Guide: Starknet for chain context

Error Code Reference

Starknet-specific error codes and system errors encountered during audits.

Starknet OS / Sequencer Errors

| Error Code | Name | Meaning | |-----------|------|----------| | TRANSACTION_FAILED | Transaction failure | Generic execution failure — check inner error | | ENTRYPOINT_NOT_FOUND | Missing entrypoint | Selector not found on contract — wrong function name/args | | UNINITIALIZED_CONTRACT | No contract | Address has no deployed contract class | | ENTRY_POINT_FAILED | Execution revert | Contract function reverted — check custom error | | FEE_TRANSFER_FAILURE | Fee payment | Insufficient balance to pay transaction fee | | VALIDATE_FAILURE | Account validation | Account __validate__ rejected transaction — signature/auth issue | | OUT_OF_RESOURCES | Resource limit | Transaction exceeded Cairo steps or builtins limit | | CLASS_ALREADY_DECLARED | Duplicate class | Contract class hash already declared on network |

Account Abstraction Errors

| Error Pattern | Source | Meaning | |--------------|--------|----------| | 'INVALID_SIGNATURE' | __validate__ | Signature verification failed in account contract | | 'INVALID_CALLER' | Account guard | Caller is not the expected account or protocol | | 'INVALID_TX_VERSION' | Version check | Transaction version not supported (v1 vs v3) | | 'EXPIRED' | Time check | Transaction or session expired | | 'UNDERSPENT_FEE' | Fee estimation | Actual fee lower than estimate — potential gas griefing | | 'PAYMASTER_REJECTED' | Paymaster | Paymaster refused to sponsor transaction |

Starknet Contract Errors (OpenZeppelin Cairo)

| Error String | Component | Meaning | |-------------|----------|----------| | 'Caller is not the owner' | OwnableComponent | Missing owner role — access control | | 'Caller is the zero address' | OwnableComponent | Invalid zero caller | | 'New owner is the zero address' | OwnableComponent | Invalid ownership transfer | | 'ERC20: insufficient balance' | ERC20Component | Token balance too low | | 'ERC20: insufficient allowance' | ERC20Component | Approval not set | | 'ERC721: invalid token ID' | ERC721Component | Token does not exist | | 'ERC721: unauthorized caller' | ERC721Component | Not owner or approved | | 'ReentrancyGuard: reentrant call' | ReentrancyGuardComponent | Reentrancy detected | | 'Class hash cannot be zero' | UpgradeableComponent | Invalid upgrade target |

L1↔L2 Messaging Errors

| Error Pattern | Direction | Meaning | |--------------|----------|----------| | 'INVALID_MESSAGE_TO_CONSUME' | L1→L2 | Message not found in L2 pending messages | | 'MESSAGE_NOT_SENT' | L2→L1 | L2 message not recorded by sequencer | | 'INVALID_FROM_ADDRESS' | L1→L2 | L1 sender address does not match expected | | 'INVALID_NONCE' | Both | Message nonce mismatch — replay or ordering issue |

Troubleshooting

| Issue | Likely Cause | Solution | |-------|-------------|----------| | Account abstraction vulnerabilities missed | Scanner uses EOA mental model | Audit __validate__ and __execute__ in all account contracts; check signature schemes | | replace_class upgrade risks not flagged | Scanner doesn't track class replacement | Map all replace_class_syscall calls; verify upgrade authority and timelock protections | | Component storage collision missed | Scanner doesn't model Cairo component storage | Verify component storage isolation; check for #[storage] field name conflicts across components | | L1↔L2 message handling gaps | Scanner audits L2 in isolation | Audit #[l1_handler] functions; trace message flow from L1 contract through Starknet OS | | Fee estimation manipulation not caught | Scanner doesn't model Starknet fee mechanism | Check __validate__ and __execute__ for fee-related assumptions; test with v3 transactions | | Missing event emission in state changes | Scanner focuses on logic, not observability | Verify all state-changing functions emit events; critical for off-chain indexing and monitoring |