Merge pull request #53 from Convex-Dev/develop

General updates

.lsp/.cache/db.transit.json

@@ -0,0 +1 @@
+["^ ","~:classpath",["~#set",[]],"~:project-hash","","~:project-root","C:\\Users\\mike_\\git\\design","~:kondo-config-hash","30602b3ab159ce6418abbdb9ccf57a58f69fcd1bd89e89ca1e8c53148f5f15b1","~:dependency-scheme","jar","~:analysis",null,"~:analysis-checksums",["^ "],"~:project-analysis-type","~:project-and-full-dependencies","~:version",12,"~:stubs-generation-namespaces",["^1",[]]]

docs/cad/003_encoding/README.md

@@ -695,7 +695,7 @@ Applications MAY in addition use the hex digit `z` to further disambiguate code
 
 ### `0xD0`-`0xDF` Data Records
 
-Data Records are record types where every field value is encoded (densely coded).
+Data Records are record types where every field value is encoded (i.e. the record is densely coded).
 
 ```
 `0xDz` <VLQ Count = n> <Continues as Vector Encoding>
@@ -705,27 +705,32 @@ Where:
 - n = the number of fields in the record
 ```
 
-Data Record encoding is exactly the same as a Vector, with the exception of the tag byte. Note that if there are more than 16 fields, this means there will be a child cells which are Vectors.
+Data Record encoding is exactly the same as a Vector, with the exception of the tag byte. Note that if there are more than 16 fields, this means there will be a child prefix cell which is a Vector.
 
 Applications MAY use the hex digit `z` and/or the field count `n` to distinguish record types. If this is insufficient, applications MAY use the first or the last field value to indicate the type, or embed a Data Record as a coded value (`0xCz`) to tag with an arbitrary type.
 
 The intention of Data records is that applications may interpret these as records in their own custom format. For example, a record might represent a listing on a decentralised market place with fields such as Asset ID, Price, Seller ID, Listing description, Creation Time, Time Limit etc.  
 
+The CVM interprets certain Data Records as CVM-specific record types (e.g. the `convex.core.cvm.State` type).
+
 ### `0xE0`-`0xEF` Extension Values
 
-Extension values are arbitrary values allowing 16 application specific meanings.
+Extension values are enumeration-style values allowing 16 application specific ranges, and 2^63 possible values for each. Typically, applications might use them for encoding known enumerations, such as a reference into an array of constant values.
 
 ```
-`0xEz` <Child Value>
+`0xEz` <VLQ Count = value>
 
 Where:
 - z = a hex value from 0-15 
+- value = any non-negative Long value (0 - 2^63-1)
 ```
 
-Extension values are arbitrary values with a one byte tag, where the low byte of the tag is available for applications to define a special meaning for the value. 
+Extension values are arbitrary non-negative integer values with a one byte tag, where the low byte of the tag is available for applications to define a special meaning for the value. 
+
+Extension values are considered "BlobLike" and can therefore be used a a key in an Index
 
 Examples: 
-- an application might define `0xEB` as an extension where the value is a String containing JSON data with a specific schema.
+- an application might define `0xE5` as an extension where the value references a known JSON schema.
 - another application might define `0xE0` as an enum where the values are the possible states of a finite state machine
 
 ### `0xFF` Illegal

docs/cad/010_transactions/README.md

@@ -36,7 +36,7 @@ A `Transfer` is a transaction requesting the transfer of Convex Coins from a use
 
 A transfer transaction MUST specify an amount to transfer, as an integer.
 
-The Source Account MUST be the origin account for the transaction, i.e. transfers can only occur from the account which has the correct digital signature
+The source Account MUST be the origin account for the transaction, i.e. transfers can only occur from the account which has the correct digital signature
 
 Both accounts MUST be valid, otherwise the transaction MUST fail
 
@@ -63,10 +63,10 @@ An Invoke Transaction MUST include a payload of CVM Code. This may be either:
 
 High volume users MAY consider pre-compilation of CVM code to avoid additional compilation juice fees.
 
-An Invoke Transaction MUST fail if:
+An Invoke transaction MUST fail if:
 - The CVM Code is not valid for execution (e.g. a syntax error in compilation)
 - The Origin Account has insufficient balance to pay for Juice required by the code execution
-- The execution of CVM Code causes any Error (e.g. a `:TRUST` Error casued by attempting an unathorised operation on an Actor)
+- The execution of CVM Code causes any Error (e.g. a `:TRUST` Error caused by attempting an unauthorised operation on an actor)
 
 Otherwise, the CVM State MUST be updated by the result of executing the CVM Code for the Origin Account
 
@@ -106,7 +106,7 @@ Transaction results MUST be returned in a `Result` record which contains the fol
 - `:id` - the message ID of the transaction to correlate with the client
 - `:result` - the final result of the transaction (will be the error message if an error occurred)
 - `:error` - the error code (MUST `nil` if no error occurred, otherwise can be any Keyword)
-- `:log` - a vector of log entries cerated (may be omitted if no logs events occurred)
+- `:log` - a vector of log entries created (may be omitted if no logs events occurred)
 - `:info` - a Map of information reported by the peer to the client, which SHOULD include:
  - `:tx` - the 32-byte SHA3-256 hash of the signed transaction
  - `:loc` - the location of the transaction in consensus, as a vector `[block-index transaction-index]`

docs/cad/016_peerstake/README.md

@@ -14,19 +14,39 @@ The total Stake of a seer determines its voting weight in the CPoS consensus alg
 
 Stake involves taking a risk and performing useful work for the network to earn rewards.
 
-A peer operator that stakes on it own peer ("peer stake") is warranting that it has **fully secured its peer key used for operational participation in consensus**. The work they do is ensuring this peer is properly managed, secured and maintains network consensus correctly. It may lose its stake if this key is compromised (typically this would mean that the peer server is itself compromised). It may also lose its stake if the controller account is compromised.
+A peer operator that stakes on its own peer ("peer stake") is warranting that it has **fully secured its peer key used for operational participation in consensus**. The work they do is ensuring this peer is properly managed, secured and maintains network consensus correctly. It may lose its stake if this key is compromised (typically this would mean that the peer server is itself compromised). It may also lose its stake if the controller account is compromised.
 
 Delegated stakers are warranting that they **trust the peer operator to maintain consensus and earn rewards while properly protecting the peer controller account**. The work they do is in evaluating peer operators and betting their coins that the peer operators performs their role honestly and effectively. Their delegated stake is not at risk if the peer itself is compromised or crashes, but *is* at risk if the controller account is compromised.
 
 It should be observed that the most important thing from a security perspective is the private key used to control the peer controller account: all stake is at risk if this is lost. For this reason it is STRONGLY RECOMMENDED that important peer controller keys are kept secure in offline storage / air-gapped systems. This is a good incentive since the network as a whole could go offline if sufficient numbers of peers are simultaneously compromised.
 
 ## Rewards
 
-Stakers are rewarded with a share of Convex Coins earned from
+Stakers are rewarded with a share of Convex Coins earned from:
 - Transaction fees executed on the network affecting the CVM global stake
-- Reward Pools set by the Convex Foundation
+- Reward Pools build up over time set by the Convex Foundation
 
-Rewards are divided as follows:
+### Transaction fee handling
+
+Transaction fees are accumulated for all transactions executed within a complete block submitted by a peer.
+
+When a block of transactions is successfully executed:
+- 50% are given to the peer and its stakers immediately
+- The remainder is added to the the common reward pool 
+
+### Reward pool distribution
+
+Rewards are delivered from the reward pools based on peer stake and active time elapsed.
+
+Active time elapsed is calculated when a block is successfully executed in consensus for a given peer. Active time is calculated as:
+- The difference between the timestamp of CVM state for this Block and the last such timestamp for the same peer
+- Subject to a maximum of 6000ms * total coin supply / total peer stake
+
+i.e. if the peer's total stake is 1% of the coin supply, it must submit a block at least once every ten minutes to maintain 100% active time. This mechanism is designed to ensure that peers must participate regularly and correctly in order to obtain full rewards.
+
+### Staking split
+
+When rewards are given to a peer, they are divided as follows:
 - The total reward is divided over all Peers according to Peer Stake
 - For each Peer:
   - 50% is allocated to the Peer itself (added to peer stake)