# Layer 2 Blockchain Fields

This document describes the Layer 2-specific fields available in Base and other L2 blockchains, and how ChainETL handles them.

## Overview

Layer 2 blockchains like Base (built on Optimism's OP Stack) are EVM-compatible chains that settle to Ethereum Layer 1. They use the same RPC interface as Ethereum but include additional metadata about their relationship to L1.

## Base L2 Block Fields

### Standard Fields (Same as Ethereum)

These fields work identically to Ethereum and are fully supported by ChainETL:

- `number`: Block number on Base L2
- `hash`: Block hash (unique to Base)
- `parentHash`: Hash of the previous Base block
- `timestamp`: Unix timestamp when the block was created
- `miner`: Address of the sequencer that produced the block
- `gasLimit`: Gas limit for the block
- `gasUsed`: Total gas used by transactions in the block
- `transactions`: Array of transaction hashes or full transaction objects

### L2-Specific Fields

These fields are specific to Layer 2 blockchains and provide information about the L2's relationship to Ethereum L1:

#### `l1BlockNumber`
- **Type**: Integer
- **Description**: The Ethereum L1 block number when this L2 block's data was posted to L1
- **Example**: If Base block 10000000 has `l1BlockNumber: 18500000`, it means this L2 block's data was submitted to Ethereum at L1 block 18500000
- **Use Case**: Tracking L1 anchoring, calculating L2→L1 finality time

#### `l1BatchNumber`
- **Type**: Integer
- **Description**: The batch number on L1. Multiple L2 blocks are typically grouped into a single batch for efficient L1 posting
- **Example**: Base blocks 10000000-10000099 might all share `l1BatchNumber: 5000`
- **Use Case**: Understanding rollup compression, calculating batch costs

#### `l1Timestamp`
- **Type**: Integer (Unix timestamp)
- **Description**: The timestamp of the L1 block referenced by `l1BlockNumber`
- **Use Case**: Comparing L1 and L2 timestamps, calculating settlement lag

#### `sequenceNumber`
- **Type**: Integer
- **Description**: The position of this L2 block within its L1 batch
- **Example**: In a batch of 100 blocks, the first block has sequenceNumber 0, the last has sequenceNumber 99
- **Use Case**: Ordering blocks within a batch

## Special Transaction Types

### Deposit Transactions (L1 → L2)

When users deposit assets from Ethereum to Base, a special "deposit transaction" is created on Base.

**Characteristics:**
- Type: `0x7E` (126 in decimal)
- No signature (generated by the L2 system, not signed by a user)
- Includes L1 block information
- Cannot be reversed on L2

**Fields:**
- `from`: L1 depositor address
- `to`: L2 recipient address
- `mint`: Amount of ETH being deposited
- `sourceHash`: Hash identifying the L1 deposit transaction
- `l1BlockNumber`: L1 block where the deposit was initiated

### Withdrawal Transactions (L2 → L1)

When users withdraw assets from Base to Ethereum, they initiate a transaction on L2 that eventually settles on L1.

**Process:**
1. User calls withdrawal on L2 (regular transaction)
2. Withdrawal is included in L2 block and batched to L1
3. After challenge period (~7 days), withdrawal can be claimed on L1

**Note:** The L2 transaction looks like a regular transaction. The L1 claim is a separate L1 transaction.

## Current ChainETL Implementation

### What's Supported

ChainETL currently extracts and stores the **standard fields** that are common to both Ethereum and Base:
- Block number
- Block hash
- Parent hash
- Timestamp
- Gas used
- Gas limit

### What's Not Yet Supported

The following L2-specific features are **not yet** persisted to the database:
- `l1BlockNumber`
- `l1BatchNumber`
- `l1Timestamp`
- `sequenceNumber`
- Deposit transactions (as a separate entity)
- Withdrawal transactions (with L1 claim tracking)

### Why This Works

The current implementation works well because:
1. **Core sync functionality** doesn't require L2-specific fields
2. **Checkpoint system** works with standard block numbers and hashes
3. **Data integrity** is maintained - all standard fields are accurate
4. **Multi-chain support** uses the same schema for both L1 and L2

### Accessing L2 Fields

Even though ChainETL doesn't persist L2-specific fields to the database, they are available in the RPC response. Developers can:

1. **Extend the Block model** to include L2 fields
2. **Create custom extractors** that capture additional fields
3. **Post-process** by re-fetching specific blocks to get L2 metadata

## Future Enhancements

### Planned Features

We plan to add L2-specific support in future versions:

**Phase 1: Extended Block Model**
- Add optional L2 fields to Block model
- Store `l1BlockNumber`, `l1BatchNumber`, `l1Timestamp`
- Backward compatible (fields nullable for L1 chains)

**Phase 2: Transaction Types**
- Detect and flag deposit transactions
- Store deposit metadata (source hash, L1 block)
- Track withdrawal initiation

**Phase 3: Cross-Chain Analysis**
- Link L2 blocks to their L1 anchors
- Calculate settlement times
- Track batch economics

### Schema Design Considerations

```sql
-- Possible future schema extensions
ALTER TABLE blocks ADD COLUMN l1_block_number INTEGER;
ALTER TABLE blocks ADD COLUMN l1_batch_number INTEGER;
ALTER TABLE blocks ADD COLUMN l1_timestamp INTEGER;
ALTER TABLE blocks ADD COLUMN sequence_number INTEGER;

-- Deposit transactions table
CREATE TABLE deposit_transactions (
  id SERIAL PRIMARY KEY,
  l2_block_number INTEGER NOT NULL,
  l2_tx_hash VARCHAR(66) NOT NULL,
  l1_block_number INTEGER NOT NULL,
  source_hash VARCHAR(66) NOT NULL,
  from_address VARCHAR(42) NOT NULL,
  to_address VARCHAR(42) NOT NULL,
  amount NUMERIC NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);
```

## References

### Base Documentation
- [Base Architecture](https://docs.base.org/architecture/)
- [OP Stack Specs](https://specs.optimism.io/)

### Related Projects
- [Optimism Block Explorer](https://optimistic.etherscan.io/)
- [Base Block Explorer](https://basescan.org/)

## Questions?

If you're working with L2-specific fields and need guidance:
1. Check the Base RPC response to see available fields
2. Review the BaseL2Extractor implementation
3. Consider extending the Block model for your use case
4. Open an issue or discussion on GitHub
