Ilariae/multigov

build/contract-integrations/.pages

@@ -8,3 +8,4 @@ nav:
  - 'Cosmos Gateway' : 'gateway.md'
  - native-token-transfers
  - 'Development Environment': 'dev-env.md'
+ - multigov

build/contract-integrations/multigov/.pages

@@ -0,0 +1,6 @@
+title: MultiGov
+nav:
+ - index.md
+ - 'Deployment': 'deployment.md'
+ - 'Upgrading': 'upgrading.md'
+ - 'Technical FAQs': 'faq.md'

build/contract-integrations/multigov/deployment.md

@@ -0,0 +1,116 @@
+---
+title: MultiGov Deployment
+description: Set up and deploy MultiGov locally with step-by-step instructions for configuring, compiling, and deploying smart contracts across chains.
+---
+
+# Deployment 
+
+## Development Setup
+<!-- check out the getting started page first -->
+For developers looking to set up a local MultiGov environment:
+
+1. Install prerequisites:
+    - [Foundry](https://book.getfoundry.sh/getting-started/installation){target=\_blank}
+    - [Git](https://git-scm.com/downloads){target=\_blank}
+
+2. Clone the repository:
+   ```bash
+   git clone [MultiGov Repository URL]
+   cd evm # for evm testing/deploying
+   ```
+
+3. Install dependencies:
+   ```bash
+   forge install
+   ```
+
+4. Set up environment variables:
+   ```bash
+   cp .env.example .env
+   ```
+   Edit `.env` with your specific [configuration](/docs/build/multigov/deployment/#configuration){target=\_blank}
+
+5. Compile contracts:
+   ```bash
+   forge build
+   ```
+
+6. Deploy contracts (example for Sepolia testnet):
+   ```bash
+   forge script script/DeployHubContractsSepolia.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast
+   ```
+
+   For spoke chains (e.g., Optimism Sepolia):
+   ```bash
+   forge script script/DeploySpokeContractsOptimismSepolia.s.sol --rpc-url $OPTIMISM_SEPOLIA_RPC_URL --broadcast
+   ```
+
+## Configuration
+
+When deploying MultiGov, several key parameters need to be set. Here are the most important configuration points:
+
+### `HubGovernor` Key Parameters
+
+1. `initialVotingDelay` - the delay before voting on a proposal begins
+    - Type: `uint256`
+    - Measured in _seconds_
+    - Example: `86400` (1 day)
+
+2. `initialProposalThreshold` - the number of tokens needed to create a proposal
+    - Type: `uint256`
+    - Measured in _tokens_
+
+3. `initialQuorum` - the number minimum number of votes needed for a proposal to be successful
+    - Type: `uint256`
+    - Measured in _votes_
+
+4. `initialVoteWeightWindow` - a window where the minimum checkpointed voting weight is taken for a given address. The window ends at the vote start for a proposal and begins at the vote start minus the vote weight window
+    - Type: `uint256`
+    - Measured in _seconds_
+    - Example: `86400` (1 day)
+    !!! note
+        This helps mitigate cross-chain double voting.
+
+### `HubProposalExtender` Key Parameters
+
+1. `extensionDuration` - the amount of time for which target proposals will be extended
+    - Type: `uint256`
+    - Measured in _seconds_
+    - Example: `10800` (3 hours)
+
+2. `minimumExtensionDuration` - lower limit for extension duration
+    - Type: `uint256`
+    - Measured in: Seconds
+    - Example: `3600` (1 hour)
+
+#### `SpokeVoteAggregator` Key Parameters
+
+1. `initialVoteWindow` - the moving window for vote weight checkpoints. These checkpoints are taken whenever an address that is delegating sends or receives tokens
+    - Type: `uint256`
+    - Measured in: Seconds
+    - Example: `86400` (1 day)
+    !!! note
+        This is crucial for mitigating cross-chain double voting
+
+### `HubEvmSpokeVoteAggregator` Key Parameters
+1. `maxQueryTimestampOffset` - the max timestamp difference between the requested target time in the query and the current block time on the hub
+    - Type: `uint256`
+    - Measure in: Seconds
+    - Example: `1800` (30 minutes)
+
+### Updateable Governance Parameters
+
+The following key parameters can be updated through governance proposals:
+
+1. `votingDelay` - delay before voting starts (in seconds)
+2. `votingPeriod` - duration of the voting period (in seconds)
+3. `proposalThreshold` - threshold for creating proposals (in tokens)
+4. `quorum` - number of votes required for quorum
+5. `extensionDuration` - the amount of time for which target proposals will be extended (in seconds)
+6. `voteWeightWindow` - window for vote weight checkpoints (in seconds)
+7. `maxQueryTimestampOffset` - max timestamp difference allowed between a query's target time and the hub's block time
+
+These parameters can be queried using their respective getter functions on the applicable contract.
+
+To update these parameters, a governance proposal must be created, voted on, and executed through the standard MultiGov process.
+

build/contract-integrations/multigov/faq.md

@@ -0,0 +1,81 @@
+---
+title: MultiGov Technical FAQs
+description: Find answers to common questions about MultiGov, covering cross-chain governance, technical setup, security, proposal creation, and more.
+---
+
+# FAQs
+
+## Technical Questions
+
+### How does MultiGov ensure security in cross-chain communication?
+
+MultiGov leverages Wormhole's robust cross-chain communication protocol. It implements several security measures:
+
+- Message origin verification to prevent unauthorized governance actions
+- Timely and consistent data checks to ensure vote aggregation is based on recent and synchronized chain states
+- Authorized participant validation to maintain the integrity of the governance process
+- Replay attack prevention by tracking executed messages
+
+### Can MultiGov integrate with any blockchain?
+
+MultiGov can potentially integrate with any blockchain supported by Wormhole. However, specific implementations may vary depending on the chain's compatibility with Ethereum Virtual Machine (EVM) and its smart contract capabilities. [Find all supported networks here](/docs/build/start-building/supported-networks/). The current implementation of MultiGov supports an EVM Hub and both the EVM and SVM for spokes.
+
+### How are votes aggregated across different chains?
+
+Votes are collected on each spoke chain using each chain's `SpokeVoteAggregator`. These votes are then transmitted to the HubVotePool on the hub chain for aggregation and tabulation. The `HubEvmSpokeVoteDecoder` standardizes votes from different EVM chains to ensure consistent processing.
+
+### Can governance upgrade from a single chain to MultiGov?
+
+Yes! MultiGov can support progressively upgrading from a single-chain governance to MultiGov. Moving to MultiGov requires upgrading the token to NTT and adding Flexible Voting to the original Governor.
+
+## Usage Questions
+
+### How can I create a proposal in MultiGov?
+
+Proposals are created on the hub chain using the `HubEvmSpokeAggregateProposer` contract or by calling `propose` on the `HubGovernor`. You need to prepare the proposal details, including targets, values, and calldatas. The proposer's voting weight is aggregated across chains using Wormhole queries to determine eligibility.
+
+### How do I vote on a proposal if I hold tokens on a spoke chain?
+
+You can vote on proposals via the `SpokeVoteAggregator` contract on the respective spoke chain where you hold your tokens. The votes are then automatically forwarded to the hub chain for aggregation.
+
+### How are approved proposals executed across multiple chains?
+
+When a proposal is approved and the timelock period elapses, it's first executed on the hub chain. A proposal can include a cross-chain message by including a call to `dispatch` on the `HubMessageDispatcher` which sends a messages to the relevant spoke chains. On each spoke chain, the `SpokeMessageExecutor` receives, verifies, and automatically executes the instructions using the `SpokeAirlock` as the `msg.sender`.
+
+## Implementation Questions
+
+### What do I need to set up MultiGov for my project?
+
+Get started by filling out the form below:
+
+https://www.tally.xyz/get-started
+
+Tally will reach out to help get your DAO set up with MultiGov.
+
+To set up testing MultiGov for your DAO, you'll need:
+
+- [Foundry](https://book.getfoundry.sh/getting-started/installation){target=\_blank} and [Git](https://git-scm.com/downloads){target=\_blank} installed
+- Test ETH on the testnets you plan to use (e.g., Sepolia for hub, Optimism Sepolia for spoke)
+- Modify and deploy the hub and spoke contracts using the provided scripts
+- Set up the necessary environment variables and configurations
+
+### Can MultiGov be used with non-EVM chains?
+
+The current implementation is designed for EVM-compatible chains. However, Solana (non-EVM) voting is currently in development and expected to go live after the EVM contracts.
+
+### How can I customize voting parameters in MultiGov?
+
+Voting parameters such as voting delay, voting period, proposal threshold, and quorum (and others) can be customized in the deployment scripts (`DeployHubContractsSepolia.s.sol` and `DeploySpokeContractsOptimismSepolia.s.sol` as examples for their respective chains). Make sure to adjust these parameters according to your DAO's specific needs before deployment.
+
+Remember to thoroughly test your MultiGov implementation on testnets before deploying to MainNet, and have your contracts audited for additional security.
+
+### How does MultiGov handle potential network issues or temporary chain unavailability?
+
+MultiGov includes several mechanisms to handle network issues or temporary chain unavailability:
+
+1. **Asynchronous vote aggregation** - votes are aggregated periodically, allowing the system to continue functioning even if one chain is temporarily unavailable
+2. **Proposal extension** - the HubGovernorProposalExtender allows trusted actors to extend voting periods if needed, which can help mitigate issues caused by temporary network problems
+3. **Wormhole retry mechanism** - Wormhole's infrastructure includes retry mechanisms for failed message deliveries, helping ensure cross-chain messages eventually get through
+4. **Decentralized relayer network** - Wormhole's decentralized network of relayers helps maintain system availability even if some relayers are offline
+
+However, prolonged outages on the hub chain or critical spoke chains could potentially disrupt governance activities. Projects should have contingency plans for such scenarios.

build/contract-integrations/multigov/index.md

@@ -0,0 +1,51 @@
+---
+title: Getting Started
+description: Learn how to get started with MultiGov, from evaluating cross-chain governance needs to deploying with help from the Tally team.
+---
+
+# Getting Started
+
+## How to Get Started with MultiGov
+
+1. Evaluate if MultiGov meets your cross-chain governance needs
+2. Fill out the intake form on the [Tally website](https://www.tally.xyz/get-started){target=\_blank}
+3. The Tally team will review your application and contact you to discuss implementation details
+4. Work with the Tally team to customize and deploy MultiGov for your specific use case
+
+## Start Building 
+
+<div class="grid cards" markdown>
+
+-   :octicons-book-16:{ .lg .middle } **Deployment**
+
+    ---
+
+    Set up and deploy MultiGov locally with step-by-step instructions for configuring, compiling, and deploying smart contracts across chains.
+
+    [:octicons-arrow-right-16: Discover how to deploy MultiGov](/docs/build/contract-integrations/multigov/deployment/){target=\_blank}
+
+-   :octicons-book-16:{ .lg .middle } **Upgrading**
+
+    ---
+
+    Learn the process and key considerations for upgrading MultiGov, ensuring system integrity and careful planning across cross-chain components.
+
+    [:octicons-arrow-right-16: Discover how to upgrade MultiGov](/docs/build/contract-integrations/multigov/upgrading/){target=\_blank}
+
+-   :octicons-book-16:{ .lg .middle } **Guides**
+
+    ---
+
+    Access step-by-step guides for executing cross-chain governance actions, including treasury management proposals with MultiGov and Wormhole.
+
+    [:octicons-arrow-right-16: Start building](/docs/tutorials/multigov/guides/){target=\_blank}
+
+-   :octicons-book-16:{ .lg .middle } **Technical FAQs**
+
+    ---
+
+    Find answers to common technical questions about MultiGov, covering technical setup, security, proposal creation, and more.
+
+    [:octicons-arrow-right-16: Find the answer to your technical questions](/docs/build/contract-integrations/multigov/faq/){target=\_blank} 
+
+</div>

build/contract-integrations/multigov/upgrading.md

@@ -0,0 +1,65 @@
+---
+title: Upgrading MultiGov
+description: Learn the process and key considerations for upgrading MultiGov, ensuring system integrity and careful planning across cross-chain components.
+---
+
+# Upgrading
+
+MultiGov is designed to be flexible but stable. Upgrades should be rare and carefully considered due to the system's complexity and cross-chain nature. When upgrades are necessary, they must be meticulously planned and executed to ensure system integrity and continuity.
+
+## Key Considerations for Upgrades
+
+1. **HubGovernor**:
+    - Not upgradeable. A new deployment requires redeploying several components of the MultiGov system
+
+2. **HubVotePool**:
+    - Can be replaced by setting a new HubVotePool on the HubGovernor
+    - Requires re-registering all spokes on the new HubVotePool
+    - Must register the query type and implementation for vote decoding by calling [registerQueryType](https://github.com/wormhole-foundation/example-multigov/blob/main/evm/src/HubVotePool.sol#L84) on the new `HubVotePool` <!-- link not working repo not public yet -->
+    - A new proposal would have to authorize the governor to use the newly created hub vote pool and will also handle registering the appropriate query decoders and registering the appropriate spoke `SpokeVoteAggregators`
+
+3. **SpokeMessageExecutor**:
+    - Upgradeable via [UUPS](https://www.rareskills.io/post/uups-proxy) proxy pattern
+    - Stores critical parameters in `SpokeMessageExecutorStorage`
+
+4. **`HubEvmSpokeAggregateProposer`**:
+    - Needs redeployment if HubGovernor changes
+    - Requires re-registering all spokes after redeployment
+
+5. **`HubProposalMetadata`**:
+    - Needs redeployment if HubGovernor changes, as it references HubGovernor as a parameter
+
+6. **`SpokeMetadataCollector`**:
+    - Requires redeployment if the hub chain ID changes or if `HubProposalMetadata` changes
+
+## Process for Major System Upgrade <!-- (e.g., New HubGovernor) i dont really like this eg being in the title -->
+
+1. **New `HubGovernor` Deployment**:
+    - Deploy the new HubGovernor contract
+1. **Component Redeployment**:
+    - Redeploy `HubEvmSpokeAggregateProposer` with the new `HubGovernor` address
+    - Redeploy `HubProposalMetadata` referencing the new `HubGovernor`
+    - If hub chain ID changes, redeploy `SpokeMetadataCollector` on all spoke chains
+1. **`HubVotePool` Update**:
+    - Set the new `HubVotePool` on the new `HubGovernor`
+    - Register all spokes on the new `HubVotePool`
+    - Register the query type and implementation for vote decoding (`HubEvmSpokeVoteDecoder`)
+1. **Spoke Re-registration**:
+    - Re-register all spokes on the new `HubEvmSpokeAggregateProposer`
+1. **Verification and Testing**:
+    - Conduct thorough testing of the new system setup
+    - Verify all cross-chain interactions are functioning correctly
+1. **System Transition and Deprecation**:
+    - Create a proposal to switch the timelock to the new governor
+    - Communicate clearly to the community what changes were made
+1. **Monitoring**:
+    - Implement a transition period where the new system is closely monitored
+    - Address any issues that arise promptly
+
+## Important Considerations
+
+- **Always prioritize system stability** - upgrades should only be performed when absolutely necessary
+- **Thoroughly audit** all new contract implementations before proposing an upgrade
+- **Account for all affected components** across all chains in the upgrade plan
+- **Provide comprehensive documentation** for the community about the upgrade process and any changes in functionality
+- **Always test upgrades extensively** on testnets before implementing in production

learn/.pages

@@ -4,3 +4,4 @@ nav:
  - fundamentals
  - infrastructure
  - messaging
+ - governance

learn/governance/.pages

@@ -0,0 +1,6 @@
+title: Multichain Governance
+nav:
+ - index.md
+ - 'Overview': 'multigov-overview.md'
+ - 'Architecture': 'multigov-architecture.md'
+ - 'Theoretical FAQs': 'faq.md'

learn/governance/faq.md

@@ -0,0 +1,25 @@
+---
+title: MultiGov Theoretical FAQs
+description: Find answers to common questions about MultiGov, covering cross-chain governance, technical setup, security, proposal creation, and more.
+---
+
+# FAQs
+
+## General Questions
+
+### What is MultiGov?
+
+MultiGov is a cross-chain governance system that extends traditional DAO governance across multiple blockchain networks. It leverages Wormhole's interoperability infrastructure for seamless voting and proposal mechanisms across various chains.
+
+### How does MultiGov differ from traditional DAO governance?
+
+Unlike traditional DAO governance, which typically operates on a single blockchain, MultiGov allows for coordinated decision-making and proposal execution across multiple chains. This enables more inclusive participation from token holders on different networks and more complex, cross-chain governance actions.
+
+### What are the main components of MultiGov?
+
+The main components of MultiGov include:
+
+- Hub Chain - central coordination point for governance activities
+- Spoke Chains - additional chains where token holders can participate in governance
+- Wormhole Integration - enables secure cross-chain message passing
+- Governance Token - allows holders to participate in governance across all integrated chains