darkfi/doc/src/arch/tx_lifetime.md

Transactions

(Temporary document, to be integrated into other docs)

Transaction behaviour

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

1. Miner (M)
2. 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 $tx$ in their mempool for some period of time, and then prune it.

Ideal simulation with instant finality

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

1. User creates a transaction $tx$
2. User broadcasts $tx$ to S
3. S validates $tx$ state transition
4. $tx$ enters S mempool
5. S broadcasts $tx$ to M
6. M validates $tx$ state transition
7. $tx$ enters M mempool
8. M validates all transactions in its mempool in sequence
9. M proposes a block finalization containing $tx$
10. M writes the state transition update of $tx$ to their chain
11. M removes $tx$ from their mempool
12. M broadcasts the finalized proposal
13. S receives the proposal and validates transactions
14. S writes the state updates to their chain
15. S removes $tx$ from their mempool

Real-world simulation with non-instant finality

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

1. User creates a transaction $tx$
2. User broadcasts $tx$ to S
3. S validates $tx$ state transition
4. $tx$ enters S mempool
5. S broadcasts $tx$ to M
6. M validates $tx$ state transition
7. $tx$ enters M mempool
8. M proposes a block proposal containing $tx$
9. M proposes more block proposals
10. When proposals can be finalized, M validates all their transactions in sequence
11. M writes the state transition update of $tx$ to their chain
12. M removes $tx$ from their mempool
13. M broadcasts the finalized proposals sequence
14. S receives the proposals sequence and validates transactions
15. S writes the state updates to their chain
16. S removes $tx$ from their mempool

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

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

1. User creates a transaction $tx$
2. User broadcasts $tx$ to S
3. S validates $tx$ state transition against canonical chain state
4. $tx$ enters S mempool
5. S broadcasts $tx$ to P
6. M validates $tx$ state transition against all known fork states
7. $tx$ enters M mempool
8. M broadcasts $tx$ to rest M nodes
9. Block producer SM finds which fork to extend
10. SM validates all unproposed transactions in its mempool in sequence, against extended fork state, discarding invalid
11. SM creates a block proposal containing $tx$ extending the fork
12. M receives block proposal and validates its transactions against the extended fork state
13. SM proposes more block proposals extending a fork state
14. When a fork can be finalized, M validates all its proposals transactions in sequence, against canonical state
15. M writes the state transition update of $tx$ to their chain
16. M removes $tx$ from their mempool
17. M drop rest forks and keeps only the finalized one
18. M broadcasts the finalized proposals sequence
19. S receives the proposals sequence and validates transactions
20. S writes the state updates to their chain
21. S removes $tx$ from their mempool

M will keep $tx$ 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 $tx$ 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.