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 ...