> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Council Governance (GovCouncil)

## Purpose and Scope

This document describes the role of the `GovCouncil` system contract within the StableNet governance architecture.\
GovCouncil manages the network-wide **blacklist** and **authorized account set**, and enforces account-level restrictions consistently by integrating with the on-chain `AccountManager` native precompile.

For an overview of all system contracts and their addresses, see [System Contracts Overview](/en/governance-system/5.1-system-contracts-overview).\
For how blacklist and authorized accounts affect transaction processing and state transitions, refer to:

* [State Transitions and Gas](/en/transaction-processing/6.2-state-transitions-and-gas)
* [Fee Delegation](/en/transaction-processing/6.5-fee-delegation)

## Contract Overview

GovCouncil is deployed at the following fixed address:

* **GovCouncil**: `0x0000000000000000000000000000000000001004`

Like other governance contracts (`GovValidator`, `GovMasterMinter`, `GovMinter`), GovCouncil inherits from the common base contract `GovBase`, and extends it with Council-specific state and actions.

Its responsibilities include:

* Managing the network-wide **blacklist** set
* Managing the **authorized account** set for privileged or priority operations
* Bridging these sets to the `AccountManager` native precompile, enabling fast and consistent checks during EVM execution and precompile handling

In summary:

* **GovBase** provides membership management, quorum calculation, proposal lifecycle, and execution-safety logic.
* **GovCouncil** defines domain-specific governance actions for modifying blacklist and authorized account sets.
* **AccountManager** and the EVM query these sets to enforce Anzeon-specific policies during transaction processing.

## Governance Responsibilities

The primary responsibilities of GovCouncil are:

* Adding or removing accounts from the **blacklist** when they must be restricted from sending or receiving transactions
* Defining and updating the set of **authorized accounts** allowed to perform privileged management actions or priority transactions
* Ensuring that all such changes are applied **only** through the quorum-based proposal and voting model provided by `GovBase`

### Example Governance Actions

While concrete Solidity action types are defined in the GovCouncil contract, conceptually they include:

* **Add to blacklist**: Add one or more addresses to the blacklist set
* **Remove from blacklist**: Remove existing addresses from the blacklist set
* **Add authorized account**: Grant authorized status to a specific account
* **Remove authorized account**: Revoke authorized status from an account

All actions are created as proposals, and no on-chain state change can occur without quorum approval by Council members.

## Storage Model

GovCouncil extends `GovBase` and defines additional storage slots for Council-specific state.\
The storage layout is implemented in `systemcontracts/gov_council.go` and is conceptually organized as follows:

* Slots `0x00–0x31`: Common `GovBase` storage\
  (member list, quorum, proposal data, execution state, reentrancy protection, etc.)
* Slots `0x32–0x35`: GovCouncil-specific storage
  * `0x32`: `_currentBlacklist` values slot (AddressSet)
  * `0x33`: `_currentBlacklist` positions mapping slot
  * `0x34`: `_currentAuthorizedAccounts` values slot (AddressSet)
  * `0x35`: `_currentAuthorizedAccounts` positions mapping slot
* Slot `0x36`: `__accountManager` address (`AccountManager` native precompile)

### AddressSet Encoding

Both `blacklist` and `authorizedAccounts` use the **AddressSet** structure defined in the shared `AddressSetLib` library.

* Each AddressSet consists of **two slots**:
  * **values slot**: Stores the array length at the base slot; actual elements are stored at `keccak256(valuesSlot) + index`
  * **positions slot**: Stores a mapping `address → index + 1`; a value of `0` means the address is not in the set

This structure enables:

* Near O(1) membership checks for `IsBlacklisted` and `IsAuthorizedAccount`
* Full enumeration via `GetAllBlacklisted` and `GetAllAuthorizedAccounts`
* Safe initialization with zero-address checks and duplicate elimination

### Genesis Initialization Parameters

GovCouncil is initialized at genesis via the `initializeGovCouncil` logic with the following parameters:

| Parameter            | Type         | Description                                        |
| -------------------- | ------------ | -------------------------------------------------- |
| `members`            | address list | Council governance members (GovBase)               |
| `quorum`             | uint         | Minimum approvals required for execution (GovBase) |
| `expiry`             | uint         | Proposal expiration time in seconds (GovBase)      |
| `memberVersion`      | uint         | Member list version (GovBase)                      |
| `blacklist`          | address list | Initial blacklist addresses                        |
| `authorizedAccounts` | address list | Initial authorized account addresses               |

During initialization, the following steps are performed:

* Validation against the zero address
* Duplicate address removal
* Encoding of `blacklist` and `authorizedAccounts` into AddressSet form in slots `0x32–0x35`
* Writing the `AccountManager` precompile address into slot `0x36` to link the account-policy layer

## Integration with AccountManager and the EVM

GovCouncil does not directly check blacklist or authorization status during transaction execution.\
Instead, it acts as the **single source of truth** for these sets.

Other components query GovCouncil state via helper functions defined in `gov_council.go`:

* `IsBlacklisted(govCouncilAddress, state, addr)`
  * Returns `true` if the address is in the blacklist
* `GetBlacklistCount`, `GetBlacklistedAddress`, `GetAllBlacklisted`
  * Used for enumeration and monitoring
* `IsAuthorizedAccount(govCouncilAddress, state, addr)`
  * Returns `true` if the address is an authorized account
* `GetAuthorizedAccountCount`, `GetAuthorizedAccountAddress`, `GetAllAuthorizedAccounts`
  * Used to enumerate authorized accounts

The `AccountManager` precompile and the EVM use this information to enforce policies such as:

* Rejecting transactions where the sender is blacklisted
* Blocking transfers or calls targeting blacklisted accounts
* Restricting certain management functions or special transactions to authorized accounts only

## Proposal and Voting Model

GovCouncil inherits the **proposal lifecycle and quorum-based voting model** directly from `GovBase`.\
As a result, its operational pattern is identical to other Gov\* contracts.

* **Members**: The set of Council members who can create proposals and vote
* **Quorum**: Minimum number of approvals required before execution
* **Expiry**: Proposal validity period; expired proposals cannot be executed
* **Member Versioning**: `memberVersion` increments on membership changes, invalidating older proposals

The conceptual proposal flow is as follows:

1. A member creates a proposal to modify the blacklist or authorized account set.
2. Other members review the proposal and vote to approve or reject it.
3. Once approvals reach quorum and the proposal has not expired, it becomes executable.
4. Upon execution, the AddressSet is updated and corresponding events are emitted.

Concrete action types and events are defined in the Solidity implementation of GovCouncil,\
but the high-level behavior is consistent across all governance contracts using GovBase.

## Operational Considerations

When configuring and operating GovCouncil, consider the following:

* **Initial blacklist and authorized accounts**
  * These can be set at genesis via `systemContracts.govCouncil.params.*`.
  * They take effect immediately from the first block, so careful review before deployment is essential.

* **Balance between quorum and member count**
  * A quorum that is too low may allow overly easy policy changes.
  * A quorum that is too high may delay emergency blacklist actions.
  * A balanced configuration aligned with network characteristics is required.

* **Monitoring**
  * Off-chain services can periodically query `GetAllBlacklisted` and `GetAllAuthorizedAccounts` to track changes.
  * Wallets or explorers can display blacklist or authorized status on account detail pages.

* **Integration with transaction processing**
  * During transaction validation and state transition, AccountManager or GovCouncil helpers can enforce:
    * Rejection of transactions from blacklisted accounts
    * Blocking calls targeting blacklisted accounts
    * Restricting specific management functions to authorized accounts

Together with `GovValidator`, `GovMasterMinter`, and `GovMinter`, GovCouncil forms StableNet’s **policy layer**.\
It defines which accounts are restricted or privileged, and ensures these decisions are applied consistently across the entire network.