crypto-com / thaler-docs Goto Github PK

This could be achieved either with CODEOWNERS or merging (and equivalents)

Current docs: https://crypto-com.github.io/getting-started/staking.html

Some initial rough work: crypto-org-chain/chain-docs#75

Desired goals:

1. module-only specifics (e.g. reward calculation formulas) go into separate pages
2. cross-module interactions are explicitly stated
3. define precisely (somewhat "formally") in relation to Tendermint ABCI what each part does, so that this can be easily checked against the implementation:

• what are data inputs from where/when
• how are they processed
• what are outputs and when they are emitted

4. if the outcome depends on network parameters, each parameter needs to be justified:

• what it does
• what are its constraints
• what its relation to Tendermint core consensus security assumptions is -- "nothing-at-stake" problem, consensus-critical parameters set in Tendermint (evidence age, etc.), ...
• what it should be set to -- if it is not given (like total maximum supply), the recommended value should be given with justification / reference explaining why, e.g. based on mechanism design simulation models

As we are keeping authentication token for client-cli, the docs are not up-to-date.

Expected outcome:

• Update examples and instruction in ClientCLI under wallet-management are based on passphrase;
• Get the authentication token by wallet auth-token.

Extra:

• Check through the whole docs and make changes to those using passphrase.

1. genesis hash not documented
   currently, only "genesis app hash" is documented.
   But app hash is different from the overall genesis hash that's expected for light client verification

2. genesis page is outdated

Add a doc to describe transaction processing logic.

It was covered in "Send you first Tx" ( subject to change #56 )

Which should also be clearly covered in Funds transfer and Staking operations under Client-cli.

"Local full node deployment" and "Send Your First Transaction" is not up-to-date and has some typos.

e.g.

For anyone interested in joining the Crypto.com chain testnet, please refer to our testnet documentation.

by clicking on testnet documentation, the reader will be navigated to http://0.0.0.0:8080/getting-started/thaler-testnet

#176
line 32 should be

echo "::set-output name=repo_name::${{ fromJson(steps.request.outputs.data).head.repo.full_name }}"

https://chain.crypto.com/docs/getting-started/thaler-testnet.html#step-0-install-intel-sgx-sdk-2-9-and-other-pre-requisites
SGX SDK installation actually is not required to run the testnet. Only SGX driver and PSW are required.
SGX SDK is required for compilation.
May not need to mention SGX SDK in step 0.
However, we can show some steps to install SGX driver and PSW in Appendix in addition to the link in github.

From the audit discussion

Who among the validators invites a newcomer when a new validator node joins?
Assuming TDBE is (in normal circumstances) provided with network updates (relevant transactions, events...), it'll go like this:
block N (time N_t), there's a valid NodeJoinTx with a metadata payload, including a ClientInitKey
TDBE corresponding to node with index 0 in the ratchet tree generates "Welcome" and "Send" payloads wrapped in a single MLS-related transaction that's then broadcasted/gossiped by Tendermint (let's call it MlsAddTx)
block M (time M_t), MlsAddTx is proposed to be in a block:
if M_t <= N_t + timeout, it's considered valid and propagated to validator TDBEs
if M_t > N_t + timeout, it's considered invalid and the process restarts with Step 2., but TDBE corresponding to a node with index 1
(and this may continue with indices 2,3,... the consensus assumption is <1/3 of nodes are malicious)
One consequence of this is there may be multiple MLS Welcome/Send payloads for one newcomer -- only one of them is applied.

Who among the validators triggers the group and key update when a validator node leaves?
Same logic as above with joining, but there multiple ways to trigger "validator node leaving" (operator decides to leave and broadcasts relevant transaction, its node was observed to be faulty, ...)

I guess for the nodes that are not in the validator set, but requested to join / have enough stake, their TDBE keypackage will still be a part of the MLS group structure and expected to generate those MlsAddTx transactions/react to the network changes.

For nodes not generating these update Txs in time, they may need to be punished

Just like in BIPs:
https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#Test_Vectors
https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki#Test_vectors
https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#Test_Vectors
https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki#Test_Vectors_and_Reference_Code

it'll be good to have some test vectors for transaction data payload + witness + addresses.
There could be a command in dev-utils "test-vectors" that will generate these fixed test vectors.
(It could also later be added to CI to check transaction format wasn't broken.)

e.g. this https://github.com/crypto-com/chain-docs/pull/116/files only updated the module

but https://github.com/crypto-com/chain-docs/blob/master/docs/getting-started/reward-and-punishments.md
https://github.com/crypto-com/chain-docs/blob/master/docs/getting-started/staking.md
may still contain out of date information

Listed in chain/client-rpc and chain/client-rpc/src/rpc/

Here https://crypto-com.github.io/getting-started/#congratulations mentions

Congratulations, now the environment to run Crypto.com Chain is all set. Let's move on to start your first transaction.

I guess start your first transaction should be linked to https://crypto-com.github.io/getting-started/send_your_first_transaction.html#types-of-transaction-and-address?

For example,

• In check_tx, tx nonce match staking state, tx passed.
• In begin block, nonce of staking state increased because of cleanup or punishment.
• In deliver_tx, tx nonce check failed.

Another issue, from the perspective of client:

• begin block, nonce increased(uncommitted)
• query nonce, get the old(last committed) nonce.
• send tx, execution failed.

In integration tests, it happens quite frequently, public tx execution failed because of nonce mismatch.
It seems mostly caused by cleanup operation increase nonce, maybe we can remove the nonce increasing from cleanup operation.

The local node development doc is outdated as pointed out by @allthatjazzleo.

Issue:

• Some detail is covered in getting-started/signature-schemes.md;
• No documentation for multisig in client-cli side.

Expected outcomes:

• Provide additional detail in getting-started/signature-schemes.md;
• Documentation for multisig in client-cli under Wallet Management.

define precisely (somewhat "formally") in relation to Tendermint ABCI what each part does, so that this can be easily checked against the implementation:
what are data inputs from where/when
how are they processed
what are outputs and when they are emitted

ideally, this will be broken down in several pages where each page may have specific details, but there are also pages linking them together and explaining interactions.

there should be a dedicated specification page

The issue:

• Current documentation provides a link to the tendermint docs in regarding to events (see Block-level filtering)only.

https://crypto-com.github.io/getting-started/send_your_first_transaction.html#create-transfer-staking-address
it should be --type Staking instead of --type Transfer below the caption
Run another time and you will get the address that stores the unbonded funds.

It should be "94BB489D59D26358F4EBF8A024F3000DCBFA1F5D040BD0C88B18C64B45EABBAB"

From @leejw51crypto:

unbonding is now simplified to tendermint evidence duration.
add these to the documentation.

and also
duration unit is 10^9 seconds (nano seconds)
give some example to user,too

All links to implementation plan only works in the markdown preview mode, but it wont work in https://crypto-com.github.io, see the example (by clicking the " implementation plan " link)

update chain-docs with fee set up for different transaction types

• @devashishdxt @lezzokafka @allthatjazzleo: new consensus pub keys + wallets + genesis file (ideally the existing 0.3 validators will start with their addresses allocated enough bonded stake, so only "nodejoin" is required)
• @allthatjazzleo : initial council nodes (validators) + full node (query) deployment (+ new monitoring? alerts?)
• @lezzokafka @allthatjazzleo : testing node join, jailing etc.
• if all goes good, @tomtau @lezzokafka : update docs + quick notification on Gitter + update preparation
• @calvinaco @foreseaz : tx bot + existing explorer quick changes
• if all went fine, @allthatjazzleo : decommission the 0.3 testnet by May 8?

Currently, it is deployed manually to crypto-com.github.io
As, we have staging and production sites, we can host docs in https://chain.crypto.com/docs instead of github.io.
we can leverage github action to automate build and deploy to staging and production.

[email protected] docs:build /home/ubuntu/playground/chain-docs
vuepress build docs

wait Extracting site metadata...
tip Apply theme @vuepress/theme-default ...
Language does not exist: text
Language does not exist: text
Language does not exist: text
Language does not exist: text
(undefined) ./docs/modules/tdbe.md?vue&type=template&id=0fe20faa& (./node_modules/cache-loader/dist/cjs.js?{"cacheDirectory":"node_modules/@vuepress/core/node_modules/.cache/vuepress","cacheIdentifier":"cb41188e-vue-loader-template"}!./node_modules/vue-loader/lib/loaders/templateLoader.js??vue-loader-options!./node_modules/cache-loader/dist/cjs.js??ref--1-0!./node_modules/vue-loader/lib??ref--1-1!./node_modules/@vuepress/markdown-loader??ref--1-2!./docs/modules/tdbe.md?vue&type=template&id=0fe20faa&)
Module build failed (from ./node_modules/vue-loader/lib/loaders/templateLoader.js):
SyntaxError: Unexpected token (1:16172)
at Parser.pp$4.raise (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2757:13)
at Parser.pp.unexpected (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:647:8)
at Parser.pp$3.parseExprAtom (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2196:10)
at Parser. (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:6003:24)
at Parser.parseExprAtom (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:6129:31)
at Parser.pp$3.parseExprSubscripts (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2047:19)
at Parser.pp$3.parseMaybeUnary (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2024:17)
at Parser.pp$3.parseExprOps (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1966:19)
at Parser.pp$3.parseMaybeConditional (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1949:19)
at Parser.pp$3.parseMaybeAssign (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1925:19)
at Parser.pp$3.parseExprList (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2663:20)
at Parser.pp$3.parseSubscripts (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2075:29)
at Parser.pp$3.parseExprSubscripts (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2050:21)
at Parser.pp$3.parseMaybeUnary (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2024:17)
at Parser.pp$3.parseExprOp (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1985:41)
at Parser.pp$3.parseExprOps (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1968:91)
@ ./docs/modules/tdbe.md?vue&type=template&id=0fe20faa& 1:0-488 1:0-488
@ ./docs/modules/tdbe.md
@ ./node_modules/@vuepress/core/.temp/internal/page-components.js
@ ./node_modules/@vuepress/core/lib/client/util.js
@ ./node_modules/@vuepress/core/lib/client/app.js
@ ./node_modules/@vuepress/core/lib/client/clientEntry.js
@ multi ./node_modules/@vuepress/core/lib/client/clientEntry.js
(undefined) ./docs/modules/tdbe.md?vue&type=template&id=0fe20faa& (./node_modules/cache-loader/dist/cjs.js?{"cacheDirectory":"node_modules/@vuepress/core/node_modules/.cache/vuepress","cacheIdentifier":"520cc585-vue-loader-template"}!./node_modules/vue-loader/lib/loaders/templateLoader.js??vue-loader-options!./node_modules/cache-loader/dist/cjs.js??ref--1-0!./node_modules/vue-loader/lib??ref--1-1!./node_modules/@vuepress/markdown-loader??ref--1-2!./docs/modules/tdbe.md?vue&type=template&id=0fe20faa&)
Module build failed (from ./node_modules/vue-loader/lib/loaders/templateLoader.js):
SyntaxError: Unexpected token (1:16172)
at Parser.pp$4.raise (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2757:13)
at Parser.pp.unexpected (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:647:8)
at Parser.pp$3.parseExprAtom (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2196:10)
at Parser. (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:6003:24)
at Parser.parseExprAtom (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:6129:31)
at Parser.pp$3.parseExprSubscripts (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2047:19)
at Parser.pp$3.parseMaybeUnary (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2024:17)
at Parser.pp$3.parseExprOps (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1966:19)
at Parser.pp$3.parseMaybeConditional (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1949:19)
at Parser.pp$3.parseMaybeAssign (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1925:19)
at Parser.pp$3.parseExprList (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2663:20)
at Parser.pp$3.parseSubscripts (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2075:29)
at Parser.pp$3.parseExprSubscripts (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2050:21)
at Parser.pp$3.parseMaybeUnary (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:2024:17)
at Parser.pp$3.parseExprOp (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1985:41)
at Parser.pp$3.parseExprOps (/home/ubuntu/playground/chain-docs/node_modules/vue-template-es2015-compiler/buble.js:1968:91)
@ ./docs/modules/tdbe.md?vue&type=template&id=0fe20faa& 1:0-488 1:0-488
@ ./docs/modules/tdbe.md
@ ./node_modules/@vuepress/core/.temp/internal/page-components.js
@ ./node_modules/@vuepress/core/lib/client/util.js
@ ./node_modules/@vuepress/core/lib/client/app.js
@ ./node_modules/@vuepress/core/lib/client/serverEntry.js
@ multi ./node_modules/@vuepress/core/lib/client/serverEntry.js
Error: Failed to compile with errors.
at webpack (/home/ubuntu/playground/chain-docs/node_modules/@vuepress/core/lib/node/build/index.js:180:16)
at finalCallback (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/MultiCompiler.js:254:12)
at runWithDependencies.err (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/MultiCompiler.js:277:6)
at done (/home/ubuntu/playground/chain-docs/node_modules/neo-async/async.js:2931:13)
at runCompilers (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/MultiCompiler.js:181:48)
at err (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/MultiCompiler.js:188:7)
at compiler.run (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/MultiCompiler.js:270:7)
at finalCallback (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/Compiler.js:257:39)
at hooks.done.callAsync.err (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/Compiler.js:273:13)
at AsyncSeriesHook.eval [as callAsync] (eval at create (/home/ubuntu/playground/chain-docs/node_modules/tapable/lib/HookCodeFactory.js:33:10), :15:1)
at AsyncSeriesHook.lazyCompileHook (/home/ubuntu/playground/chain-docs/node_modules/tapable/lib/Hook.js:154:20)
at onCompiled (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/Compiler.js:271:21)
at hooks.afterCompile.callAsync.err (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/Compiler.js:681:15)
at AsyncSeriesHook.eval [as callAsync] (eval at create (/home/ubuntu/playground/chain-docs/node_modules/tapable/lib/HookCodeFactory.js:33:10), :6:1)
at AsyncSeriesHook.lazyCompileHook (/home/ubuntu/playground/chain-docs/node_modules/tapable/lib/Hook.js:154:20)
at compilation.seal.err (/home/ubuntu/playground/chain-docs/node_modules/webpack/lib/Compiler.js:678:31)

npm ERR! Linux 5.3.0-1031-azure
npm ERR! argv "/usr/bin/node" "/usr/bin/npm" "run" "docs:build"
npm ERR! node v8.10.0
npm ERR! npm v3.5.2
npm ERR! code ELIFECYCLE
npm ERR! [email protected] docs:build: vuepress build docs
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] docs:build script 'vuepress build docs'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the demo-doc-2 package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR! vuepress build docs
npm ERR! You can get information on how to open an issue for this project with:
npm ERR! npm bugs demo-doc-2
npm ERR! Or if that isn't available, you can get their info via:
npm ERR! npm owner ls demo-doc-2
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR! /home/ubuntu/playground/chain-docs/npm-debug.log

as mentioned in the related implementation issue:

In particular, as the code runs inside enclaves, 1) it's trusted (-> needs to be simple and small without too many dependencies), 2) there's no "trusted" persistent storage (in particular, the host may replay the old state.

With regards to "light client state" / trusted anchor, it implies two parts:

1. (no state) the full genesis.json isn't known before TDBE is compiled: https://github.com/crypto-com/chain-docs/blob/master/docs/modules/tdbe.md#genesisjson-creation -- but some parts of it should be known and should be compile-time parameters crypto-com/thaler#1996 that are cross-checked
2. once a node "successfully" joins (either valid genesis.json with related mls/keypackage payload OR valid committed nodejointx) OR updates (successful committed SelfUpdateProposal after NACK timeout), it can "seal" its identity+HPKE keys altogether with the "light client state" at that point

”How it works
chain-tx-enclave (use intel sgx) -> working as dockerchain-abci (connects to enclave) tendermint (connects to chain-abci)”

Expected outcomes:

• Brief introduction at getting-started/send_your_first_transaction.md ;
• Includes import/export tx under client-cli in wallet management (wallets/client-cli);
• Link between the above two .

monetary params -- unbonding period, fee policy, minimal stakes...

if the outcome depends on network parameters, each parameter needs to be justified:
what it does
what are its constraints
what its relation to Tendermint core consensus security assumptions is -- "nothing-at-stake" problem, consensus-critical parameters set in Tendermint (evidence age, etc.), ...
what it should be set to -- if it is not given (like total maximum supply), the recommended value should be given with justification / reference explaining why, e.g. based on mechanism design simulation models

Tendermint has to be initiated before the step: "Run chain components",
if not, error message
ERROR: Failed to create node: Couldn't read GenesisDoc file: open /tendermint/config/genesis.json: no such file or directory

Suggested solutions:

• Easy one : add make prepare ( See the make file )
• Or just include make prepare in make run ?

https://github.com/crypto-com/chain-docs/blame/master/plan.md#L214-L215

"Client/Wallet" -> TQE: decryption init request
TQE -> "Client/Wallet": decryption init request challenge

has no further details.

need fairness explanation / update how votes are processed

define precisely (somewhat "formally") in relation to Tendermint ABCI what each part does, so that this can be easily checked against the implementation:
what are data inputs from where/when
how are they processed
what are outputs and when they are emitted

Provide deposit example in staking operations, which includes:

• Checking the Tx-id with client-cli;
• Deposit demonstration

On the page https://chain.crypto.com/docs/protocol/serialization.html#test-vectors, the link of Polkadot Host Protocol Specification is invalid, need to be updated.

Possible solution:

1. Deployment of staging: comment "/RUN" in PR only by limited collaborators i.e tomas and lesile, etc.
2. Deployment of production: only happen when merge to master

Currently, it just says these are the parameters and this is how stuff is calculated: https://crypto-com.github.io/getting-started/staking.html#rewards
but it doesn't explain what setting each term does

• description of the expected structure referring to the IETF doc.

https://github.com/crypto-com/chain/pull/1684/files#diff-f82b1fb372c07b9409f261820dccebc6R325

Following the instructions here https://crypto-com.github.io/getting-started/#compile-enclave the compile fails (and it's pointing to an archived repo too) so I think it may be out of date?

Currently, the protocol in the implementation plan: https://github.com/crypto-com/chain-docs/blob/master/plan.md#key-generation-and-rotation
describes 2-steps that all nodes will be expected to generate random payloads, broadcasts signed commitments to those payloads, and then broadcast those payloads.

This may be simplified a bit, some ideas:

• "0 steps" (but with no auth outside the group -- but it may be fine): latest MLS draft defines an "exporter": https://tools.ietf.org/html/draft-ietf-mls-protocol-09#section-7.11 -- similar to https://tools.ietf.org/html/rfc5705 so it can be used for a keying material -- e.g. new obfuscation key could be just defined as something like MLS-Exporter("tx_obfuscation_key", block_height_this_was_initiated, AES_GCM_SIV_KEY_LEN) ... so gets refreshed every time the group changes/updates

• "1 step": https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-vrf-06#section-5.1 -- generate a key pair using "MLS-Exporter"; public key broadcasted outside; ECVRF_prove to generate a secret... or each node having a dedicated key pair and then sending outputs of ECVRF_prove as application messages.

...
Will need to think about it more, but 0 step may be fine

@foreseaz feel free to submit a PR with thing you recorded