You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
p4u a4d8b87d93 Census Service refactory 5 years ago
..
README.md Census Service refactory 5 years ago
censushttp.go Change references to go-dvote 5 years ago

README.md

Census HTTP service

Reference implementation of a voting census service running on the Vocdoni platform

Compile

In a GO ready environment:

go get -u github.com/vocdoni/dvote-census/...
go build -o censusHttpService github.com/vocdoni/dvote-census/cmd/censushttp

Usage

./censusHttpService <port> <censusId>[:pubKey] [<censusId>[:pubKey] ...]

Example

./censusHttpService 1500 Got_Favorite
2019/02/12 10:20:16 Starting process HTTP service on port 1500 for namespace GoT_Favorite
2019/02/12 10:20:16 Starting server in http mode

API

A HTTP jSON endpoint is available with the following possible fields: method censusId, claimData, rootHash and proofData.

If pubKey has been configured for a specific censusId, then two more methods are available (timeStamp and signature) to provide authentication.

The next table shows the available methods and its relation with the fields.

method censusId claimData rootHash proofData protected? description
addClaim mandatory mandatory none none yes adds a new claim to the merkle tree
getRoot mandatory none none none no get the current merkletree root hash
genProof mandatory mandatory optional none no generate the merkle proof for a given claim
checkProof mandatory mandatory optional mandatory no check a claim and its merkle proof
getIdx mandatory mandatory optional none no get the merkletree data index of a given claim
dump mandatory none optional none yes list the contents of the census for a given hash

Signature

The signature provides authentication by signing a concatenation of the following strings (even if empty) without spaces: censusId rootHash claimData timeStamp.

The timeStamp when received on the server side must not differ more than 10 seconds from the current UNIX time.

Examples

add claims

Add two new claims, one for Jon Snow and another for Tyrion.

curl -d '{"method":"addClaim","censusID":"GoT_Favorite","claimData":"Jon Snow"}' http://localhost:1500

{"error":false,"response":""}
curl -d '{"method":"addClaim","censusID":"GoT_Favorite","claimData":"Tyrion"}' http://localhost:1500

{"error":false,"response":""}

In case signature is enabled:

curl -d '{
"method":"addClaim",
"censusID":"GoT_Favorite",
"claimData":"Jon Snow", 
"timeStamp":"1547814675",
"signature":"a117c4ce12b29090884112ffe57e664f007e7ef142a1679996e2d34fd2b852fe76966e47932f1e9d3a54610d0f361383afe2d9aab096e15d136c236abb0a0d0e" }' http://localhost:1500

{"error":false,"response":""}

generate proof

Generate a merkle proof for the claim Jon Snow

curl -d '{"method":"genProof","censusID":"GoT_Favorite","claimData":"Jon Snow"}' http://localhost:1500

{"error":false,"response":"0x000200000000000000000000000000000000000000000000000000000000000212f8134039730791388a9bd0460f9fbd0757327212a64b3a2b0f0841ce561ee3"}

If rootHash is specified, the proof will be calculated for the given root hash.

get root

The previous merkle proof is valid only for the current root hash. Let's get it

curl -d '{"method":"getRoot","censusID":"GoT_Favorite"}' http://localhost:1500

{"error":false,"response":"0x2f0ddde5cb995eae23dc3b75a5c0333f1cc89b73f3a00b0fe71996fb90fef04b"}

check proof

Now let's check if the proof is valid

curl -d '{
"method":"checkProof",
"censusID":"GoT_Favorite","claimData":"Jon Snow",
"rootHash":"0x2f0ddde5cb995eae23dc3b75a5c0333f1cc89b73f3a00b0fe71996fb90fef04b",
"proofData":"0x000200000000000000000000000000000000000000000000000000000000000212f8134039730791388a9bd0460f9fbd0757327212a64b3a2b0f0841ce561ee3"}' http://localhost:1500

{"error":false,"response":"valid"}

If rootHash is not specified, the current root hash is used.

dump

Dump contents of a specific censusId (values)

curl -d '{"method":"dump","censusID":"GoT_Favorite"}' http://localhost:1500

{"error":false,"response":"[\"Tyrion\",\"Jon Snow\"]"}

If rootHash is specified, dump will return the values for the merkle tree with the given root hash.