State Module

class hivemind.state.HivemindState(cid: str | None = None)[source]

Bases: IPFSDictChain

A class representing the current state of a Hivemind voting issue.

This class manages the state of a voting issue, including options, opinions, and voting results. It handles the addition of new options and opinions, calculates voting results, and manages restrictions on who can vote.

Variables:

hivemind_id (str | None) – The IPFS hash of the associated hivemind issue
_issue – The associated hivemind issue object
option_cids (List[str]) – List of option CIDs
opinion_cids (List[Dict[str, Any]]) – List of dictionaries containing opinions for each question
signatures (Dict[str, Dict[str, Dict[str, int]]]) – Dictionary mapping addresses to their signatures
participants (Dict[str, Any]) – Dictionary mapping addresses to their participation data
selected (List[str]) – List of options that have been selected
final (bool) – Whether the hivemind is finalized

__init__(cid: str | None = None) → None[source]

Initialize a new HivemindState.

Parameters:: cid (str) – The IPFS multihash of the state

add_opinion(timestamp: int, opinion_hash: str, address: str, signature: str) → None[source]

Add an opinion to the hivemind state.

Parameters:

timestamp (int) – Unix timestamp
opinion_hash (str) – The IPFS multihash of the opinion
address (str) – The address of the opinionator
signature (str) – The signature of the message

Raises:

Exception – If the opinion is invalid or restrictions are not met

add_option(timestamp: int, option_hash: str, address: str | None = None, signature: str | None = None) → None[source]

Add an option to the hivemind state.

Parameters:

timestamp (int) – Unix timestamp
option_hash (str) – The IPFS multihash of the option
address (str) – The address that supports the option (optional)
signature (str) – The signature of the message (optional)

Raises:

Exception – If the option is invalid or restrictions are not met

add_predefined_options() → Dict[str, Dict[str, Any]][source]

Add predefined options to the hivemind state.

Returns:: Dictionary mapping option CIDs to their data
Return type:: Dict[str, Dict[str, Any]]

add_signature(address: str, timestamp: int, message: str, signature: str) → None[source]

Add a signature to the hivemind state.

Parameters:

address (str) – The address of the participant
timestamp (int) – Unix timestamp
message (str) – The message that was signed
signature (str) – The signature of the message

Raises:

Exception – If the signature is invalid

Returns:

None

calculate_results(question_index: int = 0) → Dict[str, Dict[str, float]][source]

Calculate the results of the hivemind.

Parameters:: question_index (int) – Index of the question to calculate results for
Returns:: Dictionary mapping option CIDs to their scores
Return type:: Dict[str, Dict[str, float]]
Raises:: Exception – If question_index is invalid

compare(a: str, b: str, opinion_hash: str) → str | None[source]

Helper function to compare 2 Option objects against each other based on a given Opinion.

Parameters:

a (str) – The first Option object CID
b (str) – The second Option object CID
opinion_hash (str) – The Opinion object CID

Returns:

The Option CID that is considered better by the Opinion, or None if both options are not in the Opinion

Return type:

str | None

consensus(question_index: int = 0) → Any[source]

Get the consensus of the hivemind.

Parameters:: question_index (int) – The index of the question (default=0)
Returns:: The consensus value
Return type:: Any

contributions(results: Dict[str, Dict[str, float]], question_index: int = 0) → Dict[str, float][source]

Get the contributions of the participants.

Parameters:

results (Dict[str, Dict[str, float]]) – Dictionary mapping option CIDs to their scores
question_index (int) – The index of the question (default=0)

Returns:

Dictionary mapping participant addresses to their contributions

Return type:

Dict[str, float]

get_opinion(cid: str) → HivemindOpinion[source]

Get an opinion by its CID.

Parameters:: cid (str) – The IPFS multihash of the opinion
Returns:: The opinion object
Return type:: HivemindOpinion

get_option(cid: str) → HivemindOption[source]

Get an option by its CID.

Parameters:: cid (str) – The IPFS multihash of the option
Returns:: The option object
Return type:: HivemindOption

get_options() → List[HivemindOption][source]

Get list of hivemind options.

Returns:: List of HivemindOption objects
Return type:: List[HivemindOption]

get_score(option_hash: str, question_index: int = 0) → float[source]

Get the score of an option.

Parameters:

option_hash (str) – The IPFS multihash of the option
question_index (int) – The index of the question (default=0)

Returns:

The score of the option

Return type:

float

get_sorted_options(question_index: int = 0) → List[HivemindOption][source]

Get the sorted list of options.

Parameters:: question_index (int) – The index of the question (default=0)
Returns:: List of HivemindOption objects sorted by highest score
Return type:: List[HivemindOption]

get_weight(opinionator: str) → float[source]

Get the weight of an opinion.

Parameters:: opinionator (str) – The participant’s address
Returns:: The weight of the opinion
Return type:: float

hivemind_issue() → HivemindIssue[source]

Get the associated hivemind issue.

Returns:: The associated hivemind issue object
Return type:: HivemindIssue

info() → str[source]

Get the information of the hivemind.

Returns:: A string containing the information of the hivemind
Return type:: str

load(cid: str) → None[source]

Load the hivemind state from IPFS.

Parameters:: cid (str) – The IPFS multihash of the state
Returns:: None

opinions_info(question_index: int = 0) → str[source]

Get the information of the opinions.

Parameters:: question_index (int) – The index of the question (default=0)
Returns:: A string containing the information of the opinions
Return type:: str

options_by_participant(address: str) → List[str][source]

Get the options added by a participant.

Parameters:: address (str) – The participant’s address
Returns:: List of option CIDs
Return type:: List[str]

options_info() → str[source]

Get the information of the options.

Returns:: A string containing the information of the options
Return type:: str

ranked_consensus(question_index: int = 0) → List[Any][source]

Get the ranked consensus of the hivemind.

Parameters:: question_index (int) – The index of the question (default=0)
Returns:: List of consensus values
Return type:: List[Any]

results() → List[Dict[str, Dict[str, float]]][source]

Get the results of the hivemind.

Returns:: The results of the hivemind
Return type:: Any

results_info(results: Dict[str, Dict[str, float]], question_index: int = 0) → str[source]

Get the results information of the hivemind.

Parameters:

results (Dict[str, Dict[str, float]]) – Dictionary mapping option CIDs to their scores
question_index (int) – The index of the question (default=0)

Returns:

A string containing the results information

Return type:

str

select_consensus(timestamp: int | None = None, address: str | None = None, signature: str | None = None) → List[str][source]

Select the consensus of the hivemind.

This method selects the option with the highest consensus for each question and sets it as the selected option. If the on_selection property of the hivemind issue is set, it will perform the specified action.

Parameters:

timestamp (int) – Timestamp of the signature
address (str) – Bitcoin address of the signer
signature (str) – Signature of the message

Returns:

List of selected option CIDs

Return type:

List[str]

Raises:

ValueError – If the hivemind is already finalized
ValueError – If the address is not the author of the hivemind

set_hivemind_issue(issue_cid: str) → None[source]

Set the associated hivemind issue.

Parameters:: issue_cid (str) – IPFS hash of the hivemind issue
Returns:: None

update_participant_name(timestamp: int, name: str, address: str, signature: str, message: str) → None[source]

Update the name of a participant.

Parameters:

timestamp (int) – Unix timestamp
name (str) – The new name of the participant
address (str) – The address of the participant
signature (str) – The signature of the message
message (str) – The message that was signed

Raises:

Exception – If the signature is invalid or name exceeds maximum length

Returns:

None