Summary

QuorumVoteRole is a role that serves two purposes:

  • it is more flexible variant of ListRole in terms of getting quorums of any kind
  • it allows to start prolonged votings on a contract(s) instead of collecting signatures and attaching it to contracts body

Declaration

public QuorumVoteRole(String name, Contract contract, String source, String quorum)

As one can see from java code above QuorumVoteRole constructor takes role's standard name and contract params and also this specific role related source and quorum.

$WHERE.$WHAT concept

$where.$what format is used within QuorumVoteRole declaration in many aspects.

$where.$what points to a value and resolved in a following way.

  • source contract represented by $where is defined first. $where is always either this (current contract is taken as the source) or name of reference defined within current contract (first mathing contract of transaction is taken as the source).
  • value at $what is taken from source contract.

Examples

  • this.state.origin
  • refParent.owner
  • this.definition.data.type
  • refName.state.data.amount

Source

Source is $where.$what pointing to anything of:

  • role that is resolved as ListRole containing only roles that resolved by single KeyAddress (returned by Role.getSimpleAddress())
  • an array of KeyAddress
  • an array of string representation of KeyAddress

In addittion all KeyAddresses must be long addresses with default type mark.

Quorum

Quorum is an expression where operators + and - are supported. Values in between operators are either: - decimal (ending by % symbol) - $where.$what pointing to a decimal (ending by % symbol) - N meaning all votes

Percentage based values are always rounded down (floored) upon calculation. So it one wants for example 80% rounded up N-20% can be used instead

Examples

  • 50%+1
  • N-2
  • N-20%

Prolonged voting - concept / early access

Another cool feature of QuorumVoteRole - it can be starting point of prolonged voting. The idea is the following:

To start a vote one needs to run a command that takes:

  • voting contract a contract having QuorumVoteRole declared as one of its roles
  • QuorumVoteRole name in voting contract
  • list of HashIds of candidate contracts

To vote for a cadnidate one needs to run a command that takes:

  • voting contract id
  • candidate id to vote for
  • voter key signature
  • (optionaly) contract containing detached voting list and its possible authentification contracts (in case of multiple authority levels used)

To register a candidate voting should contain enough votes in order to resolve QuorumVoteRole of voting contract. The candidate then should somehow depend on voting contract QuorumVoteRole:

  • candidate is voting contract itself
  • candidate referencing to voting contract role through can_perform operator

Detached vote lists

Because the source of QuorumVoteRole may take voting addresses list from referenced contract it is then possible to provide these referenced contracts on demand.

The whole list of voting addresses (being possibly too big to fit into single contract) can be split into sub lists each put into separate contract. Every such contract is matching reference used by voting contract to identify the source.

User can then provide contract containing his voting address upon voting itself.

Note: N and % can't be used with detached vote lists since total number of voters is unknown at the moment of registration.