stellar-governance 0.7.1

Governance Utilities for Stellar contracts.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

# Stellar Governance

Stellar governance functionalities

This crate is part of the [OpenZeppelin Stellar Contracts](https://github.com/OpenZeppelin/stellar-contracts) library, which is published as separate crates on [crates.io](https://crates.io):

- [stellar-access](https://crates.io/crates/stellar-access): Role-based access controls and ownable
- [stellar-accounts](https://crates.io/crates/stellar-accounts): Smart accounts with custom authentication and authorization
- [stellar-contract-utils](https://crates.io/crates/stellar-contract-utils): Utilities for contracts (pausable, upgradeable, cryptography, etc.)
- [stellar-fee-abstraction](https://crates.io/crates/stellar-fee-abstraction): Fee abstraction utilities
- **[stellar-governance](https://crates.io/crates/stellar-governance)**: Governance utilities (governor, votes, timelock)
- [stellar-macros](https://crates.io/crates/stellar-macros): Proc macros (`#[only_owner]`, `#[when_not_paused]`, etc.)
- [stellar-tokens](https://crates.io/crates/stellar-tokens): Token types (fungible, non-fungible, real-world assets, vaults)

Refer to the [OpenZeppelin for Stellar Contracts](https://docs.openzeppelin.com/stellar-contracts) page for additional information.

## Overview

This package provides governance modules for Soroban smart contracts:

- **Governor**: On-chain governance with proposals, voting, counting, and execution
- **Votes**: Vote tracking with delegation and historical checkpointing
- **Timelock**: Time-delayed execution of operations

## Modules

### Governor

The `governor` module implements on-chain governance for Soroban contracts. It provides the core governance primitives for decentralized decision-making.

#### Core Concepts

- **Proposals**: Bundles of on-chain calls (targets, functions, arguments) paired with a description
- **Voting**: Token holders vote during a voting period using snapshot-based voting power
- **Counting**: Default simple counting (Against/For/Abstain) with pluggable alternatives
- **Execution**: Successful proposals can be executed, triggering on-chain calls
- **Queuing**: Optional queue step for integration with a timelock (disabled by default, enabled with a single override)

#### Key Features

- Snapshot-based voting power prevents flash loan attacks
- Proposal threshold prevents governance spam
- Dynamic quorum support (override `quorum()` for supply-relative quorum)
- Queue logic is built into the base trait but disabled by default — a single `proposals_need_queuing()` override activates the full flow
- `execute` and `cancel` have no default implementation, requiring explicit access control decisions

### Votes

The `votes` module provides vote tracking functionality with delegation and historical checkpointing for governance mechanisms.

#### Core Concepts

- **Voting Units**: The base unit of voting power, typically 1:1 with token balance
- **Delegation**: Accounts can delegate their voting power to another account (delegatee)
- **Checkpoints**: Historical snapshots of voting power at specific ledger sequence numbers
- **Clock Mode**: Uses ledger sequence numbers (`e.ledger().sequence()`) as the timepoint reference

#### Key Features

- Track voting power per account with historical checkpoints
- Support delegation (an account can delegate its voting power to another account)
- Provide historical vote queries at any past ledger sequence number
- Explicit delegation required (accounts must self-delegate to use their own voting power)
- Non-delegated voting units are not counted as votes

### Timelock

The `timelock` module provides functionality for time-delayed execution of operations, enabling governance mechanisms where actions must wait for a minimum delay before execution.

#### Core Concepts

- **Operations**: Actions to be executed on target contracts
- **Scheduling**: Proposing an operation with a delay period
- **Execution**: Running the operation after the delay has passed
- **Cancellation**: Removing a scheduled operation before execution
- **Predecessors**: Dependencies between operations (operation B requires operation A to be done first)

#### Usage Example

```rust
use soroban_sdk::{contract, contractimpl, Address, BytesN, Env, Symbol, Val, Vec};
use stellar_governance::timelock::{
    schedule_operation, execute_operation, cancel_operation,
    get_operation_state, set_min_delay, Operation, OperationState,
};

#[contract]
pub struct TimelockController;

#[contractimpl]
impl TimelockController {
    pub fn __constructor(e: &Env, min_delay: u32) {
        set_min_delay(e, min_delay);
    }

    pub fn schedule(
        e: &Env,
        target: Address,
        function: Symbol,
        args: Vec<Val>,
        predecessor: BytesN<32>,
        salt: BytesN<32>,
        delay: u32,
    ) -> BytesN<32> {
        // Add authorization checks here
        let operation = Operation {
            target,
            function,
            args,
            predecessor,
            salt,
        };
        schedule_operation(e, &operation, delay)
    }

    pub fn execute(
        e: &Env,
        target: Address,
        function: Symbol,
        args: Vec<Val>,
        predecessor: BytesN<32>,
        salt: BytesN<32>,
    ) {
        // Add authorization checks here
        let operation = Operation {
            target,
            function,
            args,
            predecessor,
            salt,
        };
        execute_operation(e, &operation);
    }

    pub fn cancel(e: &Env, id: BytesN<32>) {
        // Add authorization checks here
        cancel_operation(e, &id);
    }
}
```

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
# We recommend pinning to a specific version, because rapid iterations are expected as the library is in an active development phase.
stellar-governance = "=0.7.1"
```

## Examples

See the following examples in the repository:
- [`examples/fungible-governor/`](https://github.com/OpenZeppelin/stellar-contracts/tree/main/examples/fungible-governor) - Governor with fungible token voting
- [`examples/fungible-governor-timelock/`](https://github.com/OpenZeppelin/stellar-contracts/tree/main/examples/fungible-governor-timelock) - Governor with timelock queue
- [`examples/fungible-votes/`](https://github.com/OpenZeppelin/stellar-contracts/tree/main/examples/fungible-votes) - Fungible token with voting extension
- [`examples/timelock-controller/`](https://github.com/OpenZeppelin/stellar-contracts/tree/main/examples/timelock-controller) - Timelock controller with role-based access control