darkfi/doc/src/arch/consensus/unstake_request.md

Unstake request

The Consensus::UnstakeRequest function is used when a consensus participant wants to exit participation and plans to unstake their staked coin. What the user is essentially doing here is burning their coin they have been using for consensus participation, and minting a new coin that isn't able to compete anymore, and is timelocked for a predefined amount of time. This new coin then has to wait until the timelock is expired, and then it can be used in the Unstake function in order to be redeemed back into the Money state.

The parameters to execute this function are 1 anonymous input and 1 anonymous output:

{{#include ../../../../src/contract/consensus/src/model.rs:ConsensusUnstakeRequestParams}}

In this function, we have two ZK proofs, ConsensusBurn_V1 and ConsensusMint_V1:

{{#include ../../../../src/contract/consensus/proof/consensus_burn_v1.zk}}

{{#include ../../../../src/contract/consensus/proof/consensus_mint_v1.zk}}

Contract logic

get_metadata()

In the consensus_unstake_request_get_metadata_v1 function, we gather the public inputs necessary to verify the given ZK proofs. It's pretty straightforward, and more or less the same as other get_metadata functions in this smart contract.

process_instruction()

We perform the state transition in consensus_unstake_request_process_instruction_v1. We enforce that:

• The timelock of the burned coin has passed and the coin is eligible for unstaking
• The Merkle inclusion proof of the burned coin is valid
• The revealed nullifier of the burned coin has not been seen before
• The input and output value commitments are the same
• The output/minted coin has not been seen before

When this is done, and everything passes, we create a state update with the burned nullifier and the minted coin. Here we use the same parameters like we do in Proposal - a nullifier and a coin:

{{#include ../../../../src/contract/consensus/src/model.rs:ConsensusProposalUpdate}}

process_update()

For the state update, we use the consensus_unstake_request_process_update_v1 function. This takes the state update produced by consensus_unstake_request_process_instruction_v1. With it, we append the revealed nullifier to the set of seen nullifiers. The minted coin, in this case however, does not get added to the Merkle tree of staked coins. Instead, we add it to the Merkle tree of unstaked coins where it lives in a separate state. By doing this, we essentially disallow the new coin to compete in consensus again because in that state it does not exist. It only exists in the unstaked state, and as such can only be operated with other functions that actually read from this state - namely Unstake