> For the complete documentation index, see [llms.txt](https://celopg.gitbook.io/tokenmanager/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://celopg.gitbook.io/tokenmanager/smart-contracts/overview.md).

# Contracts Overview

A token factory system for ERC-20 tokens across Ethereum L1 and Celo L2 (Optimism Superchain compatible). Built with Foundry. MIT licensed.

## Capabilities

* Create ERC-20 tokens with custom name, symbol, decimals, and supply limits
* Deploy on L1 or L2 with full bridge support (Optimism Standard Bridge)
* Upgrade tokens and factories (UUPS proxies)

## Feature matrix

| Feature                                    | L1Token | L2SuperChainToken |
| ------------------------------------------ | ------- | ----------------- |
| ERC-20 + Permit (EIP-2612)                 | ✅       | ✅                 |
| Upgradeable (UUPS) · Pausable · Max supply | ✅       | ✅                 |
| Owner mint/burn                            | ✅       | ✅                 |
| Bridge integration                         | ❌       | ✅                 |
| Superchain (ERC-7802)                      | ❌       | ✅                 |

## Core contracts

| Contract                                              | Role                                                                      |
| ----------------------------------------------------- | ------------------------------------------------------------------------- |
| `L1Token.sol`                                         | ERC-20 for Ethereum L1                                                    |
| `L2SuperChainToken.sol`                               | Superchain-compatible ERC-20 for Celo L2                                  |
| `BaseTokenFactory.sol`                                | Shared factory logic: UUPS upgradeability, CREATE2 deployment             |
| `L1TokenFactory.sol` / `L2SuperChainTokenFactory.sol` | Per-chain factories                                                       |
| `FactoryInitializer` / `TokenInitializer`             | CREATE2 placeholders that reserve identical proxy addresses across chains |

Interfaces: `IToken`, `IFactory`, `IERC7802`, `IOptimismMintableERC20`, `ISemver`.

## Storage pattern

All contracts use **EIP-7201 namespaced storage** to prevent collisions during upgrades:

```solidity
// keccak256(abi.encode(uint256(keccak256("namespace.storage.name")) - 1)) & ~bytes32(uint256(0xff));
bytes32 private constant STORAGE_LOCATION = 0x...;
```

## Extensibility

New factories inherit `BaseTokenFactory` to get upgradeability and deterministic deployment out of the box, implementing only custom creation logic.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://celopg.gitbook.io/tokenmanager/smart-contracts/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.