Integration Details

The tutorial covers the basics, but here are some details you'll need to consider when integrating the Vocdoni SDK into your application.

Vocdoni Tokens

Running voting processes in the production environment requires the use of Vocdoni Tokens. Read the guide here.

Census Types

There are many ways to define a census of voters using the Vocdoni SDK. Each census type has different design considerations and use-cases. Read the guide here

Anonymous Voting

Anonymous voting is available in some form with all three census types, with the strongest anonymity being anonymous off-chain Merkle tree elections. Minor modifications are usually necessary to convert censuses to being fully anonymous. Read the section on census types to see how to enable anonymity.

Election Types

The Vocdoni Ballot Protocol provides a flexible way to define many types of election. Check out Voting Types for an overview of the possibilities, including ranked-choice, quadratic, weighted, and approval voting.

Environment

Production

This is the environment for any production use cases. This environment is slightly more complicated to use, as it requires the manual use of Vocdoni Tokens

const client = new VocdoniSDKClient({
  env: EnvOptions.PROD, // mandatory, can be 'dev', 'stg', or 'prod'
  wallet: signer, // optional, the signer used (Metamask, Walletconnect)
})

Staging

This is the recommended environment for most testing use cases, since the dev environment is more subject to blockchain resets and downtimes than the stg one.

const client = new VocdoniSDKClient({
  env: EnvOptions.STG, // mandatory, can be 'dev', 'stg', or 'prod'
  wallet: signer, // optional, the signer used (Metamask, Walletconnect)
})

Development

This environment is for development testing and is subject to breaking changes and downtime.

const client = new VocdoniSDKClient({
  env: EnvOptions.DEV, // mandatory, can be 'dev', 'stg', or 'prod'
  wallet: signer, // optional, the signer used (Metamask, Walletconnect)
})

Election Status

Depending on your use case, you may need to pause, cancel, or otherwise pay attention to the state of an election. Election lifecycle states details all of the possible statuses an election can have once it has been published to the blockchain.

Pause

(async () => {
  await client.pauseElection(id)
  const election = await client.fetchElection(id)
  console.log(election.status) // Matches ElectionStatus.PAUSED
})();

Cancel

(async () => {
  await client.cancelElection(id)
  const election = await client.fetchElection(id)
  console.log(election.status) // Matches ElectionStatus.CANCELED
})();

End

(async () => {
  await client.endElection(id)
  const election = await client.fetchElection(id)
  console.log(election.status) // Matches ElectionStatus.ENDED
})();

Continue

(async () => {
  await client.continueElection(id)
  const election = await client.fetchElection(id)
  console.log(election.status) // Matches ElectionStatus.READY
})();

Other SDK Tools

Generate a random Wallet

You can use the client.generateRandomWallet function to generate a random Wallet and assign it to the client. This function returns the private key of the Wallet.

const privateKey = client.generateRandomWallet();
console.log(privateKey) // the private key of the wallet

Generate deterministic Wallet from data

For some cases where the voters don't have custody over an existing Wallet, we can generate a deterministic Wallet based on arbitrary data, like, for example, the user and hash password from a custom CRM.

Here is an example of client.generateWalletFromData where a Wallet is generated using the username and the hash of the password which we would use to identify the user in our platform. This Wallet can then be used for the census and for voting purposes. This enables users to keep the same private key without having to store it in their browser or application.

// 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 is the sha256 of 'test'
const userWallet = VocdoniSDKClient.generateWalletFromData(['user1', '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08']);
console.log(userWallet) // address is 0x8AF1b3EDB817b5854e3311d583905a3421F49829