We want to integrate shutter with all relevant components in the local devnet of the optimism codebase.
Whenever make devnet-up is invoked and the SHUTTER_ENABLED=true env var is set, a full ops-bedrock devnet
including all relevant actors in the shutter network should be started in a docker compose setup.

local development

• integrate the following shutter repos as git submodules to build the newest development binaries directive

  • rolling-shutter
  • op-geth

• for faster development, use replace directives in tandem with git submodules

  • op-geth
  • shop-contracts

initialisation

• add shop-contracts to the op-binding
• implement predeploy system contracts and initialisation routines for:
  • Inbox
  • KeyperSetManager
  • KeyBroadcastContract
  • optional one initial KeyperSet contract for the first keyper set
• set the active keyperset for the 4 devnet keypers

docker compose setup

• image build, starting and configuration of shutter services: 4
  • 4 keypers
  • 4 keyper validator nodes (shuttermint)
  • 2 bootstrap nodes
  • shutter-node (op-node integration)
• bootstrap the tendermint chain from the seed-validator to the first initial keyper set

The shutter keyper for optimism has to listen for new unsafe head blocks and subscribe to the shutter contract states on L2.

• release decryption key share upon new unsafe head blocks to P2P network
• construct and release aggregate decryption key when threshold keyshares are seen on P2P network
• initiate the DKG when part of a new keyper set (KeyperSetManager event subscription)
• bootstrap command for the initial keyper set / bootstrap validator (shuttermint)

OP node state machine

The OP node is responsible for requesting the next block via the engine API. Which type of block in a shutter system is to be requested is determined by the state of the shutter system contracts.
From the OP node's perspective there are three different block types to be requested:

• (1) Shutterized Block (submits the decryption key via engine API)
• (2) Deactivation Block (submits special decryption key via engine which will disable shutter)
• (3) Vanilla Block (without submitting a decryption key)

Requirements

• The rollup should never stall (delayed is ok)
• The rollup should thus fallback to vanilla mode
• The op-node has always the ability to disable shutter
• The op-node should be able to realize that shutter is enabled and give the shutter system enough time to provide decryption keys
• There should be a different set of conditions when to request each block type

Conditions

• If shutter is enabled
  • Wait time X until a decryption key is received
  • Wait at least the minimum block time
• If shutter is disabled
  • Wait the minimum block time
• If time X is passed and shutter is enabled
  • request deactivation block

Internal State

The op node has different conditions to be met to request the the next block.
For that it needs to keep some internal state to know in which mode the rollup is running.
In its easiest form it's a flag of what the op node thinks the next block should be. Shutterized or unshutterized.

However, it is possible that the node's state is not equal to the actual state at any point in time, thus the node could accidentally request a different block type. This must result in an error being returned by op-geth.
This actually is the input to the internal op-node's shutter state transition.

stateDiagram
 direction LR
 s1: Disabled
     note left of s1
        success by engine API => Block could be produced
        error by engine API => expects decryption key
    end note
 s2: Enabled
    note right of s2
        success by engine API => Block could be produced in time with decryption key
        error by Engine API => expects vanilla block 
        timeout => did not receive decryption key during configured shutter timeout 
    end note
 
 s1 --> s2: error / (1)
 s2 --> s1: error / (3)
 s2 --> s1: timeout / (2)
 s1 --> s1: success / (3)
 s2 --> s2: success / (1)

The op-node consensus client has to be modified to integrate with the shutter op-geth execution client as well as the external shutter P2P integration (see #9) .

• implement the different behaviour of the Engine API requests depending on shutter mode (active, inactive, deactivation)
• Implement the failure handling logic described in #7
• tbd: allow to use the shutter op-node with rollups that do not implement shutter (optional)

If shutter is active

• triggered whenever key is received and x seconds have passed (instead of just time based)
• pass reveal tx via Engine API to op-geth

if shutter is not active

• continue with current implementation

•  Create deployment config
• fix #15 and #16
• deploy on sepolia

The shutter node will be a separate application that serves as a gateway to the shutter P2P network and reading the shutter contract's state for the op-node.
It will expose an HTTP API where the op-node can poll for the decryption-key of a certain L2 block-number.

• define the HTTP API's technology (push/pull/longpoll, RPC/REST, WS, etc.):

  • The shutter-node exposes a blocking GET endpoint, so that the op-node can long-poll for a block-numbers decryption-key. The op-node can remotely call (however implemented) getDecryptionKey(blocknumber int). The endpoint will either return immediately when a key has been received already, or it will block until it receives the key and then return.
    Like that, the op-node can already call getDecryptionKey(n+1), when n is the current block-number to be build.
    Keyper's then wait for their op-geth to return n from eth_blockNumber and release their key for n+1. Once the key is received by the shutter node, it will return the key immediately to the blocking http request.

• define the HTTP API's methods / state-transfer model

• P2P Handler / Validator functions

• L2 JSON RPC client

  • contract event subscription worker (shutter paused, new keyper sets, public keys)
  • eth_blockNumber new unsafe head event worker

• internal promise based event listening for long-polling GET requests

• concurrency safe data-structure for received events & data persistence (database)

We need to be able to use our own private key in the devnet script. Currently an account is proivided by the RPC.

The shutter contracts are predeployed in the genesis file. However, they are not initialized.

In order to let a devnet run we need to send certain transactions in order to initialize the contracts, so they the keyper set starts running.

In production the dao will need to send those transactions.

• Pass a public address which is controlled by us as the default admin
• KeyperSetContract
  • Deploy a KeyperSetContract
  • Set Threshold
  • Set KeyBroadcaster
  • Add Keypers to the contract
  • finalize
  • broadcast eon key
  • schedule keyper set in keyper set manager
• Set withdraw role in Inbox

• Engine API interactions / changes?
  • decr. key parameter + returns errors depending on shutter state
• HTTP API shutter-node <-> op-node
• shutter-node database persistence
• op-node state keeping (shutter-node timeouts / error handling / key forwarding)
• check if shoptimism needs to IMPORT (go mod) shutter-geth library version as well
  • if so we likely need to sync our geth with a certain upstream version for shoptimism compatibility
• L1 automatic contract deployment
  • utilisation of deployed L1 contracts in bedrock-local devnet script
  • on own new devnet L1, but external and no genesis control
  • on the sepolia chain with possibly external RPC provider
• devops / infrastructure for the docker compose hosting
  • try fist: L1 rpc provider for sepolia instead of local node (alchemy seems to have sepolia RPC endpoints)
  • rest docker compose deployment on 1 big machine
  • expose only JSON-RPC to the world ("l2 blackbox")
  • use local bedrock-devnet docker-compose without the ("genesis") L1 geth node (or use the node as proxy to sepolia)
• use "master keys" that we control for the restricted contracts
• for manual testing: tx sending / encrypting part needs to be implemented or adapted somehow

With the current devnet script L2 deposit transactions execute on L1 but are not enforced on L2. Need to investigate.

•  check if deposit transaction work without modifying devnet script

We decided to outsource the key listening process into its own application.

The main reason for it is, to keep the diff to the original op-node small as we need to maintain it. The application must

• connect to p2p network and listen to decryption keys
• connect to op-geth to be able to read the state via the standard JSON RPC interface
• once a decryption key is received for the next block, validate with respect to eon key broadcast on chain and current keyper set

The decryption key must be forwarded to the op-node app. This can be done either by pushing, polling or long-polling by the op-node.
Thus, the op-node app needs to implement this mechanism.

@ezdac any preferences regarding the inter process comms?

The operator is able to disable Shutter by requesting a new block with an empty decryption key via the engine API (@jannikluhn please share the exact interface with op-geth).
As a first iteration, the op-node should trigger the shutoff mechanism automatically if it wasn't able to receive the key in a specified amount of time. The exact timeout should be configurable.

Initial testnet release (needs a name to distinguish)

Requirements:

• Shutterized OP stack runs on testnet
• needs to run a DEX live
• needs to somehow show users that it's shutterized (at the level of Max's demo, but that they can see it for themselves)
• Faucet for ETH and Banana tokens

Components:

• Faucet
  • prefunded balance
  • Maybe reuse Beamer's faucet
  • fund user's balance with SHOP-ETH and banana tokens
• The testnet itself running on Sepolia
• Uni V2 fork smart contracts deployed
  • create and fund pool
• Uni V2 front-end hosted
  • faucet button
  • Make it work with shutter specific tx lifecycle (inclusion tx != execution)
• Frontend Popup to show transaction life cycle
  • show once transaction is included (still encrypted) and waiting for execution
  • show block when it will be executed
  • show that tx got executed

Nice to have:

• Every trade is configured with 10% slippage
• after tx is executed, shows the actual slippage
• At a later stage all unencrypted txs will be sandwiched to extract the entire 10%

Stage 2 (needs a name to distinguish)

• optional: sandwich bot which sandwiches everyone who doesn't use shutter (maybe collaborate with propellerheads)
• javascript library/SDK for end user to encrypt

Stage 3 (needs a name to distinguish)

• Deploy on Gnosis Chain?