Temp draft branch

packages/specs/pages/modules.mdx

@@ -14,4 +14,13 @@ Namada includes the following modules:
 - [Multi-asset-shielded-pool (MASP)](./modules/masp.mdx)
 - [Governance](./modules/governance.mdx)
 - [IBC](./modules/ibc.mdx)
-- [Ethereum bridge](./modules/ethereum-bridge.mdx)
+- [Ethereum bridge](./modules/ethereum-bridge.mdx)
+
+Each module page herein includes the following sub-sections:
+- Introduction
+- Design rationale
+- Data types
+- Storage layout
+- Validity predicate logic
+- Transactions
+- Handlers

packages/specs/pages/modules/ethereum-bridge.mdx

@@ -13,25 +13,12 @@ fungible assets are held in escrow.
 [ICS20]: <https://github.com/cosmos/ibc/blob/ed849c7bacf16204e9509f0f0df325391f3ce25c/spec/app/ics-020-fungible-token-transfer/README.md>
 [ERC20]: <https://eips.ethereum.org/EIPS/eip-20>
 
-The Namada Ethereum bridge system consists of:
-
-* A set of Ethereum smart contracts.
-* An Ethereum full node run by each Namada validator, to watch Ethereum
-  events emitted by the bridge's smart contracts.
-* A set of validity predicates (VPs) on Namada.
-    + A Bridge pool VP, to validate transfers to Ethereum and escrowed NAM.
-    + An Ethereum bridge VP, to protect writes to Namada storage
-      key sub-spaces containing Ethereum event tallies.
-* Two relayer utilities, to call the Ethereum smart contracts.
-    + One for performing validator set updates on the Ethereum
-      smart contracts.
-    + Another to aid in submitting batches of transactions
-      to Ethereum.
-
-This basic bridge architecture should provide for almost-Namada consensus
-security for the bridge and free Ethereum state reads on Namada, plus
-bidirectional message passing with reasonably low gas costs on the
-Ethereum side.
+- [Design rationale](./ethereum-bridge/design.mdx)
+- [Data types](./ethereum-bridge/data-types.mdx)
+- [Storage layout](./ethereum-bridge/storage.mdx)
+- [Validity predicate logic](./ethereum-bridge/vp.mdx)
+- [Transactions](./ethereum-bridge/txs.mdx)
+- [Handlers](./ethereum-bridge/handlers.mdx)
 
 ## Topics
  - [Bootstrapping](./ethereum-bridge/bootstrapping.mdx)
@@ -82,123 +69,6 @@ Validators must not vote to include events that have not met the required
 number of confirmations. Voting on unconfirmed events is considered a 
 slashable offence.
 
-### Storage
-To make including new events easy, we take the approach of always overwriting 
-the state with the new state rather than applying state diffs. The storage 
-keys involved are:
-```
-# all values are Borsh-serialized
-/eth_msgs/\$msg_hash/body : EthereumEvent
-/eth_msgs/\$msg_hash/seen_by : Vec<Address>
-/eth_msgs/\$msg_hash/voting_power: (u64, u64)  # reduced fraction < 1 e.g. (2, 3)
-/eth_msgs/\$msg_hash/seen: bool
-```
-
-`\$msg_hash` is the SHA256 digest of the Borsh serialization of the relevant 
-`EthereumEvent`.
-
-Changes to this `/eth_msgs` storage subspace are only ever made by internal 
-transactions crafted and applied by all nodes based on the aggregate of vote 
-extensions for the last Cometbft round. That is, changes to `/eth_msgs` happen 
-in block `n+1` in a deterministic manner based on the vote extensions of the 
-Cometbft round for block `n`.
-
-The `/eth_msgs` storage subspace does not belong to any account and cannot be 
-modified by transactions submitted from outside of the ledger via Cometbft. 
-The storage will be guarded by a special validity predicate - `EthSentinel` - 
-that is part of the verifier set by default for every transaction, but will be 
-removed by the ledger code for the specific permitted transactions that are 
-allowed to update `/eth_msgs`.
-
-### Including events into storage
-
-For every Namada block proposal, the vote extension of a validator should include
-the events of the Ethereum blocks they have seen via their full node such that:
-1. The storage value `/eth_msgs/\$msg_hash/seen_by` does not include their
-   address.
-2. It's correctly formatted.
-3. It's reached the required number of confirmations on the Ethereum chain
-
-Each event that a validator is voting to include must be individually signed by 
-them. If the validator is not voting to include any events, they must still
-provide a signed voted extension indicating this.
-
-The vote extension data field will be a Borsh-serialization of something like the following.
-```rust
-pub struct VoteExtension(Vec<SignedEthEvent>);
-
-/// A struct used by validators to sign that they have seen a particular
-/// ethereum event. These are included in vote extensions
-#[derive(Debug, Clone, BorshSerialize, BorshDeserialize, BorshSchema)]
-pub struct SignedEthEvent {
-    /// The address of the signing validator
-    signer: Address,
-    /// The proportion of the total voting power held by the validator
-    power: FractionalVotingPower,
-    /// The event being signed and the block height at which
-    /// it was seen. We include the height as part of enforcing
-    /// that a block proposer submits vote extensions from
-    /// **the previous round only**
-    event: Signed<(EthereumEvent, BlockHeight)>,
-}
-```
-
-These vote extensions will be given to the next block proposer who will
-aggregate those that it can verify and will inject a protocol transaction
-(the "vote extensions" transaction).
-
-```rust
-pub struct MultiSigned<T: BorshSerialize + BorshDeserialize> {
-    /// Arbitrary data to be signed
-    pub data: T,
-    /// The signature of the data
-    pub sigs: Vec<common::Signature>,
-}
-
-pub struct MultiSignedEthEvent {
-    /// Address and voting power of the signing validators
-    pub signers: Vec<(Address, FractionalVotingPower)>,
-    /// Events as signed by validators
-    pub event: MultiSigned<(EthereumEvent, BlockHeight)>,
-}
-
-pub enum ProtocolTxType {
-    EthereumEvents(Vec<MultiSignedEthEvent>)
-}
-```
-
-This vote extensions transaction will be signed by the block proposer. 
-Validators will check this transaction and the validity of the new votes as 
-part of `ProcessProposal`, this includes checking:
-- signatures
-- that votes are really from active validators
-- the calculation of backed voting power
-
-It is also checked that each vote extension came from the previous round, 
-requiring validators to sign over the Namada block height with their vote
-extension. Furthermore, the vote extensions included by the block proposer
-should have at least 2 / 3 of the total voting power of the previous round 
-backing it. Otherwise the block proposer would not have passed the 
-`FinalizeBlock` phase of the last round. These checks are to prevent censorship 
-of events from validators by the block proposer.
-
-In `FinalizeBlock`, we derive a second transaction (the "state update" 
-transaction) from the vote extensions transaction that:
-- calculates the required changes to `/eth_msgs` storage and applies it
-- acts on any `/eth_msgs/\$msg_hash` where `seen` is going from `false` to `true`
-  (e.g. appropriately minting wrapped Ethereum assets)
-
-This state update transaction will not be recorded on chain but will be 
-deterministically derived from the vote extensions transaction, which is 
-recorded on chain. All ledger nodes will derive and apply this transaction to 
-their own local blockchain state, whenever they receive a block with a vote 
-extensions transaction. This transaction cannot require a protocol signature 
-as even non-validator full nodes of Namada will be expected to do this.
-
-The value of `/eth_msgs/\$msg_hash/seen` will also indicate if the event 
-has been acted on on the Namada side. The appropriate transfers of tokens to the
-given user will be included on chain free of charge and requires no
-additional actions from the end user.
 
 ## Namada Validity Predicates
 

packages/specs/pages/modules/ethereum-bridge/_meta.json

@@ -1,9 +1,8 @@
 {
-  "security": "Security",
-  "bootstrapping": "Bootstrapping",
-  "ethereum_events_attestation": "Ethereum events attestation",
-  "transfers_to_namada": "Transfers to Namada",
-  "transfers_to_ethereum": "Transfers to Ethereum",
-  "proofs": "Proofs",
-  "ethereum_smart_contracts": "Ethereum Smart Contracts"
-}
+    "design": "Design rationale",
+    "data-types": "Data types",
+    "storage": "Storage layout",
+    "vp": "Validity predicate logic",
+    "txs": "Transactions",
+    "handlers": "Handlers"
+}

packages/specs/pages/modules/ethereum-bridge/data-types.mdx

@@ -0,0 +1,5 @@
+import { Callout } from 'nextra-theme-docs'
+
+## Data types
+
+Placeholder

packages/specs/pages/modules/ethereum-bridge/design.mdx

@@ -0,0 +1,30 @@
+import { Callout } from 'nextra-theme-docs'
+
+## Design
+
+The Namada Ethereum bridge system consists of:
+
+* A set of Ethereum smart contracts.
+* An Ethereum full node run by each Namada validator, to watch Ethereum events emitted by the bridge's smart contracts.
+* A set of validity predicates (VPs) on Namada.
+    + A Bridge pool VP, to validate transfers to Ethereum and escrowed NAM.
+    + An Ethereum bridge VP, to protect writes to Namada storage key sub-spaces containing Ethereum event tallies.
+* Two relayer utilities, to call the Ethereum smart contracts.
+    + One for performing validator set updates on the Ethereum smart contracts.
+    + Another to aid in submitting batches of transactions to Ethereum.
+
+This basic bridge architecture should provide for almost-Namada consensus
+security for the bridge and free Ethereum state reads on Namada, plus
+bidirectional message passing with reasonably low gas costs on the
+Ethereum side.
+
+### Security
+
+On Namada, the validators are full nodes of Ethereum and their stake is also
+accounting for security of the bridge. If they carry out a forking attack
+on Namada to steal locked tokens of Ethereum their stake will be slashed on Namada.
+On the Ethereum side, there exists a limit to the amount of assets that can be
+locked to limit the damage a forking attack on Namada can do. To make an attack
+more cumbersome there also exists a limit on how fast wrapped Ethereum assets can
+be redeemed from Namada. This does not add more security, but rather makes the 
+attack more inconvenient, and allows governance time to react.