Crate dusk_blindbid[−][src]

Expand description

Build Status Repository Documentation

Contents

This library provides the structures and the logic that the blind bid protocol requires in order to work. Contains the most important structures: Bid and Score.

This means we can do things like:

use dusk_blindbid::{Bid, Score, V_RAW_MIN, V_RAW_MAX};
use dusk_bls12_381::BlsScalar;
use dusk_pki::{PublicSpendKey, SecretSpendKey};
use dusk_jubjub::{JubJubScalar, JubJubAffine, GENERATOR_EXTENDED};
use phoenix_core::Message;
use rand::{Rng, thread_rng};

// Generate a Bid from some fields we have.
let mut rng = rand::thread_rng();
let psk = PublicSpendKey::from(SecretSpendKey::new(
    JubJubScalar::one(),
    -JubJubScalar::one(),
));
let secret_k = BlsScalar::one();
let secret = JubJubScalar::one();
let value: u64 =
    (&mut rand::thread_rng()).gen_range(V_RAW_MIN..V_RAW_MAX);
// Set the timestamps as the max values so the proofs do not fail
// for them (never expired or non-elegible).
let elegibility_ts = u64::MAX;
let expiration_ts = u64::MAX;

let bid = Bid::new(
    Message::new(&mut rng, &secret, &psk, value),
    secret_k,
    psk.gen_stealth_address(&secret),
    elegibility_ts,
    expiration_ts,
);

let poseidon_tree_root = BlsScalar::random(&mut thread_rng());

// Generate fields for the Bid & required by the compute_score
let consensus_round_seed = BlsScalar::random(&mut thread_rng());
let latest_consensus_round = 50u64;
let latest_consensus_step = 50u64;

// Generate a ProverID attached to the `Bid`.
let prover_id = bid.generate_prover_id(
    secret_k,
    BlsScalar::from(consensus_round_seed),
    BlsScalar::from(latest_consensus_round),
    BlsScalar::from(latest_consensus_step),
);

// The next step is only doable if `std` feature is enabled.

// Generate a `Score` for our Bid with the consensus parameters
#[cfg(feature = "std")]
 let score = Score::compute(
     &bid,
     &secret,
     &psk,
     secret_k,
     poseidon_tree_root,
     consensus_round_seed,
     latest_consensus_round,
     latest_consensus_step,
 ).expect("Score generation error");

Rationale & Theory

In order to participate in the SBA consensus, Block generators have to submit a bid in DUSK. As long as their bid is active - and their full-node is connected with the internet and running- they are participating in the consensus rounds. Essentially, every time a consensus round is run, the Block Generator software generates a comprehensive zero-knowledge proof, and executes various steps in order to generate a valid candidate block, and compete with the other Block Generators for a chance to become the winner of the consensus round.

Below we describe the three main processes that happen every consensus round. Please note that 1 and 2 are run as part of the same algorithm.

1: Score generation.

Block Generators obtain a score from a lottery by executing the Score Generation Function. The score is positively influenced by the amount of DUSK that the Block Generator bids. In other words, the higher the bid, the better the chance to generate a high score. This is important to guarantee Sybil attack protection.

Without this link a bad actor could subvert the reputation system by creating multiple identities. Also note: there are minimum and maximum thresholds that determine the minimum and maximum size of the bid.

2. Proof of Blind-Bid Generation.

In general computing science, a circuit is a computational model through which input values proceed through a sequence of gates, each of which computes a specific function. In our case, the circuits perform the logical checks with public and private inputs to make sure that the generated Blind Bid proofs are generated by the rules of the game. For explanatory reasons, we define two circuits although in practice, these two are a collection of gadgets added up together in order to compose the BlindBidCircuit.

For further information regarding the circuits, please check the blindbid-circuits crate

3. Propagation.

During each consensus round, the Block Generator checks the score that he produced, and verifies whether it is greater than the minimum score threshold. If it is indeed greater, then the Block Generator generates the aforementioned proofs and propagates the score obtained, the zero-knowledge proof computed and various other elements alongside the Block Candidate to his peers in the network. The Block Generator that computed the highest score is considered to be the leader of the current iteration of the consensus.

Documentation

The best usage example of this library can actually be found in the Bid contract. This is the place where this lib provides all it’s functionallities together with PoseidonTrees and Zero Knowledge Proofs. See: <https://github.com/dusk-network/rusk/tree/master/contracts/bid for more info and detail.>

You can also check the documentation of this crate here.

Licensing

This code is licensed under Mozilla Public License Version 2.0 (MPL-2.0). Please see LICENSE for further info.

About

Protocol & Implementation designed by the dusk team.

Contributing

  • If you want to contribute to this repository/project please, check CONTRIBUTING.md
  • If you want to report a bug or request a new feature addition, please open an issue on this repository.

Structs

Bid

The Bid structure contains all of the logic and information needed to be able to participate in the Dusk consensus lottery through the bidding process. It allows the user to generate a random Bid with which will be able to generate a Score and participate in leader election process for this consensus round iteration. In particular, a Bid provides these core functionalities among others.

Score

The Score represents a “random” value obtained from the computations based on blockchain data as well as Bid data. It derefs to it’s value although the structure contains more fields which are side-results of this computation needed to proof the correctness of the Score generation process later on.

Enums

BlindBidError

Compilation of the erros that blindbid procedures might end up producing.

Constants

BID_HASHING_TYPE_FIELDS

Following the guidelines for Poseidon Hashing proving statements generation given in https://hackmd.io/@7dpNYqjKQGeYC7wMlPxHtQ/BkfS78Y9L, we export the field types const which will be needed by the gadgets that want to implement the hash of a Bid inside of a Circuit.

V_RAW_MAX

The maximum amount of Dusk an user is permitted to bid.

V_RAW_MIN

The minimum amount of Dusk an user is permitted to bid.