Skip to main content

​
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.
For how blacklist and authorized accounts affect transaction processing and state transitions, refer to:

​
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:
ParameterTypeDescription
membersaddress listCouncil governance members (GovBase)
quorumuintMinimum approvals required for execution (GovBase)
expiryuintProposal expiration time in seconds (GovBase)
memberVersionuintMember list version (GovBase)
blacklistaddress listInitial blacklist addresses
authorizedAccountsaddress listInitial 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.