Academy: Proxy Patterns (ava-labs#2714)

navillanueva · web-flow · commit 7e3abf1e26c1 · 2025-08-08T14:31:23.000+02:00
diff --git a/components/content-design/mermaid.tsx b/components/content-design/mermaid.tsx
@@ -1,19 +1,71 @@
 "use client";
-import React, { useEffect, type JSX } from "react";
+import React, { useEffect, useRef, type JSX } from "react";
 import mermaid from "mermaid";
 
-mermaid.initialize({
-  startOnLoad: true,
-});
-
 type MermaidProps = {
   readonly chart: string;
 };
 
 const Mermaid = ({ chart }: MermaidProps): JSX.Element => {
-  useEffect(() => mermaid.contentLoaded(), []);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    let destroyed = false;
+
+    const renderDiagram = async (): Promise<void> => {
+      if (!containerRef.current) return;
+
+      const isDarkMode =
+        document.documentElement.classList.contains("dark") ||
+        document.documentElement.getAttribute("data-theme") === "dark";
+
+      // Configure theme each time before rendering
+      mermaid.initialize({ startOnLoad: false, theme: isDarkMode ? "dark" : "default" });
+
+      // Render to SVG string and inject; avoid SSR/client mismatches
+      try {
+        // Unique ID only used internally by mermaid render
+        const renderId = `mmd-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        const { svg } = await mermaid.render(renderId, chart);
+        if (!destroyed && containerRef.current) {
+          containerRef.current.innerHTML = svg;
+        }
+      } catch (_err) {
+        // Fallback: show raw text if render fails
+        if (!destroyed && containerRef.current) {
+          containerRef.current.textContent = chart;
+        }
+      }
+    };
+
+    // Initial render on mount
+    void renderDiagram();
+
+    // Watch theme toggles on <html>
+    const observer = new MutationObserver(() => {
+      void renderDiagram();
+    });
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class", "data-theme"],
+    });
+
+    // Watch OS theme changes
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    const handleMediaChange = (): void => {
+      void renderDiagram();
+    };
+    mediaQuery.addEventListener("change", handleMediaChange);
+
+    return () => {
+      destroyed = true;
+      observer.disconnect();
+      mediaQuery.removeEventListener("change", handleMediaChange);
+    };
+  }, [chart]);
 
-  return <div className="mermaid">{chart}</div>;
+  // Render an empty container on server; client fills it post-mount
+  return <div ref={containerRef} />;
 };
 
 export default Mermaid;
diff --git a/components/quizzes/quizData.json b/components/quizzes/quizData.json
@@ -1139,18 +1139,18 @@
       "chapter": "Proof of Authority"
     },
     "413": {
-      "question": "In the PoA validator management architecture, why is the PoAManager a separate contract that uses composition rather than inheritance?",
+      "question": "What is the key architectural relationship between ACP99Manager and ValidatorManager in the validator management system?",
       "options": [
-        "To reduce gas costs during deployment",
-        "To make the code more complex and secure",
-        "To separate access control from core validator logic, allowing the same ValidatorManager to work with different consensus models",
-        "To comply with Solidity language limitations"
+        "ValidatorManager uses composition to access ACP99Manager functions",
+        "ValidatorManager extends ACP99Manager through inheritance, implementing the abstract base contract",
+        "ACP99Manager delegates all operations to ValidatorManager",
+        "Both contracts are independent and don't interact with each other"
       ],
       "correctAnswers": [
-        2
+        1
       ],
-      "hint": "Think about how this design pattern enables flexibility in access control models.",
-      "explanation": "The PoAManager uses composition (has a ValidatorManager) rather than inheritance to create a clean separation between access control and core validator logic. This allows the same ValidatorManager implementation to be controlled by different access models (PoA with single owner, PoS with staking-based control, or custom governance) simply by changing the controlling contract, without modifying the core validator management functionality.",
+      "hint": "Think about the inheritance pattern shown in the class diagram.",
+      "explanation": "ValidatorManager extends ACP99Manager through inheritance, implementing the abstract base contract. This design pattern allows ValidatorManager to inherit the standardized validator management functions defined in ACP99Manager while adding its own concrete implementation of the initiate functions. The inheritance relationship ensures that all validator managers follow the same interface defined by ACP99Manager, providing consistency across different implementations.",
       "chapter": "Validator Manager Contract"
     }
   }
diff --git a/content/academy/permissioned-l1s/01-introduction/04-proxy-pattern.mdx b/content/academy/permissioned-l1s/01-introduction/04-proxy-pattern.mdx
@@ -0,0 +1,62 @@
+---
+title: Proxy Patterns
+description: Understanding proxy patterns in blockchain - their importance, advantages, and risks.
+updated: 2025-07-08
+authors: [nicolasarnedo]
+icon: BookOpen
+---
+
+In blockchain development smart contracts are **immutable by design**, this can be beneficial for users to trust the software they are using will not be altered, but can represent challenges for developers to improve existing software or fix bugs.
+
+Proxy patterns offer a solution to this dilemma by separating contract logic from data storage, enabling upgrades while maintaining the same contract address.
+
+## How Proxy Patterns Work
+
+At its core, a proxy pattern involves two main components:
+
+1. **Proxy Contract**: Holds the permanent address and stores all contract state
+2. **Implementation Contract**: Contains the actual business logic that can be upgraded
+
+When users interact with the proxy contract, it delegates all calls to the implementation contract using the `delegatecall` opcode, executing the implementation's code in the proxy's storage context.
+
+When the owner/admin of the proxy wants to upgrade
+
+![Proxy Pattern Basic Flow](/common-images/permissioned-l1s/ProxyBasic.png)
+
+## Common Proxy Patterns
+
+### 1. Transparent Proxy Pattern
+
+The Transparent Proxy pattern, developed by OpenZeppelin, ensures clear separation between admin and user interactions:
+
+- Admin calls are handled by the proxy itself
+- User calls are delegated to the implementation
+- Prevents function selector clashes between proxy and implementation
+
+### 2. UUPS (Universal Upgradeable Proxy Standard)
+
+UUPS moves the upgrade logic to the implementation contract itself:
+
+- More gas-efficient than transparent proxies
+- Implementation controls its own upgradeability
+- Requires careful implementation to avoid locking upgrades
+
+### 3. Beacon Proxy Pattern
+
+Beacon proxies enable multiple proxy instances to share the same implementation:
+
+- All proxies point to a single beacon contract
+- Beacon contract holds the implementation address
+- Upgrading the beacon updates all proxy instances simultaneously
+
+## Advantages of Proxy Patterns
+
+1. **Upgradability Without Address Changes** - Users and integrations can continue using the same contract address even after upgrades, preserving user interfaces, exchange listings, and historical transaction references.
+2. **Bug Fixes and Security Patches** - Critical vulnerabilities can be addressed without requiring users to migrate to a new contract, enabling rapid response to security incidents with minimal disruption.
+3. **Feature Addition and Optimization** - New functionality can be added over time including gas optimization improvements, new features based on user feedback, and integration with newer protocols.
+
+## Risks and Considerations
+
+1. **Centralization Risk** - Upgrade capabilities rest with a single admin or small group, creating a single point of failure and potential for malicious upgrades.
+2. **Function Selector Clashes** - Proxy and implementation functions can have matching selectors, causing unexpected behavior, security vulnerabilities, and upgrade failures.
+3. **Complexity** - Proxy patterns add complexity through additional gas costs for delegatecall operations and make contracts harder to audit and verify.
diff --git a/content/academy/permissioned-l1s/01-introduction/05-transparent-proxy.mdx b/content/academy/permissioned-l1s/01-introduction/05-transparent-proxy.mdx
@@ -0,0 +1,50 @@
+---
+title: Transparent Proxy
+description: In-depth guide of the Transparent Proxy smart contract structure flows
+updated: 2025-01-10
+authors: [nicolasarnedo]
+icon: BookOpen
+---
+
+**Key Components:**
+- **TransparentUpgradeableProxy**: Main proxy with immutable admin address for gas efficiency
+- **ProxyAdmin**: Administrative contract managing upgrades through ownership transfer capability
+- **Implementation**: Contains actual business logic, upgradeable via ProxyAdmin
+
+## Admin Flow
+
+Admins can only call upgrade functions. All other calls are blocked to prevent selector clashes.
+
+<Mermaid
+  chart="
+sequenceDiagram
+    participant Admin
+    participant ProxyAdmin
+    participant TransparentProxy
+    participant NewImplementation
+
+    Admin->>ProxyAdmin: upgradeAndCall(proxy, newImpl, data)
+    ProxyAdmin->>TransparentProxy: upgradeToAndCall(newImpl, data)
+    TransparentProxy->>TransparentProxy: _dispatchUpgradeToAndCall()
+    TransparentProxy->>NewImplementation: delegatecall(data) [if data provided]
+"
+/>
+
+## User Flow
+
+Regular users can call any function except upgrade functions, which are delegated to the implementation contract.
+
+<Mermaid
+  chart="
+sequenceDiagram
+    participant User
+    participant TransparentProxy
+    participant Implementation
+
+    User->>TransparentProxy: call someFunction()
+    Note over TransparentProxy: msg.sender != admin
+    TransparentProxy->>Implementation: delegatecall(someFunction())
+    Implementation-->>TransparentProxy: return result
+    TransparentProxy-->>User: return result
+"
+/>
diff --git a/content/academy/permissioned-l1s/02-proof-of-authority/03-validator-manager-contract.mdx b/content/academy/permissioned-l1s/02-proof-of-authority/03-validator-manager-contract.mdx
@@ -11,7 +11,36 @@ The contracts in the [`validator-manager`](https://github.com/ava-labs/icm-contr
 
 For this section we have blurred out some of the contracts, as these are not relevant to the Proof of Authority hierarchy used to create a **permissioned L1**:
 
-![Validator Manager Contract Class Diagram](/common-images/permissioned-l1s/ValidatorManagerContractBlurr.png)
+<div style={{ display: 'flex', justifyContent: 'center', margin: '2rem 0' }}>
+  <Mermaid
+    chart="
+classDiagram
+class ACP99Manager {
+    +initializeValidatorSet()
+    +completeValidatorRegistration()
+    +completeValidatorRemoval()
+    +completeValidatorWeightUpdate()
+    -_initiateValidatorRegistration()
+    -_initiateValidatorRemoval()
+    -_initiateValidatorWeightUpdate()
+}
+<<Abstract>> ACP99Manager
+
+class ValidatorManager {
+    +initializeValidatorSet()
+    +completeValidatorRegistration() onlyOwner
+    +completeValidatorRemoval() onlyOwner
+    +completeValidatorWeightUpdate() onlyOwner
+    +initiateValidatorRegistration() onlyOwner
+    +initiateValidatorRemoval() onlyOwner
+    +initiateValidatorWeightUpdate() onlyOwner
+}
+
+ACP99Manager <|-- ValidatorManager
+"
+  />
+</div>
+
 
 ## Understanding Contract Hierarchy
 
@@ -44,30 +73,4 @@ The `ValidatorManager` extends `ACP99Manager` and adds the complete validator li
 - Tracks validator states throughout their lifecycle
 - Handles Warp message construction and verification
 
-### PoAManager (Access Control Layer)
-
-The `PoAManager` is a separate contract that provides a Proof of Authority interface to the ValidatorManager:
-
-**Architecture Pattern:**
-- Uses composition rather than inheritance (has a ValidatorManager, doesn't extend it)
-- Acts as an access control proxy to the ValidatorManager
-- Separates ownership concerns from core validator logic
-
-**Key Functions:**
-- **Initiate functions** (onlyOwner): Only the PoA owner can start validator operations
-- **Complete functions** (no restrictions): Anyone can complete pending operations once initiated
-- **`transferValidatorManagerOwnership()`** (onlyOwner): Allows transferring control of the underlying ValidatorManager
-
-This separation of concerns allows the same ValidatorManager to be used with different access control models (PoA, PoS, or custom governance) by simply changing the controlling contract.
-
-### PoA Architecture Benefits
-
-The two-contract design provides several advantages:
-
-- **Separation of Concerns**: Core validator logic is separate from access control
-- **Upgradeability**: ValidatorManager can be upgraded without affecting PoAManager
-- **Flexibility**: Different access control models can be implemented without changing the core
-- **Security**: Owner permissions are clearly defined and isolated in PoAManager
-
-
 <Quiz quizId="413" />
diff --git a/public/common-images/permissioned-l1s/ProxyBasic.png b/public/common-images/permissioned-l1s/ProxyBasic.png
diff --git a/public/common-images/permissioned-l1s/ValidatorManagerContractBlurr.png b/public/common-images/permissioned-l1s/ValidatorManagerContractBlurr.png
diff --git a/toolbox/src/versions.json b/toolbox/src/versions.json
@@ -1,5 +1,5 @@
 {
   "avaplatform/avalanchego": "v1.13.3",
-  "avaplatform/subnet-evm_avalanchego": "v0.7.7_v1.13.3",
+  "avaplatform/subnet-evm_avalanchego": "v0.7.8_v1.13.4",
   "avaplatform/icm-relayer": "v1.6.6"
 }

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`	`2`	`"avaplatform/avalanchego": "v1.13.3",`
`3`		`- "avaplatform/subnet-evm_avalanchego": "v0.7.7_v1.13.3",`
	`3`	`+ "avaplatform/subnet-evm_avalanchego": "v0.7.8_v1.13.4",`
`4`	`4`	`"avaplatform/icm-relayer": "v1.6.6"`
`5`	`5`	`}`