Votings¶
Class Name | Wallet |
---|---|
Extends | Logger |
Source | votings.ts |
Examples | votings.spec.ts |
The votings helper allows to hold votes over decisions and execute them, if enough votes have been submitted.
The usual flow for proposals has the following steps:
- if not already created, create a voting contract with createContract (this doesn’t have to be done when using a central voting contract (e.g. from a well known ENS address))
- create a proposal for a change with createProposal
- let participants vote with vote
- if enough time has passed and you have enough votes, you can finally execute your proposal with execute
constructor¶
new Votings(options);
Creates a new Votings instance.
Parameters¶
options
-VotingsOptions
: options for Votings constructor.contractLoader
-ContractLoader
:ContractLoader
instanceexecutor
-Executor
:Executor
instance
Returns¶
Votings
instance
Example¶
const votings = new Votings({
contractLoader,
executor,
});
= Contract =¶
createContract¶
votings.createContract(creator, votingsContractOptions);
Create new voting contract instance.
Parameters¶
creator
-string
: identity or account that should create and own the contractvotingsContractOptions
-VotingsContractOptions
: additional options for votings contract
Returns¶
Promise
returns void
: resolved when done
Example¶
const votingsContract = await votings.createContract(
'0x1111111111111111111111111111111111111111',
{
minimumQuorumForProposals: 2,
minutesForDebate: 1,
marginOfVotesForMajority: 0,
},
);
= Members =¶
addMember¶
votings.addMember(votingsContract, votingsOwner, toInvite, memberOptions);
Add member to voting contract.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract addressexecutingAddress
-string
: identity or account that performs the action (usually the voting owner)invitee
-string
: identity or account to add to votings contractmemberOptions
-MemberOptions
: options for new member
Returns¶
Promise
returns void
: resolved when done
Example¶
await votings.addMember(
'0x00000000000000000000000000000000c0274ac7',
'0x1111111111111111111111111111111111111111',
'0x2222222222222222222222222222222222222222',
{ name: 'Member Number 2' },
);
removeMember¶
votings.removeMember(votingsContract, votingsOwner, toRemove);
Remove member from votings contract.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract addressremover
-string
: identity or account that performs the actionremovee
-string
: identity or account to remove from votings contract
Returns¶
Promise
returns void
: resolved when done
Example¶
await votings.removeMember(
'0x00000000000000000000000000000000c0274ac7',
'0x1111111111111111111111111111111111111111',
'0x2222222222222222222222222222222222222222',
);
getMemberInfo¶
votings.getMemberInfo(votingsContract, target);
Get info of a member.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract addresstarget
-string
: identity or account to get info for
Returns¶
Promise
returns MemberInfo
: member info
Example¶
console.dir(await votings.getMemberInfo(
'0x00000000000000000000000000000000c0274ac7',
'0x2222222222222222222222222222222222222222',
));
// Output:
// {
// address: '0x2222222222222222222222222222222222222222',
// name: 'Member Number 2',
// memberSince: 1544092270556
// }
isMember¶
votings.isMember(votingsContract, target);
Checks if a given identity or account is member in voting contract.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract addresstarget
-string
: identity or account to get info for
Returns¶
Promise
returns bool
: true if member
Example¶
console.dir(await votings.isMember(
'0x00000000000000000000000000000000c0274ac7',
'0x2222222222222222222222222222222222222222',
));
// Output:
// true
= Proposals =¶
createProposal¶
votings.createProposal(votingsContract, proposalCreator, proposalOptions);
Create a new proposal in votings contract.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract addressproposalCreator
-string
: identity or account to create the proposalproposalOptions
-ProposalOptions
: options for proposal
Returns¶
Promise
returns string
: id of new proposal
Example¶
// make a proposal about a suggestion (text only)
const textProposal = await votings.createProposal(
'0x00000000000000000000000000000000c0274ac7',
'0x1111111111111111111111111111111111111111',
{ description: 'Change voting time to 2 hours.' },
);
// propose a transaction
const txProposal = await votings.createProposal(
'0x00000000000000000000000000000000c0274ac7',
'0x1111111111111111111111111111111111111111',
{
description: 'set data of this contract to "def"',
data: '0x47064d6a' +
'0000000000000000000000000000000000000000000000000000000000000020' +
'0000000000000000000000000000000000000000000000000000000000000003' +
'6465660000000000000000000000000000000000000000000000000000000000',
to: '0x000000000000000000000000a2074340c0274ac7',
},
);
getProposalCount¶
votings.getProposalCount(contract);
Get number of proposals in votings contract.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract address
Returns¶
Promise
returns number
: number of proposals
Example¶
await votings.createProposal(
'0x00000000000000000000000000000000c0274ac7',
'0x1111111111111111111111111111111111111111',
{
description: 'set data of this contract to "def"',
data: '0x47064d6a' +
'0000000000000000000000000000000000000000000000000000000000000020' +
'0000000000000000000000000000000000000000000000000000000000000003' +
'6465660000000000000000000000000000000000000000000000000000000000',
to: '0x000000000000000000000000a2074340c0274ac7',
},
);
const count = await votings.getProposalCount('0x00000000000000000000000000000000c0274ac7');
console.log(count);
// Output:
// 1
getProposalInfo¶
votings.getProposalInfo(votingsContract, proposalId);
Gets info about a given proposal in contract.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract addressproposalId
-string
: id of proposal to retrieve info for
Returns¶
Promise
returns ProposalInfo
: info about proposal
Example¶
console.dir(await votings.getProposalInfo(
'0x00000000000000000000000000000000c0274ac7',
'0',
));
// Output:
// {
// currentResult: '0',
// description: 'Change voting time to 2 hours.',
// executed: false,
// minExecutionDate: 1544093505000,
// numberOfVotes: '0',
// proposalHash: '0xa86d54e9aab41ae5e520ff0062ff1b4cbd0b2192bb01080a058bb170d84e6457',
// proposalPassed: false,
// to: '0x0000000000000000000000000000000000000000',
// value: '0'
// }
getProposalInfos¶
votings.getProposalInfos(contract[, count, offset, reverse]);
Get multiple proposals from votings contract.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract addresscount
-number
(optional): number of items to retrieve, defaults to10
offset
-number
(optional): skip this many entries, defaults to0
reverse
-boolean
(optional): fetch entries, starting with last entry, defaults totrue
Returns¶
Promise
returns ProposalInfos
: proposals listing
Example¶
await votings.createProposal(
'0x00000000000000000000000000000000c0274ac7',
'0x1111111111111111111111111111111111111111',
{
description: 'set data of this contract to "def"',
data: '0x47064d6a' +
'0000000000000000000000000000000000000000000000000000000000000020' +
'0000000000000000000000000000000000000000000000000000000000000003' +
'6465660000000000000000000000000000000000000000000000000000000000',
to: '0x000000000000000000000000a2074340c0274ac7',
},
);
const proposals = await votings.getProposalInfos('0x00000000000000000000000000000000c0274ac7');
console.log(proposals.results.length);
// Output:
// 1
vote¶
votings.vote(votingsContract, voter, proposal, accept[, comment]);
Vote for a proposal.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract addressvoter
-string
: identity or account that performs the actionproposal
-string
: id of proposal to vote foraccept
-boolean
: accept proposal or notcomment
-string
(optional): comment for vote, left empty if omitted
Returns¶
Promise
returns void
: resolved when done
Example¶
await votings.vote(
'0x00000000000000000000000000000000c0274ac7',
'0x2222222222222222222222222222222222222222',
'1',
true,
);
execute¶
votings.execute(votingsContract, proposalExecutor, proposal[, data]);
Execute a proposal.
Parameters¶
contract
-string|any
: web3 voting contract instance or contract addressproposalExecutor
-string
: identity or account to execute the proposalproposal
-string
: id of proposal to vote fordata
-string
(optional): transaction input bytes as string (0x${functionhash}${argumentsData}), defaults to0x
Returns¶
Promise
returns void
: resolved when done
Example¶
// execute proposal about a suggestion (text only)
await votings.execute(
'0x00000000000000000000000000000000c0274ac7',
'0x1111111111111111111111111111111111111111',
'0',
);
// execute proposal about a transaction
await votings.execute(
'0x00000000000000000000000000000000c0274ac7',
'0x1111111111111111111111111111111111111111',
'1',
'0x47064d6a' +
'0000000000000000000000000000000000000000000000000000000000000020' +
'0000000000000000000000000000000000000000000000000000000000000003' +
'6465660000000000000000000000000000000000000000000000000000000000',
);
= Additional Components =¶
Interfaces¶
MemberInfo¶
address
-string
: member’s identity or accountname
-string
: description text of membermemberSince
-string
: date of joining votings contract
MemberOptions¶
name
-string
: description text of member
ProposalInfo¶
currentResult
-number
: current number of positive votesdescription
-string
: description textexecuted
-boolean
: true if already executedminExecutionData
-number
: earliest day of executionnumberOfVotes
-number
: number of submitted votesproposalHash
-string
: checksum of proposal: keccak256(beneficiary, weiAmount, transactionBytecode)proposalPassed
-boolean
: true if executed and proposal passedto
-string
: target of proposal (contract/identity/account to send transaction to)value
-string
: amount of Wei to send to target
ProposalInfos¶
results
-ProposalInfo[]
: proposals of current page (length is 10)totalCount
-number
: total number of results
ProposalOptions¶
description
-string
: description textdata
-string
(optional): input data for proposal, defaults to0x
to
-string
(optional): target of proposal (contract/account to send transaction to), defaults to0x0000000000000000000000000000000000000000
value
-string
(optional): amount of Wei to send to target, defaults to0
VotingsContractOptions¶
minimumQuorumForProposals
-number
: votes that must have been given before any proposal is accepted; updates to this may affect running proposalsminutesForDebate
-number
: time to have passed before a proposal can be accepted; updates to this do not affect running proposalsmarginOfVotesForMajority
-number
: accepting votes that must have been given before any proposal is accepted; updates to this may affect running proposals