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:

  1. 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))
  2. create a proposal for a change with createProposal
  3. let participants vote with vote
  4. 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

  1. options - VotingsOptions: options for Votings constructor.

Returns

Votings instance

Example

const votings = new Votings({
  contractLoader,
  executor,
});

= Contract =

createContract

votings.createContract(creator, votingsContractOptions);

Create new voting contract instance.

Parameters

  1. creator - string: identity or account that should create and own the contract
  2. votingsContractOptions - 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

  1. contract - string|any: web3 voting contract instance or contract address
  2. executingAddress - string: identity or account that performs the action (usually the voting owner)
  3. invitee - string: identity or account to add to votings contract
  4. memberOptions - 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

  1. contract - string|any: web3 voting contract instance or contract address
  2. remover - string: identity or account that performs the action
  3. removee - 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

  1. contract - string|any: web3 voting contract instance or contract address
  2. target - 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

  1. contract - string|any: web3 voting contract instance or contract address
  2. target - 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

  1. contract - string|any: web3 voting contract instance or contract address
  2. proposalCreator - string: identity or account to create the proposal
  3. proposalOptions - 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

  1. 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

  1. contract - string|any: web3 voting contract instance or contract address
  2. proposalId - 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

  1. contract - string|any: web3 voting contract instance or contract address
  2. count - number (optional): number of items to retrieve, defaults to 10
  3. offset - number (optional): skip this many entries, defaults to 0
  4. reverse - boolean (optional): fetch entries, starting with last entry, defaults to true

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

  1. contract - string|any: web3 voting contract instance or contract address
  2. voter - string: identity or account that performs the action
  3. proposal - string: id of proposal to vote for
  4. accept - boolean: accept proposal or not
  5. comment - 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

  1. contract - string|any: web3 voting contract instance or contract address
  2. proposalExecutor - string: identity or account to execute the proposal
  3. proposal - string: id of proposal to vote for
  4. data - string (optional): transaction input bytes as string (0x${functionhash}${argumentsData}), defaults to 0x

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

  1. address - string: member’s identity or account
  2. name - string: description text of member
  3. memberSince - string: date of joining votings contract

MemberOptions

  1. name - string: description text of member

ProposalInfo

  1. currentResult - number: current number of positive votes
  2. description - string: description text
  3. executed - boolean: true if already executed
  4. minExecutionData - number: earliest day of execution
  5. numberOfVotes - number: number of submitted votes
  6. proposalHash - string: checksum of proposal: keccak256(beneficiary, weiAmount, transactionBytecode)
  7. proposalPassed - boolean: true if executed and proposal passed
  8. to - string: target of proposal (contract/identity/account to send transaction to)
  9. value - string: amount of Wei to send to target

ProposalInfos

  1. results - ProposalInfo[]: proposals of current page (length is 10)
  2. totalCount - number: total number of results

ProposalOptions

  1. description - string: description text
  2. data - string (optional): input data for proposal, defaults to 0x
  3. to - string (optional): target of proposal (contract/account to send transaction to), defaults to 0x0000000000000000000000000000000000000000
  4. value - string (optional): amount of Wei to send to target, defaults to 0

VotingsContractOptions

  1. minimumQuorumForProposals - number: votes that must have been given before any proposal is accepted; updates to this may affect running proposals
  2. minutesForDebate - number: time to have passed before a proposal can be accepted; updates to this do not affect running proposals
  3. marginOfVotesForMajority - number: accepting votes that must have been given before any proposal is accepted; updates to this may affect running proposals