search

vocdoni / dvote-js

Javascript/Typescript library to interact with the Vocdoni Open Stack
GNU General Public License v3.0
13 stars 7 forks source link

readme

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

Using providers

Ethers.js providers can connect using different sources.

Example ```javascript 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 ```typescript 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 ```typescript 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 ```typescript 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.