Merge pull request #24 from casper-devrel/feat/upgrade/v2.0.0

Feat/upgrade/v2.0.0

Author: melpadden

analyse-docs.sh

@@ -0,0 +1,5 @@
+docs_folder=./cspr-docs/docs;
+regex="\/image\/"
+regex="import useBaseUrl from \'@docusaurus\/useBaseUrl\';"
+grep -r -i "$regex" $docs_folder;
+

analyse-img.sh

@@ -0,0 +1,30 @@
+image_folder=./cspr-docs/static/image;
+docs_folder=./cspr-docs/docs;
+image_count=0
+image_names=()
+images_list=./images_list.csv
+images_notused=./images_notused.csv
+images_grep=./images_grep_out.csv
+
+echo "" > $images_list
+echo "" > $images_notused
+echo "" > $images_grep
+for entry in $(find $image_folder -iname "*.jpeg" -o -iname "*.jpg" -o -iname "*.gif" -o -iname "*.png" -o -iname "*.bmp")
+do
+    # extract just the filename
+    filename="${entry##*/}"
+    printf "$entry\n" >> $images_list
+    image_names[$image_count]=$filename
+    image_count=$((image_count+1))
+done
+
+for image_name in ${image_names[@]}; do
+    grep_result=$(grep -r -i "$image_name" $docs_folder);
+
+    if [ -z "$grep_result" ];
+    then
+        printf "$image_name\n" >> $images_notused
+    else
+        printf "$grep_result\n" >> $images_grep
+    fi
+done

cspr-docs/blog/2024-07-16-fee-elimination.md

@@ -3,7 +3,7 @@ title: Fee Elimination in Condor
 description: A discussion of the Fee Elimination feature in Casper 2.0
 slug: condor-fee-elimination
 date: 2024-07-16T22:00
-authors: [ dylanireland, alexanderlimonov ]
+authors: [ dylanireland, melpadden ]
 tags: [condor, features, tokenomics]
 hide_table_of_contents: false
 ---
@@ -13,10 +13,12 @@ The Casper 2.0 (aka Condor) network upgrade introduces new options to the way a
 
 <!-- truncate -->
 
-## Gas
-Public distributed blockchain networks that support smart contracts generally use a concept commonly known as "[gas](https://docs.casper.network/concepts/glossary/G/#gas)", which can be thought of as "the ability to do work on-chain". Gas is acquired in finite quantities and used to meter and limit resource consumption by individual transactors. A transactor's available gas is consumed by their on-chain usage of computation, data storage, and possibly other chain-specific resources. The public Casper Network and its testnet have used such a gas model since their geneses.
+## Concepts
+Public distributed blockchain networks that support smart contracts generally employ a concept known as "[gas](https://docs.casper.network/concepts/glossary/G/#gas)", which can be thought of as "the ability to do work on-chain". The problem addressed by this mechanism is that **any finite resource on a publicly accessible computer network must be rate-limited**, because a resource made available without limit is a denial of service attack vector. 
 
-## Casper 1.x: Payment, Gas Price, Fees and Refunds
+Gas is acquired in finite quantities and used to meter and limit resource consumption by individual transactors. A transactor's available gas is consumed by their on-chain usage of computation, data storage, and possibly other chain-specific resources. The public Casper Network and its testnet have used such a gas model since their geneses.
+
+## Payment, Gas Price, Fees
 On Casper 1.x, every transaction is subject to gas consumption. The transactor must specify an amount of token that is converted to gas and used to pay for execution. All gas consumed in each block is allotted to the [proposer](#proposer) of that block in the form of transaction [fees](#fees). The model also includes tables to allow calculation of gas costs, and support for some portion of unconsumed gas to be refunded to transactors. We refer to these concepts using the following terms:
 
 * **Gas Limit**: An amount of gas, specified by the transactor, at which to cancel a transaction.
@@ -25,7 +27,7 @@ On Casper 1.x, every transaction is subject to gas consumption. The transactor m
 * **Payment**: The amount of token specified by the transactor to pay for the execution of a transaction.
 * **Refund**: All or a portion of the remaining token after gas is purchased for execution.
 
-> [!NOTE]
+> 
 > The Casper node software supports a number of configurable options which govern how gas may be calculated for a given transaction. A discussion of these is outside the scope of this article. This article is concerned with how these gas costs are dealt with, once calculated. Gas cost options will be the subject of another article.
 
 ## Fee Elimination
@@ -42,7 +44,7 @@ A hold may be thought of as a temporary freeze on some portion of the funds in a
 
 The Casper Node 2.0 software currently supports two hold release models: **Accrued** and **Amortized**. 
 
-> [!NOTE]
+> 
 > The Condor node architecture allows for any time-based function to be developed and used to calculate hold releases. However, for simplicity, this article will deal with the two currently available options.
 
 #### Accrued

cspr-docs/blog/2024-07-17-addressable-entity.md

@@ -0,0 +1,99 @@
+---
+title: Addressable Entity in Casper 2.0
+description: An introduction to the Addressable Entity concept. 
+slug: addressable-entity
+date: 2024-07-17T18:00
+authors: [ sczembor, melpadden ]
+tags: [condor]
+hide_table_of_contents: false
+---
+
+# AddressableEntity in Casper 2.0
+
+Casper 2.0 introduces significant changes in the representation and management of accounts and smart contracts, through the introduction of the `AddressableEntity` type. This new structure replaces the separate `AccountHash` and `ContractHash` used in Casper 1.x, bringing a unified approach to interact with entities on the network. Contracts can now hold and manage funds directly through associated purses, similar to user accounts. They can also manage their own keys, enabling more sophisticated access control.
+
+In this article, we'll dive into the details of `AddressableEntity`, exploring its structure and functionalities.
+
+<!-- truncate -->
+
+## Key Concepts
+
+**AddressableEntity**
+
+At its core, an `AddressableEntity` is a versatile data structure that represents both accounts and smart contracts within the Casper global state. It encapsulates all the necessary information for identifying and managing these entities. An `AddressableEntity` provides a unified interface for various operations, including authorization, access control, and execution of functions.
+
+**EntityAddr**
+
+An `EntityAddr` serves as the address for an `AddressableEntity`. It not only encodes the unique identifier (hash) of the entity but also its type. There are three distinct variants of `EntityAddr`:
+
+1.  **System:** Used for built-in, native contracts crucial for the blockchain's operation.
+2.  **Account:**  Represents a user's account.
+3.  **SmartContract:** Represents a user-deployed smart contract.
+
+**AddressableEntityHash**
+
+The `AddressableEntityHash` is a newtype wrapper around a 32-byte hash (`HashAddr`). This hash functions as a unique identifier for the `AddressableEntity`, typically derived from either the account's public key or the smart contract's hash using hashing algorithm.
+
+## The inner workings of AddressableEntity
+
+Let's dive into the critical components within an `AddressableEntity`:
+
+*   **`protocol_version` (ProtocolVersion):**  This field indicates the protocol version that the entity is compatible with. It ensures backward compatibility and allows for smooth upgrades as the Casper network evolves.
+*   **`entity_kind` (EntityKind):** As mentioned earlier, this enum determines the type of entity – System, Account, or SmartContract.
+*   **`associated_keys` (AssociatedKeys):** This data structure stores a map of public keys authorized to interact with the entity. Each key is associated with a weight that represents its voting power in decision-making processes within the entity.
+*   **`action_thresholds` (ActionThresholds):** These thresholds define the minimum combined weight of associated keys required to authorize specific actions. The three main action types are `deployment`, `key_management`, and `upgrade_management`. Each action type has its own weight threshold, allowing for fine-grained control over permissions.
+*   **`entry_points` (EntryPoints):** This component is relevant only for smart contracts. It defines the functions (entry points) that external actors can call on the contract, along with their parameters, return types, and access permissions.
+
+## Obtaining and converting Keys
+
+In Casper 2.0, developers will primarily work with `Key::AddressableEntity` when referring to accounts and smart contracts. Here's how you can create them and convert between different key formats:
+
+### Creating AddressableEntity Keys
+
+**From Account Hash:**
+
+```rust
+let addressable_entity_key = Key::AddressableEntity(EntityAddr::Account(account_hash)); 
+```
+
+**From Smart Contract Hash:**
+
+```rust
+let addressable_entity_key = Key::AddressableEntity(EntityAddr::SmartContract(contract_hash));
+```
+
+### Extracting AccountHash or ContractHash from a Key
+You can extract the `AccountHash` or `ContractHash` from a `Key::AddressableEntity` using pattern matching:
+
+```rust
+//For Accounts
+let account_hash = match addressable_entity_key {
+    Key::AddressableEntity(EntityAddr::Account(hash)) => hash,
+    _ => panic!("Not an account key"), 
+};
+//For Contracts
+let contract_hash = match addressable_entity_key {
+    Key::AddressableEntity(EntityAddr::SmartContract(hash)) => hash,
+    _ => panic!("Not a contract key"), 
+};
+```
+
+## The Address Merge in Condor
+
+The "Address Merge" in the Condor upgrade of Casper is a foundational shift, impacting how accounts and smart contracts are identified and interacted with.  
+
+**Global State Transformation:**
+
+Post-Condor, all accounts and smart contract addresses residing within the global state will be automatically migrated to the `AddressableEntity` structure. This means the network itself will recognize and handle these entities using the new format.
+
+**Smart Contract Compatibility Considerations:**
+
+While the global state automatically transitions to `AddressableEntity`, existing contracts are expected to function without any modification. 
+
+* **Caller Identification:**
+Existing host functions used to identify the caller within your contract will continue to work as before, ensuring no disruption to your contract's functionality. However, new host functions have been introduced that are specifically designed to work with the AddressableEntity format.
+
+* **External Contract Interaction:** Other contracts may have updated their interfaces to accept AddressableEntity arguments. Its worth to verify the argument types to avoid potential errors.
+
+> **Note**
+> * Upgrading a contract to a newer version may involve complexities, such as changes to the contract's addressable hash. These changes might require coordination with centralized and decentralized exchanges, as well as communication with your community to ensure a smooth transition.

cspr-docs/blog/2024-08-20-validator-rewards.md

@@ -0,0 +1,119 @@
+---
+title: validator rewards in Casper 2.0
+description: A discussion of validator rewards under Casper 2.0
+slug: condor-validator-rewards
+date: 2024-08-20T18:00
+authors: [ melpadden, alexanderlimonov ]
+tags: [condor, validators]
+hide_table_of_contents: false
+---
+
+# Validator rewards with Casper 2.0
+
+## Economics of consensus
+
+Proof of Stake consensus protocols explicitly impose an assumption that a critical portion of the validator set, by weight, remains honest. Normally, just as it is in Highway and will be in Zug, there is a requirement that at least 2/3 of the weight remain honest for the chain to continue to operate normally. 
+
+Proof of Stake protocols do not typically describe the particular incentives that should keep validators honest, however, so some incentive scheme must be independently developed to ensure that the assumptions of the safety and liveness theorems actually hold. Such a scheme may directly reward some measure of performance within the protocol model, but an alternative model can choose to reward consensus-independent measures of chain performance, such as chain progress.
+
+Incentive rewards in Casper come from issuance of new token at the end of each era, with quantity derived from an inflation parameter in the chainspec. The minted token are distributed in proportion to weight, assuming nominal performance of the chain.
+
+## Casper 1.X Highway-specific incentives
+
+The 1.0 rewards scheme introduced with Highway on mainnet is directly tied to the details of Highway consensus. Rewards are maximized when all validators regularly send messages necessary to finalize a block within a time limit in a particular round. 
+
+Degrading platform performance by delaying block finalization is disadvantageous for all validators, even those not directly responsible for the delay, which is a means of aligning validator incentives with each other by discouraging censorship of consensus messages produced by others. 
+
+The weakness of the 1.0 rewards model is that it is difficult to understand and maintain. Additionally, by focusing on a consensus-specific measure of performance, it does not directly incentivize the observable outcome that we actually care about, which is public knowledge of block finality.  
+
+## Casper 2.0 
+
+### Public knowledge of finality
+
+A necessary outcome of a safe consensus process over possible histories of the chain is that all honest validators should have at least mutual knowledge of the canonical history. That is, each honest validator should believe that a particular history is the correct one, and this history should be the same for all validators.
+
+This mutual knowledge is sufficient for validators to make further progress in building up the canonical history. However, for a user of the blockchain, establishing confidence in the correct operation of the protocol and the identity of the canonical history requires that the validators' knowledge of the canonical history be attested publicly.
+
+In Casper, validators create and distribute finality signatures, which are cryptographically secure witnesses of their belief in the finality of a particular block. Under 1.X, however, these are not easily verifiable by users and play no role in the reward mechanism, despite being a critical tool for building user confidence in the canonical history. In 2.0, we propose to allocate rewards for creation and publication of one's own and other validators' finality signatures.
+
+### Design
+
+Rewards that promote public knowledge of finality naturally suggest rewarding publicly observable behaviors, rather than metrics only readily visible to the consensus component. This, together with the expected transition from Highway to Zug, naturally led to a system that rewards three publicly observable activities
+
+* Block proposal
+* Signature creation
+* Signature publication
+
+Note that we expect very little, if any, rewards to be allocated for block proposals on mainnet, but the feature remains available.
+
+The rewards apportioned to a block, under nominal operating conditions, are the same as they are under 1.X, that is, they amount to total supply at last era's end multiplied by an inflation factor derived from the chainspec. "Nominal" here means that all rounds result in a finalized block and that all finality signatures are collected and published.
+
+The rewards are apportioned to these three activities based on chainspec settings governing the split between block proposals and signature rewards, and, within signature rewards, between finality signature creation and publication.
+
+Note that this split ensures that validators' incentives are aligned, in the sense that other validators' correct operation is beneficial for each validator. This is because each validator is rewarded for publishing other validators' signature, and because each validator benefits from other publishing its own signatures.
+
+#### Expected rewards & volatility
+
+Under nominal operating conditions, the total rewards for each validator will be proportional to weight in the long run. Depending on the particular values of the parameters governing the split between the three components of the rewards, short-run rewards can be more or less variable.
+
+In the long run, with a stable validator set, each validator eventually produces a number of blocks proportional to its weight. Small validators can do months between producing a block, and will experience variable wait times between such occasions. However, each validator is supposed to produce signatures for each finalized block, so moving the allocation towards signature creation can reduce volatility.
+
+#### Rewards formula
+
+The rewards have three additive components, one for each observable activity we described in the previous section. The era rewards for a particular validator can be described using a simple formula, given below. Note that the formula does not exactly correspond to the actual on-chain calculation, for technical reasons we discuss in a further section.
+
+Let us define some notation first
+
+**N** - expected number of blocks in an era
+
+**N*** - the *set* of observed blocks in an era
+
+**R** - total potential reward pot for the era (i.e., nominal inflation based on chainspec and current supply)
+
+**r** - fraction of reward pot dedicated to block production rewards
+
+**f** - finder's fee for finality signatures
+
+**I** - validator index set
+
+**i**: **N*** -> {0,1} - indicator function for blocks produced by validator i (with abuse of notation)
+
+**w**: **I** -> [0,1] - validator's weight
+
+**W** - total weight of the validator set
+
+**S**: **N*** -> **P(I)** - set of validators associated with finality signatures for a particular observed block
+
+**s_i**: **N*** -> {0,1} - indicator functions for existence of finality signatures associated with validator i for particular observed blocks
+
+Now, we can use our defined symbols to concisely describe era rewards for a particular validator
+
+Era rewards for validator i = 
+
+**Σ** (n in **N***) **i(n)** * (**rR/N**) (block production)
+
++ **Σ** (n in **N***) **i(n)** * **Σ** (j in **S(n)**) (**w(j)/W**) * (**f(1-r)R/N**) (finality signature publication)  
+
++ **Σ** (n in **N***) **s_i(n)** * (**w(i)/W**) * (**(1-f)(1-r)R/N**) (finality signature contribution)
+
+The meanings of the three additive components in the formula above are, in order
+
+* Sum over blocks, discarding blocks not proposed by this validator
+  * For each block, add the per-block reward allocation for block proposals from the total pot for the era
+* Sum over blocks, discarding blocks not proposed by this validator
+  * For each block, sum over published signatures
+    * For each signature, add the per-block reward allocation for signature publication from the total pot for the era, weighing each signature by its creator's proportion of total validator weight
+* Sum over blocks, discarding those for which this validator did not create a signature
+  * For each block, add the per-block reward allocation for signature creation from the total pot for the era, weighing it by the validator's proportion of total validator weight
+
+#### Notes on implementation
+
+In a real network, messages arrive with a delay. This means that we cannot guarantee that all finality signatures for an era will arrive in time to be used by the rewards calculation carried out in the switch block.
+
+We solve this problem by allowing publication of finality signatures for a preceding era. As long as the validator set stays unchanged, in the long run the formula above is a near-exact representation of rewards. 
+
+However, entry of new validators means that some of the publication rewards may be distributed among more validators than just those who participated in the era in which the signatures were created.
+
+### Impact on validator revenue
+
+No impact is expected on average validator rewards under nominal operating conditions. Note that shortfall in signature creation, or network issues preventing the propagation of such signatures, can reduce rewards, even for validators who honestly publish all incoming signatures and honestly create signatures for each block. Additionally, allocating more rewards to block proposals or finality publication can make the rewards more volatile.