Skip to main content

Voting, Phasing & Governance Subsystem

The Shamwari Voting, Phasing & Governance Subsystem (nxt.voting) provides a protocol-native framework for conditional transaction execution, decentralized voting, multi-signature approvals, and account-level governance enforcement built directly into the core Shamwari ledger engine.

By handling transaction phasing and voting directly within nxt.voting—rather than relying on external virtual machine smart contracts—Shamwari achieves zero-overhead condition evaluation, reentrancy-safe multi-signature workflows, composable boolean voting logic, and native integration with on-chain holdings, properties, identity credentials, and post-quantum account controls across BetaChains.

Core Capabilities & Architecture​

  • Protocol-Native Transaction Phasing (PhasingAppendix): Transactions can be attached with a PhasingAppendix (appendixType = 64), deferring final execution until defined block heights or until explicit on-chain approval criteria (quorum) are satisfied.
  • Multi-Model Vote Weighting (VoteWeighting): Supports 10 distinct voting models—including per-account (ACCOUNT), totem-weighted (TOTEM), currency-weighted (CURRENCY), secret pre-image revelation (HASH), property verification (PROPERTY), linked transaction dependency (TRANSACTION), demographic identity data (IDENTITY_DATA), and verified credential certificates (CERTIFICATE).
  • Composite Boolean Logic Expressions (CompositeVoting): Enables complex multi-condition governance rules by evaluating boolean expressions (∧,∨,¬\land, \lor, \neg) over multiple distinct sub-polls in real time.
  • Mandatory Account Control (PhasingControl): Account-level policy enforcement that forces all outgoing transactions from an account to be phased under mandatory governance rules (e.g., NN-of-MM corporate treasury approvals or board consent).
  • Real-Time Early Execution & Rejection Engine: Block listeners (tryCountVotes) evaluate pending phased transactions at every block. Transactions meeting quorum release early immediately, while transactions failing boolean logic rejections fail fast, freeing pending resources.
  • Atomic State Rollbacks: Unconfirmed attachment funds and reserved asset balances are safely unlocked and restored if a phased transaction is rejected or fails to meet quorum before its finish height.

Voting Models & Parameter Matrix​

The core engine supports multiple voting models defined in VoteWeighting.VotingModel:

Voting ModelCodeWeighting Source & CriterionPrimary Use Case
NONE0No voting model; default baseline.Simple time-based execution delays.
ACCOUNT11 Account = 1 Vote (Equal Weighting).Multi-sig approvals, council voting, DAO governance.
TOTEM2Weighted by QNTQNT holdings of a specific Totem (holding_id).Token-weighted shareholder voting & dApp governance.
CURRENCY3Weighted by QNTQNT holdings of a Monetary System currency.Currency-holder monetary policy referendums.
HASH4Requires revealing a secret pre-image matching hashedSecret.Atomic cross-chain swaps (HTLCs) & secret releases.
PROPERTY5Requires recipient or sender to possess specified Account Property key/value.Role-based permissioning & compliance gating.
TRANSACTION6Execution depends on the confirmation of linked transaction IDs.Sequential transaction pipelines & conditional cascades.
IDENTITY_DATA7Gated by age bounds, gender, or nationality profile attributes.Demographic voting & regional governance.
CERTIFICATE8Gated by verified credentials issued by accredited institutions.Academic, accredited investor, or regulatory voting.
COMPOSITE9Boolean expression logic combining multiple sub-polls (A∧(B∨C)A \land (B \lor C)).Advanced corporate governance & multi-tier authorization.

Data Model & Relational Schema​

Phasing parameters, active poll structures, vote tallies, and account controls are maintained in relational database tables indexed by transaction IDs, account keys, and block heights.

1. Primary Phasing & Governance Entities​

TablePrimary / Composite KeyEntity ClassDescription
public.phasing_pollid, heightPhasingPollActive phasing poll registrations, quorum targets, and finish heights.
public.phasing_voteid, voter_idPhasingVoteIndividual voter submissions and cast weight records.
public.phasing_controlaccount_id, heightPhasingControlActive account governance policies requiring mandatory transaction phasing.

2. Phasing Parameters Schema (PhasingParams)​

Phasing parameters encode the precise approval criteria required for transaction release:

FieldSQL TypeDescription
voting_modelTINYINTNumerical code mapping to VoteWeighting.VotingModel.
quorumBIGINTTotal required vote weight or threshold count to approve execution.
holding_idBIGINTTotem or Currency ID used for weighted voting (00 for account voting).
min_balanceBIGINTMinimum balance threshold required for a voter's vote to be valid.
min_balance_modelTINYINTBalance evaluation model (e.g., liquid balance, locked balance).
expressionVARCHARBoolean algebra expression string for COMPOSITE voting models.
sender_property_setter_idBIGINTRequired account ID of the setter for sender property checks.
sender_property_nameVARCHARProperty key name required on sender account.
sender_property_valueVARCHARExpected property value string on sender account.
recipient_property_setter_idBIGINTRequired account ID of the setter for recipient property checks.
recipient_property_nameVARCHARProperty key name required on recipient account.
recipient_property_valueVARCHARExpected property value string on recipient account.
nationalityVARCHARISO country code filter for IDENTITY_DATA voting.
genderVARCHARGender string filter for IDENTITY_DATA voting.
min_ageINTMinimum voter age constraint derived from dateOfBirth.
max_ageINTMaximum voter age constraint derived from dateOfBirth.
certificate_issuerBIGINTIssuer account ID of required verification certificate.
certificate_nameVARCHARCredential name for CERTIFICATE voting.
certificate_typeVARCHARCredential category for CERTIFICATE voting.

Transaction Phasing State Machine​

A phased transaction undergoes state transitions from initial broadcast to either execution or rejection:

                      ┌───────────────────────────────────────────────┐
                      │    Transaction Broadcast + PhasingAppendix    │
                      └───────────────────────┬───────────────────────┘
                                              │
                                              ▼
                          ┌───────────────────────────────────────┐
                          │            PENDING PHASED             │
                          │   (Held in PhasingPollHome Registry)  │
                          └───────┬───────────────┬───────┬───────┘
                                  │               │       │
      tryCountVotes()             │               │       │   tryCountVotes()
    Quorum Met / Composite TRUE   │               │       │   Composite FALSE
                                  ▼               │       ▼
                          ┌───────────────┐       │   ┌───────────────────────┐
                          │ EARLY RELEASE │       │   │    EARLY REJECTION    │
                          └───────┬───────┘       │   └───────────┬───────────┘
                                  │               │               │
                                  │   Finish Height Reached       │
                                  │   (countVotes())              │
                                  │               │               │
                                  ▼               ▼               ▼
                          ┌───────────────────────────────────────┐
                          │            FINAL STATE                │
                          ├───────────────────────┬───────────────┤
                          │  RELEASED (Executed)  │ REJECTED      │
                          └───────────────────────┴───────────────┘

Mathematical Formulas & Quorum Logic​

1. Vote Weight Attribution​

When a voter casts a vote on a phased poll, their vote weight (WvW_v) is determined based on the specified VotingModel:

1 & \text{if Model} = \text{ACCOUNT} \\ \text{Balance}_{\text{Totem}}(v, \text{holdingId}) & \text{if Model} = \text{TOTEM} \land \text{Balance} \ge \text{minBalance} \\ \text{Balance}_{\text{Currency}}(v, \text{holdingId}) & \text{if Model} = \text{CURRENCY} \land \text{Balance} \ge \text{minBalance} \\ 1 & \text{if Model} = \text{HASH} \land \text{VerifyHash}(\text{secret}) = \text{True} \\ 0 & \text{otherwise} \end{cases}$$ --- ### 2. Quorum Satisfaction For standard single-poll models, a phased transaction satisfies quorum ($\text{IsApproved}$) when aggregate cast vote weight reaches or exceeds the target $\text{quorum}$: $$\text{TotalWeight} = \sum_{v \in \text{Voters}} W_v$$ $$\text{IsApproved} \iff \text{TotalWeight} \ge \text{quorum}$$ --- ### 3. Composite Boolean Expression Evaluation For `COMPOSITE` voting models, the approval condition is expressed as a boolean function $E(x_1, x_2, \dots, x_n)$ over sub-poll outcomes $x_i \in \{\text{TRUE}, \text{FALSE}, \text{UNKNOWN}\}$: $$x_i = \begin{cases} \text{TRUE} & \text{if } \text{TotalWeight}(x_i) \ge \text{quorum}(x_i) \\ \text{FALSE} & \text{if } \text{MaxPossibleWeight}(x_i) \lt \text{quorum}(x_i) \lor \text{SubPollFailed} \\ \text{UNKNOWN} & \text{otherwise} \end{cases}$$ The core engine utilizes three-valued boolean logic to evaluate $E$: - If $E \implies \text{TRUE}$: Transaction releases **early** without waiting for `finishHeight`. - If $E \implies \text{FALSE}$: Transaction is rejected **early**, returning unconfirmed balances. --- ### 4. Dynamic Baseline Phasing Fee Formula The fee for attaching a `PhasingAppendix` ($\text{Fee}_{\text{phasing}}$) is computed dynamically based on parameter complexity, sub-polls, boolean expression length, and string lengths: $$\text{Fee}_{\text{phasing}} = \text{Fee}_{\text{base}} + \sum \text{Fee}_{\text{subpoll}} + \text{Fee}_{\text{strings}}$$ Where for composite expressions: $$\text{Fee}_{\text{base}} = \left(2 + \max\left(\left\lfloor \frac{|\text{Expression}|}{32} \right\rfloor, \text{LiteralsCount}\right)\right) \times \frac{\text{ONE\_FXT}}{100}$$ And per individual poll or sub-poll: $$\text{Fee}_{\text{poll}} = \begin{cases} 0.20 \times \text{ONE\_FXT} & \text{if } \text{BalanceDependent} \\ 0.01 \times \text{ONE\_FXT} & \text{if } \text{BalanceIndependent} \end{cases} + \left(1 + \left\lfloor \frac{|\text{HashedSecret}| - 1}{32} \right\rfloor\right) \times 0.01 \times \text{ONE\_FXT}$$ $$\text{Fee}_{\text{strings}} = 0.01 \times \text{ONE\_FXT} \times \left( |\text{LinkedTx}| + \sum \left\lfloor \frac{|\text{StringAttr}|}{32} \right\rfloor \right)$$ --- ## Mandatory Account Governance Control (`PhasingControl`) `PhasingControl` enables institutional accounts (such as bank treasuries, government departments, or joint ventures) to enforce account-level multi-signature or policy constraints. ### 1. Implication Verification (`fastImplicationCheck`) When an account with active `PhasingControl` submits a transaction, the engine checks whether the transaction's attached phasing expression ($\text{Expr}_{\text{tx}}$) strictly implies the account's mandatory governance policy ($\text{Expr}_{\text{control}}$): $$\text{Expr}_{\text{tx}} \implies \text{Expr}_{\text{control}}$$ ```java // Logic from PhasingControl.checkPhasing() if (!BooleanExpression.fastImplicationCheck(transactionExpression, controlExpression)) { throw new AccountControlException("Phasing expression does not imply mandatory control expression."); } ``` If $\text{Expr}_{\text{tx}}$ is less restrictive than $\text{Expr}_{\text{control}}$, the node rejects transaction submission immediately. --- ## Lifecycle Execution Engine The block execution loop processes pending phased transactions during the `AFTER_BLOCK_APPLY` phase: ```java // Phasing evaluation loop inside PhasingAppendix.tryCountVotes PhasingPollHome.PhasingPoll poll = transaction.getChain().getPhasingPollHome().getPoll(transaction); long result; BooleanExpression.Value compositeVotingResult = BooleanExpression.Value.UNKNOWN; if (poll.isCompositeVoting()) { compositeVotingResult = poll.getCompositeVotingResult(); result = compositeVotingResult == BooleanExpression.Value.TRUE ? 1 : 0; } else { result = poll.countVotes(); } if (result >= poll.getQuorum() || compositeVotingResult != BooleanExpression.Value.UNKNOWN) { if (compositeVotingResult == BooleanExpression.Value.FALSE) { reject(transaction); poll.finish(result); } else if (!transaction.attachmentIsDuplicate(duplicates, false)) { release(transaction); poll.finish(result); } } ``` --- ## Event Listener Matrix The Voting and Phasing subsystem exposes strongly-typed event listeners for indexing engines and off-chain signers: | Event Enum | Trigger Condition | Operational Action | | :--- | :--- | :--- | | `RELEASE_PHASED_TRANSACTION` | Phased transaction satisfied quorum or composite expression evaluated to `TRUE`. | Applies underlying transaction attachments and executes state changes. | | `REJECT_PHASED_TRANSACTION` | Phased transaction failed quorum at `finishHeight` or composite expression evaluated to `FALSE`. | Reverts unconfirmed attachment locks and releases reserved sender funds. | | `VOTE_CAST` | A voter submitted a valid vote on an active phasing poll. | Recalculates current poll tallies and checks for early release. | --- ## Related APIs | API | Description | | :--- | :--- | | [SetPhasingOnlyControl](/api/phasing/set-phasing-only-control) | Set account phasing control | | [GetPhasingOnlyControl](/api/phasing/get-phasing-only-control) | Get account phasing control | | [GetAllPhasingOnlyControls](/api/phasing/get-all-phasing-only-controls) | List all phasing controls | | [ParsePhasingParams](/api/phasing/parse-phasing-params) | Parse phasing parameters | | [GetPhasingPoll](/api/phasing/get-phasing-poll) | Get phasing poll | | [GetPhasingPollVote](/api/phasing/get-phasing-poll-vote) | Get poll vote | | [GetPhasingPollVotes](/api/phasing/get-phasing-poll-votes) | Get all poll votes | | [SetPhasingTotemControl](/api/phasing/set-phasing-totem-control) | Set Totem phasing control | | [GetPhasingTotemControl](/api/phasing/get-phasing-totem-control) | Get Totem phasing control | --- ## Primary Institutional & Commercial Use Cases - **Corporate Treasury Multi-Sig:** Enterprise accounts enforce 3-of-5 executive sign-off policies (`ACCOUNT` model) for all outgoing payroll and supplier transfers. - **Cross-Chain Hash Time-Locked Contracts (HTLCs):** Atomic cross-chain swaps execute automatically when a valid pre-image matching `hashedSecret` is submitted on-chain (`HASH` model). - **Tokenized Shareholder Governance:** Decentralized organizations and fund managers conduct asset-weighted referendums where vote weight tracks $QNT$ totem balances (`TOTEM` model). - **Sequential Supply Chain Workflows:** Multi-stage logistics transactions execute automatically only after linked milestone transactions receive final confirmation (`TRANSACTION` model). - **Demographic & Certified Grant Distribution:** Municipal development grants phase disbursements contingent on accredited identity credentials and regional residence properties (`IDENTITY_DATA` + `CERTIFICATE` models).