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 tagsA_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.