solana-docs 0.0.0

package/src/implemented-proposals/repair-service.md

@@ -0,0 +1,108 @@
+---
+title: Repair Service
+---
+
+## Repair Service
+
+The RepairService is in charge of retrieving missing shreds that failed to be
+delivered by primary communication protocols like Turbine. It is in charge of
+managing the protocols described below in the `Repair Protocols` section below.
+
+## Challenges:
+
+1\) Validators can fail to receive particular shreds due to network failures
+
+2\) Consider a scenario where blockstore contains the set of slots {1, 3, 5}.
+Then Blockstore receives shreds for some slot 7, where for each of the shreds
+b, b.parent == 6, so then the parent-child relation 6 -> 7 is stored in
+blockstore. However, there is no way to chain these slots to any of the
+existing banks in Blockstore, and thus the `Shred Repair` protocol will not
+repair these slots. If these slots happen to be part of the main chain, this
+will halt replay progress on this node.
+
+## Repair-related primitives
+
+Epoch Slots:
+Each validator advertises separately on gossip the various parts of an
+`Epoch Slots`:
+
+- The `stash`: An epoch-long compressed set of all completed slots.
+- The `cache`: The Run-length Encoding (RLE) of the latest `N` completed
+  slots starting from some some slot `M`, where `N` is the number of slots
+  that will fit in an MTU-sized packet.
+
+`Epoch Slots` in gossip are updated every time a validator receives a
+complete slot within the epoch. Completed slots are detected by blockstore
+and sent over a channel to RepairService. It is important to note that we
+know that by the time a slot `X` is complete, the epoch schedule must exist
+for the epoch that contains slot `X` because WindowService will reject
+shreds for unconfirmed epochs.
+
+Every `N/2` completed slots, the oldest `N/2` slots are moved from the
+`cache` into the `stash`. The base value `M` for the RLE should also
+be updated.
+
+## Repair Request Protocols
+
+The repair protocol makes best attempts to progress the forking structure of
+Blockstore.
+
+The different protocol strategies to address the above challenges:
+
+1. Shred Repair \(Addresses Challenge \#1\): This is the most basic repair
+   protocol, with the purpose of detecting and filling "holes" in the ledger.
+   Blockstore tracks the latest root slot. RepairService will then periodically
+   iterate every fork in blockstore starting from the root slot, sending repair
+   requests to validators for any missing shreds. It will send at most some `N`
+   repair reqeusts per iteration. Shred repair should prioritize repairing
+   forks based on the leader's fork weight. Validators should only send repair
+   requests to validators who have marked that slot as completed in their
+   EpochSlots. Validators should prioritize repairing shreds in each slot
+   that they are responsible for retransmitting through turbine. Validators can
+   compute which shreds they are responsible for retransmitting because the
+   seed for turbine is based on leader id, slot, and shred index.
+
+   Note: Validators will only accept shreds within the current verifiable
+   epoch \(epoch the validator has a leader schedule for\).
+
+2. Preemptive Slot Repair \(Addresses Challenge \#2\): The goal of this
+   protocol is to discover the chaining relationship of "orphan" slots that do not
+   currently chain to any known fork. Shred repair should prioritize repairing
+   orphan slots based on the leader's fork weight.
+
+   - Blockstore will track the set of "orphan" slots in a separate column family.
+   - RepairService will periodically make `Orphan` requests for each of
+     the orphans in blockstore.
+
+     `Orphan(orphan)` request - `orphan` is the orphan slot that the
+     requestor wants to know the parents of `Orphan(orphan)` response -
+     The highest shreds for each of the first `N` parents of the requested
+     `orphan`
+
+     On receiving the responses `p`, where `p` is some shred in a parent slot,
+     validators will:
+
+     - Insert an empty `SlotMeta` in blockstore for `p.slot` if it doesn't
+       already exist.
+     - If `p.slot` does exist, update the parent of `p` based on `parents`
+
+     Note: that once these empty slots are added to blockstore, the
+     `Shred Repair` protocol should attempt to fill those slots.
+
+     Note: Validators will only accept responses containing shreds within the
+     current verifiable epoch \(epoch the validator has a leader schedule
+     for\).
+
+Validators should try to send orphan requests to validators who have marked that
+orphan as completed in their EpochSlots. If no such validators exist, then
+randomly select a validator in a stake-weighted fashion.
+
+## Repair Response Protocol
+
+When a validator receives a request for a shred `S`, they respond with the
+shred if they have it.
+
+When a validator receives a shred through a repair response, they check
+`EpochSlots` to see if <= `1/3` of the network has marked this slot as
+completed. If so, they resubmit this shred through its associated turbine
+path, but only if this validator has not retransmitted this shred before.

package/src/implemented-proposals/rpc-transaction-history.md

@@ -0,0 +1,107 @@
+# Long term RPC Transaction History
+
+There's a need for RPC to serve at least 6 months of transaction history. The
+current history, on the order of days, is insufficient for downstream users.
+
+6 months of transaction data cannot be stored practically in a validator's
+rocksdb ledger so an external data store is necessary. The validator's
+rocksdb ledger will continue to serve as the primary data source, and then will
+fall back to the external data store.
+
+The affected RPC endpoints are:
+
+- [getFirstAvailableBlock](developing/clients/jsonrpc-api.md#getfirstavailableblock)
+- [getConfirmedBlock](developing/clients/jsonrpc-api.md#getconfirmedblock)
+- [getConfirmedBlocks](developing/clients/jsonrpc-api.md#getconfirmedblocks)
+- [getConfirmedSignaturesForAddress](developing/clients/jsonrpc-api.md#getconfirmedsignaturesforaddress)
+- [getConfirmedTransaction](developing/clients/jsonrpc-api.md#getconfirmedtransaction)
+- [getSignatureStatuses](developing/clients/jsonrpc-api.md#getsignaturestatuses)
+- [getBlockTime](developing/clients/jsonrpc-api.md#getblocktime)
+
+Some system design constraints:
+
+- The volume of data to store and search can quickly jump into the terabytes,
+  and is immutable.
+- The system should be as light as possible for SREs. For example an SQL
+  database cluster that requires an SRE to continually monitor and rebalance
+  nodes is undesirable.
+- Data must be searchable in real time - batched queries that take minutes or
+  hours to run are unacceptable.
+- Easy to replicate the data worldwide to co-locate it with the RPC endpoints
+  that will utilize it.
+- Interfacing with the external data store should be easy and not require
+  depending on risky lightly-used community-supported code libraries
+
+Based on these constraints, Google's BigTable product is selected as the data
+store.
+
+## Table Schema
+
+A BigTable instance is used to hold all transaction data, broken up into
+different tables for quick searching.
+
+New data may be copied into the instance at anytime without affecting the existing
+data, and all data is immutable. Generally the expectation is that new data
+will be uploaded once an current epoch completes but there is no limitation on
+the frequency of data dumps.
+
+Cleanup of old data is automatic by configuring the data retention policy of the
+instance tables appropriately, it just disappears. Therefore the order of when data is
+added becomes important. For example if data from epoch N-1 is added after data
+from epoch N, the older epoch data will outlive the newer data. However beyond
+producing _holes_ in query results, this kind of unordered deletion will
+have no ill effect. Note that this method of cleanup effectively allows for an
+unlimited amount of transaction data to be stored, restricted only by the
+monetary costs of doing so.
+
+The table layout s supports the existing RPC endpoints only. New RPC endpoints
+in the future may require additions to the schema and potentially iterating over
+all transactions to build up the necessary metadata.
+
+## Accessing BigTable
+
+BigTable has a gRPC endpoint that can be accessed using the
+[tonic](https://crates.io/crates/crate)] and the raw protobuf API, as currently no
+higher-level Rust crate for BigTable exists. Practically this makes parsing the
+results of BigTable queries more complicated but is not a significant issue.
+
+## Data Population
+
+The ongoing population of instance data will occur on an epoch cadence through the
+use of a new `solana-ledger-tool` command that will convert rocksdb data for a
+given slot range into the instance schema.
+
+The same process will be run once, manually, to backfill the existing ledger
+data.
+
+### Block Table: `block`
+
+This table contains the compressed block data for a given slot.
+
+The row key is generated by taking the 16 digit lower case hexadecimal
+representation of the slot, to ensure that the oldest slot with a confirmed
+block will always be first when the rows are listed. eg, The row key for slot
+42 would be 000000000000002a.
+
+The row data is a compressed `StoredConfirmedBlock` struct.
+
+### Account Address Transaction Signature Lookup Table: `tx-by-addr`
+
+This table contains the transactions that affect a given address.
+
+The row key is `<base58 address>/<slot-id-one's-compliment-hex-slot-0-prefixed-to-16-digits>`. The row
+data is a compressed `TransactionByAddrInfo` struct.
+
+Taking the one's compliment of the slot allows for listing of slots ensures that
+the newest slot with transactions that affect an address will always
+be listed first.
+
+Sysvar addresses are not indexed. However frequently used programs such as
+Vote or System are, and will likely have a row for every confirmed slot.
+
+### Transaction Signature Lookup Table: `tx`
+
+This table maps a transaction signature to its confirmed block, and index within that block.
+
+The row key is the base58-encoded transaction signature.
+The row data is a compressed `TransactionInfo` struct.

package/src/implemented-proposals/snapshot-verification.md

@@ -0,0 +1,56 @@
+---
+title: Snapshot Verification
+---
+
+## Problem
+
+When a validator boots up from a snapshot, it needs a way to verify the account set matches what the rest of the network sees quickly. A potential
+attacker could give the validator an incorrect state, and then try to convince it to accept a transaction that would otherwise be rejected.
+
+## Solution
+
+Currently the bank hash is derived from hashing the delta state of the accounts in a slot which is then combined with the previous bank hash value.
+The problem with this is that the list of hashes will grow on the order of the number of slots processed by the chain and become a burden to both
+transmit and verify successfully.
+
+Another naive method could be to create a merkle tree of the account state. This has the downside that with each account update, the merkle tree
+would have to be recomputed from the entire account state of all live accounts in the system.
+
+To verify the snapshot, we do the following:
+
+On account store of non-zero lamport accounts, we hash the following data:
+
+- Account owner
+- Account data
+- Account pubkey
+- Account lamports balance
+- Fork the account is stored on
+
+Use this resulting hash value as input to an expansion function which expands the hash value into an image value.
+The function will create a 440 byte block of data where the first 32 bytes are the hash value, and the next 440 - 32 bytes are
+generated from a Chacha RNG with the hash as the seed.
+
+The account images are then combined with xor. The previous account value will be xored into the state and the new account value also xored into the state.
+
+Voting and sysvar hash values occur with the hash of the resulting full image value.
+
+On validator boot, when it loads from a snapshot, it would verify the hash value with the accounts set. It would then
+use SPV to display the percentage of the network that voted for the hash value given.
+
+The resulting value can be verified by a validator to be the result of xoring all current account states together.
+
+A snapshot must be purged of zero lamport accounts before creation and during verify since the zero lamport accounts do not affect the hash value but may cause
+a validator bank to read that an account is not present when it really should be.
+
+An attack on the xor state could be made to influence its value:
+
+Thus the 440 byte image size comes from this paper, avoiding xor collision with 0 \(or thus any other given bit pattern\): \[[https://link.springer.com/content/pdf/10.1007%2F3-540-45708-9_19.pdf](https://link.springer.com/content/pdf/10.1007%2F3-540-45708-9_19.pdf)\]
+
+The math provides 128 bit security in this case:
+
+```text
+O(k * 2^(n/(1+lg(k)))
+k=2^40 accounts
+n=440
+2^(40) * 2^(448 * 8 / 41) ~= O(2^(128))
+```

package/src/implemented-proposals/staking-rewards.md

@@ -0,0 +1,33 @@
+---
+title: Staking Rewards
+---
+
+A Proof of Stake \(PoS\), \(i.e. using in-protocol asset, SOL, to provide secure consensus\) design is outlined here. Solana implements a proof of stake reward/security scheme for validator nodes in the cluster. The purpose is threefold:
+
+- Align validator incentives with that of the greater cluster through skin-in-the-game deposits at risk
+
+- Avoid 'nothing at stake' fork voting issues by implementing slashing rules aimed at promoting fork convergence
+
+- Provide an avenue for validator rewards provided as a function of validator participation in the cluster.
+
+While many of the details of the specific implementation are currently under consideration and are expected to come into focus through specific modeling studies and parameter exploration on the Solana testnet, we outline here our current thinking on the main components of the PoS system. Much of this thinking is based on the current status of Casper FFG, with optimizations and specific attributes to be modified as is allowed by Solana's Proof of History \(PoH\) blockchain data structure.
+
+## General Overview
+
+Solana's ledger validation design is based on a rotating, stake-weighted selected leader broadcasting transactions in a PoH data structure to validating nodes. These nodes, upon receiving the leader's broadcast, have the opportunity to vote on the current state and PoH height by signing a transaction into the PoH stream.
+
+To become a Solana validator, one must deposit/lock-up some amount of SOL in a contract. This SOL will not be accessible for a specific time period. The precise duration of the staking lockup period has not been determined. However we can consider three phases of this time for which specific parameters will be necessary:
+
+- _Warm-up period_: which SOL is deposited and inaccessible to the node, however PoH transaction validation has not begun. Most likely on the order of days to weeks
+
+- _Validation period_: a minimum duration for which the deposited SOL will be inaccessible, at risk of slashing \(see slashing rules below\) and earning rewards for the validator participation. Likely duration of months to a year.
+
+- _Cool-down period_: a duration of time following the submission of a 'withdrawal' transaction. During this period validation responsibilities have been removed and the funds continue to be inaccessible. Accumulated rewards should be delivered at the end of this period, along with the return of the initial deposit.
+
+Solana's trustless sense of time and ordering provided by its PoH data structure, along with its [turbine](https://www.youtube.com/watch?v=qt_gDRXHrHQ&t=1s) data broadcast and transmission design, should provide sub-second transaction confirmation times that scale with the log of the number of nodes in the cluster. This means we shouldn't have to restrict the number of validating nodes with a prohibitive 'minimum deposits' and expect nodes to be able to become validators with nominal amounts of SOL staked. At the same time, Solana's focus on high-throughput should create incentive for validation clients to provide high-performant and reliable hardware. Combined with potential a minimum network speed threshold to join as a validation-client, we expect a healthy validation delegation market to emerge.
+
+## Penalties
+
+As discussed in the [Economic Design](ed_overview/ed_overview.md) section, annual validator interest rates are to be specified as a function of total percentage of circulating supply that has been staked. The cluster rewards validators who are online and actively participating in the validation process throughout the entirety of their _validation period_. For validators that go offline/fail to validate transactions during this period, their annual reward is effectively reduced.
+
+Similarly, we may consider an algorithmic reduction in a validator's active amount staked amount in the case that they are offline. I.e. if a validator is inactive for some amount of time, either due to a partition or otherwise, the amount of their stake that is considered ‘active’ \(eligible to earn rewards\) may be reduced. This design would be structured to help long-lived partitions to eventually reach finality on their respective chains as the % of non-voting total stake is reduced over time until a supermajority can be achieved by the active validators in each partition. Similarly, upon re-engaging, the ‘active’ amount staked will come back online at some defined rate. Different rates of stake reduction may be considered depending on the size of the partition/active set.

package/src/implemented-proposals/testing-programs.md

@@ -0,0 +1,53 @@
+---
+title: Testing Programs
+---
+
+Applications send transactions to a Solana cluster and query validators to confirm the transactions were processed and to check each transaction's result. When the cluster doesn't behave as anticipated, it could be for a number of reasons:
+
+- The program is buggy
+- The BPF loader rejected an unsafe program instruction
+- The transaction was too big
+- The transaction was invalid
+- The Runtime tried to execute the transaction when another one was accessing
+
+  the same account
+
+- The network dropped the transaction
+- The cluster rolled back the ledger
+- A validator responded to queries maliciously
+
+## The AsyncClient and SyncClient Traits
+
+To troubleshoot, the application should retarget a lower-level component, where fewer errors are possible. Retargeting can be done with different implementations of the AsyncClient and SyncClient traits.
+
+Components implement the following primary methods:
+
+```text
+trait AsyncClient {
+    fn async_send_transaction(&self, transaction: Transaction) -> io::Result<Signature>;
+}
+
+trait SyncClient {
+    fn get_signature_status(&self, signature: &Signature) -> Result<Option<transaction::Result<()>>>;
+}
+```
+
+Users send transactions and asynchrounously and synchrounously await results.
+
+### ThinClient for Clusters
+
+The highest level implementation, ThinClient, targets a Solana cluster, which may be a deployed testnet or a local cluster running on a development machine.
+
+### TpuClient for the TPU
+
+The next level is the TPU implementation, which is not yet implemented. At the TPU level, the application sends transactions over Rust channels, where there can be no surprises from network queues or dropped packets. The TPU implements all "normal" transaction errors. It does signature verification, may report account-in-use errors, and otherwise results in the ledger, complete with proof of history hashes.
+
+## Low-level testing
+
+### BankClient for the Bank
+
+Below the TPU level is the Bank. The Bank doesn't do signature verification or generate a ledger. The Bank is a convenient layer at which to test new on-chain programs. It allows developers to toggle between native program implementations and BPF-compiled variants. No need for the Transact trait here. The Bank's API is synchronous.
+
+## Unit-testing with the Runtime
+
+Below the Bank is the Runtime. The Runtime is the ideal test environment for unit-testing. By statically linking the Runtime into a native program implementation, the developer gains the shortest possible edit-compile-run loop. Without any dynamic linking, stack traces include debug symbols and program errors are straightforward to troubleshoot.

package/src/implemented-proposals/tower-bft.md

@@ -0,0 +1,138 @@
+---
+title: Tower BFT
+---
+
+This design describes Solana's _Tower BFT_ algorithm. It addresses the following problems:
+
+- Some forks may not end up accepted by the supermajority of the cluster, and voters need to recover from voting on such forks.
+- Many forks may be votable by different voters, and each voter may see a different set of votable forks. The selected forks should eventually converge for the cluster.
+- Reward based votes have an associated risk. Voters should have the ability to configure how much risk they take on.
+- The [cost of rollback](tower-bft.md#cost-of-rollback) needs to be computable. It is important to clients that rely on some measurable form of Consistency. The costs to break consistency need to be computable, and increase super-linearly for older votes.
+- ASIC speeds are different between nodes, and attackers could employ Proof of History ASICS that are much faster than the rest of the cluster. Consensus needs to be resistant to attacks that exploit the variability in Proof of History ASIC speed.
+
+For brevity this design assumes that a single voter with a stake is deployed as an individual validator in the cluster.
+
+## Time
+
+The Solana cluster generates a source of time via a Verifiable Delay Function we are calling [Proof of History](../cluster/synchronization.md).
+
+Proof of History is used to create a deterministic round robin schedule for all the active leaders. At any given time only 1 leader, which can be computed from the ledger itself, can propose a fork. For more details, see [fork generation](../cluster/fork-generation.md) and [leader rotation](../cluster/leader-rotation.md).
+
+## Lockouts
+
+The purpose of the lockout is to force a validator to commit opportunity cost to a specific fork. Lockouts are measured in slots, and therefor represent a real-time forced delay that a validator needs to wait before breaking the commitment to a fork.
+
+Validators that violate the lockouts and vote for a diverging fork within the lockout should be punished. The proposed punishment is to slash the validator stake if a concurrent vote within a lockout for a non-descendant fork can be proven to the cluster.
+
+## Algorithm
+
+The basic idea to this approach is to stack consensus votes and double lockouts. Each vote in the stack is a confirmation of a fork. Each confirmed fork is an ancestor of the fork above it. Each vote has a `lockout` in units of slots before the validator can submit a vote that does not contain the confirmed fork as an ancestor.
+
+When a vote is added to the stack, the lockouts of all the previous votes in the stack are doubled \(more on this in [Rollback](tower-bft.md#Rollback)\). With each new vote, a validator commits the previous votes to an ever-increasing lockout. At 32 votes we can consider the vote to be at `max lockout` any votes with a lockout equal to or above `1<<32` are dequeued \(FIFO\). Dequeuing a vote is the trigger for a reward. If a vote expires before it is dequeued, it and all the votes above it are popped \(LIFO\) from the vote stack. The validator needs to start rebuilding the stack from that point.
+
+### Rollback
+
+Before a vote is pushed to the stack, all the votes leading up to vote with a lower lock time than the new vote are popped. After rollback lockouts are not doubled until the validator catches up to the rollback height of votes.
+
+For example, a vote stack with the following state:
+
+| vote | vote time | lockout | lock expiration time |
+| ---: | --------: | ------: | -------------------: |
+|    4 |         4 |       2 |                    6 |
+|    3 |         3 |       4 |                    7 |
+|    2 |         2 |       8 |                   10 |
+|    1 |         1 |      16 |                   17 |
+
+_Vote 5_ is at time 9, and the resulting state is
+
+| vote | vote time | lockout | lock expiration time |
+| ---: | --------: | ------: | -------------------: |
+|    5 |         9 |       2 |                   11 |
+|    2 |         2 |       8 |                   10 |
+|    1 |         1 |      16 |                   17 |
+
+_Vote 6_ is at time 10
+
+| vote | vote time | lockout | lock expiration time |
+| ---: | --------: | ------: | -------------------: |
+|    6 |        10 |       2 |                   12 |
+|    5 |         9 |       4 |                   13 |
+|    2 |         2 |       8 |                   10 |
+|    1 |         1 |      16 |                   17 |
+
+At time 10 the new votes caught up to the previous votes. But _vote 2_ expires at 10, so the when _vote 7_ at time 11 is applied the votes including and above _vote 2_ will be popped.
+
+| vote | vote time | lockout | lock expiration time |
+| ---: | --------: | ------: | -------------------: |
+|    7 |        11 |       2 |                   13 |
+|    1 |         1 |      16 |                   17 |
+
+The lockout for vote 1 will not increase from 16 until the stack contains 5 votes.
+
+### Slashing and Rewards
+
+Validators should be rewarded for selecting the fork that the rest of the cluster selected as often as possible. This is well-aligned with generating a reward when the vote stack is full and the oldest vote needs to be dequeued. Thus a reward should be generated for each successful dequeue.
+
+### Cost of Rollback
+
+Cost of rollback of _fork A_ is defined as the cost in terms of lockout time to the validator to confirm any other fork that does not include _fork A_ as an ancestor.
+
+The **Economic Finality** of _fork A_ can be calculated as the loss of all the rewards from rollback of _fork A_ and its descendants, plus the opportunity cost of reward due to the exponentially growing lockout of the votes that have confirmed _fork A_.
+
+### Thresholds
+
+Each validator can independently set a threshold of cluster commitment to a fork before that validator commits to a fork. For example, at vote stack index 7, the lockout is 256 time units. A validator may withhold votes and let votes 0-7 expire unless the vote at index 7 has at greater than 50% commitment in the cluster. This allows each validator to independently control how much risk to commit to a fork. Committing to forks at a higher frequency would allow the validator to earn more rewards.
+
+### Algorithm parameters
+
+The following parameters need to be tuned:
+
+- Number of votes in the stack before dequeue occurs \(32\).
+- Rate of growth for lockouts in the stack \(2x\).
+- Starting default lockout \(2\).
+- Threshold depth for minimum cluster commitment before committing to the fork \(8\).
+- Minimum cluster commitment size at threshold depth \(50%+\).
+
+### Free Choice
+
+A "Free Choice" is an unenforcible validator action. There is no way for the protocol to encode and enforce these actions since each validator can modify the code and adjust the algorithm. A validator that maximizes self-reward over all possible futures should behave in such a way that the system is stable, and the local greedy choice should result in a greedy choice over all possible futures. A set of validator that are engaging in choices to disrupt the protocol should be bound by their stake weight to the denial of service. Two options exits for validator:
+
+- a validator can outrun previous validator in virtual generation and submit a concurrent fork
+- a validator can withhold a vote to observe multiple forks before voting
+
+In both cases, the validator in the cluster have several forks to pick from concurrently, even though each fork represents a different height. In both cases it is impossible for the protocol to detect if the validator behavior is intentional or not.
+
+### Greedy Choice for Concurrent Forks
+
+When evaluating multiple forks, each validator should use the following rules:
+
+1. Forks must satisfy the _Threshold_ rule.
+2. Pick the fork that maximizes the total cluster lockout time for all the ancestor forks.
+3. Pick the fork that has the greatest amount of cluster transaction fees.
+4. Pick the latest fork in terms of PoH.
+
+Cluster transaction fees are fees that are deposited to the mining pool as described in the [Staking Rewards](staking-rewards.md) section.
+
+## PoH ASIC Resistance
+
+Votes and lockouts grow exponentially while ASIC speed up is linear. There are two possible attack vectors involving a faster ASIC.
+
+### ASIC censorship
+
+An attacker generates a concurrent fork that outruns previous leaders in an effort to censor them. A fork proposed by this attacker will be available concurrently with the next available leader. For nodes to pick this fork it must satisfy the _Greedy Choice_ rule.
+
+1. Fork must have equal number of votes for the ancestor fork.
+2. Fork cannot be so far a head as to cause expired votes.
+3. Fork must have a greater amount of cluster transaction fees.
+
+This attack is then limited to censoring the previous leaders fees, and individual transactions. But it cannot halt the cluster, or reduce the validator set compared to the concurrent fork. Fee censorship is limited to access fees going to the leaders but not the validators.
+
+### ASIC Rollback
+
+An attacker generates a concurrent fork from an older block to try to rollback the cluster. In this attack the concurrent fork is competing with forks that have already been voted on. This attack is limited by the exponential growth of the lockouts.
+
+- 1 vote has a lockout of 2 slots. Concurrent fork must be at least 2 slots ahead, and be produced in 1 slot. Therefore requires an ASIC 2x faster.
+- 2 votes have a lockout of 4 slots. Concurrent fork must be at least 4 slots ahead and produced in 2 slots. Therefore requires an ASIC 2x faster.
+- 3 votes have a lockout of 8 slots. Concurrent fork must be at least 8 slots ahead and produced in 3 slots. Therefore requires an ASIC 2.6x faster.
+- 10 votes have a lockout of 1024 slots. 1024/10, or 102.4x faster ASIC.
+- 20 votes have a lockout of 2^20 slots. 2^20/20, or 52,428.8x faster ASIC.

package/src/implemented-proposals/transaction-fees.md

@@ -0,0 +1,32 @@
+---
+title: Deterministic Transaction Fees
+---
+
+Transactions currently include a fee field that indicates the maximum fee field a slot leader is permitted to charge to process a transaction. The cluster, on the other hand, agrees on a minimum fee. If the network is congested, the slot leader may prioritize the transactions offering higher fees. That means the client won't know how much was collected until the transaction is confirmed by the cluster and the remaining balance is checked. It smells of exactly what we dislike about Ethereum's "gas", non-determinism.
+
+## Congestion-driven fees
+
+Each validator uses _signatures per slot_ \(SPS\) to estimate network congestion and _SPS target_ to estimate the desired processing capacity of the cluster. The validator learns the SPS target from the genesis config, whereas it calculates SPS from recently processed transactions. The genesis config also defines a target `lamports_per_signature`, which is the fee to charge per signature when the cluster is operating at _SPS target_.
+
+## Calculating fees
+
+The client uses the JSON RPC API to query the cluster for the current fee parameters. Those parameters are tagged with a blockhash and remain valid until that blockhash is old enough to be rejected by the slot leader.
+
+Before sending a transaction to the cluster, a client may submit the transaction and fee account data to an SDK module called the _fee calculator_. So long as the client's SDK version matches the slot leader's version, the client is assured that its account will be changed exactly the same number of lamports as returned by the fee calculator.
+
+## Fee Parameters
+
+In the first implementation of this design, the only fee parameter is `lamports_per_signature`. The more signatures the cluster needs to verify, the higher the fee. The exact number of lamports is determined by the ratio of SPS to the SPS target. At the end of each slot, the cluster lowers `lamports_per_signature` when SPS is below the target and raises it when above the target. The minimum value for `lamports_per_signature` is 50% of the target `lamports_per_signature` and the maximum value is 10x the target \`lamports_per_signature'
+
+Future parameters might include:
+
+- `lamports_per_pubkey` - cost to load an account
+- `lamports_per_slot_distance` - higher cost to load very old accounts
+- `lamports_per_byte` - cost per size of account loaded
+- `lamports_per_bpf_instruction` - cost to run a program
+
+## Attacks
+
+### Hijacking the SPS Target
+
+A group of validators can centralize the cluster if they can convince it to raise the SPS Target above a point where the rest of the validators can keep up. Raising the target will cause fees to drop, presumably creating more demand and therefore higher TPS. If the validator doesn't have hardware that can process that many transactions that fast, its confirmation votes will eventually get so long that the cluster will be forced to boot it.

package/src/implemented-proposals/validator-timestamp-oracle.md

@@ -0,0 +1,107 @@
+---
+title: Validator Timestamp Oracle
+---
+
+Third-party users of Solana sometimes need to know the real-world time a block
+was produced, generally to meet compliance requirements for external auditors or
+law enforcement. This proposal describes a validator timestamp oracle that
+would allow a Solana cluster to satisfy this need.
+
+The general outline of the proposed implementation is as follows:
+
+- At regular intervals, each validator records its observed time for a known slot
+  on-chain (via a Timestamp added to a slot Vote)
+- A client can request a block time for a rooted block using the `getBlockTime`
+  RPC method. When a client requests a timestamp for block N:
+
+  1. A validator determines a "cluster" timestamp for a recent timestamped slot
+     before block N by observing all the timestamped Vote instructions recorded on
+     the ledger that reference that slot, and determining the stake-weighted mean
+     timestamp.
+
+  2. This recent mean timestamp is then used to calculate the timestamp of
+     block N using the cluster's established slot duration
+
+Requirements:
+
+- Any validator replaying the ledger in the future must come up with the same
+  time for every block since genesis
+- Estimated block times should not drift more than an hour or so before resolving
+  to real-world (oracle) data
+- The block times are not controlled by a single centralized oracle, but
+  ideally based on a function that uses inputs from all validators
+- Each validator must maintain a timestamp oracle
+
+The same implementation can provide a timestamp estimate for a not-yet-rooted
+block. However, because the most recent timestamped slot may or may not be
+rooted yet, this timestamp would be unstable (potentially failing requirement
+1). Initial implementation will target rooted blocks, but if there is a use case
+for recent-block timestamping, it will be trivial to add the RPC apis in the
+future.
+
+## Recording Time
+
+At regular intervals as it is voting on a particular slot, each validator
+records its observed time by including a timestamp in its Vote instruction
+submission. The corresponding slot for the timestamp is the newest Slot in the
+Vote vector (`Vote::slots.iter().max()`). It is signed by the validator's
+identity keypair as a usual Vote. In order to enable this reporting, the Vote
+struct needs to be extended to include a timestamp field, `timestamp: Option<UnixTimestamp>`, which will be set to `None` in most Votes.
+
+As of https://github.com/solana-labs/solana/pull/10630, validators submit a
+timestamp every vote. This enables implementation of a block time caching
+service that allows nodes to calculate the estimated timestamp immediately after
+the block is rooted, and cache that value in Blockstore. This provides
+persistent data and quick queries, while still meeting requirement 1) above.
+
+### Vote Accounts
+
+A validator's vote account will hold its most recent slot-timestamp in VoteState.
+
+### Vote Program
+
+The on-chain Vote program needs to be extended to process a timestamp sent with
+a Vote instruction from validators. In addition to its current process_vote
+functionality (including loading the correct Vote account and verifying that the
+transaction signer is the expected validator), this process needs to compare the
+timestamp and corresponding slot to the currently stored values to verify that
+they are both monotonically increasing, and store the new slot and timestamp in
+the account.
+
+## Calculating Stake-Weighted Mean Timestamp
+
+In order to calculate the estimated timestamp for a particular block, a
+validator first needs to identify the most recently timestamped slot:
+
+```text
+let timestamp_slot = floor(current_slot / timestamp_interval);
+```
+
+Then the validator needs to gather all Vote WithTimestamp transactions from the
+ledger that reference that slot, using `Blockstore::get_slot_entries()`. As these
+transactions could have taken some time to reach and be processed by the leader,
+the validator needs to scan several completed blocks after the timestamp_slot to
+get a reasonable set of Timestamps. The exact number of slots will need to be
+tuned: More slots will enable greater cluster participation and more timestamp
+datapoints; fewer slots will speed how long timestamp filtering takes.
+
+From this collection of transactions, the validator calculates the
+stake-weighted mean timestamp, cross-referencing the epoch stakes from
+`staking_utils::staked_nodes_at_epoch()`.
+
+Any validator replaying the ledger should derive the same stake-weighted mean
+timestamp by processing the Timestamp transactions from the same number of
+slots.
+
+## Calculating Estimated Time for a Particular Block
+
+Once the mean timestamp for a known slot is calculated, it is trivial to
+calculate the estimated timestamp for subsequent block N:
+
+```text
+let block_n_timestamp = mean_timestamp + (block_n_slot_offset * slot_duration);
+```
+
+where `block_n_slot_offset` is the difference between the slot of block N and
+the timestamp_slot, and `slot_duration` is derived from the cluster's
+`slots_per_year` stored in each Bank