Feature/docs v2 (#91)

* restructure and apply puffer design system

* AVS section

* fixing institutional page index

* Update broken link, edit page and build

---------

Co-authored-by: Jasmin <[email protected]>

Author: SebForz

README.md

@@ -1,41 +1,71 @@
-# Website
+# Puffer Finance Documentation
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This repository contains the documentation for Puffer Finance products.
 
-### Installation
+## MDX Issues Resolution
 
-```
-$ yarn
-```
+We've implemented several fixes to resolve MDX compilation errors that occurred with Docusaurus 3.x:
 
-### Local Development
+1. **Configuration Changes**:
+   - Updated `docusaurus.config.js` to use appropriate MDX options:
+     - Set `format: 'detect'` to automatically detect the MDX format
+     - Properly configured KaTeX for math rendering
 
-```
-$ yarn start
-```
+2. **Markdown File Fixes**:
+   - Simplified math expressions by removing unnecessary backslash escaping
+   - Converted simple expressions like `\(22\%\)` to regular text `22%`
+   - For complex math equations, used proper KaTeX syntax with `$$...$$`
+   - Added comments to prevent JSX from being parsed as JavaScript
+   - Ensured all code blocks have explicit language tags
+   - Added MDX comments around problematic areas to prevent incorrect parsing
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+3. **Fix Script**:
+   - Created a script (`scripts/fixMdx.js`) that automatically fixes these issues
+   - The script targets specific line ranges that were causing errors
+   - Handles acorn parse errors in JSX expressions
 
-### Build
+## Development
 
-```
-$ yarn build
-```
+To work on this documentation:
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+1. Install dependencies:
+   ```
+   npm install
+   ```
 
-### Deployment
+2. Start the development server:
+   ```
+   npm start
+   ```
 
-Using SSH:
+3. Build the static site:
+   ```
+   npm run build
+   ```
 
-```
-$ USE_SSH=true yarn deploy
-```
+## Math Rendering
 
-Not using SSH:
+The documentation uses KaTeX for rendering mathematical expressions. Use the following syntax:
 
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
+- For simple percentage values, use regular Markdown: `22%` (not `\(22\%\)`)
+- For emphasis, use standard Markdown: `**bold text**` (not math expressions)
+- For complex math formulas, use KaTeX block notation: 
+  ```
+  $$
+  \text{formula goes here}
+  $$
+  ```
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+## Troubleshooting
+
+If you encounter MDX compilation errors:
+
+1. Run the fix script:
+   ```
+   node scripts/fixMdx.js
+   ```
+
+2. Check the error messages for specific line numbers and file paths
+3. If needed, manually add `{/* MDX-BLOCK-START */}` and `{/* MDX-BLOCK-END */}` comments around problematic content
+4. Ensure all code blocks have language tags
+5. For JSX expressions that cause acorn parse errors, wrap them with `{/* JSX-FIX */}` and `{/* END-JSX-FIX */}`

docs/burst-threshold.md

@@ -1,6 +1,6 @@
 ---
 title: Puffer Institutional Staking Solution
-slug: puffer-institutional
+slug: institutional-intro
 ---
 
 # Puffer Institutional Solution

docs/institutional.md renamed to docs/institutional/institutional.md

@@ -49,6 +49,10 @@ Preconfirmations provide near-instant transaction assurances by leveraging a net
 - 🛡️ Backed by economic security from Ethereum validators
   - Validators stake ETH as collateral, ensuring honest behavior
   - Breaking preconf promises can result in slashing of staked assets
+{/* MDX-BLOCK-START */}
+{/* MDX-BLOCK-START */}
+{/* MDX-BLOCK-START */}
+{/* MDX-BLOCK-START */}
 - 🌐 Maintain neutrality and decentralization
   - Multiple validators participate, preventing single points of failure
   - Open participation ensures no central authority controls the process

docs/purchase-vts.md

@@ -22,49 +22,43 @@ Before you begin, ensure you have the following:
 
 1. Install Foundry (if not already installed):
 
-   ```
+   ```text
    curl -L https://foundry.paradigm.xyz | bash
    foundryup
-   ```
-
+   ```text
 2. Clone the UniFi repository:
 
-   ```
+   ```text
    git clone https://github.com/PufferFinance/UniFi.git
-   ```
-
+   ```text
 3. Navigate to the cloned directory:
 
-   ```
+   ```text
    cd UniFi
-   ```
-
+   ```text
 4. Install dependencies:
 
-   ```
+   ```text
    yarn install
-   ```
-
+   ```text
 5. Navigate to the l1-contracts directory:
 
-   ```
+   ```text
    cd l1-contracts
-   ```
-
+   ```text
 6. Install Foundry dependencies:
-   ```
+   ```text
    forge build
-   ```
-
+   ```text
 ## Phase 1 - Register to UniFi AVS
 
 During phase 1 of UniFi AVS mainnet, Operators can register as follows.
 
 1. **Register as an Operator**
    Run the following Solidity script:
-   ```
+   ```text
    forge script script/UniFiAVSScripts.sol:UniFiAVSScripts --sig "registerOperatorToUniFiAVS(uint256 signerPk)" 'YOUR_OPERATOR_PRIVATE_KEY' --private-key 'YOUR_OPERATOR_PRIVATE_KEY' --rpc-url 'YOUR_MAINNET_RPC_URL' --broadcast
-   ```
+   ```text
    Replace `YOUR_OPERATOR_PRIVATE_KEY` and `YOUR_MAINNET_RPC_URL` with your actual values.
 
 :::tip

docs/unifi-avs-background.md renamed to docs/unifi-avs/unifi-avs-background.md

@@ -1,5 +1,5 @@
 ---
-title: Hello UniFi AVS 🦄
+title: Introduction to UniFi AVS
 slug: /unifi-avs-intro
 ---
 

docs/unifi-avs-getting-started.md renamed to docs/unifi-avs/unifi-avs-getting-started.md

@@ -32,35 +32,51 @@ The UniFi AVS ecosystem involves several key components and actors:
 ```mermaid
 sequenceDiagram
     autonumber
-    participant U as Users
-    participant O as Operator
-    participant UAM as UniFiAVSManager
-    participant G as Gateway
-    participant BN as Beacon Node
-    participant CB as Commit-Boost
-    participant RM as RewardsManager
-    participant L1 as Ethereum L1
-
+    participant U as 👤 Users
+    participant O as 👨‍💼 Operator
+    participant UAM as 📋 UniFiAVSManager
+    participant G as 🌐 Gateway
+    participant BN as 📡 Beacon Node
+    participant CB as ⚡ Commit-Boost
+    participant RM as 💰 RewardsManager
+    participant L1 as 🔗 Ethereum L1
+
+    Note over O,UAM: 🚀 Registration Phase
     O->>UAM: Set delegate key to Gateway
+    
+    Note over G,BN: 🔍 Discovery Phase
     G->>BN: Query lookahead window
     BN-->>G: Return upcoming proposer indices
-    loop For each validator
+    
+    loop 🔄 For each validator
         G->>UAM: getValidator(validatorIndex)
         UAM-->>G: Validator registration status
     end
-    Note over G: confirm Gateway is delegated to
+    
+    Note over G: ✅ Confirm Gateway is delegated to
+    
+    Note over U,G: 💳 Transaction Phase
     U->>G: Send transactions to preconf RPC / router
     G-->>U: Return Gateway-signed pre-confs
-    CB->>CB: wait for slot...
+    
+    Note over CB: ⏳ wait for slot...
+    
+    Note over CB,L1: 🏗️ Block Production Phase
     CB->>G: Request L1 block
     G-->>CB: Provide L1 block
     CB->>L1: Propose L1 block
+    
+    Note over L1,G: 💸 Fee Distribution
     L1->>G: gateway fee
+    
+    Note over O,RM: 🎁 Rewards Phase
     O->>RM: Claim AVS rewards
 ```
-
+{/* MDX-BLOCK-START */}
 The preconf flow in UniFi AVS involves several interactions:
+{/* MDX-BLOCK-START */}
 
+{/* MDX-BLOCK-START */}
 1. Operators set their delegate key to point to a Gateway
 2. Gateway queries the Beacon Node for the lookahead window to check the upcoming proposers
 3. Gateway checks if any of the upcoming proposers are delegated to them
@@ -165,17 +181,7 @@ UniFi AVS will implement a rewards distribution mechanism designed to provide co
 
 #### Rewards Flow
 
-```mermaid
-graph TD
-    A[User] -->|Pays preconf tips in priority fees| B[Gateway]
-    B -->|Aggregates transactions and produces blocks| C[Validators]
-    C -->|Publish blocks| D[Fee Recipient]
-    D -->|Sends block rewards| E[RewardsManager Contract]
-    E -->|Distribute rewards| F[Operators]
-    E -->|Distribute rewards| G[Validators]
-    E -->|Distribute rewards| H[Gateway]
-```
-
+<img src="/img/unifi-avs-rewards.png" alt="UniFi AVS Rewards Flow" style={{maxWidth: '100%', height: 'auto', width: '50%', minWidth: '300px', display: 'block', margin: '0 auto'}} />
 #### Claiming Rewards
 
 Rewards will be distributed for each validator on the L2. Validators will be able to claim their rewards by setting a claimer address on the rewards contract by signing an EIP-712 hash with their BLS validator key.
@@ -200,15 +206,4 @@ The implementation of the mechanism will depend on EigenLayer's slashing design
 
 #### Slashing Flow
 
-```mermaid
-graph TD
-    A[Validator Signs Pre-confirmation] --> B{Validator Behavior}
-    B -->|Breaks Promise| C[Safety Fault]
-    B -->|Misses Block Proposal| D[Liveness Fault]
-    B -->|Steals MEV| E[Rug Pooling]
-    C --> F[Proof Submitted]
-    D --> F
-    E --> F
-    F --> G[Slashing Mechanism Triggered]
-    G --> H[Penalize Validator's Restaked Ether]
-```
+<img src="/img/unifi-avs-slashing.png" alt="UniFi AVS Slashing Flow" style={{maxWidth: '100%', height: 'auto', width: '50%', minWidth: '300px', display: 'block', margin: '0 auto'}} />

docs/unifi-avs-intro.md renamed to docs/unifi-avs/unifi-avs-intro.md

@@ -0,0 +1,16 @@
+---
+title: Burst Threshold
+slug: /protocol/burst-threshold
+---
+
+:::info
+The Burst Threshold is Puffer's commitment to Ethereum's Ethos.
+:::
+
+### Burst Threshold
+
+Puffer is [committed to self-capping](https://x.com/puffer_finance/status/1697817894900711700?s=20) its validator marketshare to \(22\%\) of Ethereum's validator set, which we refer to as the protocol's _Burst Threshold_. Instead of abruptly pausing staking and NoOp registration once the burst threshold is reached, Puffer introduces a mechanism to organically reduce staker demand as the protocol reaches the threshold.
+
+As the protocol reaches \(22\%\), the number of mintable validator tickets will be reduced such that it can only sustain existing validators but not new ones.
+
+This pledge is critical to ensure that the Puffer protocol never breaches the [dangerous consensus threshold of \(33\%\)](https://x.com/dannyryan/status/1688644951230267392?s=46&t=bsdBaPIHlTHEWDDdVUJW4g), which threatens the stability of Ethereum. We firmly believe that the burst threshold must be included from day one rather than after the protocol is profitable.