[Chore] Document contract interaction (#926)

* placeholder docs

* adding more documentation

* documentation work in progress

* add main linking or index documents

* add a link images

* add messaging flows

* linking operator documentation and folder cleanup

* use correct pathing on tokenbridge.md

* link workflow documents

* add function signatures

* remove welcome to

* cross reference blob submission and finalization

* remove confusing text

* use better definition of shnarf

* fix broken link

* add charter, diagram and address book

* docs(LSC): Rename security-council-charter-v1.3.md to security-council-charter.md

Signed-off-by: Julien Marchand <julien-marchand@users.noreply.github.com>

* Update contracts/docs/mainnet-address-book.csv

Co-authored-by: Julien Marchand <julien-marchand@users.noreply.github.com>
Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com>

---------

Signed-off-by: Julien Marchand <julien-marchand@users.noreply.github.com>
Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com>
Co-authored-by: Julien Marchand <julien-marchand@users.noreply.github.com>

contracts/README.md

@@ -11,6 +11,8 @@ The Linea Rollup, which contains the L1MessageService, is the smart contract tha
 - Submission of L2 compressed data using EIP-4844 blobs or via calldata.
 - Finalization of L2 state on L1 using a Zero Knowledge Proof verified via a Plonk verifier contract.
 
+Workflow Documentation [Linea Rollup Workflows](./docs/workflows/LineaRollup.md)
+
 ## Verifiers
 A Plonk based verifier contract is responsible for: 
 - verifying the Zero Knowledge proof that proves correct
@@ -25,13 +27,16 @@ The L2MessageService is the L2 smart contract that is responsible for:
 - Anchoring of L1 to L2 Message hashes for later claiming.
 - Claiming of messages sent from L1 to L2.
 
+Workflow Documentation [L2MessageService Workflows](./docs/workflows/L2MessageService.md)
+
 ## Linea Canonical Token Bridge
 
 The Canonical Token Bridge (TokenBridge) is a canonical ERC20 token brige between Ethereum and Linea networks.
 
 The TokenBridge utilises the L1MessageService and the L2MessageService for the transmission of messages between each layer's TokenBridge.
 
-Documentation: [Token Bridge](./docs/linea-token-bridge.md)
+Deployment Documentation: [Token Bridge](./docs/linea-token-bridge.md)
+Workflow Documentation [Token Bridge Workflows](./docs/workflows/TokenBridge.md)
 
 # Style Guide
 Please see the [Smart Contract Style Guide](./docs/contract-style-guide.md) for in depth smart contract layout and styling.

contracts/docs/linea-token-bridge.md

@@ -82,7 +82,7 @@ npx hardhat test
 
 ### Test coverage
 
-This project uses the Hardhat plugin [solidity-coverage](https://github.com/sc-forks/solidity-coverage/blob/master/HARDHAT_README.md) to assess the overall coverage of the unit tests.
+This project uses the Hardhat plugin [solidity-coverage](https://github.com/sc-forks/solidity-coverage/blob/master/README.md) to assess the overall coverage of the unit tests.
 To generate a boilerplate report, use the following command:
 
 ```shell

contracts/docs/mainnet-address-book.csv

@@ -0,0 +1,40 @@
+address,name,chainId
+0x051F1D88f0aF5763fB888eC4378b4D8B29ea3319,L1 TokenBridge,1
+0x971f46a2852d11D59dbF0909e837cfd06f357DeB,L1 BridgedToken Template,1
+0x892bb7EeD71efB060ab90140e7825d8127991DD3,L1 Main Security Council Safe,1
+0xA11BA93aFbD6D18e26fefdB2C6311dA6c9b370D6,L2 ERC20 ProxyAdmin,59144
+0x353012dc4a9A6cF55c941bADC267f82004A8ceB9,L2 TokenBridge,59144
+0xE798695d2e78f7caeb5BbF3385433959324c02c0,L2 BridgedToken Template,59144
+0xA219439258ca9da29E9Cc4cE5596924745e12B93,USDT,59144
+0x4AF15ec2A0BD43Db75dd04E62FAA3B8EF36b00d5,DAI,59144
+0x3aAB2285ddcDdaD8edf438C1bAB47e1a9D05a9b4,WBTC,59144
+0x37cc52fe20c2E13DD68728e0e595761a8cEad306,BUSD,59144
+0x5B16228B94b68C7cE33AF2ACc5663eBdE4dCFA2d,LINK,59144
+0xB5beDd42000b71FddE22D3eE8a79Bd49A568fC8F,wstETH,59144
+0x6bAA318CF7C51C76e17ae1EbE9Bbff96AE017aCB,ApeCoin,59144
+0x0ECE76334Fb560f2b1a49A60e38Cf726B02203f0,Compound,59144
+0xf5cc7604a5ef3565b4D2050D65729A06B68AA0bD,L2 Linea Safe,59144
+0xd19d4B5d358258f05D7B411E21A1460D11B0876F,L1 MessageService,1
+0x508Ca82Df566dCD1B0DE8296e70a96332cD644ec,L2 MessageService,59144
+0xd6B95c960779c72B8C6752119849318E5d550574,L1 Main TimelockController,1
+0xF5058616517C068C7b8c7EbC69FF636Ade9066d6,L1 Main ProxyAdmin,1
+0xc808BfCBeD34D90fa9579CAa664e67B9A03C56ca,L2 Main TimelockController,59144
+0x1E1f6F22f97b4a7522D8B62e983953639239774E,L2 Main ProxyAdmin,59144
+0x46eA7a855DA88FBC09cc59de93468E6bFbf0d81b,L1 Postman EOA,1
+0x46eA7a855DA88FBC09cc59de93468E6bFbf0d81b,L2 Postman EOA,59144
+0xc1C6B09D1eB6fCA0fF3cA11027E5Bc4AeDb47F67,L2 Anchorer EOA,59144
+0x6dD3120E329dC5FaA3d2Cf65705Ef4f6486F65F7,L1 Deployer EOA,1
+0x49ee40140E522651744e1C27828c76eE92802833,L2 Deployer EOA,59144
+0x6D7A601bE312A3678E9d0577DF3A0b01e62aDABf,L1 Finance Safe,1
+0x4761458bE94F60868F496BBAFDb2E0Abaa3231B6,L2 Finance Safe,59144
+0xd83af4fbD77f3AB65C3B1Dc4B38D7e67AEcf599A,L2 LineaVoyageXP Token LXP,59144
+0xBfF4a03A355eEF7dA720bBC7878F9BdBBE81fe6F,(old) PlonkVerifierForMultiTypeDataAggregation Alpha v3.4,1
+0x96B3a15257c4983A6fE9073D8C91763433124B82,L2 LineaSurgeXP Token LXP-L,59144
+0xdeFc3a33e18Dd479c5936F31497bc8650Dcfa070,L2 LineaSurgeXP Minter EOA,59144
+0x407e548C453d57DD56Bf6A74D15D940ad793489e,L2 ENS Profanity Safe,59144
+0xeCa8A765ebc86C95DDF8F0aAc4838454EA60cbeF,L2 ENS Reserved Safe,59144
+0x50130b669B28C339991d8676FA73CF122a121267,ENS Registry,59144
+0x46d2f319fd42165d4318f099e143dea8124e9e3e,L1 Data Submission Operator EOA,1
+0x52ff08f313a00a54e3beffb5c4a7f7446efb6754,L1 Finalization Operator EOA,1
+0xe5D7C2a44FfDDf6b295A15c148167daaAf5Cf34f,WETH9,59144
+0x41a4d93d09f4718fe899d12a4ad2c8a09104bdc7,PlonkVerifierMainnetFull,1

contracts/docs/security-council-charter.md

@@ -0,0 +1,114 @@
+# Linea Security Council Charter
+
+This Charter outlines the structure and responsibilities of the Linea Security Council (LSC) and its members.
+
+The Linea Security Council is composed of twelve members responsible for Linea's operational security and functionality. They operate a Gnosis Safe multisig wallet as signatories of 9/12 multisigs on the Ethereum and Linea blockchains. LSC members are tasked with creating, reviewing, and signing multisig transactions to upgrade and configure contracts on L1 Ethereum Mainnet and L2 Linea Mainnet, while protecting the chain and its users from any malicious change linked to the Security Council.
+
+This charter sets forth the operations of the LSC and the responsibilities of its members. It provides operational guidelines to ensure the reliability, security, and efficiency of the Linea Security Council's activities and satisfy the requirements of Stages 0, 1, and 2 of the [L2Beat framework](https://l2beat.com/scaling/projects/linea#stage).
+
+# Scope and responsibilities
+
+LSC members are tasked with reviewing and signing multisig transactions to implement changes requested by Linea governance, on Ethereum Mainnet or Linea Mainnet. LSC members are required to carry out their responsibilities in a manner consistent with this Charter and pursuant to the decisions of Linea governance, while protecting the chain and its users from any malicious change linked to the Security Council. These operations include but are not limited to:
+
+- Scheduling and Executing smart-contract upgrades and verifiers (based on OpenZeppelin Timelock controller)  
+- Changing role designations (based on OZ and Zodiac roles)  
+- Operationally configuring contracts  
+- Signing unpause transactions (when an emergency pause was triggered)  
+- Changing the signatories and threshold of the LSC
+
+The contracts under the responsibility of the Security Council are (but not limited to):
+
+1. The L1 and L2 multisigs themselves  
+2. Finalization and bridge-related contracts:  
+   1. L1 Rollup+MessageService, L2 MessageService  
+   2. L1 and L2 TokenBridge  
+   3. L1 Verifiers (indirectly) and the verification key of the zkEVM circuit  
+3. Voyage and Surge-related contracts:  
+   1. L2 LineaVoyageXP LXP  
+   2. L2 LineaSurgeXP Token LXP-L  
+4. ENS related contracts  
+   1. L2 PublicResolver, NameWrapper, Registrars, etc.   
+5. All TimelockController and ProxyAdmin related to the above contracts
+
+The verification key of the zkEVM circuit connects the contract to the zkEVM itself.
+
+# Signing process
+
+1. ## Notice of transaction \- Linea Association
+
+After Linea governance has determined that transactions should occur, the Linea Association shall send a notice of future transactions to be signed at least 48 hours before the actual signing request, with the context of the upcoming request and necessary inputs (audits, addresses on testnet, Github repository commits, …)
+
+2. ## Transaction crafting \- Linea Association
+
+The Linea Association will craft the transactions and send the transactions' descriptions (including Layer, Nonce, Action performed, and Verification). Linea team should try to give as much time as possible for the signature—48 hours minimum is recommended, more for complex operations.  
+A Tenderly simulation may be shared (only) in case of a scheduled transaction to facilitate the review.
+
+3. ## Transaction review \- Linea Security Council
+
+Security Council members must carefully examine the transactions before signing, specifically the Event tab. Linea provides a static document with [diagrams of all the contracts under the Security Council's responsibility](./workflows/diagrams/Linea-Security-Council.png) and a static [Address book](./mainnet-address-book.csv) to be imported inside the Gnosis Safe App to facilitate the review of transactions.
+
+The members of the Security Council are not expected to be able to review the smart contracts or the EVM circuits. Their review should ensure that:
+
+* The transaction does what is effectively intended by the Linea governance, as documented by the Linea team  
+* For smart-contract upgrades, the updates are audited, and the upgrade version is the same as the version audited. It includes all the recommended fixes and has already been deployed on the Sepolia and/or Linea Sepolia testnets.
+
+# Additional requirements
+
+## Eligibility
+
+Members of the LSC should be selected by the Linea Association in accordance with the following criteria:
+
+* Technical competency. Baseline proficiency with Linea Stack, experience with Safe infrastructure, and secure key management and signing standards.  
+* Reputation. Known, trusted standalone individuals or entities that have demonstrated consistent alignment with the Ethereum and Linea ethos.  
+* Geographic diversity. The number of participants who reside in any country should be less than 3\. The Linea Association will enforce this requirement as part of the eligibility screening process to avoid requiring participants to disclose their physical locations publicly.  
+* Diversity of interests. No more than 1 participant is associated with a particular entity, or that entity’s employees or affiliates, with the exception of Linea Association or Consensys employees.  
+* Alignment. Participants should not possess conflicts of interest that will regularly impact their ability to make impartial decisions in the performance of their role.
+
+In addition, all participants must sign a standard contract obligating the member to comply with this Charter and all Linea governance instructions, among other things, which the Linea Association will implement at its procedural discretion.
+
+Finally, standalone individuals or entities must publicly disclose their participation in the LSC when requested by the Linea Association.
+
+## Availability of Signing Device
+
+### Notification Requirement
+
+Members must give the council at least 48 hours’ notice if they anticipate that their wallet, private key or signing device will not be in their possession for more than 48 hours. This notice should be communicated via the official LSC communication channel and should include the expected duration of unavailability.
+
+### Immediate Loss Reporting
+
+In case of a lost private key or suspicion of its compromise, members must inform the other LSC members and the Association immediately. Prompt disclosure allows for swift action to mitigate potential risks. The LSC can quickly replace the compromised address among the multisig signers, ensuring continued security.
+
+## Liveness check
+
+The Linea Association might require LSC members to undergo periodic liveness checks. In these checks, participants must sign a message proving they can access their keys within a set time limit.
+
+## Communication and Response Times
+
+LSC members are required to communicate with other members and monitor the communication channel designated by the Linea Association \- currently a Telegram Channel.
+
+Each member must acknowledge all transaction requests made through the official LSC communication channel within 48 hours of receipt.
+
+After acknowledging a request, LSC members must take necessary action or respond fully within 48 hours unless prior notification regarding the unavailability of the signing device has been communicated.
+
+## Security requirements
+
+### Dedicated Signing Device
+
+Members must maintain their signing keys on a dedicated hardware device, such as a hardware wallet (e.g., Ledger, Trezor), used exclusively for LSC-related transactions. This practice minimizes the risk of unauthorized access and enhances the security of the signing process by isolating the signing keys from potentially compromised environments.
+
+Private keys owned by the Linea Security Council members should either be:
+
+- Keys managed by a single known individual or entity  
+- A multisig owned by a few known individuals within the entity
+
+### Continuous education and training
+
+Members should actively participate in relevant training sessions, workshops, and courses to the extent set forth by the Linea Association. Additionally, members should review and familiarize themselves with process documents. This preparedness is crucial for effective and timely responses during critical situations.
+
+## Conflict of Interest disclosure
+
+Members must disclose to the Linea Association any conflicts of interest regarding their duties in LSC, including personal investments, affiliations, or relationships that might influence their decisions. This disclosure should occur per-transaction, allowing members to abstain from voting or signing when a conflict exists.
+
+## Amendment
+
+This charter can be amended at any time. Amendment proposals can be put forward by the Association or any LSC member. Amendments will be accepted, and this Charter will be revised and republished upon a majority vote of the LSC and the concurrence of the Association.     

contracts/docs/workflows/L2MessageService.md

@@ -0,0 +1,44 @@
+# 📘 L2 Message Service Core Admin Workflows
+
+This collection of guides outlines key privileged workflows that govern the operation and upgrade lifecycle of the L2 Message Service smart contract. These workflows are designed to be executed via multisig-controlled safes, with strong verification and simulation practices to ensure safety and auditability.
+
+Each section below links to a dedicated Markdown document detailing that category of administrative action.
+
+---
+
+## 📑 Workflows
+
+### 1. 🔐 [Role Management](./administration/roleManagement.md)
+Granting or revoking operational roles on core contracts like LineaRollup, L2MessageService, and TokenBridge.
+
+### 2. ⏸️ [Pausing Features](./administration/pausing.md)
+How to pause contract functionality using well-defined pause types.
+
+### 3. ▶️ [Unpausing Features](./administration/unpausing.md)
+How to resume paused features using the same set of pause types.
+
+### 4. 🧮 [Rate Limiting](./administration/rateLimiting.md)
+How to configure or reset message throughput limits.
+
+### 5. ♻️ [Upgrading Without Reinitialization](./administration/upgradeContract.md)
+Securely upgrade the L2 Message Service or related contracts without calling reinitialization logic.
+
+### 6. 🔁 [Upgrading With Reinitialization](./administration/upgradeAndCallContract.md)
+Same upgrade flow but includes immediate initialization logic for the new implementation.
+
+### 7. 🧾 [Setting minimum L2 Fee](./administration/settingMinimumL2Fee.md)
+How to set the minimum L2 fee.
+
+### 8. 🧾 [L2 to L1 Messaging](./messaging/canonicalL2ToL1Messaging.md)
+View the L2 to L1 Messaging flow.
+
+### 9. 🧾 [L1 to L2 Messaging](./messaging/canonicalL1ToL2Messaging.md)
+View the L1 to L2 Messaging flow.
+
+---
+
+## ✅ Notes
+
+- All workflows require transaction simulation and parameter verification.
+- Some admin operations are governed by time-locked multisigs.
+- Contract addresses and roles are listed inline in each document.

contracts/docs/workflows/LineaRollup.md

@@ -0,0 +1,47 @@
+# 📘 LineaRollup Core Admin Workflows
+
+This collection of guides outlines key privileged workflows that govern the operation and upgrade lifecycle of the LineaRollup smart contract. These workflows are designed to be executed via multisig-controlled safes, with strong verification and simulation practices to ensure safety and auditability.
+
+Each section below links to a dedicated Markdown document detailing that category of administrative action.
+
+---
+
+## 📑 Workflows
+
+### 1. 🔐 [Role Management](./administration/roleManagement.md)
+Granting or revoking operational roles on core contracts like LineaRollup, L2MessageService, and TokenBridge.
+
+### 2. ⏸️ [Pausing Features](./administration/pausing.md)
+How to pause contract functionality using well-defined pause types.
+
+### 3. ▶️ [Unpausing Features](./administration/unpausing.md)
+How to resume paused features using the same set of pause types.
+
+### 4. 🧮 [Rate Limiting](./administration/rateLimiting.md)
+How to configure or reset message throughput limits.
+
+### 5. ♻️ [Upgrading Without Reinitialization](./administration/upgradeContract.md)
+Securely upgrade the LineaRollup or related contracts without calling reinitialization logic.
+
+### 6. 🔁 [Upgrading With Reinitialization](./administration/upgradeAndCallContract.md)
+Same upgrade flow but includes immediate initialization logic for the new implementation.
+
+### 7. 🧾 [Verifier Setting/Unsetting](./administration/verifierSettingUnsetting.md)
+How to configure or verifier contracts for ZK Proof verification.
+
+### 8. 🧾 [L1 to L2 Messaging](./messaging/canonicalL1ToL2Messaging.md)
+View the L1 to L2 Messaging flow.
+
+### 9. 🧾 [L2 to L1 Messaging](./messaging/canonicalL2ToL1Messaging.md)
+View the L2 to L1 Messaging flow.
+
+### 10. 📦 [Blob Submission and Finalization](./operations/blobSubmissionAndFinalization.md)
+See the blob and finalization submission flows.
+
+---
+
+## ✅ Notes
+
+- All workflows require transaction simulation and parameter verification.
+- Some admin operations are governed by time-locked multisigs.
+- Contract addresses and roles are listed inline in each document.

contracts/docs/workflows/TokenBridge.md

@@ -0,0 +1,44 @@
+# 📘 Canonical Token Bridge Core Admin Workflows
+
+This collection of guides outlines key privileged workflows that govern the operation and upgrade lifecycle of the Canonical Token Bridge smart contract. These workflows are designed to be executed via multisig-controlled safes, with strong verification and simulation practices to ensure safety and auditability.
+
+Each section below links to a dedicated Markdown document detailing that category of administrative action.
+
+---
+
+## 📑 Workflows
+
+### 1. 🔐 [Role Management](./administration/roleManagement.md)
+Granting or revoking operational roles on core contracts like LineaRollup, L2MessageService, and TokenBridge.
+
+### 2. ⏸️ [Pausing Features](./administration/pausing.md)
+How to pause contract functionality using well-defined pause types.
+
+### 3. ▶️ [Unpausing Features](./administration/unpausing.md)
+How to resume paused features using the same set of pause types.
+
+### 4. 🧮 [Rate Limiting](./administration/rateLimiting.md)
+How to configure or reset message throughput limits.
+
+### 5. ♻️ [Upgrading Without Reinitialization](./administration/upgradeContract.md)
+Securely upgrade the Canonical Token Bridge or related contracts without calling reinitialization logic.
+
+### 6. 🔁 [Upgrading With Reinitialization](./administration/upgradeAndCallContract.md)
+Same upgrade flow but includes immediate initialization logic for the new implementation.
+
+### 7. 🧾 [Other Token Bridge Specific Admin Functions](./administration/tokenBridge.md)
+How to execute `setCustomContract`,`removeReserved`, `setMessageService` and `setReserved`
+
+### 8. 🧾 [L1 to L2 Token Bridging](./messaging/canonicalL1ToL2TokenBridging.md)
+View the L1 to L2 Token Bridging flow.
+
+### 9. 🧾 [L2 to L1 Token Bridging](./messaging/canonicalL2ToL1TokenBridging.md)
+View the L2 to L1 Token Bridging flow.
+---
+
+## ✅ Notes
+
+- All workflows require transaction simulation and parameter verification.
+- Some admin operations are governed by time-locked multisigs.
+- Contract addresses and roles are listed inline in each document.
+

contracts/docs/workflows/administration/pausing.md

@@ -0,0 +1,79 @@
+
+# ⏸️ Pausing Features on the LineaRollup, TokenBridge, and L2MessageService (with Pause Types)
+
+This document outlines how a Safe Member can pause specific features on key Linea ecosystem contracts using well-defined pause types.
+
+**Note**: These contracts are governed by the [Security Council Charter](../../security-council-charter-v1.3.md).
+
+---
+
+## 🟧 Flow to Pause Features or Set Roles Allowed to Pause Types 
+
+**Actor:** Safe Member  
+**Actions:**
+
+- Selects a pause type from the list below
+- Adds a transaction via **Security Council** or **Operational Safe**
+- Targets the relevant **Proxy**
+- Calls the `pauseByType()` or `updatePauseTypeRole()` function with the selected values to unpause or set unpause type roles
+
+**Execution Path:**
+```
+Safe Member
+    → Security Council / Operational Safe
+        → targets Proxy
+            → calls pauseByType(type)
+                → signs and executes on-chain
+```
+
+**Verification Requirements:**
+- ✅ Function and parameters must be verified
+- ✅ Transaction hash and simulation results must be confirmed
+
+**Note:** Non-security council members are bound by cooldown period and timed expiry.
+
+## 🗂️ Function Signatures
+
+| 4bytes | Signature                              |
+|-------|---------------------------------------|
+| `0xe196fb5d`     | pauseByType(uint8)                   |
+| `0x3e9ebfc2`     | updatePauseTypeRole(uint8,bytes32)                   |
+
+---
+
+## 🗂️ Pause Types
+
+
+| Value | Address                              |
+|-------|---------------------------------------|
+| 1     | GENERAL_PAUSE_TYPE                   |
+| 2     | L1_L2_PAUSE_TYPE                     |
+| 3     | L2_L1_PAUSE_TYPE                     |
+| 4     | PROVING_SYSTEM_PAUSE_TYPE           |
+| 5     | CALLDATA_SUBMISSION_PAUSE_TYPE      |
+| 6     | FINALIZATION_PAUSE_TYPE             |
+| 7     | INITIATE_TOKEN_BRIDGING_PAUSE_TYPE  |
+| 8     | COMPLETE_TOKEN_BRIDGING_PAUSE_TYPE  |
+
+
+---
+
+## 🗂️ Mainnet Contract Addresses
+
+### 🔐 Security Council Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0x892bb72De7f1b06B08a09140e7825d1827991DD3` |
+| Linea     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319` |
+
+### 📦 Proxy Addresses
+
+| Contract           | Address                                           |
+|--------------------|---------------------------------------------------|
+| LineaRollup        | `0xd194Bd535d285f05D7B411E21A1460D11B0876F`       |
+| L1 TokenBridge     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319`       |
+| L2MessageService   | `0x508cA82Df566dCD1B0DE828967a0e96332cDc446`      |
+| L2 Token Bridge    | `0x353012d04a9A6cF5C941bADC267f82004A8ceB9`        |
+
+<img src="../diagrams/pausing.png">

contracts/docs/workflows/administration/rateLimiting.md

@@ -0,0 +1,67 @@
+
+# 🧮 Setting/Resetting Rate Limit Values on the LineaRollup and L2MessageService
+
+This process allows a designated Safe Member to set or reset rate limit values, either by defining a new limit or resetting the amount used during a period.
+
+**Note**: These contracts are governed by the [Security Council Charter](../../security-council-charter-v1.3.md).
+
+---
+
+## 🟧 Flow: Rate Limit Configuration
+
+**Actor:** Safe Member  
+**Actions:**
+
+- Adds a transaction via **Security Council** or **Operational Safe**
+- Targets the appropriate **Proxy**
+- Calls one of the following functions:
+  - `resetRateLimitAmount`
+  - `resetAmountUsedInPeriod`
+
+**Execution Path:**
+```
+Safe Member
+    → Security Council / Operational Safe
+        → targets Proxy
+            → calls resetRateLimitAmount or resetAmountUsedInPeriod
+                → signs and executes on-chain
+```
+
+**Verification Requirements:**
+- ✅ Transaction hash, parameters, and simulation must be verified
+
+
+## 🗂️ Function Signatures
+
+| 4bytes | Signature                              |
+|-------|---------------------------------------|
+| `0x557eac73`     | resetRateLimitAmount(uint256)                   |
+| `0xaea4f745`    | resetAmountUsedInPeriod()                   |
+
+---
+
+## 🗂️ All Mainnet Contract Addresses
+
+### 🔐 Security Council Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0x892bb72De7f1b06B08a09140e7825d1827991DD3` |
+| Linea     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319` |
+
+### 📦 Proxy Addresses
+
+| Contract           | Address                                           |
+|--------------------|---------------------------------------------------|
+| LineaRollup        | `0xd194Bd535d285f05D7B411E21A1460D11B0876F`       |
+| L2MessageService   | `0x508cA82Df566dCD1B0DE828967a0e96332cDc446`      |
+
+---
+
+## ✅ Security Summary
+
+- Changes require **multisig execution**
+- All function parameters must be **explicitly verified**
+- Simulation before execution is mandatory
+
+<img src="../diagrams/rateLimiting.png">

contracts/docs/workflows/administration/roleManagement.md

@@ -0,0 +1,117 @@
+
+# 🛡️ Granting or Revoking Roles
+
+This document outlines the procedure for assigning or removing specific roles on various components of the Linea ecosystem: **LineaRollup**, **L2MessageService**, and **TokenBridge**.
+
+**Note**: These contracts are governed by the [Security Council Charter](../../security-council-charter-v1.3.md).
+
+---
+
+## 🟧 Flow: Role Management
+
+**Actor:** Safe Member  
+**Actions:**
+
+- Adds a transaction via the **Security Council**
+- Targets the appropriate **Proxy**
+- Calls one of the following functions:
+  - `grantRole`
+  - `revokeRole`
+
+**Execution Path:**
+```
+Safe Member
+    → Security Council
+        → targets Proxy
+            → calls grantRole or revokeRole
+                → signs and executes on-chain
+```
+
+**Verification Requirements:**
+- ✅ Transaction hash, function selector, parameters, and simulation must be verified
+
+## 🗂️ Function Signatures
+
+| 4bytes | Signature                              |
+|-------|---------------------------------------|
+| `0x2f2ff15d`     | grantRole(bytes32,address)                   |
+| `0xd547741f`    | revokeRole(bytes32,address)                   |
+
+---
+
+## 🗂️ All Mainnet Contract Addresses
+
+### 🔐 Security Council Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0x892bb72De7f1b06B08a09140e7825d1827991DD3` |
+| Linea     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319` |
+
+### 📦 Proxy Addresses
+
+| Contract           | Address                                           |
+|--------------------|---------------------------------------------------|
+| LineaRollup        | `0xd194Bd535d285f05D7B411E21A1460D11B0876F`       |
+| L1 TokenBridge     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319`       |
+| L2MessageService   | `0x508cA82Df566dCD1B0DE828967a0e96332cDc446`      |
+| L2 Token Bridge    | `0x353012d04a9A6cF5C941bADC267f82004A8ceB9`        |
+
+---
+
+## 🔑 Available Roles by Component
+
+### 📘 LineaRollup Roles
+
+- `DEFAULT_ADMIN_ROLE`
+- `VERIFIER_SETTER_ROLE`
+- `VERIFIER_UNSETTER_ROLE`
+- `RATE_LIMIT_SETTER_ROLE`
+- `USED_RATE_LIMIT_RESETTER_ROLE`
+- `PAUSE_FINALIZATION_ROLE`
+- `UNPAUSE_FINALIZATION_ROLE`
+- `PAUSE_ALL_ROLE`
+- `UNPAUSE_ALL_ROLE`
+- `PAUSE_L1_L2_ROLE`
+- `UNPAUSE_L1_L2_ROLE`
+- `PAUSE_L2_L1_ROLE`
+- `UNPAUSE_L2_L1_ROLE`
+- `PAUSE_L2_BLOB_SUBMISSION_ROLE`
+- `UNPAUSE_L2_BLOB_SUBMISSION_ROLE`
+- `FORCED_TRANSACTION_SENDER_ROLE`
+
+### 📗 L2 Message Service Roles
+
+- `DEFAULT_ADMIN_ROLE`
+- `RATE_LIMIT_SETTER_ROLE`
+- `USED_RATE_LIMIT_RESETTER_ROLE`
+- `MINIMUM_FEE_SETTER_ROLE`
+- `PAUSE_ALL_ROLE`
+- `UNPAUSE_ALL_ROLE`
+- `PAUSE_L1_L2_ROLE`
+- `UNPAUSE_L1_L2_ROLE`
+- `PAUSE_L2_L1_ROLE`
+- `UNPAUSE_L2_L1_ROLE`
+
+### 📙 Token Bridge Roles
+
+- `DEFAULT_ADMIN_ROLE`
+- `SET_RESERVED_TOKEN_ROLE`
+- `REMOVE_RESERVED_TOKEN_ROLE`
+- `SET_CUSTOM_CONTRACT_ROLE`
+- `SET_MESSAGE_SERVICE_ROLE`
+- `SET_REMOTE_TOKENBRIDGE_ROLE`
+- `PAUSE_INITIATE_TOKEN_BRIDGING_ROLE`
+- `UNPAUSE_INITIATE_TOKEN_BRIDGING_ROLE`
+- `PAUSE_COMPLETE_TOKEN_BRIDGING_ROLE`
+- `UNPAUSE_COMPLETE_TOKEN_BRIDGING_ROLE`
+
+---
+
+## ✅ Security Summary
+
+- Role changes are **on-chain** and require **multisig execution**
+- Clear access separation across all core modules
+- Function selectors and role identifiers must be fully **verified and simulated**
+
+<img src="../diagrams/roleManagement.png">

contracts/docs/workflows/administration/settingMinimumL2Fee.md

@@ -0,0 +1,62 @@
+
+# 💸 Setting the Minimum Fee in Wei on the L2MessageService
+
+This process allows setting a new **minimum fee in Wei** to be paid for each L2 to L1 message on the L2MessageService contract.
+
+**Note**: These contracts are governed by the [Security Council Charter](../../security-council-charter-v1.3.md).
+
+---
+
+## 🟧 Flow: Minimum Fee Setting
+
+**Actor:** Safe Member  
+**Actions:**
+
+- Adds a transaction via **Security Council** or **Operational Safe**
+- Targets the **L2MessageService Proxy**
+- Calls the function `setMinimumFee`
+
+**Execution Path:**
+```
+Safe Member
+    → Security Council / Operational Safe
+        → targets L2MessageService Proxy
+            → calls setMinimumFee
+                → signs and executes on-chain
+```
+
+**Verification Requirements:**
+- ✅ Transaction hash, function, and simulation must be verified
+- ✅ Fee amount must be thoroughly reviewed before execution
+
+## 🗂️ Function Signatures
+
+| 4bytes | Signature                              |
+|-------|---------------------------------------|
+| `0x182a7506`     | setMinimumFee(uint256)                   |
+
+---
+
+## 🗂️ All Mainnet Contract Addresses
+
+### 🔐 Security Council Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Linea     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319` |
+
+### 📦 Proxy Address
+
+| Contract           | Address                                           |
+|--------------------|---------------------------------------------------|
+| L2MessageService   | `0x508cA82Df566dCD1B0DE828967a0e96332cDc446`      |
+
+---
+
+## ✅ Security Summary
+
+- Only council or operational safes may perform this action
+- **Fee changes** must be reviewed for economic impact
+- Requires **simulation and multisig confirmation**
+
+<img src="../diagrams/settingMinimumL2Fee.png">

contracts/docs/workflows/administration/tokenBridge.md

@@ -0,0 +1,71 @@
+
+# 🛠️ Executing TokenBridge Admin Functions (Excluding Pausing)
+
+This guide outlines how authorized safe members can execute core **TokenBridge admin functions** like setting or removing reserved addresses or setting custom contracts and message services.
+
+**Note**: These contracts are governed by the [Security Council Charter](../../security-council-charter-v1.3.md).
+
+---
+
+## 🟧 Flow: Admin Execution Path
+
+**Actor:** Safe Member  
+**Actions:**
+
+- Adds a transaction via **Security Council** or **Operational Safe**
+- Targets the relevant **TokenBridge Proxy**
+- Calls one of the following functions:
+  - `setCustomContract`
+  - `removeReserved`
+  - `setMessageService`
+  - `setReserved`
+
+**Execution Path:**
+```
+Safe Member
+    → Security Council / Operational Safe
+        → targets Proxy
+            → calls admin function
+                → signs and executes on-chain
+```
+
+**Verification Requirements:**
+- ✅ Transaction hash, parameters, and simulation must be verified
+
+## 🗂️ Function Signatures
+
+| 4bytes | Signature                              |
+|-------|---------------------------------------|
+| `0x1754f301`    | setCustomContract(address,address)                   |
+| `0xedc42a22`    | removeReserved(address)                   |
+| `0xbe46096f`    | setMessageService(address)                   |
+| `0xcdd914c5`    | setReserved(address)                   |
+
+---
+
+## 🗂️ All Mainnet Contract Addresses
+
+### 🔐 Security Council Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0x892bb72De7f1b06B08a09140e7825d1827991DD3` |
+| Linea     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319` |
+
+### 📦 Proxy Addresses
+
+| Contract         | Address                                           |
+|------------------|---------------------------------------------------|
+| L1 TokenBridge   | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319`       |
+| L2 Token Bridge  | `0x353012d04a9A6cF5C941bADC267f82004A8ceB9`        |
+
+---
+
+## ✅ Security Summary
+
+- Admin functions require **authorized multisig approval**
+- All actions are **on-chain and irreversible**
+- **Parameter verification and simulation** are mandatory before execution
+
+
+<img src="../diagrams/tokenBridge.png">

contracts/docs/workflows/administration/unpausing.md

@@ -0,0 +1,79 @@
+
+# ▶️ Unpausing Features on the LineaRollup, TokenBridge, and L2MessageService (with Pause Types)
+
+This document outlines how a Safe Member can unpause previously paused features on key Linea ecosystem contracts using the specified pause types.
+
+**Note**: These contracts are governed by the [Security Council Charter](../../security-council-charter-v1.3.md).
+
+---
+
+## 🟧 Flow to Unpause Features or Set Roles Allowed to Unpause Types 
+
+**Actor:** Safe Member  
+**Actions:**
+
+- Selects a pause type from the list below
+- Adds a transaction via **Security Council** or **Operational Safe**
+- Targets the relevant **Proxy**
+- Calls the `unPauseByType()` or `updateUnpauseTypeRole()` function with the selected values to unpause or set unpause type roles
+
+**Execution Path:**
+```
+Safe Member
+    → Security Council / Operational Safe
+        → targets Proxy
+            → calls pauseByType(type)
+                → signs and executes on-chain
+```
+
+**Verification Requirements:**
+- ✅ Function and parameters must be verified
+- ✅ Transaction hash and simulation results must be confirmed
+
+## 🗂️ Function Signatures
+
+| 4bytes | Signature                              |
+|-------|---------------------------------------|
+| `0x1065a399`     | unPauseByType(uint8)                   |
+| `0x52abf32d`     | updateUnpauseTypeRole(uint8,bytes32)                   |
+
+**Note:** Non-security council members are bound by cooldown period and timed expiry.
+
+---
+
+## 🗂️ Pause Types
+
+
+| Value | Address                              |
+|-------|---------------------------------------|
+| 1     | GENERAL_PAUSE_TYPE                   |
+| 2     | L1_L2_PAUSE_TYPE                     |
+| 3     | L2_L1_PAUSE_TYPE                     |
+| 4     | PROVING_SYSTEM_PAUSE_TYPE           |
+| 5     | CALLDATA_SUBMISSION_PAUSE_TYPE      |
+| 6     | FINALIZATION_PAUSE_TYPE             |
+| 7     | INITIATE_TOKEN_BRIDGING_PAUSE_TYPE  |
+| 8     | COMPLETE_TOKEN_BRIDGING_PAUSE_TYPE  |
+
+
+---
+
+## 🗂️ Mainnet Contract Addresses
+
+### 🔐 Security Council Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0x892bb72De7f1b06B08a09140e7825d1827991DD3` |
+| Linea     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319` |
+
+### 📦 Proxy Addresses
+
+| Contract           | Address                                           |
+|--------------------|---------------------------------------------------|
+| LineaRollup        | `0xd194Bd535d285f05D7B411E21A1460D11B0876F`       |
+| L1 TokenBridge     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319`       |
+| L2MessageService   | `0x508cA82Df566dCD1B0DE828967a0e96332cDc446`      |
+| L2 Token Bridge    | `0x353012d04a9A6cF5C941bADC267f82004A8ceB9`        |
+
+<img src="../diagrams/unpausing.png">

contracts/docs/workflows/administration/upgradeAndCallContract.md

@@ -0,0 +1,118 @@
+
+# 🔁 Upgrading a Contract While Calling a Reinitialize Function
+
+This guide outlines the process of **upgrading an upgradable contract** (e.g. **LineaRollup**, **L2MessageService**, **TokenBridge**) and calling a **reinitialize function** in the same transaction. This flow ensures integrity while applying critical upgrades.
+
+**Note**: These contracts are governed by the [Security Council Charter](../../security-council-charter-v1.3.md).
+
+---
+
+## 🟨 1. Deploy Implementation of Upgradable Contract
+
+**Actor:** Well-Known Deployer  
+**Actions:**
+
+- Deploys a new `Implementation` contract (e.g. `0xAbCd1234`)
+- The implementation:
+  - ✅ Must be **verified on Etherscan or Linescan**
+  - ✅ Must be **audited and bytecode-confirmed** by multiple auditors
+
+---
+
+## 🟧 2. Schedule Upgrade Transaction with Reinitialization
+
+**Timeframe:** Some time after deployment  
+**Actor:** Council Member  
+**Actions:**
+
+- Adds a **scheduled transaction** via the `Security Council Safe`
+- Routed through the `TimelockController`
+- Targets the `ProxyAdmin`
+- Calls `upgradeAndCall()`:
+  - Sets the proxy implementation to `0xAbCd1234`
+  - Immediately calls a **reinitialize function** (with or without parameters)
+
+**Verification Requirements:**
+- ✅ Transaction hash, details, and simulation must be verified
+- ✅ Function name, arguments, and reinit logic must be confirmed
+
+---
+
+## 🟩 3. Execute the Transaction After Delay
+
+**Timeframe:** After the configured delay  
+**Actor:** Council Member  
+**Actions:**
+
+- Adds and signs an **execute transaction** via the `Security Council Safe`
+- Routed through `TimelockController` → `ProxyAdmin` → `Proxy`
+- Executes `upgradeAndCall()` with:
+  - Implementation update
+  - Reinitialization function call
+
+**Outcome:**  
+➡️ Proxy’s implementation is upgraded and new state is initialized
+
+**Verification Requirements:**
+- ✅ Same payload as scheduled
+- ✅ Parameters and reinit target must be verified
+
+## 🗂️ Function Signatures
+
+| 4bytes | Signature                              |
+|-------|---------------------------------------|
+| `0x9623609d`     | upgradeAndCall(address,address,bytes)                   |
+
+---
+
+## 🗂️ Mainnet Contract Addresses
+
+### 🔐 Security Council Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0x892bb72De7f1b06B08a09140e7825d1827991DD3` |
+| Linea     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319` |
+
+### 🕓 TimelockController Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0xd6B9c960f779c728C6752119849318E5d550574`  |
+| Linea     | `0xC80BB1C8eD34D049bA579CaBa646e67B9A03C56a` |
+
+- Security Council has **Proposer and Executor roles**
+- Timelock owns `ProxyAdmin` contracts
+
+### 👤 Proxy Admin Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0xF50586165710C86c7b7EcC6B9F636Ada9606d6d6` |
+| Linea     | `0x1E16fF2297b4a7522Df8b62e99353692399774E` |
+
+### 🧑‍💻 Deployer Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0x6dD3120E329dC5FaA3d2c6f65705E4f648fF65F7` |
+| Linea     | `0x49ee40140E522651744c1C2878c76eE9f28028d33` |
+
+### 📦 Proxy Addresses
+
+| Contract           | Address                                           |
+|--------------------|---------------------------------------------------|
+| LineaRollup        | `0xd194Bd535d285f05D7B411E21A1460D11B0876F`       |
+| TokenBridge        | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319`       |
+| L2MessageService   | `0x508cA82Df566dCD1B0DE828967a0e96332cDc446`      |
+| L2 Token Bridge    | `0x353012d04a9A6cF5C541BADC267f82004A8ceB9`        |
+
+---
+
+## ✅ Security Summary
+
+- Upgrades and initializations happen **atomically** via `upgradeAndCall()`
+- Timelock and council governance ensures **review and delay**
+- Full **simulation and verification** required before execution
+
+<img src="../diagrams/upgradeAndCallContract.png">

contracts/docs/workflows/administration/upgradeContract.md

@@ -0,0 +1,116 @@
+
+# 🔄 Upgrading a Contract Without Calling a Reinitialize Function
+
+This guide outlines the secure process for upgrading a contract (e.g. **LineaRollup**, **L2MessageService**, **TokenBridge**) without calling a reinitialize function, via a timelock-protected upgrade flow.
+
+**Note**: These contracts are governed by the [Security Council Charter](../../security-council-charter-v1.3.md).
+
+---
+
+## 🟨 1. Deploy Implementation of Upgradable Contract
+
+**Actor:** Well-Known Deployer  
+**Actions:**
+
+- Deploys a new `Implementation` contract (e.g. `0xAbCd1234`)
+- The implementation:
+  - ✅ Must be **verified on Etherscan or Linescan**
+  - ✅ Must match **audited code** confirmed by multiple auditors
+  - ✅ Bytecode must be **verified** to match the audit
+
+## 🗂️ Function Signatures
+
+| 4bytes | Signature                              |
+|-------|---------------------------------------|
+| `0x99a88ec4`     | upgrade(address,address)                   |
+
+---
+
+## 🟧 2. Schedule Upgrade Transaction
+
+**Timeframe:** Some time after deployment  
+**Actor:** Council Member  
+**Actions:**
+
+- Adds a **scheduled upgrade transaction** via the `Security Council Safe`
+- The transaction:
+  - Is routed through the `TimelockController`
+  - Targets the `ProxyAdmin`
+  - Calls the `upgrade()` function to set the proxy’s implementation to the new contract address (e.g. `0xAbCd1234`)
+  - Final target: the `Proxy` contract
+
+**Verification Requirements:**
+- ✅ Transaction hash, details, and simulation must be verified
+- ✅ Function and parameters must be verified
+
+---
+
+## 🟩 3. Execute Upgrade Transaction After Delay
+
+**Timeframe:** After the configured delay  
+**Actor:** Council Member  
+**Actions:**
+
+- Adds a matching **execute transaction** through the `Security Council Safe`
+- Routed again through the `TimelockController`
+- Reaches `ProxyAdmin`, which executes the upgrade on the `Proxy`
+
+**Outcome:**  
+➡️ Proxy’s implementation is updated (contract logic changed)
+
+**Verification Requirements:**
+- ✅ Same transaction hash, parameters, and targets must match scheduled version
+
+---
+
+## 🗂️ Mainnet Contract Addresses
+
+### 🔐 Security Council Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0x892bb72De7f1b06B08a09140e7825d1827991DD3` |
+| Linea     | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319` |
+
+### 🕓 TimelockController Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0xd6B9c960f779c728C6752119849318E5d550574`  |
+| Linea     | `0xC80BB1C8eD34D049bA579CaBa646e67B9A03C56a` |
+
+- Security Council is both **Proposer** and **Executor**
+- Timelock owns `ProxyAdmin` contracts
+
+### 👤 Proxy Admin Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0xF50586165710C86c7b7EcC6B9F636Ada9606d6d6` |
+| Linea     | `0x1E16fF2297b4a7522Df8b62e99353692399774E` |
+
+### 🧑‍💻 Deployer Addresses
+
+| Network   | Address                                      |
+|-----------|----------------------------------------------|
+| Ethereum  | `0x6dD3120E329dC5FaA3d2c6f65705E4f648fF65F7` |
+| Linea     | `0x49ee40140522561744c1C2878c76eE9f28028d33` |
+
+### 📦 Proxy Addresses
+
+| Contract           | Address                                           |
+|--------------------|---------------------------------------------------|
+| LineaRollup        | `0xd194Bd535d285f05D7B411E21A1460D11B0876F`       |
+| TokenBridge        | `0x051F1D88f0aF5673fB88BeC4378eD4BB29ea3319`       |
+| L2MessageService   | `0x508cA82Df566dCD1B0DE828967a0e96332cDc446`      |
+| L2 Token Bridge    | `0x353012d04a9A6cF5C541BADC267f82004A8ceB9`        |
+
+---
+
+## ✅ Security Summary
+
+- All upgrades go through a **timelock delay** using multisig control
+- Contract upgrades do **not require reinitialization**
+- **Transaction simulation and parameter verification** are essential at both stages
+
+<img src="../diagrams/upgradeContract.png">

contracts/docs/workflows/administration/verifierSettingUnsetting.md

@@ -0,0 +1,103 @@
+
+# 🧩 Setting/Unsetting a Verifier Address
+
+This document outlines the secure and auditable flow for **setting or unsetting a verifier address** via a Timelock-controlled multisig process.
+
+**Note**: These contracts are governed by the [Security Council Charter](../../security-council-charter-v1.3.md).
+
+---
+
+## 🟨 1. Deploy Implementation of Verifier Contract
+
+**Actor:** Well-Known Deployer  
+**Actions:**
+
+- Deploys the `Implementation` contract (e.g. `0xAbCd1234`)
+- The implementation:
+  - ✅ Must be **verified on Etherscan**
+  - ✅ Must be **confirmed to match audited code** by multiple auditors
+  - ✅ Bytecode must be **verified** to match the audited version
+
+---
+
+## 🟧 2. Schedule Transaction via Timelock
+
+**Timeframe:** Some time after the implementation is deployed  
+**Actor:** Council Member  
+**Actions:**
+
+- Adds a **scheduled transaction** via the `Security Council Safe`
+- This transaction goes to the `TimelockController`
+- It schedules a call to the `Proxy` to invoke:
+  - `setVerifierAddress` or `unsetVerifierAddress`
+  - At a specific index (e.g. `0xAbCd1234 at index 0`)
+
+**Verification Requirements:**
+- ✅ Transaction hash, details, and simulation must be verified
+- ✅ Function and parameters must be verified
+
+**Flow:**
+```
+Council Member 
+    → Security Council Safe (adds schedule)
+        → TimelockController (with configured delay)
+            → Proxy (targets and calls set/unset function)
+                → Signatures and on-chain execution
+```
+
+---
+
+## 🟩 3. Execute Transaction After Delay
+
+**Timeframe:** Some time after the configured delay  
+**Actor:** Council Member  
+**Actions:**
+
+- Adds an **execute transaction** with a payload **matching** the scheduled transaction
+- Follows same path:
+  - `Security Council Safe` → `TimelockController` → `Proxy`
+  - Executes `setVerifierAddress` or `unsetVerifierAddress`
+
+**Verification Requirements:**
+- ✅ Transaction hash, details, and simulation must be verified
+- ✅ Function and parameters must be verified
+
+## 🗂️ Function Signatures
+
+| 4bytes | Signature                              |
+|-------|---------------------------------------|
+| `0xc2116974`     | setVerifierAddress(address,uint256)                   |
+| `0x28958174`    | unsetVerifierAddress(uint256)                   |
+
+**Outcome:**  
+➡️ Verifier address is **set** or **unset**
+
+---
+
+## 🗂️ Mainnet Contract Addresses
+
+| Component               | Chain         | Address                                                                 |
+|------------------------|---------------|-------------------------------------------------------------------------|
+| **TimelockController** | Ethereum      | `0xd6B9c960f779c728C86752119849318E5d550574`                            |
+| **Proxy**              | LineaRollup   | `0xd194Bd535d285f05D7B411E21A1460D11B0876F`                             |
+| **Deployer**           | Ethereum      | `0x6dD3120E329dC5FaA3d2c6f65705E4f648fF65F7`                            |
+
+---
+
+## 🧾 Verifier Address Types
+
+| Description               | Value                                                                        |
+|---------------------------|------------------------------------------------------------------------------|
+| Legacy Placeholder        | `0x1111111111111111111111111111111111111111`                                 |
+| Removed / Unassigned      | `0x0000000000000000000000000000000000000000`                                 |
+| New Verifier              | Any **standard non-zero Ethereum address**                                   |
+
+---
+
+## ✅ Security Summary
+
+- All changes go through **delayed execution** via the `TimelockController`
+- All functions and parameters must be **independently verified**
+- Ensures decentralized governance and secure upgrades
+
+<img src="../diagrams/verifierSettingUnsetting.png">

contracts/docs/workflows/messaging/canonicalL1ToL2Messaging.md

@@ -0,0 +1,34 @@
+
+# 📩 Interaction Flow: Canonical Message Sending (L1 → L2)
+
+This document describes the step-by-step flow of how a canonical message is sent from L1 to L2 in the Linea network.
+
+---
+
+## 🔄 Step-by-Step Flow
+
+1. **L1 User** calls `sendMessage()` on the `LineaRollup` or `L1MessageService` contract.
+2. The contract:
+   - Verifies non-empty data
+   - Gets the next message number
+   - Computes the message hash with all the message fields
+   - Computes the rolling hash using the previous rolling hash and the new message hash
+   - Stores the rolling hash and emits a message event
+3. **Coordinator** captures the emitted event and message hash.
+4. Coordinator:
+   - Anchors the message hash on L2
+5. **L2MessageService** receives the anchored message hash.
+   - Computes and verifies the rolling hash sync
+   - Stores each hash for claiming
+6. **Postman** service or **L2 User** calls `claimMessage()` to deliver the message to the **L2 User**.
+7. As part of regular chain operations:
+   - **L2 Blocks and Transactions** are produced
+   - **Prover / Trace Generator Compressor** uses L2 data, generates traces and all proofs
+   - Proofs are submitted to the Coordinator via `SubmitBlocks` / `finalizeBlocks`
+8. **L1MessageService / LineaRollup** verifies rolling hash sync as part of a feedback loop.
+
+---
+
+<img src="../diagrams/canonicalL1ToL2Messaging.png">
+
+

contracts/docs/workflows/messaging/canonicalL1ToL2TokenBridging.md

@@ -0,0 +1,40 @@
+
+# 🔁 Interaction Flow: Canonical Token Bridging (L1 → L2)
+
+This document describes how tokens are bridged canonically from L1 to L2, step-by-step.
+
+---
+
+## 🔄 Step-by-Step Flow
+
+1. **L1 User** calls `bridgeToken()` on the `L1 Token Bridge`.
+2. The `L1 Token` is either:
+   - Transferred using `safeTransferFrom()`, or
+   - Burned
+3. `L1 Token Bridge` sends a message using `sendMessage()` to `LineaRollup / L1MessageService`.
+4. The contract:
+   - Verifies non-empty data
+   - Gets the next message number
+   - Computes the message hash with all the message fields
+   - Computes the rolling hash using the previous rolling hash and the new message hash
+   - Stores the rolling hash and emits a message event
+5. **Coordinator** captures the event and message hash.
+6. Coordinator:
+   - Anchors the message hash on L2
+7. **L2MessageService** receives the message on L2.
+   - Computes and verifies the rolling hash sync
+   - Stores each hash for claiming   
+8. **Postman** service or **user** calls `claimMessage()` on the L2MessageService.
+9. **L2MessageService** calls the **L2 Token Bridge** performing `completeBridging()`.
+10. Depending on token status, **L2 Token** is:
+    - Minted or,
+    - Transferred to the L2 User
+11. As part of regular chain operations:
+    - **L2 Blocks and Transactions** are produced
+    - **Prover / Trace Generator Compressor** uses L2 data, generates traces and all proofs
+    - Proofs are submitted to the Coordinator via `SubmitBlocks` / `finalizeBlocks`
+12. **LineaRollup / L1MessageService** verifies rolling hash sync as part of a feedback loop.
+
+---
+
+<img src="../diagrams/canonicalL1ToL2TokenBridging.png">

contracts/docs/workflows/messaging/canonicalL2ToL1Messaging.md

@@ -0,0 +1,27 @@
+
+# 📩 Interaction Flow: Canonical Message Sending (L2 → L1)
+
+This document describes the step-by-step flow of how a canonical message is sent from L2 to L1 in the Linea network.
+
+---
+
+## 🔄 Step-by-Step Flow
+
+1. **L2 User** calls `sendMessage()` on the `L2MessageService`.
+2. The contract:
+   - Verifies non-empty data
+   - Gets the next message number
+   - Computes the message hash with all the message fields
+   - Stores the message hash and emits events
+3. **Coordinator** captures the event and message hash.
+4. Coordinator:
+   - Anchors the messaging Merkle root(s) on L1 during finalization
+   - Emits events for the L2 user to construct a Merkle proof
+5. **L1 User** claims the message with proof on the `LineaRollup` / `L1MessageService`.
+6. The contract verifies and **delivers the message** to the recipient.
+
+---
+
+## 🖼️ Diagram
+
+<img src="../diagrams/canonicalL2ToL1Messaging.png">

contracts/docs/workflows/messaging/canonicalL2ToL1TokenBridging.md

@@ -0,0 +1,30 @@
+
+# 🔁 Interaction Flow: Canonical Token Bridging (L2 → L1)
+
+This document outlines the process of bridging tokens from L2 back to L1 using the canonical bridge mechanism.
+
+---
+
+## 🔄 Step-by-Step Flow
+
+1. **L2 User** calls `bridgeToken()` on the `L2 Token Bridge`.
+2. The `L2 Token` is either:
+   - Transferred via `safeTransferFrom()`, or
+   - Burned
+3. `L2 Token Bridge` sends a message to the `L2MessageService` using `sendMessage()`.
+4. The `L2MessageService`:
+   - Verifies non-empty data
+   - Gets the next message number
+   - Computes the message hash with all the message fields
+   - Stores message hash and emits event
+5. **Coordinator** captures the event and message hash.
+6. Coordinator:
+   - Anchors the message Merkle root(s) on L1 during finalization
+   - Emits events for proof generation
+7. **L1 User** claims the message with proof.
+8. `L1 Token Bridge` executes `completeBridging()`.
+9. The `L1 Token` is delivered (either minted or transferred) to the **L1 User**.
+
+---
+
+<img src="../diagrams/canonicalL2ToL1TokenBridging.png">

contracts/docs/workflows/operations/blobSubmissionAndFinalization.md

@@ -0,0 +1,52 @@
+# 🧩 Blob Submission & Finalization
+
+This document outlines the core data and finalization flows involved in LineaRollup's lifecycle, including blob commitment and zk-proof-based finality.
+
+---
+
+## 📦 Blob Submission
+
+This flow is used by the **Data Submission Operator** to submit blobs to the LineaRollup system.
+
+### 🔄 Steps
+
+1. **Data Submission Operator** calls `submitBlobs()` on the `LineaRollup` contract with **1 to N blobs**, where **N = network maximum**.
+2. For each submitted blob:
+   - The contract verifies data integrity.
+   - Performs evaluation checks via the point evaluation precompile.
+   - Computes a `shnarf` for internal tracking.
+3. The final computed `shnarf` is stored.
+4. A corresponding event is emitted to reflect successful blob(s) storage.
+
+**Note:** `Shnarf` denotes a generic and iterative hashing structure for a sequence of values. It is somewhat analog to a stack and supports efficient `proof of append` and `proof of pop`. The structure is similar to how block hashes are computed: for appends, `newShnarf = H(oldShnarf || appendedValue)`. In Linea, the structure is used to encode the sequence of the submitted blobs.
+
+---
+
+## 🧮 Finalization Submission
+
+This flow finalizes 1 or more aggregated blob transaction submissions by verifying correct execution proven via zero-knowledge proofs.
+
+### 🔄 Steps
+
+1. **Finalization Submission Operator** calls `finalizeBlocks()`.
+2. `LineaRollup` contract:
+   - Verifies submitted data matches the last finalized state and is non-empty to verify proper continuity.
+   - Validates the messaging rolling hash feedback loop preventing manipulation or censorship.
+   - Emits events for L2 blocks containing L2 → L1 messages.
+   - Stores **Merkle roots** of L2 messages for proof-based claiming.
+3. Computes the **public input** to be verified.
+4. Calls the Plonk-based **Verifier** to validate the provided zk-proof.
+5. Upon success, updates finalized state:
+   - Includes latest 
+   - Stores the `currentL2BlockNumber`, `finalStateRootHash` and other related finalization state metadata.
+
+---
+
+### 🔐 Verifier Contract
+
+The verifier contract is an advanced zero-knowledge proof verifier specifically tailored for the PLONK protocol on Ethereum mainnet. It verifies zk-SNARK proofs generated using [gnark](https://github.com/ConsenSys/gnark), ensuring that a given proof corresponds to a valid computation without revealing inputs. The contract is written almost entirely in inline Yul assembly for gas efficiency and precision, and it uses elliptic curve operations, pairings, and the Fiat-Shamir heuristic to validate a serialized proof against public inputs. This is critical infrastructure for trustless, privacy-preserving applications such as rollups, where it ensures the integrity of off-chain computations before accepting their results on-chain.
+
+---
+
+<img src="../diagrams/blobSubmissionAndFinalization.png">
+

contracts/docs/workflows/operations/l2MessageHashAnchoring.md

@@ -0,0 +1,18 @@
+# 🧩 L2 Message hash anchoring
+
+## 📦 Anchoring
+
+This flow is used by the **L2 Message Anchoring Operator** to submit L1 to L2 hashes synchronising the rolling hash for the feedback loop.
+
+
+For all L1 to L2 messaging, please see the L1 to L2 messaging workflows.
+
+### 1. 🧾 [L1 to L2 Messaging](./messaging/canonicalL1ToL2Messaging.md)
+View the L1 to L2 Messaging flow.
+
+### 2. 🧾 [L1 to L2 Token Bridging](../messaging/canonicalL1ToL2TokenBridging.md)
+View the L1 to L2 Token Bridging flow.
+---
+
+<img src="../diagrams/l2MessageHashAnchoring.png">
+