/dvote-js

Javascript/Typescript library to interact with the Vocdoni Open Stack

Primary LanguageTypeScriptGNU General Public License v3.0GPL-3.0

DVote JS

DVoteJS aims to provide utility classes and methods to invoke decentralized operations within a voting process. It covers the typical functionality of Client applications, as well as the Process Manager or the Census Manager.

The intended functionality is to interact with a public Ethereum blockchain, to fetch data from a decentralized filesystem, to enforce data schema validity, to prepare vote packages and using decentralized messaging networks through Gateways.

This library implements the protocol defined on https://docs.vocdoni.io/architecture/components.html

Getting started

npm install dvote-js ethers

DVoteJS is a superset of smaller NPM packages that can be installed individually:

If you are developing a frontend application using React, you can check out @vocdoni/react-hooks.

Ethers

The library is tightly coupled with ethers.js in order to sign payloads, communicate with Web3 endpoints and attach to physical/virtual wallets.

Signers and Wallets are both used to sign Web3 transactions, as well as authenticating DVote requests

  • To interact with the Ethereum blockchain, a Provider is needed.
  • In order to send transactions a Wallet or a Signer (like Metamask) are needed to sign.

Using providers

Ethers.js providers can connect using different sources.

Example 
const ethers = require("ethers")   // NodeJS
import { providers } from "ethers"    // ES6 Browser

// Well-known
const provider = ethers.getDefaultProvider('homestead') // mainnet

// Etherscan
const altProvider = new providers.EtherscanProvider('ropsten')

// Using injected web3 on a browser
const web3Provider1 = new providers.Web3Provider(web3.currentProvider)

const currentProvider2 = new web3.providers.HttpProvider('http://localhost:8545')
const web3Provider2 = new providers.Web3Provider(currentProvider2)

More information

Wallets

Generating a wallet from a mnemonic (and an optional path and Web3 provider):

Example 
const { WalletUtil } = require("dvote-js")
const mnemonic = "my mnemonic ..."
const mnemonicPath = "m/44'/60'/0'/0/0"
const provider = ethers.getDefaultProvider('goerli')

const wallet = WalletUtil.fromMnemonic(mnemonic, mnemonicPath, provider)
wallet.sendTransaction(...)
// ...

Generating a standalone deterministic wallet from a passphrase and a (non-private) seed. They are intended to provide wallets where the private key can be accessed.

Example 
const { Random, WalletUtil } = require("dvote-js")
const provider = ethers.getDefaultProvider('goerli')

// Created from scratch
const hexSeed = Random.getHex()  // could be stored locally
const passphrase = "A very Difficult 1234 passphrase" // must be private and include upper/lowercase chars and numbers

// Or using an already created seed
const hexSeed = "0xfdbc446f9f3ea732d23c7bcd10c784d041887d48ebc392c4ff51882ae569ca15"
const passphrase = "A very Difficult 1234 passphrase" // must be private and include upper/lowercase chars and numbers

const wallet = WalletUtil.fromSeededPassphrase(passphrase, hexSeed, provider)
wallet.signMessage(...)
// ...

Accessing the browser wallet or MetaMask:

Example 
const { SignerUtil } = require("dvote-js")
const signer = SignerUtil.fromInjectedWeb3()
signer.sendTransaction(...)

Components

Entity / Organization

The entity API allows reading and managing the metadata of an organization. On top of a key-value store, lies a link to the entity's metadata, which is the human readable information about it.

Process

A Voting process contains a group of settings defining how an L2 governance process is conducted on the Vochain.

In addition to the flags there is also the process metadata, which is the human readable content that voters will be prompted for making a choice.

Gateway

Provides utility functions to fetch data from decentralized filesystems, sending messages and adding files to IPFS.

Examples

See the examples for different use cases:

Development

Run npm run build to compile the whole library or the individual packages. Run npm run test on each one of the packages.

Mocha

When adding new test suites, don't forget to add a call to addCompletionHooks(). Otherwise, the NodeJS process will keep up indefinitely when testing.