@kosu/gov-portal-helper
Abstraction library for interacting with the Kosu contract system governance functions.
Last updated 10 months ago by henryharder .
MIT · Original npm · Tarball · package.json
$ cnpm install @kosu/gov-portal-helper 
SYNC missed versions from official npm registry.

Classes

Gov

Gov is a helper library for interacting with the Kosu validator governance system (primarily the Kosu ValidatorRegistry contract).

It is designed with the browser in mind, and is intended to be used in front- end projects for simplifying interaction with the governance system.

Methods may be used to load the current proposals, validators, and challenges from the prototype's state, or the gov.ee object (an EventEmitter) may be used to detect updates to the state, emitted as gov_update events.

After a gov_update event, the read methods for proposals, challenges, and validators must be called to load the current listings. Alternatively, access the objects directly with gov.listings, etc.

Typedefs

Validator

Represents an active validator in the registry.

Proposal

Represents a pending listing application for a spot on the ValidatorRegistry.

StoreChallenge

Represents a current challenge (in the gov state).

PastChallenge

Represents a historical challenge, and its outcome.

ListingSnapshot

Represents a listing at the time it was challenged.

Vote

Represents a stored vote in a challenge poll.

ChallengeInfo

Contains block numbers for various state changes for a given challenge.

PastGovernanceActivity

An object representing an instance of past "activity" within the ValidatorRegistry contract.

If actionable is true, the following actions can be taken for a given type:

  • CHALLENGE_BY: challenge can be resolved
  • CHALLENGE_AGAINST: challenge can be resolved
  • PROPOSAL: the listing can be confirmed

If state is "PENDING" for a given type, the following action can be taken:

  • CHALLENGE_BY: the challenge can be voted on in the active poll
  • CHALLENGE_AGAINST: the challenge can be voted on in the active poll
  • PROPOSAL: the proposal may be challenged

Gov

Gov is a helper library for interacting with the Kosu validator governance system (primarily the Kosu ValidatorRegistry contract).

It is designed with the browser in mind, and is intended to be used in front- end projects for simplifying interaction with the governance system.

Methods may be used to load the current proposals, validators, and challenges from the prototype's state, or the gov.ee object (an EventEmitter) may be used to detect updates to the state, emitted as gov_update events.

After a gov_update event, the read methods for proposals, challenges, and validators must be called to load the current listings. Alternatively, access the objects directly with gov.listings, etc.

Kind: global class

new Gov()

Create a new Gov instance (gov). Requires no arguments, but can be set to "debug" mode by passing true or 1 (or another truthy object to the constructor).

Prior to using most gov functionality, the async gov.init() method must be called, which will initialize the module and load state from the Kosu contract system.

gov.init()

Main initialization function for the gov module. You must call init prior to interacting with most module functionality, and gov.init() will load the current registry status (validators, proposals, etc.) so it should be called early-on in the page life-cycle.

Performs many functions, including:

  • prompt user to connect MetaMask
  • load user's address (the "coinbase")
  • load the current Ethereum block height
  • load and process the latest ValidatorRegistry state

Kind: instance method of Gov

gov.currentProposals() ⇒ Map.<Proposal>

Load the current proposal map from state.

Kind: instance method of Gov
Returns: Map.<Proposal> -

a map where the key is the listing public key, and the value is a proposal object


Example

const proposals = gov.currentProposals();

gov.currentValidators() ⇒ Map.<Validator>

Load the current validators map from state.

Kind: instance method of Gov
Returns: Map.<Validator> -

a map where the key is the listing public key, and the value is a validator object


Example

const validators = gov.currentValidators();

gov.currentChallenges() ⇒ Map.<StoreChallenge>

Load the current challenges map from state.

Kind: instance method of Gov
Returns: Map.<StoreChallenge> -

a map where the key is the listing public key, and the value is a challenge object


Example

const challenges = gov.currentChallenges();

gov.weiToEther(wei) ⇒ string

Convert a number of tokens, denominated in the smallest unit - "wei" - to "full" units, called "ether". One ether = 1*10^18 wei.

All contract calls require amounts in wei, but the user should be shown amounts in ether.

Kind: instance method of Gov
Returns: string -

the same amount in ether, string used for precision

Param Type Description
wei BigNumber | string

the token amount in wei to convert

Example

gov.weiToEther("100000000000000000000"); // > "100"
gov.weiToEther(100000000000000000000); // > "100"

gov.etherToWei(ether) ⇒ string

Convert a number of tokens (full units, called "ether") to "wei", the smallest denomination of most ERC-20 tokens with 18 decimals.

All contract calls require amounts in wei, but the user should be shown amounts in ether.

Kind: instance method of Gov
Returns: string -

the same amount in wei, string used for precision

Param Type Description
ether BigNumber | string

the token amount to convert

Example

gov.etherToWei(10); // > "10000000000000000000"
gov.etherToWei("1"); // > "1000000000000000000"

gov.commitVote(challengeId, value, amount) ⇒ Promise.<string>

Commit a vote in an active a challenge poll.

This method creates a vote (with value and salt), encodes it, and submits it as a transaction (requires MetaMask signature).

It stores the vote data in a browser cookie so it may be revealed later, which means voters must reveal a vote with the same browser they used to commit it.

Kind: instance method of Gov
Returns: Promise.<string> -

the transaction hash of the commit tx

Param Type Description
challengeId BigNumber

the pollId of the challenge, as a string

value string

the vote value, "1" to vote for the challenge, "0" to vote against

amount BigNumber

the number of tokens (in wei) to commit in the vote

Example

// we are looking at challenge #13, and want to vote AGAINST it with 10 tokens
const pollId = new BigNumber(13);
const amount = new BigNumber(gov.etherToWei("10"));
const value = "0";

// will prompt for MetaMask signature
const commitVoteTxId = await gov.commitVote(pollId, value, amount);

// ... some time passes, we now want to reveal ...

// load vote from cookie and reveal
const revealTxId = await gov.revealVote(new BigNumber("13"));

// ... wait for Tx's to confirm or whatever, etc.

gov.hasCommittedVote(challengeId) ⇒ boolean

Check for a previously committed vote, by challengeId (as a BigNumber).

Kind: instance method of Gov
Returns: boolean -

the boolean representing the presence of a commit vote

Param Type Description
challengeId BigNumber

the challenge to check for a stored commit vote for

gov.revealVote(challengeId) ⇒ Promise.<string>

Reveal a previously committed vote, by challengeId (as a BigNumber).

For this method to work, the user must have committed a vote during the commit period for the given challenge.

This method must also be called during the reveal period in order for the transaction not to fail.

Calling this method will trigger a MetaMask pop-up asking for the user's signature and approval.

Kind: instance method of Gov
Returns: Promise.<string> -

the transaction hash of the reveal tx.

Param Type Description
challengeId BigNumber

the challenge to reveal a stored vote for

gov.hasRevealedVote(challengeId) ⇒ boolean

Check for a previously revealed vote, by challengeId (as a BigNumber).

Kind: instance method of Gov
Returns: boolean -

the boolean representing the presence of a reveal vote

Param Type Description
challengeId BigNumber

the challenge to check for a stored reveal vote for

gov.estimateFutureBlockTimestamp(blockNumber) ⇒ Promise.<number>

Estimate the UNIX timestamp (in seconds) at which a given block will be mined.

Kind: instance method of Gov
Returns: Promise.<number> -

the block's estimated UNIX timestamp (in seconds)

Param Type Description
blockNumber number

the block number to estimate the timestamp for

Example

const block = 6102105;
const unixTs = gov.estimateFutureBlockTimestamp(block);

// use as a normal date object (multiply by 1000 to get ms)
const blockDate = new Date(ts * 1000);

gov.getPastBlockTimestamp(blockNumber) ⇒ Promise.<number>

Retrieve the Unix timestamp of a block that has already been mined. Should be used to display times of things that have happened (validator confirmed, etc.).

Kind: instance method of Gov
Returns: Promise.<number> -

the Unix timestamp of the specified blockNumber

Param Type Description
blockNumber number

the block to get the unix timestamp for

Example

await gov.getPastBlockTimestamp(515237); // > 1559346404

gov.getHistoricalChallenges() ⇒ Promise.<Array.<PastChallenge>>

This method returns an array (described below) that contains information about all past challenges. Intended to be used for the "Past Challenges" section.

Kind: instance method of Gov
Returns: Promise.<Array.<PastChallenge>> -

all historical challenges.


gov.getChallengeInfo(challengeId) ⇒ Promise.<ChallengeInfo>

Returns an object with the block numbers of important times for a given challenge. Between challengeStart and endCommitPeriod, votes may be committed (submitted) to the challenge.

Between endCommitPeriod and challengeEnd, votes may be revealed with the same salt and vote value.

Kind: instance method of Gov
Returns: Promise.<ChallengeInfo> -

the block numbers for this challenge

Param Type Description
challengeId string | number | BigNumber

the ID of the challenge to query

Example

const info = await gov.getChallengeInfo(new BigNumber(1));
const currentBlock = await gov.currentBlockNumber();

if (currentBlock < endCommitPeriod && currentBlock >= challengeStart) {
    // in "commit" period; voters may submit votes
} else if (currentBlock >= endCommitPeriod && currentBlock <= challengeEnd) {
    // in "reveal" period; voters may reveal votes
} else {
    // challenge has ended (or issues with block numbers)
}

gov.currentBlockNumber() ⇒ number

Returns the current block height (as a number).

Kind: instance method of Gov
Returns: number -

The current (or most recent) Ethereum block height.


gov.getPastGovernanceActivity(address) ⇒ Promise.<Array.<PastGovernanceActivity>>

Get information about a given Ethereum address's past governance activity within the system.

Returns info about proposals submitted, challenges created, and challenges against listings owned by the user.

For a given activity object, if actionable is true, the following action may be taken for each state:

  • If "CHALLENGE_BY": the challenge can be resolved
  • If "CHALLENGE_AGAINST": the challenge can be resolved
  • If "PROPOSAL" the listing can be confirmed

Kind: instance method of Gov
Returns: Promise.<Array.<PastGovernanceActivity>> -

An array of snippets about past governance activity.

Param Type Description
address string

Ethereum address of user to get past activity for.

Gov.ZERO

The value 0 as an instance ofBigNumber.

Kind: static property of Gov

Gov.ONE

The value 1 as an instance ofBigNumber.

Kind: static property of Gov

Gov.ONE_HUNDRED

The value 100 as an instance ofBigNumber.

Kind: static property of Gov

Gov.BLOCKS_PER_DAY

Estimated blocks per day (mainnet only).

Kind: static property of Gov

Validator

Represents an active validator in the registry.

Kind: global typedef
Properties

Name Type Description
owner string

the Ethereum address of the validator

stakeSize BigNumber

the staked balance (in wei) of the validator

dailyReward BigNumber

the approximate daily reward to the validator (in wei)

confirmationUnix number

the unix timestamp of the block the validator was confirmed in

power BigNumber

the validators approximate current vote power on the Kosu network

details string

arbitrary details provided by the validator when they applied

Proposal

Represents a pending listing application for a spot on the ValidatorRegistry.

Kind: global typedef
Properties

Name Type Description
owner string

the Ethereum address of the applicant

stakeSize BigNumber

the total stake the applicant is including with their proposal (in wei)

dailyReward BigNumber

the approximate daily reward (in wei) the applicant is requesting

power BigNumber

the estimated vote power the listing would receive if accepted right now

details string

arbitrary details provided by the applicant with their proposal

acceptUnix number

the approximate unix timestamp the listing will be accepted, if not challenged

StoreChallenge

Represents a current challenge (in the gov state).

Kind: global typedef
Properties

Name Type Description
listingOwner string

the Ethereum address of the owner of the challenged listing

listingStake BigNumber

the total stake of the challenged listing

listingPower BigNumber

the current vote power of the listing (if they are a validator)

challenger string

the Ethereum address of the challenger

challengeId BigNumber

the incremental ID of the current challenge

challengerStake BigNumber

the staked balance of the challenger

challengeEndUnix number

the estimated unix timestamp the challenge ends at

challengeEnd BigNumber

the block at which the challenge reveal period ends

totalTokens BigNumber

if finalized, the total number of tokens from participating voters

winningTokens BigNumber

if finalized, the number of tokens that voted on the winning side

result string

the final result of the challenge; "passed", "failed", or null if not finalized

challengeType string

the type of listing the challenge is against, either a "validator" or a "proposal"

listingDetails string

details provided by the listing holder

challengeDetails string

details provided by the challenger

PastChallenge

Represents a historical challenge, and its outcome.

Kind: global typedef
Properties

Name Type Description
balance BigNumber

the number of tokens (in wei) staked in the challenge

challengeEnd BigNumber

the block the challenge ends at

challenger string

the Ethereum address of the challenger

details string

additional details provided by the challenger

finalized boolean

true if the challenge result is final, false if it is ongoing

listingKey string

the key that corresponds to the challenged listing

listingSnapshot ListingSnapshot

an object representing the state of the challenged listing at the time of challenge

passed boolean

true if the challenge was successful, false otherwise

pollId BigNumber

the incremental ID used to identify the poll

voterTotal BigNumber

the total number of tokens participating in the vote

winningTokens BigNumber

the total number of tokens voting for the winning option

ListingSnapshot

Represents a listing at the time it was challenged.

Kind: global typedef
Properties

Name Type Description
applicationBlock BigNumber

the block the listing application was submitted

confirmationBlock BigNumber

the block the listing was confirmed (0 if unconfirmed)

currentChallenge BigNumber

the ID of the current challenge against the listing

details string

arbitrary details provided by the listing applicant

exitBlock BigNumber

the block (if any) the listing exited at

lastRewardBlock BigNumber

the last block the listing owner claimed rewards for

owner string

the Ethereum address of the listing owner

rewardRate BigNumber

the number of tokens (in wei) rewarded to the listing per reward period

stakedBalance BigNumber

the number of tokens staked by the listing owner (in wei)

status number

the number representing the listing status (0: no listing, 1: proposal, 2: validator, 3: in-challenge, 4: exiting)

tendermintPublicKey string

the 32 byte Tendermint public key of the listing holder

Vote

Represents a stored vote in a challenge poll.

Kind: global typedef
Properties

Name Type Description
id BigNumber

the challengeId the vote is for

value string

the vote value (should be "1" or "0" for challenge votes)

salt string

a secret string used to hash the vote; must use same salt in commit as reveal

encoded string

the encoded vote, as passed to the contract system

commitTxHash string

the transaction hash of the commit transaction

revealTxHash string

the transaction hash of the reveal transaction

ChallengeInfo

Contains block numbers for various state changes for a given challenge.

Kind: global typedef
Properties

Name Type Description
challengeStart number

the block at which the challenge was initiated, and when the commit period starts

endCommitPeriod number

the block the commit period ends, and the reveal period starts

challengeEnd number

the block the reveal period ends, and the challenge finalizes

PastGovernanceActivity

An object representing an instance of past "activity" within the ValidatorRegistry contract.

If actionable is true, the following actions can be taken for a given type:

  • CHALLENGE_BY: challenge can be resolved
  • CHALLENGE_AGAINST: challenge can be resolved
  • PROPOSAL: the listing can be confirmed

If state is "PENDING" for a given type, the following action can be taken:

  • CHALLENGE_BY: the challenge can be voted on in the active poll
  • CHALLENGE_AGAINST: the challenge can be voted on in the active poll
  • PROPOSAL: the proposal may be challenged

Kind: global typedef
Properties

Name Type Description
type string

Either "CHALLENGE_BY" for created challenges, "CHALLENGE_AGAINST" for challenges against a user, and "PROPOSAL" for created listings

result string

Either "PENDING" for active, "ACCEPTED" for successful listings and challenges, and "REJECTED" for failed challenges and applications

actionable boolean

Indicates if some on-chain action can be taken to change the governance activity state

challengeId number

If present, indicates the challenge ID associated with the activity

listingPubKey string

The public key of the listing (proposal or challenged proposal)

Current Tags

  • 0.1.25-patch.1                                ...           latest (10 months ago)

27 Versions

  • 0.1.25-patch.1                                ...           10 months ago
  • 0.1.25                                ...           a year ago
  • 0.1.24                                ...           a year ago
  • 0.1.23                                ...           a year ago
  • 0.1.22                                ...           a year ago
  • 0.1.21                                ...           a year ago
  • 0.1.20                                ...           a year ago
  • 0.1.19                                ...           a year ago
  • 0.1.18                                ...           a year ago
  • 0.1.17                                ...           a year ago
  • 0.1.16                                ...           a year ago
  • 0.1.15                                ...           a year ago
  • 0.1.14                                ...           a year ago
  • 0.1.13                                ...           a year ago
  • 0.1.12                                ...           a year ago
  • 0.1.11                                ...           a year ago
  • 0.1.10                                ...           a year ago
  • 0.1.9                                ...           a year ago
  • 0.1.8                                ...           a year ago
  • 0.1.7                                ...           a year ago
  • 0.1.6                                ...           a year ago
  • 0.1.5                                ...           a year ago
  • 0.1.4                                ...           a year ago
  • 0.1.3                                ...           a year ago
  • 0.1.2                                ...           a year ago
  • 0.1.1                                ...           a year ago
  • 0.1.0                                ...           a year ago
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (6)
Dev Dependencies (9)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |