Xahau Network
Testnet FaucetExplorerHooks API Docs
Xahau Network
Xahau Network
  • 🪝Xahau Documentation
    • XRPL/Xahau: What is Different?
  • 🪝Hooks
  • 🚨Concepts
    • Introduction
      • Example Usage
      • Xahau Testnet
      • Xahau Testnet Explorer
      • Examples (source code)
      • Blogs (concepts)
    • Terminology
    • Loops and Guarding
    • Compiling Hooks
    • Chaining
    • Weak and Strong
    • Collect Call
    • SetHook Transaction
    • Parameters
    • Namespaces
    • Grants
    • HookOn Field
    • Reference Counted Hook Definitions
    • Hook Fees
    • Execution Metadata
    • Debugging Hooks
    • State Management
    • Slots and Keylets
    • Floating Point Numbers (XFL)
    • Emitted Transactions
    • Serialized Objects
  • Features
    • Public Nodes (RPC)
    • Amendments
    • Transaction Signing
      • Transaction Fees
    • Developer Tooling
      • Curated Tooling
      • Client Libraries
      • Developer Tricks
    • HTTP / WebSocket APIs
      • Request Formatting Guide
      • Response Formatting Guide
      • Considerations
      • Public API Methods
      • Admin API Methods
    • Network Features
      • Account Managment
      • Balance Rewards
      • Check
      • Escrow
      • Hooks
      • Offer
      • Payments
      • URIToken
    • Faucet & Explorers
    • Data API's
  • Infrastructure
    • Node Requirements
    • Running a Node
      • Running a Mainnet Node
      • Running a Testnet Node
    • Building Xahau (Dev)
      • Ubuntu - 22.04
      • Mac OS - 15.3.2 (24D81)
  • Technical
    • 📐Hooks Functions
      • Overview
        • Hook API Conventions
        • Return Codes
      • Developer Defined
        • hook
        • cbak / Callback
      • Control
        • accept
        • rollback
      • Utilities
        • util_raddr
        • util_accid
        • util_verify
        • util_sha512h
        • util_keylet
      • Serialization
        • sto_subfield
        • sto_to_json
        • sto_from_json
        • sto_subarray
        • sto_emplace
        • sto_erase
        • sto_validate
      • Emitted Transaction
        • etxn_burden
        • etxn_details
        • etxn_fee_base
        • etxn_nonce
        • etxn_reserve
        • etxn_generation
        • prepare
        • emit
      • Float
        • float_set
        • float_multiply
        • float_mulratio
        • float_negate
        • float_compare
        • float_sum
        • float_sto
        • float_sto_set
        • float_invert
        • float_divide
        • float_one
        • float_exponent
        • float_mantissa
        • float_sign
        • float_int
        • float_root
        • float_log
      • Ledger
        • fee_base
        • ledger_seq
        • ledger_last_hash
        • ledger_last_time
        • ledger_nonce
        • ledger_keylet
      • Hook Context
        • hook_account
        • hook_hash
        • hook_param
        • hook_param_set
        • hook_skip
        • hook_pos
        • hook_again
      • Slot
        • slot
        • slot_clear
        • slot_count
        • slot_set
        • slot_size
        • slot_subarray
        • slot_subfield
        • slot_type
        • xpop_slot
        • slot_float
      • State
        • state
        • state_set
        • state_foreign
        • state_foreign_set
      • Trace (Debug)
        • trace
        • trace_num
        • trace_float
      • Originating Transaction
        • otxn_burden
        • otxn_field
        • otxn_generation
        • otxn_id
        • otxn_type
        • otxn_slot
        • otxn_param
        • otxn_json
        • meta_slot
      • Websocket APIs
        • account_info
        • account_namespace
    • Protocol Reference
      • Transactions
        • Transaction Common Fields
        • Transaction Types
          • AccountDelete
          • AccountSet
          • CheckCancel
          • CheckCash
          • CheckCreate
          • ClaimReward
          • DepositPreauth
          • EscrowCancel
          • EscrowCreate
          • EscrowFinish
          • GenesisMint - (Emitted Txn)
          • Import
          • Invoke
          • OfferCancel
          • OfferCreate
          • Payment
          • PaymentChannelClaim
          • PaymentChannelCreate
          • PaymentChannelFund
          • Remit
          • SetHook
          • SetRegularKey
          • SignerListSet
          • TicketCreate
          • TrustSet
          • URITokenBurn
          • URITokenBuy
          • URITokenCancelSellOffer
          • URITokenCreateSellOffer
          • URITokenMint
        • Pseudo Transaction Types
          • EmitFailure
          • UNLReport
          • UNLModify
          • SetFee
          • EnableAmendment
        • Transaction Results
          • TES Codes
          • TER Codes
          • TEM Codes
          • TEL Codes
          • TEF Codes
          • TEC Codes
        • Transaction Metadata
      • Ledger Data
        • Ledger Objects Types
          • AccountRoot
          • Amendments
          • Check
          • Deposit Pre Auth
          • Directory Node
          • Emitted Txn
          • Escrow
          • Fee Settings
          • Hook
          • Hook Definition
          • Hook State
          • Import VL Sequence
          • Ledger Hashes
          • Negative UNL
          • Offer
          • Pay Channel
          • Ripple State
          • Signers List
          • Ticket
          • UNL Report
          • URIToken
        • Ledger Header
        • Ledger Object IDs
      • Data Types
        • Currency Formats
        • Base 58 Encodings
      • Binary Format
    • Balance Adjustments
    • Governance Game
    • Burn 2 Mint (B2M)
    • Versioning Process
  • Compliance
    • Security Audits
      • Responsible Disclosure
  • Support
    • Help Us
Powered by GitBook
On this page
  • Overview
  • Layer 1
  • Layer 2
  • Game Constraints
  • Validator Rewards
  • Technical Specification
  • Governance Hook Parameters
  • Governance Hook State
  • Governance Hook Transactions
  • Clearing a Vote

Was this helpful?

Edit on GitHub
Export as PDF
  1. Technical

Governance Game

The Governance Game is an innovative governance mechanism within the Xahau ecosystem to ensure a community-centric approach towards decision-making.

Overview

The Xahau Governance Game allows up to 400 stakeholders to democratically participate in the management of the Xahau network via the Governance Hook installed on the Genesis Account.

Layer 1

The game consists of a "Layer 1" table at which there are 20 seats. A Xahau account (r-address) may fill each seat, or it may be empty. When a seat is filled, it is said that a member of the table sits there.

To play the game, the members of the table cast votes. The votes are for one of three types of topics:

  • Seat topics

  • Hook topics

  • Reward topics.

Seat topics are S00 through S19 and represent a vote for who (if anyone) currently sits in that seat. A vote of 80% is sufficient to make a change. The voting process is continuous, with the final vote that crosses the threshold actioning the change.

Hook topics are H0 through H9 and represent which Hooks, including the Governance Hook itself, are installed on the table's account. These topics require 100% of the members seated at that table to agree before a change can be made. This allows the Governance Game to be updated and for more Genesis account features to be added over time.

Reward topics are RR and RD, which stand for Reward-Rate and Reward-Delay, respectively. These topics also require 100% of the members at the table to agree in order to make a change. These parameters affect the BalanceAdjustments system: how much each active user on the network can claim and how often.

Layer 2

The members who fill seats on the Layer 1 table are Xahau accounts (r-addresses). The governance game is designed to be structurally recursive, such that one of these accounts may itself be a table consisting of another 20 seats. This is called a Layer 2 table, and the seats are Layer 2 seats.

Within a Layer 2 table, the same seat voting and hook voting topics exist, with the same voting rules as the Layer 1 table. This allows a table to govern its own membership and the hooks that run there.

In addition to these topics, a Layer 2 table may also, by a 51% vote, raise a vote to the Layer 1 table. This is a vote on behalf of the r-address that the Layer 2 table exists on and counts as a single vote at the Layer 1 table.

The Layer 2 table vote may fall below 51%, in which case the vote originally raised to the Layer 1 table is not retracted. Only a new (different) vote attaining 51% can change the table's vote at Layer 1.

Layer 2 tables can only vote on Reward topics via a vote raised to Layer 1.

In summary, Layer 2 members can vote for:

  • Seats and Hooks for their own table, and

  • Seats, Hooks, and Reward topics for the L1 table via the Layer 1 seat their Layer 2 table resides in.

Game Constraints

  • Any table may have at least 2 members and at most 20 members.

  • A single r-address can only occupy one seat at a given table but may occupy one seat at each of many different tables.

  • The Governance Game is not designed to recurse beyond two layers. There's no technical infeasibility in implementing a Layer 3 table, but the current Governance Hook does not support it.

Validator Rewards

Validator rewards are an incentive for running a validator on the network. The rewards are generated by the network and granted to the intersection of Layer 1 members and active UNL validators. To qualify for validator rewards within a given block of 256 ledgers, the following must be true:

  • The validator is on the Xahau UNL.

  • The validator validates successfully in the eyes of other UNL validators.

  • When the validator's master public key is converted to an r-address, that account sits at the L1 Table.

Rewards are ad-hoc and based on Xahau users' Balance Adjustments. When a user performs a Balance Adjustment, an amount equal to their adjustment divided by 20 is sent to the r-address of each of the active validators that meet the above criteria.

Technical Specification

The Governance Hook is installed on the genesis account by the XahauGenesis amendment several ledgers after ledger 1 on a new network. This is the L1 table. To create an L2 table, install the Hook on a different account, then seat that account at the L1 table.

Governance Hook Parameters

When the Governance Hook is installed, it is installed with a set of HookParameters. These specify the initial composition of the table.

Each HookParameter has a 3-byte name consisting of either 3 Ascii characters or 2 Ascii characters and an identifier as below. LE = Little Endian.

Parameter Name: {'I', 'R', 'R'}
Parameter Value: Initial Reward Rate <8 byte XFL fraction between 0 and 1, LE>
Parameter Name: {'I', 'R', 'D'}
Parameter Value: Initial Reward Delay <8 byte LE XFL seconds between rewards>
Parameter Name: {'I', 'M', 'C'}
Parameter Value: Initial Member Count <1 byte>
Parameter Name: {'I', 'S', 0x00}
Parameter Value: Initial seat #0's member's 20 byte Account ID.
Parameter Name: {'I', 'S', 0x01}
Parameter Value: Initial seat #1's member's 20 byte Account ID.
... etc ... up to at most Seat 19.

To kick-off the game, an Invoke transaction must be sent to the Hook. This may be sent by any account. No Blob or HookParameters are required. This Invoke transaction triggers the Hook for the first time and prompts it to create state entries for each initial seat, reward rate, and reward delay.

Governance Hook State

The Hook State of the Governance Hook is stored in the zero namespace: 0000000000000000000000000000000000000000000000000000000000000000.

There are several types of state entry. The first is what are referred to as forward and reverse member keys. These map each seat number to the member who sits there and each member to the seat they sit at.

Key: 0x0000000000000000000000000000000000000000000000000000000000000005
Val: <20 byte AccountID of the member at seat 5 or all 0's or absent.>

Key: <20 byte AccountID of the member at seat 3>
Val: 0x03

Next, there are some singleton state entries. Member Count, Reward Rate, and Reward Delay, respectively:

Key in Ascii: MC
Key: 0x0000000000000000000000000000000000000000000000000000000000004D43
Val: <1 byte member count (how many seats are occupied)>

Key in Ascii: RR
Key: 0x0000000000000000000000000000000000000000000000000000000000005252
Val: <8 byte LE XFL reward rate (between 0 and 1 (1 being 100%))>

Key in Ascii: RD
Key: 0x0000000000000000000000000000000000000000000000000000000000005244
Val: <8 byte LE XFL reward delay in seconds>

Finally, votes and vote counters are also stored in Hook state. When a vote is cast by a seat it is recorded in Hook state as follows:

Vote key is 32 bytes comprising:
    'V' (0x56) - vote
    'H' (0x48) or 'R' (0x52) or 'S' (0x53) - topic type
    'R' (0x52) or 'D' (0x44) or 0 (0x00) to 19 (0x13) - topic detail
     1  (0x01) or  2  (0x02) - target layer for this vote
    0x00 00 00 00 00 00 00 00 - 8 bytes of padding
    20 byte Account ID - the voter
Vote data:
    20 byte Account ID or 8 byte XFL

When a vote is cast, it increments a vote counter-state entry. This counter keeps track of how many votes there currently are for this topic-data pair and allows the Hook to action the vote when voting crosses the required threshold. The counter state is as follows:

Counter key is 32 bytes comprising:
    'C' (0x43) - count
    'H' (0x48) or 'R' (0x52) or 'S' (0x53) - topic type
    'R' (0x52) or 'D' (0x44) or 0 (0x00) to 19 (0x13) - topic detail
     1  (0x01) or  2  (0x02) - target layer for this vote
     0's for padding
     vote data or left-truncated vote data

Governance Hook Transactions

The Governance Hook is interacted with by its members using ttINVOKE transactions. In addition to this, the Hook may also emit its own ttINVOKE transactions if it is an L2 table raising a vote to the L1 table.

A vote transaction contains a HookParameters array at the top level of the transaction:

{
    Account: <member's account>,
    TransactionType: Invoke,
    NetworkID: 21337,
    Destination: <table's account>,
    HookParameters:
    [
        {
            HookParameter:
            {
                HookParameterName: "4C",     // L - the target layer
                HookParameterValue: "01",    // 01 for L1 table, 02 for L2 table
                                             // note: this is the table the vote is
                                             // intended for, not the table you're at
                                             // i.e. for a L2 table you can vote on
                                             // your own membership or on L1's
            }
        },
        {
             HookParameter:
             {
                 HookParameterName: "54",    // T - topic type
                 HookParameterValue: "4801", // H [0x00-0x09] or 
                                             // S [0x00-0x13] or
                                             // RR or RD
             }
        },
        {
             HookParameter:
             {
                 HookParameterName: "56",    // V - vote data
                 HookParameterValue: <32 or 20 or 8 bytes of vote data>
             }
         }
    ]
}
    

Clearing a Vote

There is no way to "delete a vote" per se. You can change your vote back to reflect the current position instead.

So, for example, if no one sits at seat 8 and you have voted for account A to sit there, and then you change your mind, you can make a vote to vacate seat 8 (even though it's already vacant) thus aligning your vote with the current state of the seat.

To do this, you vote with all 0's in the vote data, to the same length as the vote topic normally requires. So, for a seat vote, this is 20 bytes of 0.

Last updated 1 year ago

Was this helpful?

Page cover image