From 946ee8a354b0c2e83082e09227bec4614bbf17a6 Mon Sep 17 00:00:00 2001
From: Anatoly Yakovenko <aeyakovenko@gmail.com>
Date: Tue, 5 Mar 2019 21:24:25 -0800
Subject: [PATCH] Add description of vote and rewards programs

---
 book/src/SUMMARY.md                      |  1 +
 book/src/stake-delegation-and-rewards.md | 63 ++++++++++++++++++++++++
 2 files changed, 64 insertions(+)
 create mode 100644 book/src/stake-delegation-and-rewards.md

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 99ff6f90f1..b00e188bed 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -36,6 +36,7 @@
   - [Ledger Replication](ledger-replication-to-implement.md)
   - [Secure Vote Signing](vote-signing-to-implement.md)
   - [Staking Rewards](staking-rewards.md)
+  - [Staking Delegation and Rewards](stake-delegation-and-rewards.md)
   - [Fork Selection](fork-selection.md)
   - [Reliable Vote Transmission](reliable-vote-transmission.md)
   - [Bank Forks](bank-forks.md)
diff --git a/book/src/stake-delegation-and-rewards.md b/book/src/stake-delegation-and-rewards.md
new file mode 100644
index 0000000000..b6e015f378
--- /dev/null
+++ b/book/src/stake-delegation-and-rewards.md
@@ -0,0 +1,63 @@
+# Stake Delegation and Reward
+
+This design covers the current architecture to how stakes are delegated to
+validators.  This design focuses on the software architecture for the actual
+on-chain programs.  Incentives for staking is covered in [staking
+rewardsd](staking-rewards.md).
+
+The main problem this proposal is solving is to allow many delegated stakes to
+generate rewards with a single validator vote without permission from the
+validator.
+
+## Terminology
+
+* VoteState - Instance of the vote program.  This program keeps track of
+validator votes.
+
+* RewardState - Instance of the reward state program.  This program pays out
+rewards for votes to the staker.
+
+* Staker - The lamport owner that is risking lamports with consensus votes in
+exchange for network rewards.
+
+* Delegate - The validator that is submitting votes on behave of the staker.
+
+## Current Architecture
+
+VoteState contains the following state information:
+
+* votes - The submitted votes.
+
+* `delegate_id` - The delegated stake identity.  This identity can submit votes
+as well.
+
+* `credits` - The amount of unclaimed rewards.
+
+* `root_slot` - The last slot to reach the full lockout commitment necessary for
+rewards.
+
+Reward program is stateless, and pays out the reward when that reward is
+claimed.  Claim the reward requires a transaction that includes the following
+instructions:
+
+1. RewardsInstruction::RedeemVoteCredits
+
+2. VoteInstruction::ClearCredits
+
+The payout of the rewards transfers lamports from the rewards program to the
+VoteState address. It ensures that VoteState clears its credits in the next
+instruction.
+
+### VoteInstruction::DelegateStake(Pubkey)
+
+This instruction assigns the delegate\_id to the supplied Pubkey.  The
+delegation allows the delegate\_id to submit votes on behalf of the vote
+program.
+
+## Validator work flow.
+
+A validator that has been delegated N stakes needs to submit N votes, and the
+validator must submit each vote, for each of the delegated state to earn a
+reward.  We expect each validator to vote once per block, and for there to be
+much more delegated stakes in number then validators.  With the current design,
+each delegated stake requires an independent vote.