π Governance — Algorithm Extraction

Language-agnostic pseudocode extracted from Phoenix Python source. Source files: governance.py (268L), axioms.py (726L).

1. Proposal Lifecycle 

PENDING --activation threshold--> ACTIVE --voting period ends--> PASSED
                                                               --> REJECTED

enum ProposalStatus:
    PENDING     // Submitted; awaiting activation (minimum sponsorship)
    ACTIVE      // Voting period open
    PASSED      // 66% weighted threshold met; moves to time-lock
    REJECTED    // Voting period ended; threshold not met

struct Proposal:
    id:              bytes32
    category:        VotingCategory
    proposer:        NodeId
    title:           string
    description:     string
    payload:         bytes           // encoded state mutation
    status:          ProposalStatus
    created_epoch:   int64
    active_epoch:    int64?          // set when PENDING -> ACTIVE
    closed_epoch:    int64?          // set when ACTIVE -> PASSED/REJECTED
    votes:           Vote[]
    time_lock:       TimeLock?       // set when PASSED

function submit_proposal(proposer: NodeId, category: VotingCategory, payload: bytes) -> Proposal:
    require can_govern(proposer.reputation)    // governance rep >= 4000
    return Proposal {
        id:            sha256(proposer || payload || current_epoch),
        category:      category,
        proposer:      proposer,
        status:        PENDING,
        created_epoch: current_epoch,
    }

function activate_proposal(proposal: Proposal):
    require proposal.status == PENDING
    require count_sponsors(proposal.id) >= MIN_SPONSORS   // minimum backing
    proposal.status = ACTIVE
    proposal.active_epoch = current_epoch

2. Voting Categories 

enum VotingCategory:
    ECONOMICS      // Token distribution, decay rates, gain ceilings
    SOCIAL         // Reputation policy, identity rules, vouching
    INVARIANTS     // System invariants (requires supermajority)
    GENERAL        // All other governance matters

3. QuadraticVote: cost = votes², power = sqrt(credits) 

// Quadratic voting: prevents whale domination
// Credits = governance reputation units allocated for voting

function quadratic_cost(votes_desired: int64) -> int64:
    // Cost in credits to cast `votes_desired` votes on one proposal
    return votes_desired * votes_desired    // v²

function quadratic_power(credits_spent: int64) -> int64:
    // Voting power from `credits_spent` credits
    return isqrt(credits_spent)            // sqrt(c)

// Example: spend 100 credits -> sqrt(100) = 10 voting power
//          spend 400 credits -> sqrt(400) = 20 voting power (doubled power, 4× cost)

struct Vote:
    proposal_id:    bytes32
    voter:          NodeId
    credits_spent:  int64
    power:          int64           // = isqrt(credits_spent)
    direction:      VoteDirection   // FOR / AGAINST / ABSTAIN
    epoch:          int64
    signature:      Ed25519Signature

function cast_vote(voter: NodeId, proposal_id: bytes32, credits: int64, direction: VoteDirection):
    require credits <= voter.available_governance_credits
    require proposal.status == ACTIVE

    power = isqrt(credits)
    voter.available_governance_credits -= credits

    vote = Vote {
        proposal_id:   proposal_id,
        voter:         voter.id,
        credits_spent: credits,
        power:         power,
        direction:     direction,
        epoch:         current_epoch,
    }
    proposal.votes.append(vote)

4. 66% Weighted Threshold for Passing 

QUADRATIC_THRESHOLD = 0.66    // 66% of weighted voting power must be FOR
SIMPLE_THRESHOLD    = 3       // simple mode: need 3 sponsors (small groups)

function compute_result(proposal: Proposal) -> ProposalStatus:
    total_power_for     = sum(v.power for v in proposal.votes if v.direction == FOR)
    total_power_against = sum(v.power for v in proposal.votes if v.direction == AGAINST)
    total_power         = total_power_for + total_power_against

    if total_power == 0: return REJECTED    // no votes cast

    weighted_ratio = total_power_for / total_power

    if weighted_ratio >= QUADRATIC_THRESHOLD:
        return PASSED
    else:
        return REJECTED

5. 3-Stage Time-Lock Structure

After a proposal PASSES, it enters a time-lock before execution:

struct TimeLock:
    proposal_id:    bytes32
    stage:          int         // 1, 2, or 3
    unlock_epoch:   int64       // epoch when this stage unlocks
    executed:       bool

TIME_LOCK_STAGES = [
    { stage: 1, duration_epochs: 10  },    // Initial delay
    { stage: 2, duration_epochs: 20  },    // Challenge window
    { stage: 3, duration_epochs: 50  },    // Final confirmation (INVARIANTS only)
]

function create_time_lock(proposal: Proposal) -> TimeLock:
    stages = 1 if proposal.category != INVARIANTS else 3
    return TimeLock {
        proposal_id:  proposal.id,
        stage:        1,
        unlock_epoch: current_epoch + TIME_LOCK_STAGES[0].duration_epochs,
        executed:     false,
    }

function advance_time_lock(lock: TimeLock, proposal: Proposal):
    if current_epoch < lock.unlock_epoch:
        return    // not yet unlocked

    if lock.stage < required_stages(proposal.category):
        // Advance to next stage
        lock.stage += 1
        lock.unlock_epoch = current_epoch + TIME_LOCK_STAGES[lock.stage - 1].duration_epochs
    else:
        // All stages complete; execute
        execute_proposal(proposal)
        lock.executed = true

function required_stages(category: VotingCategory) -> int:
    if category == INVARIANTS: return 3
    return 1

6. Constitutional Guards: AX-01 through AX-12

From axioms.py (726L). Each axiom defines what the ConstitutionalChecker protects:

Axiom Name Protects
AX-01 Identity Sovereignty Every participant owns their identity; no forced identity reassignment
AX-02 Non-Coercion No action may be extracted under threat or manipulation
AX-03 Proportionality Penalties proportional to offense; no excessive punishment
AX-04 Transparency All governance decisions visible to all participants
AX-05 Reversibility Except ABSOLUTE finality, all states have defined reversal paths
AX-06 Due Process Disputes require evidence; no ex parte decisions
AX-07 Consensus Integrity No forking without quorum evidence; no unilateral state changes
AX-08 Reputation Fairness Reputation can only change via defined actions; no admin override
AX-09 Token Permanence L3 tokens (MORAL/SYSTEMIC) cannot be deleted by any party
AX-10 Stake Protection Staked funds protected until contract resolution
AX-11 Fork Rights Any minority may fork with their current state snapshot
AX-12 Exit Rights Any participant may voluntarily exit with their reputation intact 
function check_axiom(action: Action, axiom_id: AxiomId, context: State) -> AxiomResult:
    axiom = AXIOMS[axiom_id]
    if axiom.predicate(action, context):
        return AxiomResult { violated: false }
    return AxiomResult {
        violated: true,
        axiom_id: axiom_id,
        reason:   axiom.violation_message,
    }

function constitutional_check(action: Action, context: State) -> ConstitutionalResult:
    for axiom_id in AxiomId:
        result = check_axiom(action, axiom_id, context)
        if result.violated:
            return ConstitutionalResult {
                allowed: false,
                violation: AxiomViolation {
                    axiom_id: axiom_id,
                    action:   action,
                    evidence: result,
                },
            }
    return ConstitutionalResult { allowed: true }

7. AxiomViolation Detection 

struct AxiomViolation:
    axiom_id:  AxiomId
    action:    Action
    evidence:  bytes            // serialized proof of violation
    epoch:     int64
    reporter:  NodeId

function handle_axiom_violation(violation: AxiomViolation):
    // 1. Block the action immediately
    reject_action(violation.action)

    // 2. Record violation in governance log
    governance_log.append(violation)

    // 3. Trigger automatic freeze if severe
    if violation.axiom_id in [AX-07, AX-09, AX-10]:
        freeze_actor(violation.action.initiator, epochs=50)

    // 4. Escalate to governance proposal if systemic
    if is_systemic_violation(violation):
        submit_proposal(
            category=INVARIANTS,
            payload=encode_remediation(violation),
        )

8. Entropy Injection Mechanism

Prevents voting patterns from becoming predictable or gameable:

// Entropy injection: mix VRF randomness into credit allocation
function compute_voting_credits(node: NodeId, epoch: int64) -> int64:
    base_credits = node.reputation[GOVERNANCE]

    // VRF entropy per epoch to prevent pre-computed strategies
    vrf_output, _ = vrf_prove(node.secret_key, hash("voting-entropy" || epoch))
    entropy_factor = (bytes_to_int(vrf_output[:4]) % 1000) + 9000    // 90%..100%

    return (base_credits * entropy_factor) / 10000

// Credits reset each epoch; unused credits do not carry forward
// This prevents vote accumulation attacks

9. GovernanceManager Algorithm 

class GovernanceManager:
    proposals: Map<bytes32, Proposal>
    time_locks: Map<bytes32, TimeLock>

    function process_epoch(epoch: int64):
        for proposal in active_proposals():
            // Check if voting period ended
            if epoch >= proposal.active_epoch + VOTING_PERIOD_EPOCHS:
                result = compute_result(proposal)
                proposal.status = result
                if result == PASSED:
                    lock = create_time_lock(proposal)
                    self.time_locks[proposal.id] = lock

        for lock in pending_locks():
            advance_time_lock(lock, self.proposals[lock.proposal_id])

    function execute_proposal(proposal: Proposal):
        // Decode and apply the state mutation
        mutation = decode_payload(proposal.payload)
        const_result = constitutional_check(mutation, current_state)
        if not const_result.allowed:
            handle_axiom_violation(const_result.violation)
            return

        apply_mutation(mutation)
        emit GovernanceExecuted { proposal_id: proposal.id, epoch: current_epoch }

10. Dependencies

Module Interaction
κ Rule Engine Policy checks gate governance actions
θ Consensus Votes require finality; proposal execution needs quorum
λ Reputation Governance reputation gates proposal and vote rights
ι State Fork Rejected proposals may trigger voluntary forks
μ Integrity Constitutional guards checked before any state mutation
[[concepts/π-governance π Governance]] · [[spec/S01-constitution S01 Constitution Spec]] · [[reference/extractions/theta-consensus-extraction θ Extraction]] · [[reference/extractions/iota-state-fork-extraction ι Extraction]] · [[reference/extractions/xi-identity-extraction ξ Extraction]]

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.