Gov is a helper library for interacting with the Kosu validator governance\nsystem (primarily the Kosu ValidatorRegistry contract).
It is designed with the browser in mind, and is intended to be used in front-\nend projects for simplifying interaction with the governance system.
\nMethods may be used to load the current proposals, validators, and\nchallenges from the prototype's state, or the gov.ee object (an EventEmitter)\nmay be used to detect updates to the state, emitted as gov_update events.
After a gov_update event, the read methods for proposals, challenges,\nand validators must be called to load the current listings. Alternatively,\naccess the objects directly with gov.listings, etc.
Represents an active validator in the registry.
Represents a pending listing application for a spot on the ValidatorRegistry.
Represents a current challenge (in the gov state).
Represents a historical challenge, and its outcome.
Represents a listing at the time it was challenged.
Represents a stored vote in a challenge poll.
Contains block numbers for various state changes for a given challenge.
An object representing an instance of past "activity" within the ValidatorRegistry contract.
\nIf actionable is true, the following actions can be taken for a given type:
If state is "PENDING" for a given type, the following action can be taken:
Gov is a helper library for interacting with the Kosu validator governance\nsystem (primarily the Kosu ValidatorRegistry contract).
It is designed with the browser in mind, and is intended to be used in front-\nend projects for simplifying interaction with the governance system.
\nMethods may be used to load the current proposals, validators, and\nchallenges from the prototype's state, or the gov.ee object (an EventEmitter)\nmay be used to detect updates to the state, emitted as gov_update events.
After a gov_update event, the read methods for proposals, challenges,\nand validators must be called to load the current listings. Alternatively,\naccess the objects directly with gov.listings, etc.
Map.<Proposal>](#Proposal)\n - [.currentValidators()](#Gov+currentValidators) ⇒ [Map.<Validator>](#Validator)\n - [.currentChallenges()](#Gov+currentChallenges) ⇒ [Map.<StoreChallenge>](#StoreChallenge)\n - [.weiToEther(wei)](#Gov+weiToEther) ⇒ string\n - [.etherToWei(ether)](#Gov+etherToWei) ⇒ string\n - [.commitVote(challengeId, value, amount)](#Gov+commitVote) ⇒ Promise.<string>\n - [.hasCommittedVote(challengeId)](#Gov+hasCommittedVote) ⇒ boolean\n - [.revealVote(challengeId)](#Gov+revealVote) ⇒ Promise.<string>\n - [.hasRevealedVote(challengeId)](#Gov+hasRevealedVote) ⇒ boolean\n - [.estimateFutureBlockTimestamp(blockNumber)](#Gov+estimateFutureBlockTimestamp) ⇒ Promise.<number>\n - [.getPastBlockTimestamp(blockNumber)](#Gov+getPastBlockTimestamp) ⇒ Promise.<number>\n - [.getHistoricalChallenges()](#Gov+getHistoricalChallenges) ⇒ Promise.<Array.<PastChallenge>>\n - [.getChallengeInfo(challengeId)](#Gov+getChallengeInfo) ⇒ [Promise.<ChallengeInfo>](#ChallengeInfo)\n - [.currentBlockNumber()](#Gov+currentBlockNumber) ⇒ number\n - [.getPastGovernanceActivity(address)](#Gov+getPastGovernanceActivity) ⇒ Promise.<Array.<PastGovernanceActivity>>\n - _static_\n - [.ZERO](#Gov.ZERO)\n - [.ONE](#Gov.ONE)\n - [.ONE_HUNDRED](#Gov.ONE_HUNDRED)\n - [.BLOCKS_PER_DAY](#Gov.BLOCKS_PER_DAY)\n\n\n\n### new Gov()\n\nCreate a new Gov instance (gov). Requires no arguments, but can be\nset to "debug" mode by passing true or 1 (or another truthy object to\nthe constructor).
Prior to using most gov functionality, the async gov.init() method\nmust be called, which will initialize the module and load state from\nthe Kosu contract system.
Main initialization function for the gov module. You must call init\nprior to interacting with most module functionality, and gov.init() will\nload the current registry status (validators, proposals, etc.) so it should\nbe called early-on in the page life-cycle.
Performs many functions, including:
\nGov](#Gov) \n\n\n### gov.currentProposals() ⇒ [Map.<Proposal>](#Proposal)\n\nLoad the current proposal map from state.
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: [Map.<Proposal>](#Proposal) - a map where the key is the listing public key, and the value is a proposal object
\n**Example**\n\n```javascript\nconst proposals = gov.currentProposals();\n```\n\n\n\n### gov.currentValidators() ⇒ [Map.<Validator>](#Validator)\n\nLoad the current validators map from state.
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: [Map.<Validator>](#Validator) - a map where the key is the listing public key, and the value is a validator object
\n**Example**\n\n```javascript\nconst validators = gov.currentValidators();\n```\n\n\n\n### gov.currentChallenges() ⇒ [Map.<StoreChallenge>](#StoreChallenge)\n\nLoad the current challenges map from state.
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: [Map.<StoreChallenge>](#StoreChallenge) - a map where the key is the listing public key, and the value is a challenge object
\n**Example**\n\n```javascript\nconst challenges = gov.currentChallenges();\n```\n\n\n\n### gov.weiToEther(wei) ⇒string\n\nConvert a number of tokens, denominated in the smallest unit - "wei" - to\n"full" units, called "ether". One ether = 1*10^18 wei.
\nAll contract calls require amounts in wei, but the user should be shown\namounts in ether.
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: string - the same amount in ether, string used for precision
\n\n| Param | Type | Description |\n| ----- | --------------------------------------------- | ----------------------------------------- |\n| wei |BigNumber \\| string | the token amount in wei to convert
|\n\n**Example**\n\n```javascript\ngov.weiToEther(\"100000000000000000000\"); // > \"100\"\ngov.weiToEther(100000000000000000000); // > \"100\"\n```\n\n\n\n### gov.etherToWei(ether) ⇒string\n\nConvert a number of tokens (full units, called "ether") to "wei", the\nsmallest denomination of most ERC-20 tokens with 18 decimals.
\nAll contract calls require amounts in wei, but the user should be shown\namounts in ether.
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: string - the same amount in wei, string used for precision
\n\n| Param | Type | Description |\n| ----- | --------------------------------------------- | ---------------------------------- |\n| ether |BigNumber \\| string | the token amount to convert
|\n\n**Example**\n\n```javascript\ngov.etherToWei(10); // > \"10000000000000000000\"\ngov.etherToWei(\"1\"); // > \"1000000000000000000\"\n```\n\n\n\n### gov.commitVote(challengeId, value, amount) ⇒Promise.<string>\n\nCommit a vote in an active a challenge poll.
\nThis method creates a vote (with value and salt), encodes it, and submits\nit as a transaction (requires MetaMask signature).
\nIt stores the vote data in a browser cookie so it may be revealed later,\nwhich means voters must reveal a vote with the same browser they used to\ncommit it.
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: Promise.<string> - the transaction hash of the commit tx
\n\n| Param | Type | Description |\n| ----------- | ---------------------- | --------------------------------------------------------------------------------------------- |\n| challengeId |BigNumber | the pollId of the challenge, as a string
|\n| value |string | the vote value, "1" to vote for the challenge, "0" to vote against
|\n| amount |BigNumber | the number of tokens (in wei) to commit in the vote
|\n\n**Example**\n\n```javascript\n// we are looking at challenge #13, and want to vote AGAINST it with 10 tokens\nconst pollId = new BigNumber(13);\nconst amount = new BigNumber(gov.etherToWei(\"10\"));\nconst value = \"0\";\n\n// will prompt for MetaMask signature\nconst commitVoteTxId = await gov.commitVote(pollId, value, amount);\n\n// ... some time passes, we now want to reveal ...\n\n// load vote from cookie and reveal\nconst revealTxId = await gov.revealVote(new BigNumber(\"13\"));\n\n// ... wait for Tx's to confirm or whatever, etc.\n```\n\n\n\n### gov.hasCommittedVote(challengeId) ⇒boolean\n\nCheck for a previously committed vote, by challengeId (as a BigNumber).
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: boolean - the boolean representing the presence of a commit vote
\n\n| Param | Type | Description |\n| ----------- | ---------------------- | ---------------------------------------------------------- |\n| challengeId |BigNumber | the challenge to check for a stored commit vote for
|\n\n\n\n### gov.revealVote(challengeId) ⇒Promise.<string>\n\nReveal a previously committed vote, by challengeId (as a BigNumber).
\nFor this method to work, the user must have committed a vote during the\ncommit period for the given challenge.
\nThis method must also be called during the reveal period in order for the\ntransaction not to fail.
\nCalling this method will trigger a MetaMask pop-up asking for the user's\nsignature and approval.
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: Promise.<string> - the transaction hash of the reveal tx.
\n\n| Param | Type | Description |\n| ----------- | ---------------------- | ------------------------------------------------ |\n| challengeId |BigNumber | the challenge to reveal a stored vote for
|\n\n\n\n### gov.hasRevealedVote(challengeId) ⇒boolean\n\nCheck for a previously revealed vote, by challengeId (as a BigNumber).
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: boolean - the boolean representing the presence of a reveal vote
\n\n| Param | Type | Description |\n| ----------- | ---------------------- | ---------------------------------------------------------- |\n| challengeId |BigNumber | the challenge to check for a stored reveal vote for
|\n\n\n\n### gov.estimateFutureBlockTimestamp(blockNumber) ⇒Promise.<number>\n\nEstimate the UNIX timestamp (in seconds) at which a given block will be\nmined.
Gov](#Gov) \n**Returns**: Promise.<number> - the block's estimated UNIX timestamp (in seconds)
\n\n| Param | Type | Description |\n| ----------- | ------------------- | ----------------------------------------------------- |\n| blockNumber |number | the block number to estimate the timestamp for
|\n\n**Example**\n\n```javascript\nconst block = 6102105;\nconst unixTs = gov.estimateFutureBlockTimestamp(block);\n\n// use as a normal date object (multiply by 1000 to get ms)\nconst blockDate = new Date(ts * 1000);\n```\n\n\n\n### gov.getPastBlockTimestamp(blockNumber) ⇒Promise.<number>\n\nRetrieve the Unix timestamp of a block that has already been mined.\nShould be used to display times of things that have happened (validator\nconfirmed, etc.).
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: Promise.<number> - the Unix timestamp of the specified blockNumber
number | the block to get the unix timestamp for
|\n\n**Example**\n\n```javascript\nawait gov.getPastBlockTimestamp(515237); // > 1559346404\n```\n\n\n\n### gov.getHistoricalChallenges() ⇒Promise.<Array.<PastChallenge>>\n\nThis method returns an array (described below) that contains information\nabout all past challenges. Intended to be used for the "Past Challenges"\nsection.
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: Promise.<Array.<PastChallenge>> - all historical challenges.
Promise.<ChallengeInfo>](#ChallengeInfo)\n\nReturns an object with the block numbers of important times for a given\nchallenge. Between challengeStart and endCommitPeriod, votes may be\ncommitted (submitted) to the challenge.
Between endCommitPeriod and challengeEnd, votes may be revealed with\nthe same salt and vote value.
Gov](#Gov) \n**Returns**: [Promise.<ChallengeInfo>](#ChallengeInfo) - the block numbers for this challenge
\n\n| Param | Type | Description |\n| ----------- | -------------------------------------------------------------------- | --------------------------------------- |\n| challengeId |string \\| number \\| BigNumber | the ID of the challenge to query
|\n\n**Example**\n\n```javascript\nconst info = await gov.getChallengeInfo(new BigNumber(1));\nconst currentBlock = await gov.currentBlockNumber();\n\nif (currentBlock < endCommitPeriod && currentBlock >= challengeStart) {\n // in \"commit\" period; voters may submit votes\n} else if (currentBlock >= endCommitPeriod && currentBlock <= challengeEnd) {\n // in \"reveal\" period; voters may reveal votes\n} else {\n // challenge has ended (or issues with block numbers)\n}\n```\n\n\n\n### gov.currentBlockNumber() ⇒number\n\nReturns the current block height (as a number).
\n\n**Kind**: instance method of [Gov](#Gov) \n**Returns**: number - The current (or most recent) Ethereum block height.
\n\n\n### gov.getPastGovernanceActivity(address) ⇒Promise.<Array.<PastGovernanceActivity>>\n\nGet information about a given Ethereum address's past governance activity\nwithin the system.
\nReturns info about proposals submitted, challenges created, and challenges\nagainst listings owned by the user.
\nFor a given activity object, if actionable is true, the following\naction may be taken for each state:
Gov](#Gov) \n**Returns**: Promise.<Array.<PastGovernanceActivity>> - An array of snippets about past governance activity.
\n\n| Param | Type | Description |\n| ------- | ------------------- | --------------------------------------------------------- |\n| address |string | Ethereum address of user to get past activity for.
|\n\n\n\n### Gov.ZERO\n\nThe value 0 as an instance ofBigNumber.
Gov](#Gov) \n\n\n### Gov.ONE\n\nThe value 1 as an instance ofBigNumber.
Gov](#Gov) \n\n\n### Gov.ONE_HUNDRED\n\nThe value 100 as an instance ofBigNumber.
Gov](#Gov) \n\n\n### Gov.BLOCKS_PER_DAY\n\nEstimated blocks per day (mainnet only).
\n\n**Kind**: static property of [Gov](#Gov) \n\n\n## Validator\n\nRepresents an active validator in the registry.
\n\n**Kind**: global typedef \n**Properties**\n\n| Name | Type | Description |\n| ---------------- | ---------------------- | ------------------------------------------------------------------------ |\n| owner |string | the Ethereum address of the validator
|\n| stakeSize |BigNumber | the staked balance (in wei) of the validator
|\n| dailyReward |BigNumber | the approximate daily reward to the validator (in wei)
|\n| confirmationUnix |number | the unix timestamp of the block the validator was confirmed in
|\n| power |BigNumber | the validators approximate current vote power on the Kosu network
|\n| details |string | arbitrary details provided by the validator when they applied
|\n\n\n\n## Proposal\n\nRepresents a pending listing application for a spot on the ValidatorRegistry.
string | the Ethereum address of the applicant
|\n| stakeSize |BigNumber | the total stake the applicant is including with their proposal (in wei)
|\n| dailyReward |BigNumber | the approximate daily reward (in wei) the applicant is requesting
|\n| power |BigNumber | the estimated vote power the listing would receive if accepted right now
|\n| details |string | arbitrary details provided by the applicant with their proposal
|\n| acceptUnix |number | the approximate unix timestamp the listing will be accepted, if not challenged
|\n\n\n\n## StoreChallenge\n\nRepresents a current challenge (in the gov state).
string | the Ethereum address of the owner of the challenged listing
|\n| listingStake |BigNumber | the total stake of the challenged listing
|\n| listingPower |BigNumber | the current vote power of the listing (if they are a validator)
|\n| challenger |string | the Ethereum address of the challenger
|\n| challengeId |BigNumber | the incremental ID of the current challenge
|\n| challengerStake |BigNumber | the staked balance of the challenger
|\n| challengeEndUnix |number | the estimated unix timestamp the challenge ends at
|\n| challengeEnd |BigNumber | the block at which the challenge reveal period ends
|\n| totalTokens |BigNumber | if finalized, the total number of tokens from participating voters
|\n| winningTokens |BigNumber | if finalized, the number of tokens that voted on the winning side
|\n| result |string | the final result of the challenge; "passed", "failed", or null if not finalized
string | the type of listing the challenge is against, either a "validator" or a "proposal"
|\n| listingDetails |string | details provided by the listing holder
|\n| challengeDetails |string | details provided by the challenger
|\n\n\n\n## PastChallenge\n\nRepresents a historical challenge, and its outcome.
\n\n**Kind**: global typedef \n**Properties**\n\n| Name | Type | Description |\n| --------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |\n| balance |BigNumber | the number of tokens (in wei) staked in the challenge
|\n| challengeEnd |BigNumber | the block the challenge ends at
|\n| challenger |string | the Ethereum address of the challenger
|\n| details |string | additional details provided by the challenger
|\n| finalized |boolean | true if the challenge result is final, false if it is ongoing
string | the key that corresponds to the challenged listing
|\n| listingSnapshot | [ListingSnapshot](#ListingSnapshot) | an object representing the state of the challenged listing at the time of challenge
|\n| passed |boolean | true if the challenge was successful, false otherwise
BigNumber | the incremental ID used to identify the poll
|\n| voterTotal |BigNumber | the total number of tokens participating in the vote
|\n| winningTokens |BigNumber | the total number of tokens voting for the winning option
|\n\n\n\n## ListingSnapshot\n\nRepresents a listing at the time it was challenged.
\n\n**Kind**: global typedef \n**Properties**\n\n| Name | Type | Description |\n| ------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| applicationBlock |BigNumber | the block the listing application was submitted
|\n| confirmationBlock |BigNumber | the block the listing was confirmed (0 if unconfirmed)
|\n| currentChallenge |BigNumber | the ID of the current challenge against the listing
|\n| details |string | arbitrary details provided by the listing applicant
|\n| exitBlock |BigNumber | the block (if any) the listing exited at
|\n| lastRewardBlock |BigNumber | the last block the listing owner claimed rewards for
|\n| owner |string | the Ethereum address of the listing owner
|\n| rewardRate |BigNumber | the number of tokens (in wei) rewarded to the listing per reward period
|\n| stakedBalance |BigNumber | the number of tokens staked by the listing owner (in wei)
|\n| status |number | the number representing the listing status (0: no listing, 1: proposal, 2: validator, 3: in-challenge, 4: exiting)
|\n| tendermintPublicKey |string | the 32 byte Tendermint public key of the listing holder
|\n\n\n\n## Vote\n\nRepresents a stored vote in a challenge poll.
\n\n**Kind**: global typedef \n**Properties**\n\n| Name | Type | Description |\n| ------------ | ---------------------- | ------------------------------------------------------------------------------------ |\n| id |BigNumber | the challengeId the vote is for
|\n| value |string | the vote value (should be "1" or "0" for challenge votes)
|\n| salt |string | a secret string used to hash the vote; must use same salt in commit as reveal
|\n| encoded |string | the encoded vote, as passed to the contract system
|\n| commitTxHash |string | the transaction hash of the commit transaction
|\n| revealTxHash |string | the transaction hash of the reveal transaction
|\n\n\n\n## ChallengeInfo\n\nContains block numbers for various state changes for a given challenge.
\n\n**Kind**: global typedef \n**Properties**\n\n| Name | Type | Description |\n| --------------- | ------------------- | ---------------------------------------------------------------------------------------- |\n| challengeStart |number | the block at which the challenge was initiated, and when the commit period starts
|\n| endCommitPeriod |number | the block the commit period ends, and the reveal period starts
|\n| challengeEnd |number | the block the reveal period ends, and the challenge finalizes
|\n\n\n\n## PastGovernanceActivity\n\nAn object representing an instance of past "activity" within the ValidatorRegistry contract.
\nIf actionable is true, the following actions can be taken for a given type:
If state is "PENDING" for a given type, the following action can be taken:
string | Either "CHALLENGE_BY" for created challenges, "CHALLENGE_AGAINST" for challenges against a user, and "PROPOSAL" for created listings
|\n| result |string | Either "PENDING" for active, "ACCEPTED" for successful listings and challenges, and "REJECTED" for failed challenges and applications
|\n| actionable |boolean | Indicates if some on-chain action can be taken to change the governance activity state
|\n| challengeId |number | If present, indicates the challenge ID associated with the activity
|\n| listingPubKey |string | The public key of the listing (proposal or challenged proposal)
|\n","readmeFilename":"README.md"}