Giter VIP home page Giter VIP logo

symbol-technicalref's Introduction

symbol-technicalref's People

Contributors

bloodyrookie avatar dgarcia360 avatar gimre-xymcity avatar ivyfung1 avatar jaguar0625 avatar orisdorch avatar segfaultxavi avatar wayonb avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

symbol-technicalref's Issues

blockchain.tex suggestions

  • page 36 “The maximum change rate of 5% per block makes it hard for an attacker with considerably less than 50% importance to create a better chain in secret.” -> Why 5% rate change makes it hard for an attacker to create a better chain?
  • page 39 transfer transaction not referenced nor described before. You could add a footnote or reference to docs.
  • page 39: effective amount formula format looks different than page 31 effectiveFee format (spaces, camel case,...)

cryptography.tex suggestions

  • “The specific curve being used is the Twisted Edwards curve: EQUATION over the finite field defined by the prime number 2255 − 19 together with the digital signature algorithm called Ed25519.” Is it saying that Twisted Edwards Curve is everything after the colon? Or is it saying that the “specific curve” is the whole thing including the Twisted Edwards Curve.

All terms should be defined before use

The first paragraph of the introduction refers to DLT, DAG and dBFT. I understand these might be common acronyms in the cryptospace, but it does not hurt to define them (ideally on first use) and it does gives the document a far more professional look.
Maybe a Glossary chapter can be created and make these words automatically link to it?

This is substantial work since the whole document needs to be checked for correctness. It probably requires time planning from the docs team.

timesync.tex suggestions

  • Page 79 “Symbol relies on timestamps for transactions and blocks” -> may elaborate more e.g. Symbol relies on timestamps for the integrity/accuracy of transactions and blocks.
  • Consider adding a reference link to NTP.

network.tex suggestions

  • “should contain a random subset of these nodes” Possible clarity needed, each one has an independent random subset that is determined when?
  • “API writers is experimental.” What if I don’t want experimental features in my application? Is there another alternative? Is it default disabled or enabled, or is it even possible to disable?
  • “individual writers can be checked out” Unclear what checked out means, as this is its first mention. Only a specific writer on a certain node? All of a certain writer type across the network?
  • pg 61 network:nodeEqualityStrategy settings are discussed without introducing what it’s for. The introduction does not come until the next page at the beginning of 12.6 Node Discovery.

transactions.tex suggestions

  • Page 22: inherent disadvantages→ Explain more or add a reference link.
  • Figure 8 of page 29: V, N, T are not clear, it would be good to have additional info.

Copy Editing Feedback Sections 0-3

In response to Jaguar's recent Twitter post regarding improvement and review, here are comments and suggestions up to page 10.

Document-Wide Comments

Presumably all references to Catapult should change to SYMBOL.

Chapter quotes and artistic drop caps seem a bit self-indulgent for a typical white paper, but do add entertaining flair. These elements suggest devs are idealists who are working for some kind of grander purpose or lasting statement. That's okay as long as it's intentional. Is there any concern about how this would comport with SYMBOL's high-tech business branding?

Chapter headings 2, 4-8, 10-12, 14, and 16 have empty/lorem ipsum quotes. Need to fill in or remove empties. Some suggestions below.

Preface

Text
...we quickly decided to create something new from scratch. We wanted to challenge ourselves...
Comment
Besides the challenge, what was the goal of building from scratch? What advantages were the team seeking that motivated such an ambitious idea?

Text
... we hope this is the last blockchain we build from scratch.
Comment
This makes it seem like devs are sick of the project and it's not encouraging to read at the start of a long white paper. Suggest cutting.

1 Introduction

Comment pg. 1
To help the reader get oriented the introduction should briefly summarize the bigger purpose or vision of the project (beyond the functional description of fast trustless blockchain). Why did this project need to be built? What are the top few defining features that make it different? Why was this combination of features chosen, and what do you hope users will create with them?

Comment pg. 1
The introduction seems to assume some previous knowledge of NEM. It would be helpful to specify this fact and provide a link to a definitive reference for those new to NEM basics. It could also include a link to the Github page.

Text pg. 1
As part of a focus on trustlessness, the following features were added relative to NEM:
Comment
The subsequent items may be better formatted as a bulleted list, which would allow a reader to skip ahead if they are not familiar with NEM.

Text pg. 1
...verification of specific state within the blockchain
Comment
Missing period.

Comment pg. 2
The Introduction section mostly covers thinking behind design choices. The 1.1 Variants section seems out of place here. I suggest putting it in another chapter, such as Cryptography, and changing its subheading to "Hashing Variants".

Text pg. 2
Catapult supports compile time substitution of its primary hash algorithm that produces a 32-byte value from input data. For conciseness, the rest of this document will refer to this hash assuming its default setting (SHA3).
Suggested
Catapult supports compile-time substitution of its primary hash algorithm, which produces a 32-byte value from input data. For conciseness, the rest of this document refers to this hash by its default setting (SHA3).

2 System

Comment pg. 3
Chapter quote missing
Suggestions
"They constantly try to escape
From the darkness outside and within
By dreaming of systems so perfect that no one will need to be good." - T.S. Eliot
"What is needed is an electronic payment system based on cryptographic proof instead of trust, allowing any two willing parties to transact directly with each other without the need for a trusted third party." - Satoshi Nakamoto
"When you are wrestling for possession of a sword, the man with the handle always wins." - Neal Stephen

Text pg. 3
High degrees of customization are supported by Catapult at both the network
level and the individual node level. Network wide settings specified in network
:network must be the same for all nodes in a network. Node specific settings
specified in node:node can vary across nodes in the same network.
Suggested
Catapult supports high customization at both the network and individual node levels. Network-wide settings must be the same for all nodes in a network, and are specified in network:network. In contrast, node-specific settings can vary across all nodes in the same network, and are located in node:node.

Comment pg. 3
Section 2 could use a sentence stating the reasoning/advantages of the plugin-based design (in contrast to more common smart contract based designs).

Text pg. 3
The transactions a network supports are determined by the set of transaction plugins the network requires each node to load.
Suggested
The network requires each node to load a set of transaction plugins, and this set determines the kinds of transactions the network supports.

Text pg. 3
This set is determined by the presence of network:plugin* sections in the configuration.
Comment
Could possibly use clarification. Where in configuration? config-network.properties?

Text pg. 3
PluginManager provides access to the subset of configuration ...
Comment
configurations

Text pg. 4
Handlers - APIs that are always ...
Suggested
Handlers - These are APIs that are always ...

Text pg. 4
Diagnostics - APIs and counters ...
Suggested
Diagnostics - These are APIs and counters ...

Text pg. 4
Validators - Stateless and stateful validators that process the ...
Suggested
Validators - Stateless and stateful validators process the ...

Text pg. 4
Observers - Observers that process the notifications ...
Suggested
Observers - Observers process the notifications ...

Text pg. 4
Resolvers - Custom mappings from unresolved to resolved types can ...
Suggested
Resolvers - Custom mappings from unresolved to resolved transaction types can ...

Text pg. 4
An extension is a separate dynamically linked ...
Suggested
dynamically-linked

Text pg. 5
... please refer to the project code or developer documentation.
Comment
Add a link to developer guide here?

Text pg. 5
The most simple catapult topology ...
Suggested
The simplest SYMBOL topology ...

Text pg. 6
Files ending in Cache.dat store complete cache data.
Comment
Should Cache.dat be uncapitalized?

Text pg. 6
commit step.dat - Stores the most ...
Suggested
commit step.dat - This stores the most ...

Text pg. 6
index.dat - Counter that contains ...
Suggested
index.dat - This is a counter that contains ...

Text pg. 6
The server supports running both with and without ...
Suggested
The server can run with or without ...

Text pg. 7
Please refer to the project code or developer documentation.
Comment
Add a link to developer guide here?

Text pg. 7
The server raises subscription events in the block chain sync consumer ...
Suggested
blockchain

Text pg. 7
In order to prevent slow database operations from occurring when ...
Suggested
To prevent slow database operations when ...

Text pg. 8
... most nodes will fall into one of three categories: Peer, Api or Dual.
Comment
On page 1, these are listed as peer, api, and dual. Is there a reason the capitalizations don't match?

Text pg. 8
They require a broker process, which is configured to persist data into ...
Suggested
... configured to write data into ...

Text pg. 8
The REST Api is dependent on ...
Suggested
REST API

Text pg. 8
... is typically co-located with an Api node ...
Comment
Should Api capitalization match api or API? Same question applies when Api is also mentioned twice in the following paragraph.

Text pg. 9
Catapult has chosen to use the Twisted Edwards curve:
Suggested
The SYMBOL team chose the Twisted Edwards curve:

Text pg. 9
Catapult is using cryptography based on ...
Suggested
SYMBOL uses cryptography based on ...

Text pg. 9
... the algorithm produces short 64 byte signatures ...
Suggested
64-byte

Text pg. 10
... and public key A one checks S < q and S > 0 and ...
Suggested
... and public key A, the system checks S < q and S > 0 and ...

consensus.tex suggestions

  • “PoS that borrows key concepts from Proof of Importance (PoI).” POI has not been explained at this point. Needs short explanation or something to assure the reader they didn’t somehow miss it previously.
  • “cumulative transaction score accounts for 4% of importance” It would be nice to link/reference the relevant calculation so I can go back and look at where the 4% comes from.

reputation.tex suggestions

  • “One of the most successful is building a reputation system for nodes” This is a notable design choice for Symbol. Perhaps add brief reasoning why this reputation system was chosen over those used in other blockchains.
  • “each node monitors the read rate from the socket used for communication” Is it monitoring one socket, or the socket of each node it’s connected to?

trees.tex suggestions

For the hash function H mentioned in the paper, Symbol uses the 512-bit SHA3 hash function.

To calculate the transactionsRoot , H is used but seems to be 256-bit (32 bytes).

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.