> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set L2

> Overview of the Set L2 chain, anchoring, and verification flow.

<Info>
  **Early preview.** This section describes a surface that is not generally available; interfaces
  here may change without notice. Talk to us before building against it.
</Info>

# Set

```bash theme={null}
git clone https://github.com/stateset/set.git
cd set
```

Set is an Ethereum Layer-2 (L2) network built on the **OP Stack**, designed for **commerce**. It offers faster, cheaper, and cryptographically verifiable transactions by leveraging optimistic rollups with Merkle root anchoring.

## Table of Contents

* [Architecture](#architecture)
* [Key Features](#key-features)
* [Chain Configuration](#chain-configuration)
* [Directory Structure](#directory-structure)
* [Technology Stack](#technology-stack)
* [Quick Start](#quick-start)
  * [Local Development (Anvil)](#local-development-anvil)
  * [Full Devnet](#full-devnet)
* [Smart Contracts](#smart-contracts)
  * [SetRegistry](#setregistry)
  * [SetPaymaster](#setpaymaster)
* [Anchor Service](#anchor-service)
* [Integration with stateset-sequencer](#integration-with-stateset-sequencer)
* [Docker Deployment](#docker-deployment)
* [Testing](#testing)
* [Deployment Checklist](#deployment-checklist)
* [Monitoring](#monitoring)
* [Security](#security)
* [Decentralization and Fault Proofs](#decentralization-and-fault-proofs)
* [Scorecard](#scorecard)
* [Troubleshooting](#troubleshooting)
* [Resources](#resources)

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                             SET L2 (84532001)                           │
│                      (Commerce-Optimized OP Stack)                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐ │
│  │   op-geth    │  │   op-node    │  │  op-batcher  │  │ op-proposer │ │
│  │  (execution) │  │  (consensus) │  │   (batches)  │  │   (state)   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘  └─────────────┘ │
│         │                │                  │                │         │
│         └────────────────┼──────────────────┴────────────────┘         │
│                          │                                              │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                    Smart Contracts                                │  │
│  │  ┌─────────────────────────┐  ┌────────────────────────────────┐ │  │
│  │  │      SetRegistry        │  │         SetPaymaster           │ │  │
│  │  │  (Merkle root anchoring │  │  (Gas abstraction for          │ │  │
│  │  │   from sequencer)       │  │   merchant transactions)       │ │  │
│  │  └─────────────────────────┘  └────────────────────────────────┘ │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                          │                                              │
└──────────────────────────┼──────────────────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  │                  ▼
┌───────────────────┐      │      ┌─────────────────────────┐
│  Anchor Service   │      │      │  stateset-sequencer     │
│  (Rust)           │◄─────┴─────►│  (Off-chain commerce    │
│  - Health metrics │             │   event processing)     │
│  - Batch anchoring│             └─────────────────────────┘
└───────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      ETHEREUM SEPOLIA (L1) - 11155111                   │
│         OptimismPortal │ L2OutputOracle │ SystemConfig                  │
└─────────────────────────────────────────────────────────────────────────┘
```

## Key Features

| Feature | Description |
| - | - |
| **2-second block times** | Fast confirmations optimized for commerce operations |
| **Low gas fees** | EIP-1559 parameters tuned for merchant transactions |
| **Merkle root anchoring** | Verifiable event commitments from stateset-sequencer |
| **Multi-tenant isolation** | Per-tenant/store state tracking via `keccak256(tenantId, storeId)` |
| **Inclusion proof verification** | On-chain verification of off-chain events |
| **Gas sponsorship** | Merchants can sponsor user transactions via SetPaymaster |
| **Strict mode verification** | State chain continuity checking to prevent gaps/forks |

<Note>
  Chain configuration is consensus-critical: every validator must agree on it
  exactly. A node started with a different chain id, genesis hash or set of
  parameters does not run in a degraded mode — it fails to sync at all, which is
  the intended behaviour and the usual explanation for a node that never leaves
  catching-up.
</Note>

## Chain Configuration

| Parameter | Value |
| - | - |
| Chain ID | `84532001` |
| Block Time | 2 seconds |
| Gas Limit | 30M gas/block |
| L1 Settlement | Ethereum Sepolia (11155111) |
| Native Token | ETH |
| EVM Version | Cancun |
| OP Contracts Version | v1.8.0 |

## Directory Structure

```
set/
├── anchor/                     # Rust anchor service
│   ├── src/
│   │   ├── main.rs            # Entry point
│   │   ├── config.rs          # Configuration from env vars
│   │   ├── client.rs          # Sequencer API client
│   │   ├── service.rs         # Main anchor logic
│   │   ├── health.rs          # Health/metrics HTTP server
│   │   └── types.rs           # Data structures
│   └── tests/
│       └── integration.rs     # Integration tests
├── contracts/                  # Solidity smart contracts
│   ├── src/
│   │   ├── SetRegistry.sol    # Merkle root anchoring (433 lines)
│   │   └── commerce/
│   │       └── SetPaymaster.sol # Gas abstraction (558 lines)
│   ├── test/
│   │   ├── SetRegistry.t.sol  # Registry tests
│   │   └── SetPaymaster.t.sol # Paymaster tests
│   └── lib/                   # Dependencies (git submodules)
│       ├── forge-std/         # Foundry testing framework
│       └── openzeppelin-contracts/
├── op-stack/                   # OP Stack configuration
│   ├── deployer/              # op-deployer intent files
│   ├── batcher/               # Batch submission config
│   ├── proposer/              # State root submission config
│   ├── challenger/            # Dispute resolution config
│   └── sequencer/             # op-geth/op-node config
├── docker/                     # Docker Compose files
│   ├── docker-compose.yml     # Main local devnet
│   ├── docker-compose.sepolia.yml
│   ├── docker-compose.local.yml
│   └── config/                # JWT and node configs
├── scripts/                    # Deployment and management
│   ├── dev.sh                 # Local Anvil development helper
│   ├── anchor-devnet.sh       # Anchor service local helper
│   ├── deploy-set-contracts.sh
│   ├── deploy-l1.sh
│   ├── generate-genesis.sh
│   ├── reset-devnet.sh
│   ├── start-devnet.sh
│   ├── stop-devnet.sh
│   ├── quick-start-local.sh
│   └── install-op-stack.sh
├── config/                     # Chain configuration
│   ├── chain-config.toml     # L2 chain parameters
│   ├── local.env.example     # Local devnet env template
│   └── sepolia.env.example   # Sepolia env template
└── docs/                       # Documentation
    ├── README.md              # Architecture overview
    └── local_testing_guide.md # Anvil testing guide
```

## Technology Stack

### Languages & Frameworks

| Component | Technology | Version |
| - | - | - |
| Smart Contracts | Solidity | 0.8.20 |
| Contract Framework | Foundry (Forge) | Latest |
| Anchor Service | Rust | 2021 Edition |
| Async Runtime | Tokio | Full features |
| Ethereum Client | Alloy | 0.9 |
| HTTP Server | Axum | 0.8 |
| Scripting | Bash | - |

### OP Stack Components

| Component | Purpose |
| - | - |
| op-geth | L2 execution client (EVM) |
| op-node | L2 consensus client |
| op-batcher | Submits transaction batches to L1 |
| op-proposer | Submits state roots to L1 |
| op-challenger | Dispute resolution |

### Dependencies

**Solidity:**

* OpenZeppelin Contracts (Upgradeable patterns)
* Forge-std (Testing)

**Rust:**

* `tokio` - Async runtime
* `alloy` - Ethereum interactions
* `axum` - HTTP server for health endpoints
* `tracing` - Structured logging
* `serde` - Serialization
* `reqwest` - HTTP client

## Quick Start

### Local Development (Anvil)

The fastest way to get started for development and testing:

```bash theme={null}
# 1. Start local Anvil node (Chain ID: 84532001, 2s blocks)
./scripts/dev.sh start

# 2. Deploy contracts to local Anvil
./scripts/dev.sh deploy

# 3. Run contract tests
./scripts/dev.sh test

# 4. Check node status
./scripts/dev.sh status

# 5. Fund a test account
./scripts/dev.sh fund 0xYourAddress

# Other commands
./scripts/dev.sh accounts  # List pre-funded accounts
./scripts/dev.sh console   # Open Foundry console
```

**Pre-funded Test Accounts:**

| Account | Address | Private Key |
| - | - | - |
| Account 0 | `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266` | `0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80` |
| Account 1 | `0x70997970C51812dc3A010C7d01b50e0d17dc79C8` | `0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d` |
| … | See `./scripts/dev.sh accounts` for all 10 accounts | |

### Full Devnet

For a complete L2 environment with all OP Stack components:

**Prerequisites:**

* Go 1.21+
* Rust 1.70+
* Docker & Docker Compose
* 2+ ETH on Sepolia (for deployment)

```bash theme={null}
# 1. Install OP Stack binaries
./scripts/install-op-stack.sh

# 2. Configure environment
cp config/sepolia.env.example config/sepolia.env
# Edit sepolia.env with your addresses and private keys

# 3. Deploy L1 contracts to Sepolia
./scripts/deploy-l1.sh

# 4. Generate L2 genesis
./scripts/generate-genesis.sh

# 5. Start the devnet
./scripts/start-devnet.sh

# Or use quick-start for minimal setup
./scripts/quick-start-local.sh
```

**Verify Chain is Running:**

```bash theme={null}
# Check L2 block number
cast block-number --rpc-url http://localhost:8547

# Get chain ID (should return 84532001)
cast chain-id --rpc-url http://localhost:8547

# Check sync status
curl -s http://localhost:8547 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'
```

## Smart Contracts

### SetRegistry

The SetRegistry contract stores batch commitments from the stateset-sequencer, enabling on-chain verification of off-chain commerce events.

**Key Features:**

* Multi-sequencer authorization
* State chain continuity verification
* Merkle inclusion proof verification
* Per-tenant/store isolation

**Core Functions:**

| Function | Description |
| - | - |
| `commitBatch()` | Submit a batch commitment with Merkle roots |
| `verifyInclusion()` | Verify an event is included in a committed batch |
| `getLatestStateRoot()` | Get current state root for a tenant/store |
| `setSequencerAuthorization()` | Admin: authorize/revoke sequencers |
| `setStrictMode()` | Enable/disable state chain verification |

**Example Usage:**

```solidity theme={null}
// Verify an order event was included in a batch
bool valid = registry.verifyInclusion(
    batchId,
    orderEventHash,
    merkleProof,
    leafIndex
);

// Get latest state root for a tenant/store
bytes32 stateRoot = registry.getLatestStateRoot(tenantId, storeId);
```

**Interact via CLI:**

```bash theme={null}
# Check if a sequencer is authorized
cast call $REGISTRY_ADDRESS "authorizedSequencers(address)" $SEQUENCER_ADDRESS

# Get batch commitment
cast call $REGISTRY_ADDRESS "batchCommitments(bytes32)" $BATCH_ID
```

### SetPaymaster

Gas abstraction for sponsored commerce transactions, allowing merchants to pay for user gas fees.

**Sponsorship Tiers:**

| Tier | Monthly Limit | Per-Tx Limit |
| - | - | - |
| Starter | 0.1 ETH | 0.001 ETH |
| Growth | 1 ETH | 0.01 ETH |
| Enterprise | 10 ETH | 0.1 ETH |

**Supported Operation Types:**

| Operation | Description |
| - | - |
| `ORDER_CREATE` | Creating new orders |
| `ORDER_UPDATE` | Updating order status |
| `PAYMENT_PROCESS` | Processing payments |
| `INVENTORY_UPDATE` | Updating inventory |
| `RETURN_PROCESS` | Processing returns |
| `COMMITMENT_ANCHOR` | Anchoring commitments |
| `OTHER` | Other operations |

**Features:**

* Per-transaction and daily/monthly spend limits
* Automatic refund of unused gas
* Category-based sponsorship
* Merchant dashboards

## Anchor Service

The anchor service (`set-anchor`) is a Rust service that bridges the stateset-sequencer to the SetRegistry contract on-chain.

### Building

```bash theme={null}
cd anchor
cargo build --release
```

### Running

```bash theme={null}
# Set required environment variables
export SET_REGISTRY_ADDRESS=0x...
export SEQUENCER_PRIVATE_KEY=0x...
export SEQUENCER_API_URL=http://localhost:3000
export L2_RPC_URL=http://localhost:8547
export ANCHOR_INTERVAL_SECS=60  # seconds
export MIN_EVENTS_FOR_ANCHOR=100

# Run the service
./target/release/set-anchor
```

**Local devnet:**

```bash theme={null}
./scripts/dev.sh anchor-start
./scripts/dev.sh anchor-smoke
```

Smoke overrides (optional):

```bash theme={null}
EVENT_LEAF_0=0x... EVENT_LEAF_1=0x... TENANT_ID=0x... STORE_ID=0x... \
NEW_STATE_ROOT=0x... ./scripts/dev.sh smoke
```

### Health Endpoints

The anchor service exposes health and metrics endpoints:

| Endpoint | Description |
| - | - |
| `GET /health` | Liveness probe (service is running) |
| `GET /ready` | Readiness probe (connected to chain and sequencer) |
| `GET /metrics` | Prometheus-format metrics |
| `GET /stats` | JSON statistics (anchored count, last anchor time, etc.) |

**Example:**

```bash theme={null}
# Check if service is ready
curl http://localhost:9090/ready

# Get metrics
curl http://localhost:9090/metrics
```

## Integration with stateset-sequencer

Set integrates with the stateset-sequencer through a two-phase process:

```
stateset-sequencer                    Anchor Service                    SetRegistry
       │                                    │                                │
       │  1. Create BatchCommitment         │                                │
       │     with Merkle roots              │                                │
       │                                    │                                │
       │  2. GET /v1/commitments/pending    │                                │
       │◄───────────────────────────────────│                                │
       │     Return unanchored batches      │                                │
       │                                    │                                │
       │                                    │  3. commitBatch(...)           │
       │                                    │───────────────────────────────►│
       │                                    │     Returns tx hash            │
       │                                    │◄───────────────────────────────│
       │                                    │                                │
       │  4. POST /v1/commitments/{id}/anchored                              │
       │◄───────────────────────────────────│                                │
       │     with chain_tx_hash             │                                │
       │                                    │                                │
```

**API Endpoints:**

| Endpoint | Method | Description |
| - | - | - |
| `/v1/commitments/pending` | GET | List unanchored commitments |
| `/v1/commitments/{id}/anchored` | POST | Notify of successful anchoring |

## Docker Deployment

### Local Devnet

```bash theme={null}
cd docker

# Start full local devnet (includes L1)
docker-compose up -d

# Check logs
docker-compose logs -f op-geth

# Stop
docker-compose down
```

### Sepolia Testnet

```bash theme={null}
cd docker

# Connects to real Ethereum Sepolia
docker-compose -f docker-compose.sepolia.yml up -d
```

### With Optional Services

```bash theme={null}
# With block explorer
docker-compose --profile explorer up -d

# With anchor service
docker-compose --profile anchor up -d
```

### Alternative L1 Clients

```bash theme={null}
# Using Nethermind as L1
docker-compose -f docker-compose.nethermind.yml up -d

# Using Reth as L1
docker-compose -f docker-compose.reth.yml up -d
```

## Testing

### Contract Tests

```bash theme={null}
cd contracts

# Run all tests
forge test

# Run with verbosity
forge test -vvv

# Run specific test
forge test --match-test testCommitBatch

# Run with gas reporting
forge test --gas-report

# Generate coverage
forge coverage
```

### Anchor Service Tests

```bash theme={null}
cd anchor

# Run unit tests
cargo test

# Run integration tests (requires Anvil running)
cargo test --test integration

# Run with logs
RUST_LOG=debug cargo test
```

## Deployment Checklist

### Accounts Setup

1. [ ] Generate 5 Ethereum accounts:
   * Admin (owns contracts)
   * Batcher (submits batches to L1)
   * Proposer (submits state roots)
   * Challenger (dispute resolution)
   * Sequencer (L2 block production)

2. [ ] Fund each account with 0.5+ Sepolia ETH

### Infrastructure

3. [ ] Configure Sepolia RPC endpoint (Infura/Alchemy)
4. [ ] Set up JWT secret for engine API authentication
5. [ ] Prepare data directories for persistent storage

### Deployment

6. [ ] Run `deploy-l1.sh` - Deploy OP Stack contracts to Sepolia
7. [ ] Run `generate-genesis.sh` - Create L2 genesis block
8. [ ] Start L2 nodes (op-geth, op-node)
9. [ ] Start op-batcher and op-proposer
10. [ ] Deploy SetRegistry to L2
11. [ ] Deploy SetPaymaster to L2
12. [ ] Start anchor service

### Verification

13. [ ] Verify L2 is producing blocks (2s intervals)
14. [ ] Verify batches are being submitted to L1
15. [ ] Test anchor service connectivity
16. [ ] Verify contract deployments with `cast`

## Monitoring

See `docs/monitoring.md` for SLOs, alert suggestions, and metric definitions.

### Key Metrics

| Metric | Expected | Alert Threshold |
| - | - | - |
| Block production | Every 2 seconds | > 10s gap |
| Batch submission | Every few minutes | > 30 min gap |
| Anchor lag | \< 5 minutes | > 15 minutes |
| L2 safe head lag | \< 10 blocks | > 100 blocks |

### Viewing Logs

```bash theme={null}
# op-geth logs
tail -f logs/op-geth.log

# op-node logs
tail -f logs/op-node.log

# Anchor service logs
docker-compose logs -f set-anchor

# All OP Stack logs
./scripts/start-devnet.sh logs
```

### Anchor Service Metrics

```bash theme={null}
# Prometheus metrics (HEALTH_PORT, default 9090)
curl http://localhost:9090/metrics

# JSON stats
curl http://localhost:9090/stats | jq
```

## Security

### Best Practices

* **Multi-sig admin**: Use a multisig wallet for admin/owner roles in production
* **Key management**: Never commit private keys; use environment variables or secret managers
* **Sequencer authorization**: Only authorize trusted sequencer addresses
* **Strict mode**: Enable strict mode in production to prevent state gaps
* **Threat model**: Review and maintain `docs/threat-model.md`
* **Operations runbook**: Keep `docs/runbook.md` current with incident response steps
* **Governance policy**: Maintain `docs/security.md` for upgrade and key management

### Pre-Production Checklist

* [ ] Smart contract audit completed
* [ ] Penetration testing of anchor service
* [ ] Key rotation procedures documented
* [ ] Incident response plan prepared
* [ ] Monitoring and alerting configured

## Decentralization and Fault Proofs

See `docs/decentralization.md` and `docs/fault-proofs.md` for the phased
decentralization plan and fault-proof operations. Validate production config with:

```bash theme={null}
./scripts/validate-ops-config.sh --mode testnet --require-fault-proofs --require-admin-policy
```

Verify L1 settlement contracts:

```bash theme={null}
./scripts/check-l1-settlement.sh --env-file config/sepolia.env --mode testnet --require-addresses
```

## Scorecard

See `docs/scorecard.md` for the 10/10 rubric and progress tracking. Supporting
docs include `docs/threat-model.md`, `docs/security.md`, `docs/runbook.md`, and
`docs/architecture.md`.

## Troubleshooting

### Common Issues

**L2 not producing blocks:**

```bash theme={null}
# Check op-node sync status
curl -s http://localhost:9545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' | jq

# Verify L1 connection
curl -s http://localhost:8545 -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

**Anchor service not connecting:**

```bash theme={null}
# Check health endpoint
curl http://localhost:9090/ready

# Verify environment variables
echo $SET_REGISTRY_ADDRESS
echo $L2_RPC_URL

# Check sequencer API
curl http://localhost:3000/v1/commitments/pending
```

**Contract deployment failing:**

```bash theme={null}
# Ensure you have ETH
cast balance $DEPLOYER_ADDRESS --rpc-url http://localhost:8547

# Check gas prices
cast gas-price --rpc-url http://localhost:8547

# Verify RPC is responding
cast chain-id --rpc-url http://localhost:8547
```

**Tests failing:**

```bash theme={null}
# Update dependencies
cd contracts && forge update

# Clean and rebuild
forge clean && forge build

# Run with more verbosity
forge test -vvvv
```

## Resources

### Documentation

* [OP Stack Documentation](https://docs.optimism.io/operators/chain-operators)
* [Optimism Monorepo](https://github.com/ethereum-optimism/optimism)
* [Foundry Book](https://book.getfoundry.sh/)
* [Alloy Documentation](https://alloy.rs/)

### Project Documentation

* [Local Testing Guide](docs/local_testing_guide.md)
* [Architecture Overview](docs/architecture.md)
* [Scorecard](docs/scorecard.md)
* [Toolchain Versions](docs/toolchain.md)
* [Monitoring and SLOs](docs/monitoring.md)
* [Security and Governance](docs/security.md)
* [Node Operator Guide](docs/node-operators.md)
* [Integration Example](docs/integration-example.md)
* [Block Explorer and Indexing](docs/explorer.md)
* [Bridge and Onramp Support](docs/bridge.md)
* [Operations History](docs/operations-history.md)
* [SDK](sdk/README.md)
* [Audit Report](docs/audit-report.md)
* [Governance Evidence](docs/governance-evidence.md)
* [Fault Proof Exercise Log](docs/fault-proof-exercise.md)
* [Decentralization Roadmap](docs/decentralization.md)
* [Fault Proof Operations](docs/fault-proofs.md)
* [Threat Model](docs/threat-model.md)
* [Operations Runbook](docs/runbook.md)

### Related Projects

* [StateSet Sequencer](../stateset-sequencer/) - Off-chain commerce event processing
* [StateSet Network](../) - Parent project documentation

## License

MIT

## Next steps

<CardGroup cols={2}>
  <Card title="Set L2" icon="cube" href="/set/stateset-set-l2">
    The L2 in overview.
  </Card>

  <Card title="Verification" icon="circle-check" href="/set/stateset-set-l2-verification">
    Proving an event was anchored.
  </Card>

  <Card title="Compliance proofs" icon="shield-check" href="/set/stateset-set-l2-compliance-proof">
    Proving a policy held over data you never reveal.
  </Card>

  <Card title="Sequencer architecture" icon="sitemap" href="/stateset-sequencer-architecture">
    What feeds the chain.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.