bowenwang1996
commented
4 years ago It seems that this issue should go to https://github.com/nearprotocol/NEPs
Open MaksymZavershynskyi opened 4 years ago
bowenwang1996
commented
4 years ago It seems that this issue should go to https://github.com/nearprotocol/NEPs
This issue tracks the specs that were not yet written:
Protocol Specs
Transaction runtime
While http://nomicon.io/ provides some specification of the runtime it is far from being complete. Currently, we only have description of the main runtime data-structures, explanation of the actions, examples of the transaction execution. What is missing: detailed explanation of when fees are applied and how, e.g. do we apply the base fee for reading storage before we start reading it or after; details on how runtime allows contracts to return promises, e.g. if we create a promise that awaits on receipts A and B then can we return it from the contract? What sequences of actions are prohibited and what are allowed? In what order local receipts, delayed receipts, and other receipts are processed? What is the exact consistency check for the tokens? In what cases refunds are not issued?
Overall, it might be the case that the spec of the blockchain runtime will be large part of the Rust code rewritten as a pseudocode or Python.
Contract runtime
We need to have clear explanations on how we actually run the smart contracts, what transformations and checks do we apply before running Wasm. What is the part of the protocol and what is not, e.g. is the fact that we compile instead of interpreting is the part of the protocol? How do we make sure the specifics of Wasmer backend do not leak into the protocol spec? E.g. we make sure compilation errors and execution errors are indistinguishable. How do we share the Wasm memory? The gas injection on its own can take a large time to write the specification for.
Trie
Detailed specification on the structure of the trie. How do we make sure the runtime-specific abstractions, like accounts do not leak into the design of the trie. How do we do state split for the state sync. We also need to draw the line what is the part of the protocol spec and what is not, e.g. whether trie is used directly during the transaction execution or whether it is only constructed/updated at the end of the block is implementation-specific.
Staking state-machine
We need an exhaustive diagram describing the state of the given validator and how it changes when they send staking proposal, the proposal gets accepted, whey unstake, etc.
API Specs
RPC API
Since we want different implementations of our node to be compatible with the same Applayer ecosystem, they need to have the same RPC. Describing such RPC and writing the spec tests is a large tedious work.