@asoltys/secp256k1-zkp v2.0.4

Secp256k1-zkp

This library is under development, and, like the secp256k1-zkp C library it depends on, this is a research effort to determine an optimal API for end-users of the liquidjs ecosystem.

Installation

Build steps (with Docker)

# Install node dependencies
$ npm install

# Pull the latest secp256k1-zkp as a git submodule
$ git submodule update --init

# This will copy secp256k1-zkp folder along with the main.c wrapper and build with emscripten inside the docker container
$ ./bash scripts/compile_wasm_docker

Bundle for browsers

$ npx browserify lib/index.js --standalone secp256k1 > bundle.browser.js

Test

# lint & prettier & node
$ npm run test
# Only node
$ npm run unit:node
# Only browser
$ npm run unit:web

Usage

Install

$ npm install vulpemventures/secp256k1-zkp
# or with yarn
$ yarn add vulpemventures/secp256k1-zkp

Import

const secp256k1 = require('secp256k1-zkp');

// secp256k1 returns a Promise that must be resolved before using the exported methods
const { rangeproof, surjectionproof } = await secp256k1(); 

rangeproof.rewind(...)
surjectionproof.verify(...)

Documentation

Ecdh

ecdh(pubkey, scalar)

ecdh :: Buffer -> Buffer -> Buffer

Compute an EC Diffie-Hellman secret in constant time.

• pubkey 33-byte representation of a point.
• scalar 32-byte arrayscalar with which to multiply the point.

Generator

generateBlinded(key, blind)

generateBlinded :: Buffer -> Buffer -> Buffer

Generate a blinded generator for the curve.

• key 32-byte seed.
• blind 32-byte secret value to blind the generator with.

parse(input)

parse :: Buffer -> Buffer

Parse a 33-byte generator byte sequence into a 64-byte raw generator.

• input 33-byte serialized generator.

serialzie(generator)

serialize :: Buffer -> Buffer

Serialize a raw generator into a serialized byte sequence.

• generator 64-byte raw generator to serialize.

Pedersen

commit(blindFactor, value)

commit :: Buffer -> String -> Buffer

Generate a pedersen commitment.

• blindFactor 32-byte blinding factor.
• value uint64 value to commit to as string.

commitSerialize(commitment)

commitSerialize :: Buffer -> Buffer

Serialize a raw commitment into a 33-byte serialized byte sequence.

• commitment raw commitment to serialize.

commitParse(input)

commitParse :: Buffer -> Buffer

Parse a 33-byte commitment into a raw commitment.

• input 33-byte serialized commitment key

blindGeneratorBlindSum(values, nInputs, blindGenerators, blindFactors)

blindGeneratorBlindSum :: Array -> Number -> Array -> Array -> Buffer

Set the final Pedersen blinding factor correctly when the generators themselves have blinding factors.

• values array of string asset values.
• nInputs How many of the initial array elements represent commitments that will be negated in the final sum.
• blindGenerators array of asset blinding factors.
• blindFactors array of commitment blinding factors.

blindSum(blinds, nneg=0)

blindSum :: Array [-> Number] -> Buffer

Compute the sum of multiple positive and negative blinding factors.

• blinds array of 32-byte blinding factors.
• nneg how many of the initial factors should be treated with a negative sign.

verifySum(commits, negativeCommits)

verifySum :: Array -> Array -> Bool

Verify a tally of pedersen commitments.

• commits array of 33-byte pedersen commitments
• negativeCommits array of 33-byte pedersen negative commitments

Rangeproof

sign(commit, blind, nonce, value[, minValue="0", base10Exp=0, minBits=0, message=[], extraCommit=[]])

sign :: Buffer -> Buffer -> Buffer -> String [-> String -> Number -> Number -> Buffer -> Buffer] -> Buffer

Author a proof that a committed value is within a range.

• commit 33-byte commitment to being proved.
• blind 32-byte blinding factor used by commit.
• nonce 32-byte secret nonce used to initialize the proof.
• value actual value of the commitment as string.
• minValue constructs a proof where the verifer can tell the minimum value is at least the specified amount (passed as string).
• base10Exp base-10 exponent. Digits below above will be made public, but the proof will be made smaller. Allowed range is -1 to 18.
• minBits number of bits of the value to keep private. (0 = auto/minimal, - 64).
• message data to be embedded in the rangeproof that can be recovered by rewinding the proof.
• extraCommit additional data to be covered in rangeproof signature.

info(proof)

info :: Object -> Object

Extract some basic information from a range-proof.

• proof rangeproof to extract information to.

verify(commit, proof[, extraCommit=[]])

verify :: Buffer -> Object [-> Buffer] -> Bool

Verify a proof that a committed value is within a range.

• commit 33-byte commitments being proved.
• proof rangeproof used to verify commitment.
• extraCommit additional data covered in rangeproof signature.

rewind(commit, proof, nonce[, extraCommit = []])

rewind :: Buffer -> Object -> Buffer [-> Buffer] -> Object

Verify a range proof and rewind the proof to recover information sent by its author.

• commit 33-byte commitment being proved.
• proof rangeproof.
• nonce 32-byte secret nonce used by the prover.
• extraCommit additional data covered in rangeproof signature.

Returns wether the value is within the range [0..2^64), the specifically proven range is in the min/max value outputs, and the value and blinding were recovered.

• value uint64 which has the exact value of the commitment.
• minValue uint64 which will be updated with the minimum value that commit could have.
• maxValue uint64 which will be updated with the maximum value that commit could have.
• blindFactor 32-byte blinding factor used for the commitment.
• message message data from the proof author.

Surjectionproof

serialize(proof)

serialize :: Object -> Buffer

Serialize a surjection proof.

• proof initialized surjection proof.

initialize(inputTags, inputTagsToUse, outputTag, maxIterations, seed)

initialize :: Array -> Number -> Buffer -> Number -> Object

Initialize a surjection proof.

• inputTags fixed input tags A_i for all inputs.
• inputTagsToUse the number of inputs to select randomly to put in the anonymity set.
• outputTag fixed output tag.
• maxIterations the maximum number of iterations to do before giving up.
• seed a random seed to be used for input selection.

generate(proof, inputTags, outputTag, inputIndex, inputBlindingKey, outputBlindingKey)

generate :: Object -> Array -> Buffer -> Number -> Buffer -> Buffer -> Object

Generate an initialized surjection proof.

• proof initialized surjection proof
• inputTags the ephemeral asset tag of all inputs.
• outputTag the ephemeral asset tag of the output.
• inputIndex the index of the input that actually maps to the output.
• inputBlindingKey the blinding key of the input.
• outputBlindingKey the blinding key of the output.

verify(proof, inputTags, outputTag)

verify :: Object -> Array -> Buffer -> Bool

Verify a surjection proof.

• proof surjection proof to be verified.
• inputTags the ephemeral asset tag of all inputs.
• outputTag the ephemeral asset tag of the output.

Credit

This library uses the native library secp256k1-zkp by the Elements Project developers, including derivatives of its tests and test vectors.

LICENSE MIT