# Watchtower Architecture

## Architecture

<figure><img src="/files/fkewKEvlAGCGDONwrAAK" alt=""><figcaption></figcaption></figure>

WitnessChain Watchtowers' software stack comprise of &#x20;

1. Watchtower Client (written in Go)&#x20;
2. On-chain Smart Contracts on Ethereum & on a Layer-2 chain
   1. **Layer 1:** Operator Registry, Settlement (ServiceManager aka EigenTower) & Alert Manager
   2. **Layer 2:** DiligenceProofManager Contract
3. Centralized Aggregator (to submit "batched" bounty settlements (rewards) on Ethereum)

## Watchtower client

### Proof of Diligence

At a high level, the process of L2 state validation in a watchtower node client has 4 stages

1. Output State Root Extraction from L1
2. Output State Root Extraction (Tracer execution) from L2 Node
3. Comparison & generating proofs of diligence
4. Smart Contract integration to publish the proofs

<figure><img src="/files/2jXZLGH5e23VSXTvweMt" alt=""><figcaption><p>Sequence of Steps</p></figcaption></figure>

## List of Key Smart Contracts and their key functions

### 1. OperatorRegistry

This is Registry-type contract for keeping track of operators. It is used for registering and deregistering new operators. Only registered and delegated EigenLayer operators are allowed into the watchtower network

### *<mark style="color:green;">addToOperatorWhitelist(\[OperatorAddress])</mark>*

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Called By</strong></td><td>Contract Owner</td></tr><tr><td><strong>Returns</strong></td><td>None</td></tr><tr><td><strong>Emits</strong></td><td><p></p><pre class="language-solidity"><code class="lang-solidity">OperatorsWhiteListed(operatorsList, block.number);
</code></pre></td></tr></tbody></table>

* Adds the list of operators to the whitelist mapping

### *<mark style="color:green;">suspend</mark>*<mark style="color:green;">(operator)</mark>

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Called By</strong></td><td>Contract Owner</td></tr><tr><td><strong>Returns</strong></td><td>None</td></tr><tr><td><strong>Emits</strong></td><td><p></p><pre class="language-solidity"><code class="lang-solidity">OperatorSuspended(operatorAddress, block.number);
</code></pre></td></tr></tbody></table>

* Removes the operator from the whitelist mapping

### *<mark style="color:green;">registerWatchtowerAsOperator(watchtower, expiry, signedMessage)</mark>*

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Called By</strong></td><td>Node operator</td></tr><tr><td><strong>Returns</strong></td><td>None</td></tr><tr><td><strong>Emits</strong></td><td><p></p><pre class="language-solidity"><code class="lang-solidity">WatchtowerRegisteredToOperator(msg.sender, _watchtowerAddress, block.number);
</code></pre></td></tr></tbody></table>

* Registers the operator as a watchtower

### *<mark style="color:green;">deRegister(watchtowerAddress)</mark>*

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Called By</strong></td><td>Node operator</td></tr><tr><td><strong>Returns</strong></td><td>None</td></tr><tr><td><strong>Emits</strong></td><td><p></p><pre class="language-solidity"><code class="lang-solidity">WatchtowerDeRegisteredFromOperator(msg.sender, watchtowerAddress, block.number);
</code></pre></td></tr></tbody></table>

* Deregisters the watchtower
* The watchtower client will no longer be able to post any proofs, until the operator registers the watchtower address again

### 2. DiligenceProofManager

The DiligenceProofManager Contract contains functionality for miners (aka Watchtowers) to submit (mine) their Proofs of Diligence for a Bounty Period (which is the period between 2 L2 Txn Batch submissions). After the next L2 output state root is posted on L1, the bounty is rewarded to the miner. Bounties are given for every L2 Output (L2 Block).&#x20;

### *<mark style="color:green;">setPoDClaimBounties(\_chainID, \_claimBounties)</mark>*

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Called By</strong></td><td>Owner of the Contract</td></tr><tr><td><strong>Returns</strong></td><td>None</td></tr><tr><td><strong>Emits</strong></td><td><p></p><pre class="language-solidity"><code class="lang-solidity">NewPODBountyInitialized(_chainID, _claimBounties);
</code></pre></td></tr></tbody></table>

* The owner of the Contract sets the Bounty Amount.
* Consider PoD bounties are just reward points for now. Lets say 1 point for every L2 block mined successfully by a WatchTower. A detailed Points documentation is in progress.

### *<mark style="color:green;">setPoIClaimBounties(\_chainID, \_claimBounties)</mark>*

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Called By</strong></td><td>Owner of the Contract</td></tr><tr><td><strong>Returns</strong></td><td>None</td></tr><tr><td><strong>Emits</strong></td><td><p></p><pre class="language-solidity"><code class="lang-solidity">NewPOIBountyInitialized(_chainID, _claimBounties);
</code></pre></td></tr></tbody></table>

* The owner of the Contract sets the Bounty Amount.
* Consider PoI bounties are just reward points for now. Lets say 1 point for every L2 block mined successfully by a WatchTower. A detailed Points documentation is in progress.

### *<mark style="color:green;">submitPoDProof (chainID, l2\_blockNumber, proofOfDiligence, signatureProofOfDiligence)</mark>*

| **Called By** | WatchTower (EigenLayer Node Operator) |
| ------------- | ------------------------------------- |
| **Returns**   | None                                  |
| **Emits**     | NewBountyClaimed event                |

* Watchtower(s) submits/mine a L2 block by submitting the Hash(intermediate state root) and signing the Hash.
* Validations on Contract take care if the right sender is sending this transaction

### *<mark style="color:green;">submitPoIProof (chainID, l2\_blockNumber, proofOfDiligence, signatureProofOfDiligence)</mark>*

| **Called By** | WatchTower (EigenLayer Node Operator) |
| ------------- | ------------------------------------- |
| **Returns**   | None                                  |
| **Emits**     | NewBountyClaimed event                |

* Watchtower(s) submits/mine a L2 block for a PoI proof.
* Validations on Contract take care if the right sender is sending this transaction

### 3. AlertManager

This contract is used for keeping track of alerts raised by watchtowers

### *<mark style="color:green;">raiseAlert(chainID, l2BlockNumber, originalOutputRoot, computedOutputRoot, proofofDiligence)</mark>*

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Called By</strong></td><td>Node Operator</td></tr><tr><td><strong>Returns</strong></td><td>None</td></tr><tr><td><strong>Emits</strong></td><td><p></p><pre class="language-solidity"><code class="lang-solidity">NewAlertRaised(msg.sender, _chainID, _l2BlockNumber);
</code></pre></td></tr></tbody></table>

* Raise an alert when there is a mismatch in output root between what is exeucte on L2 Node and asserted on L1 Contract

### *<mark style="color:green;">getAlerts(chainID,L2BlockNumber)</mark>*

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Called By</strong></td><td>Node Operator</td></tr><tr><td><strong>Returns</strong></td><td><p></p><pre class="language-solidity"><code class="lang-solidity">// chainID => block number => list of alerts raised
<strong>mapping(uint256 => mapping(uint256 => Alert[]))
</strong></code></pre></td></tr><tr><td><strong>Emits</strong></td><td>None</td></tr></tbody></table>

* Get all alerts raised so far a particular chainID and L2BlockNumber

### 4. WitnessHub (AVS ServiceManager Contract)

The WitnessHub Contract enables the aggregator to process settlements for collective submissions of Proofs of Diligence and Proofs of Inclusion provided by watchtowers on a Layer 2 (L2) blockchain. These submissions correspond to a Bounty Period, which is defined as the interval between two transactions on the L2 chain.

### *<mark style="color:green;">updateRewards (</mark>*<mark style="color:green;">chainID, blockNumBegin, blockNumEnd, operatorsList, proofRewards, rewardHash</mark>*<mark style="color:green;">)</mark>*

| **Called By** | Aggregator       |
| ------------- | ---------------- |
| **Returns**   | None             |
| **Emits**     | NewRewardsUpdate |

* Accepts a list of operators and proof rewards, which correspond to the aggregated rewards for the operators across their watchtowers's proof submissions for a particular chain id and a range of blocks. This function may only be called by the aggregator.

## Aggregator

An aggregator, a centralised entity managed by Witness Chain, listens for the PoD and PoI submissions made by the watchtowers on the L2 chain contracts (DiligenceProofManager). It employs a "weighted stake" strategy to determine the winning watchtower for each group of blocks.&#x20;

This approach allows for a fair and transparent winning process. The winning watchtower's information, along with the number of wins and a Proof of Settlement, is then recorded on the WitnessHub settlement contract on Layer 1 (L1).&#x20;

The aggregator has the flexibility to adjust the settlement frequency based on gas costs, optimizing the balance between operational efficiency and cost-effectiveness.


---

# Agent Instructions: 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://docs.witnesschain.com/archive/proof-of-diligence-watchtower-protocol/watchtower-architecture.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.