feat: add custom gas token

specs/interop/managed-node.md

@@ -56,7 +56,7 @@ the file containing the jwt secret should be provided to the supervisor instance
 ## Node `->` Supervisor
 
 Events that a supervisor should subscribe to, originating from the node, handled by the supervisor. For the used types,
-refer [this](#Types) section.
+refer [this](#types) section.
 
 Every event sent from the node is of type `ManagedEvent` whose fields are populated with the events that occurred. All
 non-null events are sent at once. The other fields are omitted.

specs/protocol/jovian/bridges.md

@@ -0,0 +1,19 @@
+# Bridges
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Overview](#overview)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Overview
+
+ETH bridging functions MUST revert when Custom Gas Token mode is enabled and the function involves ETH transfers.
+This revert behavior is necessary because when a chain operates in Custom Gas Token mode, ETH is no longer the native
+asset used for gas fees and transactions. The chain has shifted to using a different native asset entirely.
+Allowing ETH transfers could create confusion about which asset serves as the native currency, potentially leading
+to user errors and lost funds. Additionally, the custom gas token's supply is managed independently through
+dedicated contracts (`NativeAssetLiquidity` and `LiquidityController`), and combining ETH bridging with custom gas
+token operations introduces additional complexity to supply management and accounting.

specs/protocol/jovian/messengers.md

@@ -0,0 +1,13 @@
+# Cross Domain Messengers
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Message Passing](#message-passing)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Message Passing
+
+The `sendMessage` function MUST revert when Custom Gas Token mode is enabled and `msg.value > 0`.

specs/protocol/jovian/optimism-portal.md

@@ -0,0 +1,42 @@
+# Optimism Portal
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Definitions](#definitions)
+  - [Custom Gas Token Flag](#custom-gas-token-flag)
+- [Rationale](#rationale)
+- [Function Specification](#function-specification)
+  - [isCustomGasToken](#iscustomgastoken)
+  - [donateETH](#donateeth)
+  - [depositTransaction](#deposittransaction)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Definitions
+
+### Custom Gas Token Flag
+
+The **Custom Gas Token Flag** (`isCustomGasToken`) is a boolean value that indicates
+whether the chain is operating in Custom Gas Token mode.
+
+## Rationale
+
+The OptimismPortal's ETH-related logic must revert when Custom Gas Token mode is enabled to prevent ETH from
+acting as the native asset. Since the client side does not discern native asset supply creation, allowing
+ETH deposits would incorrectly imply that it can be minted in the chain.
+
+## Function Specification
+
+### isCustomGasToken
+
+Returns true if the gas token is a custom gas token, false otherwise.
+
+### donateETH
+
+- MUST revert if `isCustomGasToken()` returns `true` and `msg.value > 0`.
+
+### depositTransaction
+
+- MUST revert if `isCustomGasToken()` returns `true` and `msg.value > 0`.

specs/protocol/jovian/overview.md

@@ -6,6 +6,9 @@
 
 - [Execution Layer](#execution-layer)
 - [Consensus Layer](#consensus-layer)
+- [Smart Contracts](#smart-contracts)
+  - [Core L2 Smart Contracts](#core-l2-smart-contracts)
+    - [Custom Gas Token](#custom-gas-token)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -14,3 +17,45 @@ This document is not finalized and should be considered experimental.
 ## Execution Layer
 
 ## Consensus Layer
+
+## Smart Contracts
+
+- [Predeploys](./predeploys.md)
+- [Bridges](./bridges.md)
+- [Cross Domain Messengers](./messengers.md)
+- [System Config](./system-config.md)
+- [Withdrawals](./withdrawals.md)
+- [Optimism Portal](./optimism-portal.md)
+
+### Core L2 Smart Contracts
+
+#### Custom Gas Token
+
+The Custom Gas Token (CGT) feature allows OP Stack chains to use a native asset other than ETH as the gas
+currency. This implementation introduces a streamlined approach with minimal core code intrusion through a
+single `isCustomGasToken()` flag.
+
+Key components:
+
+- **NativeAssetLiquidity**: A predeploy contract containing pre-minted native assets, deployed only for
+  CGT-enabled chains.
+- **LiquidityController**: An owner-governed mint/burn router that manages supply control, deployed only for
+  CGT-enabled chains.
+- **ETH Transfer Blocking**: When CGT is enabled, all ETH transfer flows in bridging methods are disabled via
+  the `isCustomGasToken()` flag.
+- **ETH Bridging Disabled**: ETH bridging functions in `L2ToL1MessagePasser` and `OptimismPortal` MUST revert
+  when CGT mode is enabled to prevent confusion about which asset is the native currency.
+- **Native Asset Bridging**: Custom Gas Token chains use dedicated CGT bridges (`L1CGTBridge` and
+  `L2CGTBridge`) for native asset transfers between L1 ERC20 tokens and L2 native assets.
+- **WETH as ERC20**: ETH can still be bridged as WETH using the standard `OptimismMintableERC20` bridging
+  path through `L2StandardBridge`.
+
+OP Stack chains that use a native asset other than ETH (or the native asset of the settlement layer)
+introduce custom requirements that go beyond the current supply management model based on deposits and
+withdrawals. This architecture decouples and winds down the native bridging for the native asset, shifting
+the responsibility for supply management to the application layer. The chain operator becomes responsible
+for defining and assigning meaning to the native asset, which is managed through a new set of predeployed
+contracts.
+
+This approach preserves full alignment with EVM equivalence and client-side compatibility as provided by the
+standard OP Stack. No new functionalities outside the execution environment are required to make it work.