Transactions

(Temporary document, to be integrated into other docs)

Transaction behaviour

In our network context, we have two types of nodes.

Miner (M)
Spectator (S)

S acts as a relayer for transactions in order to help out that transactions reach M.

To avoid spam attacks, S should keep $t x$ in their mempool for some period of time, and then prune it.

Ideal simulation with instant finality

The lifetime of a transaction $t x$ that passes verification and whose state transition can be applied on top of the finalized (canonical) chain:

User creates a transaction $t x$
User broadcasts $t x$ to S
S validates $t x$ state transition
$t x$ enters S mempool
S broadcasts $t x$ to M
M validates $t x$ state transition
$t x$ enters M mempool
M validates all transactions in its mempool in sequence
M proposes a block finalization containing $t x$
M writes the state transition update of $t x$ to their chain
M removes $t x$ from their mempool
M broadcasts the finalized proposal
S receives the proposal and validates transactions
S writes the state updates to their chain
S removes $t x$ from their mempool

Real-world simulation with non-instant finality

The lifetime of a transaction $t x$ that passes verification and whose state transition is pending to be applied on top of the finalized (canonical) chain:

User creates a transaction $t x$
User broadcasts $t x$ to S
S validates $t x$ state transition
$t x$ enters S mempool
S broadcasts $t x$ to M
M validates $t x$ state transition
$t x$ enters M mempool
M proposes a block proposal containing $t x$
M proposes more block proposals
When proposals can be finalized, M validates all their transactions in sequence
M writes the state transition update of $t x$ to their chain
M removes $t x$ from their mempool
M broadcasts the finalized proposals sequence
S receives the proposals sequence and validates transactions
S writes the state updates to their chain
S removes $t x$ from their mempool

Real-world simulation with non-instant finality, forks and multiple `CP` nodes

The lifetime of a transaction $t x$ that passes verifications and whose state transition is pending to be applied on top of the finalized (canonical) chain:

User creates a transaction $t x$
User broadcasts $t x$ to S
S validates $t x$ state transition against canonical chain state
$t x$ enters S mempool
S broadcasts $t x$ to P
M validates $t x$ state transition against all known fork states
$t x$ enters M mempool
M broadcasts $t x$ to rest M nodes
Block producer SM finds which fork to extend
SM validates all unproposed transactions in its mempool in sequence, against extended fork state, discarding invalid
SM creates a block proposal containing $t x$ extending the fork
M receives block proposal and validates its transactions against the extended fork state
SM proposes more block proposals extending a fork state
When a fork can be finalized, M validates all its proposals transactions in sequence, against canonical state
M writes the state transition update of $t x$ to their chain
M removes $t x$ from their mempool
M drop rest forks and keeps only the finalized one
M broadcasts the finalized proposals sequence
S receives the proposals sequence and validates transactions
S writes the state updates to their chain
S removes $t x$ from their mempool

M will keep $t x$ in its mempool as long as it is a valid state transition for any fork(including canonical) or it get finalized.

Unproposed transactions refers to all $t x$ not included in a proposal of any fork.

If a fork that can be finalized fails to validate all its transactions(14), it should be dropped.

The `Transaction` object

pub struct ContractCall {
    /// The contract ID to which the payload is fed to
    pub contract_id: ContractId,
    /// Arbitrary payload for the contract call
    pub payload: Vec<u8>,
}

pub struct Transaction {
    /// Calls executed in this transaction
    pub calls: Vec<ContractCall>,
    /// Attached ZK proofs
    pub proofs: Vec<Vec<Proof>>,
    /// Attached Schnorr signatures
    pub signatures: Vec<Vec<Signature>>,
}

A generic DarkFi transaction object is simply an array of smart contract calls, along with attached ZK proofs and signatures needed to properly verify the contracts' execution. A transaction can have any number of calls, and proofs, provided it does not exhaust a set gas limit.

In DarkFi, every operation is a smart contract. This includes payments, which we'll explain in the following section.

Payments

For A -> B payments in DarkFi we use the Sapling scheme that originates from zcash. A payment transaction has a number of inputs (which are coins being burned/spent), and a number of outputs (which are coins being minted/created). An explanation for the ZK proofs for this scheme can be found in the Zkas section of this book, under Sapling.

In code, the structs we use are the following:

pub struct MoneyTransferParams {
    pub inputs: Vec<Input>,
    pub outputs: Vec<Output>,
}

pub struct Input {
    /// Pedersen commitment for the input's value
    pub value_commit: ValueCommit,
    /// Pedersen commitment for the input's token ID
    pub token_commit: ValueCommit,
    /// Revealed nullifier
    pub nullifier: Nullifier,
    /// Revealed Merkle root
    pub merkle_root: MerkleNode,
    /// Public key for the Schnorr signature
    pub signature_public: PublicKey,
}

pub struct Output {
    /// Pedersen commitment for the output's value
    pub value_commit: ValueCommit,
    /// Pedersen commitment for the output's token ID
    pub token_commit: ValueCommit,
    /// Minted coin: poseidon_hash(pubkey, value, token, serial, blind)
    pub coin: Coin,
    /// The encrypted note ciphertext
    pub encrypted_note: EncryptedNote,
}

pub struct EncryptedNote {
    pub ciphertext: Vec<u8>,
    pub ephemeral_key: PublicKey,
}

pub struct Note {
    /// Serial number of the coin, used to derive the nullifier
    pub serial: pallas::Base,
    /// Value of the coin
    pub value: u64,
    /// Token ID of the coin
    pub token_id: TokenId,
    /// Blinding factor for the value Pedersen commitment
    pub value_blind: ValueBlind,
    /// Blinding factor for the token ID Pedersen commitment
    pub token_blind: ValueBlind,
    /// Attached memo (arbitrary data)
    pub memo: Vec<u8>,
}

In the blockchain state, every minted coin must be added into a Merkle tree of all existing coins. Once added, the new tree root is used to prove existence of this coin when it's being spent.

Let's imagine a scenario where Alice has 100 ALICE tokens and wants to send them to Bob. Alice would create an Input object using the info she has of her coin. She has to derive a nullifier given her secret key and the serial number of the coin, hash the coin bulla so she can create a merkle path proof, and derive the value and token commitments using the blinds.

let nullifier = poseidon_hash([alice_secret_key, serial]);
let signature_public = alice_secret_key * Generator;
let coin = poseidon_hash([signature_public, value, token_id, blind]);
let merkle_root = calculate_merkle_root(coin);
let value_commit = pedersen_commitment(value, value_blind);
let token_commit = pedersen_commitment(token_id, token_blind);

The values above, except coin become the public inputs for the Burn ZK proof. If everything is correct, this allows Alice to spend her coin. In DarkFi, the changes have to be atomic, so any payment transaction that is burning some coins, has to mint new coins at the same time, and no value must be lost, nor can the token ID change. We enforce this by using Pedersen commitments.

Now that Alice has a valid Burn proof and can spend her coin, she can mint a new coin for Bob.

let blind = pallas::Base::random();
let value_blind = ValueBlind::random();
let token_blind = ValueBlind::random();
let coin = poseidon_hash([bob_public, value, token_id, blind]);
let value_commit = pedersen_commitment(value, value_blind);
let token_commit = pedersen_commitment(token, token_blind);

coin, value_commit, and token_commit become the public inputs for the Mint ZK proof. If this proof is valid, it creates a new coin for Bob with the given parameters. Additionally, Alice would put the values and blinds in a Note which is encrypted with Bob's public key so only Bob is able to decrypt it. This Note has the necessary info for him to further spend the coin he received.

At this point Alice should have 1 input and 1 output. The input is the coin she burned, and the output is the coin she minted for Bob. Along with this, she has two ZK proofs that prove creation of the input and output. Now she can build a transaction object, and then use her secret key she derived in the Burn proof to sign the transaction and publish it to the blockchain.

The blockchain will execute the smart contract with the given payload and verify that the Pedersen commitments match, that the nullifier has not been published before, and also that the merkle authentication path is valid and therefore the coin existed in a previous state. Outside of the VM, the validator will also verify the signature(s) and the ZK proofs. If this is valid, then Alice's coin is now burned and cannot be used anymore. And since Alice also created an output for Bob, this new coin is now added to the Merkle tree and is able to be spent by him. Effectively this means that Alice has sent her tokens to Bob.

The DarkFi Book