Martinh/multigov sol architecture (#267)

* add solana staking program

* add solana workflow steps

* llm check

* grammarly check

* llm check

* update index to include solana architecture

* llm check

* Update learn/governance/architecture.md

Co-authored-by: Dawn Kelly <83190195+dawnkelly09@users.noreply.github.com>

* Update learn/governance/architecture.md

Co-authored-by: Dawn Kelly <83190195+dawnkelly09@users.noreply.github.com>

* llm check

---------

Co-authored-by: Dawn Kelly <83190195+dawnkelly09@users.noreply.github.com>

Author: martin0995

learn/governance/architecture.md

@@ -27,28 +27,87 @@ Spoke chains handle local voting, forward votes to the hub, and execute approved
    - **`SpokeVoteAggregator`** - collects votes on the spoke chain and forwards them to the hub
    - **`SpokeMessageExecutor`** - receives and executes approved proposals from the hub
    - **`SpokeMetadataCollector`** - fetches proposal metadata from the hub for spoke chain voters
-   - **`SpokeAirlock`** - acts as governance's "admin" on the spoke, has permissions and its treasury
+   - **`SpokeAirlock`** - acts as governance's "admin" on the spoke, has permissions, and its treasury
+
+### Spoke Solana Staking Program
+
+The Spoke Solana Staking Program handles local voting from users who have staked W tokens or are vested in the program, forwards votes to the hub, and executes approved proposals from the hub for decentralized governance.
+
+The program implements its functionality through instructions, using specialized PDA accounts where data is stored. Below are the key accounts in the program:
+
+ - **`GlobalConfig`** - global program configuration
+ - **`StakeAccountMetadata`** - stores user's staking information
+ - **`CustodyAuthority`** - PDA account managing custody and overseeing token operations related to stake accounts
+ - **`StakeAccountCustody`** - token account associated with a stake account for securely storing staked tokens
+ - **`CheckpointData`** - tracks delegation history
+ - **`SpokeMetadataCollector`** - collects and updates proposal metadata from the hub chain
+ - **`GuardianSignatures`** - stores guardian signatures for message verification
+ - **`ProposalData`** - stores data about a specific proposal, including votes and start time
+ - **`ProposalVotersWeightCast`** - tracks individual voter's weight for a proposal
+ - **`SpokeMessageExecutor`** - processes messages from a spoke chain via the Wormhole protocol
+ - **`SpokeAirlock`** - manages PDA signing and seed validation for secure instruction execution
+ - **`VestingBalance`** - stores total vesting balance and related staking information of a vester
+ - **`VestingConfig`** - defines vesting configuration, including mint and admin details
+ - **`Vesting`** - represents individual vesting allocations with maturation data
+ - **`VoteWeightWindowLengths`** - tracks lengths of vote weight windows
+
+Each account is implemented as a Solana PDA (Program Derived Address) and utilizes Anchor's account framework for serialization and management.
 
 ## System Workflow
 
-The MultiGov system workflow details the step-by-step process for creating, voting on and executing governance proposals across connected chains, from proposal creation to final cross-chain execution.
+The MultiGov system workflow details the step-by-step process for creating, voting on, and executing governance proposals across connected chains, from proposal creation to final cross-chain execution.
+
+### EVM Governance Workflow
+
+The EVM-based MultiGov workflow follows these steps:
+
+1. **Proposal creation**:
+    1. A user creates a proposal through the `HubEvmSpokeAggregateProposer`, which checks eligibility across chains, or directly on the `HubGovernor` via the `propose` method
+    2. The proposal is submitted to the `HubGovernor` if the user meets the proposal threshold
+2. **Proposal metadata distribution**:
+    1. `HubProposalMetadata` creates a custom view method to be queried for use in the `SpokeMetadataCollector`
+    2. `SpokeMetadataCollector` on each spoke chain queries `HubProposalMetadata` for proposal details
+3. **Voting process**:
+    1. Users on spoke chains vote through their respective `SpokeVoteAggregators`
+    2. `SpokeVoteAggregators` send aggregated votes to the `HubVotePool` via Wormhole
+    3. `HubVotePool` submits the aggregated votes to the `HubGovernor`
+4. **Vote tallying and proposal execution**:
+    1. `HubGovernor` tallies votes from all chains
+    2. If a quorum is reached and there are more for votes than against votes, the vote passes and is queued for execution
+    3. After the timelock delay, the proposal can be executed on the hub chain
+    4. For cross-chain actions, a proposal should call the `dispatch` method in the `HubMessageDispatcher`, which sends execution messages to the relevant spoke chains
+    5. `SpokeMessageExecutors` on each spoke chain receive and execute the approved actions through their respective `SpokeAirlocks`
+
+### Solana Governance Workflow
+
+The Solana-based MultiGov workflow follows these steps:
 
 1. **Proposal creation**:
-    - A user creates a proposal through the `HubEvmSpokeAggregateProposer`, which checks eligibility across chains, or directly on the `HubGovernor` via the `propose` method
-    - The proposal is submitted to the `HubGovernor` if the user meets the proposal threshold
-1. **Proposal metadata distribution**:
-    - `HubProposalMetadata` creates a custom view method to be queried for use in the `SpokeMetadataCollector`
-    - `SpokeMetadataCollector` on each spoke chain queries `HubProposalMetadata` for proposal details
-1. **Voting process**:
-    - Users on spoke chains vote through their respective `SpokeVoteAggregators`
-    - `SpokeVoteAggregators` send aggregated votes to the `HubVotePool` via Wormhole
-    - `HubVotePool` submits the aggregated votes to the `HubGovernor`
-1. **Vote tallying and proposal execution**:
-    - `HubGovernor` tallies votes from all chains
-    - If a quorum is reached and there are more for votes than against votes, the vote passes and is queued for execution
-    - After the timelock delay, the proposal can be executed on the hub chain
-    - For cross-chain actions, a proposal should call the `dispatch` method in the `HubMessageDispatcher`, which sends execution messages to the relevant spoke chains
-    - `SpokeMessageExecutors` on each spoke chain receive and execute the approved actions through their respective `SpokeAirlocks`
+    1. A user creates a proposal on `HubGovernor` by calling the `propose` method, provided they meet the proposal threshold
+    2. For the proposal to be executed on the Solana blockchain, a `SolanaPayload` must be generated and included in the `calldata` parameter of the `propose` function
+    3. The `SolanaPayload` contains encoded details specifying which instructions will be executed and which Solana program is responsible for execution
+
+2. **Proposal metadata distribution**:
+    1. A user queries `getProposalMetadata` from `HubProposalMetadata` via the Wormhole query system to create a proposal on the **Spoke Solana Chain Staking Program**
+    2. The retrieved metadata is used in the `AddProposal` instruction in the Solana program
+    3. The proposal data is verified to ensure it matches the expected format
+    4. Guardian signatures are posted using the `PostSignatures` instruction
+    5. Once validated, the proposal is stored on-chain
+
+3. **Voting process**:
+    1. Users vote on proposals stored in the `ProposalData` account on Solana
+    2. The `CastVote` instruction records their choice (`for_votes`, `against_votes`, or `abstain_votes`)
+    3. Eligibility and vote weight are verified using historical voter checkpoint data
+    4. A **Query Wormhole** request retrieves vote data from a Solana PDA
+    5. The signed response from Wormhole guardians is submitted to the `HubVotePool` on Ethereum for verification
+    6. The `crossChainVote` function in `HubVotePool` processes the validated response and forwards the aggregated vote data to the `HubGovernor` to finalize the decision
+
+4. **Vote tallying and proposal execution**:
+    1. `HubGovernor` tallies votes from all chains
+    2. If a quorum is reached with more **for votes** than **against votes**, the proposal passes and is queued for execution
+    3. After the timelock delay, the proposal can be executed either on the hub chain or another chain
+    4. For cross-chain execution involving Solana, the proposal calls the `dispatch` method in `HubSolanaMessageDispatcher`, which sends execution messages to Solana
+    5. On Solana, the `ReceiveMessage` instruction processes the approved message, and the `SpokeAirlock` executes the corresponding instructions
 
 ## Cross-Chain Communication
 

learn/governance/index.md

@@ -23,7 +23,7 @@ Discover everything you need to know about MultiGov, Wormhole's cross-chain gove
 
     ---
 
-    Discover an overview of MultiGov's hub-and-spoke architecture, including how it enables cross-chain governance by coordinating decision-making across blockchain.
+    Discover MultiGov's hub-and-spoke architecture, enabling EVM and Solana cross-chain governance through coordinated decision-making.
 
     [:custom-arrow: Learn about MultiGov architecture](/docs/learn/governance/architecture/)
 

llms.txt

@@ -15229,28 +15229,87 @@ Spoke chains handle local voting, forward votes to the hub, and execute approved
    - **`SpokeVoteAggregator`** - collects votes on the spoke chain and forwards them to the hub
    - **`SpokeMessageExecutor`** - receives and executes approved proposals from the hub
    - **`SpokeMetadataCollector`** - fetches proposal metadata from the hub for spoke chain voters
-   - **`SpokeAirlock`** - acts as governance's "admin" on the spoke, has permissions and its treasury
+   - **`SpokeAirlock`** - acts as governance's "admin" on the spoke, has permissions, and its treasury
+
+### Spoke Solana Staking Program
+
+The Spoke Solana Staking Program handles local voting from users who have staked W tokens or are vested in the program, forwards votes to the hub, and executes approved proposals from the hub for decentralized governance.
+
+The program implements its functionality through instructions, using specialized PDA accounts where data is stored. Below are the key accounts in the program:
+
+ - **`GlobalConfig`** - global program configuration
+ - **`StakeAccountMetadata`** - stores user's staking information
+ - **`CustodyAuthority`** - PDA account managing custody and overseeing token operations related to stake accounts
+ - **`StakeAccountCustody`** - token account associated with a stake account for securely storing staked tokens
+ - **`CheckpointData`** - tracks delegation history
+ - **`SpokeMetadataCollector`** - collects and updates proposal metadata from the hub chain
+ - **`GuardianSignatures`** - stores guardian signatures for message verification
+ - **`ProposalData`** - stores data about a specific proposal, including votes and start time
+ - **`ProposalVotersWeightCast`** - tracks individual voter's weight for a proposal
+ - **`SpokeMessageExecutor`** - processes messages from a spoke chain via the Wormhole protocol
+ - **`SpokeAirlock`** - manages PDA signing and seed validation for secure instruction execution
+ - **`VestingBalance`** - stores total vesting balance and related staking information of a vester
+ - **`VestingConfig`** - defines vesting configuration, including mint and admin details
+ - **`Vesting`** - represents individual vesting allocations with maturation data
+ - **`VoteWeightWindowLengths`** - tracks lengths of vote weight windows
+
+Each account is implemented as a Solana PDA (Program Derived Address) and utilizes Anchor's account framework for serialization and management.
 
 ## System Workflow
 
-The MultiGov system workflow details the step-by-step process for creating, voting on and executing governance proposals across connected chains, from proposal creation to final cross-chain execution.
+The MultiGov system workflow details the step-by-step process for creating, voting on, and executing governance proposals across connected chains, from proposal creation to final cross-chain execution.
+
+### EVM Governance Workflow
+
+The EVM-based MultiGov workflow follows these steps:
+
+1. **Proposal creation**:
+    1. A user creates a proposal through the `HubEvmSpokeAggregateProposer`, which checks eligibility across chains, or directly on the `HubGovernor` via the `propose` method
+    2. The proposal is submitted to the `HubGovernor` if the user meets the proposal threshold
+2. **Proposal metadata distribution**:
+    1. `HubProposalMetadata` creates a custom view method to be queried for use in the `SpokeMetadataCollector`
+    2. `SpokeMetadataCollector` on each spoke chain queries `HubProposalMetadata` for proposal details
+3. **Voting process**:
+    1. Users on spoke chains vote through their respective `SpokeVoteAggregators`
+    2. `SpokeVoteAggregators` send aggregated votes to the `HubVotePool` via Wormhole
+    3. `HubVotePool` submits the aggregated votes to the `HubGovernor`
+4. **Vote tallying and proposal execution**:
+    1. `HubGovernor` tallies votes from all chains
+    2. If a quorum is reached and there are more for votes than against votes, the vote passes and is queued for execution
+    3. After the timelock delay, the proposal can be executed on the hub chain
+    4. For cross-chain actions, a proposal should call the `dispatch` method in the `HubMessageDispatcher`, which sends execution messages to the relevant spoke chains
+    5. `SpokeMessageExecutors` on each spoke chain receive and execute the approved actions through their respective `SpokeAirlocks`
+
+### Solana Governance Workflow
+
+The Solana-based MultiGov workflow follows these steps:
 
 1. **Proposal creation**:
-    - A user creates a proposal through the `HubEvmSpokeAggregateProposer`, which checks eligibility across chains, or directly on the `HubGovernor` via the `propose` method
-    - The proposal is submitted to the `HubGovernor` if the user meets the proposal threshold
-1. **Proposal metadata distribution**:
-    - `HubProposalMetadata` creates a custom view method to be queried for use in the `SpokeMetadataCollector`
-    - `SpokeMetadataCollector` on each spoke chain queries `HubProposalMetadata` for proposal details
-1. **Voting process**:
-    - Users on spoke chains vote through their respective `SpokeVoteAggregators`
-    - `SpokeVoteAggregators` send aggregated votes to the `HubVotePool` via Wormhole
-    - `HubVotePool` submits the aggregated votes to the `HubGovernor`
-1. **Vote tallying and proposal execution**:
-    - `HubGovernor` tallies votes from all chains
-    - If a quorum is reached and there are more for votes than against votes, the vote passes and is queued for execution
-    - After the timelock delay, the proposal can be executed on the hub chain
-    - For cross-chain actions, a proposal should call the `dispatch` method in the `HubMessageDispatcher`, which sends execution messages to the relevant spoke chains
-    - `SpokeMessageExecutors` on each spoke chain receive and execute the approved actions through their respective `SpokeAirlocks`
+    1. A user creates a proposal on `HubGovernor` by calling the `propose` method, provided they meet the proposal threshold
+    2. For the proposal to be executed on the Solana blockchain, a `SolanaPayload` must be generated and included in the `calldata` parameter of the `propose` function
+    3. The `SolanaPayload` contains encoded details specifying which instructions will be executed and which Solana program is responsible for execution
+
+2. **Proposal metadata distribution**:
+    1. A user queries `getProposalMetadata` from `HubProposalMetadata` via the Wormhole query system to create a proposal on the **Spoke Solana Chain Staking Program**
+    2. The retrieved metadata is used in the `AddProposal` instruction in the Solana program
+    3. The proposal data is verified to ensure it matches the expected format
+    4. Guardian signatures are posted using the `PostSignatures` instruction
+    5. Once validated, the proposal is stored on-chain
+
+3. **Voting process**:
+    1. Users vote on proposals stored in the `ProposalData` account on Solana
+    2. The `CastVote` instruction records their choice (`for_votes`, `against_votes`, or `abstain_votes`)
+    3. Eligibility and vote weight are verified using historical voter checkpoint data
+    4. A **Query Wormhole** request retrieves vote data from a Solana PDA
+    5. The signed response from Wormhole guardians is submitted to the `HubVotePool` on Ethereum for verification
+    6. The `crossChainVote` function in `HubVotePool` processes the validated response and forwards the aggregated vote data to the `HubGovernor` to finalize the decision
+
+4. **Vote tallying and proposal execution**:
+    1. `HubGovernor` tallies votes from all chains
+    2. If a quorum is reached with more **for votes** than **against votes**, the proposal passes and is queued for execution
+    3. After the timelock delay, the proposal can be executed either on the hub chain or another chain
+    4. For cross-chain execution involving Solana, the proposal calls the `dispatch` method in `HubSolanaMessageDispatcher`, which sends execution messages to Solana
+    5. On Solana, the `ReceiveMessage` instruction processes the approved message, and the `SpokeAirlock` executes the corresponding instructions
 
 ## Cross-Chain Communication
 
@@ -15327,7 +15386,7 @@ Discover everything you need to know about MultiGov, Wormhole's cross-chain gove
 
     ---
 
-    Discover an overview of MultiGov's hub-and-spoke architecture, including how it enables cross-chain governance by coordinating decision-making across blockchain.
+    Discover MultiGov's hub-and-spoke architecture, enabling EVM and Solana cross-chain governance through coordinated decision-making.
 
     [:custom-arrow: Learn about MultiGov architecture](/docs/learn/governance/architecture/)