docs: Fixes #157. Add Gitbook documentation for Polkadot-JS Common (#231)

* fix: Remove prior docs attempt files

* docs: Add Gitbook docs for common repo with examples. See detailed comments

* Remove old attempt at docs in docs/ folders

* Add Typedoc config typedoc.js

* Add .nvmrc for easily switching Node.js version with NVM

* Add ESLint config .eslintrc.json and .eslintignore

* Fix in tsconfig.json so is keyring not util-keyring

* Update package.json with dependencies and script same as in polkadot-js/api

* Update root README fixing CI icons, adding guide same as in polkadot-js/api, and fixing link to keyring, not util-keyring

* Update root .gitignore with Gitbook build files same as in polkadot-js/api

* Add Gitbook docs structure same as in polkadot-js/api

* Add Gitbook examples for keyring, trie-db, util-crypto

* Add Gitbook outer summary for the menu, Readme, logo and styles same as in polkadot-js/api

* Add Gitbook config book.json

* docs: Remove db and util-rlp from Gitbook summary menu since RLP not in PoC-3

* docs: Add Typedocs with examples for db MemoryDb and DiskDb

* docs: Update db/ Readme with CI icons fixed, and indicating that no methods exposed in Common Docs

* docs: Update keyring Readme with CI icons fixed and link to Common Docs

* fix: Fix keyring package.json info to refer to common, not client

* fix: Updates license in 4x files in keyring/address folder with keyring, not util-keyring

* docs: Add Typedocs to Keyring class, pair function, and testKeyring function

* docs: Update keyring Readme with CI icons fixed and link to Common Docs

* fix: Update package.json moving @polkadot/db from devDependencies to dependencies

* fix: Update test to iterate array not object with forEach

* fix: Use semicolon instead of comma in tests to fix linting errors. Fix typo

* docs: Add Typedoc to Trie class

* docs: Add Typedoc to is functions

* docs: Update keyring Readme with CI icons fixed and link to Common Docs

* fix: Add return type to encodeAux function

* docs: Add Typedoc to encode function

* fix: Fix formatting of Typedoc example for root

* docs: Add Typedoc for genRoot

* docs: Add Typedoc for pairsUniq

* docs: Add Typedoc for getSharedLength

* docs: Add Typedoc for sharedPrefixLength

* fix: Fix formatting of Typedoc example for rootOrdered, asNibbles, fromNibbles

* fix: Various fixes to util-crypto. See commit detail comments

* Update root Readme with class and function info
* Fix typos and Typedoc examples
* Expose mnemonic by exporting it in an index.ts
* Fix naming from naclKeypair to naclKeypairFromRandom
* Fix typos
* Fix randomAsU8s to be randomAsU8a
* Fix spelling of bitLength

* fix: Various fixes to util-rlp. See detailed commit comments

* Update keyring Readme with CI icons fixed and link to Common Docs mentioning since RLP not in PoC-3 nothing exposed in Common Docs
* Add Typedocs
* Move Typedocs to different file so they appear in Common Docs

* fix: Various fixes to util. See detailed commit comments

* Update root Readme to use Yarn and list and explain exposed Common Docs methods
* Fix typos and Typedoc examples

* fix: Restore tests back using variable they were iterating over before

* docs: Move nested part of Summary to individual package Readme. Add Usage to Readmes

* fix: Add missing semicolon to existing test

* fix: Remove docs/gitbook folder and files since generated by CI

* feat: Update Gitignore to ignore CI-generated files like .html and docs/gitbook/ folder

* docs: Remove CI-icons from all packages within polkadot-js/common, except its root Readme

* fix: Update to incorporate changes from PR #233 and #229

* fix: Ignore build directories in Jest tests using modulePathIgnorePatterns

* fix: Remove useless docs/html from .gitignore since there is no html subdirectory

* fix: Update util-crypto README with link to mnemonicToSeed instead of toSecret

* docs: Update keyring create account example to show result to user

* fix: Update dependencies in examples so the examples work again

* fix: Update keyring example 02 load accounts not to use addFromAddress

* fix: Update .gitignore so it is suitable for both polkadot-js common and api

* fix: Adjust .gitignore after testing changes that work with polkadot-js api too

* fix: Resolve .gitignore to overcome FileNotFoundError: No README file (or is ignored)

* fix: Remove from Git tracking docs/.nojekyll since generated

* fix: Add lerna to gitignore to match api repo

* Revert to original .gitignore. Does not work without Gitbooks files Git tracked

* docs: Hide trie-db Examples since have limited use
This commit is contained in:
Luke Schoen
2018-10-19 17:33:58 +02:00
committed by Jaco Greeff
parent 1cb7bfd9b4
commit 1fb1f9d743
174 changed files with 2158 additions and 709 deletions
+1
View File
@@ -0,0 +1 @@
yarn.lock
@@ -0,0 +1,5 @@
# Create Account
The following example shows how to create and account with keyring.
[include](index.js)
+19
View File
@@ -0,0 +1,19 @@
// Import Keyring class and utility function
const Keyring = require('@polkadot/keyring').default;
const stringToU8a = require('@polkadot/util/string/toU8a').default;
async function main () {
// Create account seed for Alice
const ALICE_SEED = 'Alice'.padEnd(32, ' ');
// Create an instance of the Keyring
const keyring = new Keyring();
// Create pair and add Alice to keyring pair dictionary (with account seed)
const pairAlice = keyring.addFromSeed(stringToU8a(ALICE_SEED));
console.log(`Created keyring pair for Alice with address: ` +
`${keyring.getPair(pairAlice.address()).address()}`);
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,19 @@
{
"name": "01_create_account",
"version": "0.1.0",
"description": "Example showing how to create an account",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/util": "^0.32.2",
"@polkadot/keyring": "^0.32.1"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
@@ -0,0 +1,5 @@
# Load Accounts
The following example shows how to load all accounts from the keyring as pairs and convert them into JSON format.
[include](index.js)
+31
View File
@@ -0,0 +1,31 @@
// Import Keyring class and utility function
const Keyring = require('@polkadot/keyring').default;
const stringToU8a = require('@polkadot/util/string/toU8a').default;
async function main () {
// Create account seed for Alice and Bob
const ALICE_SEED = 'Alice'.padEnd(32, ' ');
const BOB_SEED = 'Bob'.padEnd(32, ' ');
// Create an instance of the Keyring
const keyring = new Keyring();
// Create their pairs with account seeds. Add to keyring pair dictionary
keyring.addFromSeed(stringToU8a(ALICE_SEED));
keyring.addFromSeed(stringToU8a(BOB_SEED));
// Note that we did not use `addFromAddress` since it does not add the
// secret key to memory so we cannot later retrieve it with `getPairs`
// Retrieve all keyring pairs from the keyring pair dictionary
keyring
.getPairs()
.forEach((pair, index) => {
const address = pair.address();
console.log(`${index} account has json: `,
JSON.stringify(keyring.toJson(address), null, 2));
});
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,19 @@
{
"name": "02_load_accounts",
"version": "0.1.0",
"description": "Example showing how to load accounts",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/util": "^0.32.2",
"@polkadot/keyring": "^0.32.1"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
+12
View File
@@ -0,0 +1,12 @@
# Keyring Examples
Here you will find a list of examples that takes you through the basics of connecting to a local node, retrieving data from the Node and chain and execute transactions on the chain.
## Running the examples
From within each folder run the following to install required dependencies and to execute the example:
```shell
yarn;
yarn start
```
@@ -0,0 +1,5 @@
# Create Patricia Trie
The following example shows how to create a Patricia Trie.
[include](index.js)
+13
View File
@@ -0,0 +1,13 @@
const Trie = require('@polkadot/trie-db').default;
async function main () {
const trie = new Trie();
// Open the database for each of the trie instances
trie.open();
// Initial root value is valid
console.log(`Initial root Uint8Array value: ${trie.getRoot()}`);
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,19 @@
{
"name": "01_create_patricia_trie",
"version": "0.1.0",
"description": "Example showing how to create a Patricia Trie",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/trie-db": "^0.32.1",
"@polkadot/db": "^0.32.2"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
@@ -0,0 +1,5 @@
# Get & Set & Delete Trie Nodes
The following example shows how to get, set, and delete nodes of a Patricia Trie.
[include](index.js)
+48
View File
@@ -0,0 +1,48 @@
const toU8a = require('@polkadot/util/u8a/toU8a').default;
const Trie = require('@polkadot/trie-db').default;
async function main () {
const trie = new Trie();
// Open the database for each of the trie instances
trie.open();
// Initial root value is valid
console.log(`Initial root Uint8Array value: ${trie.getRoot()}`);
// Create a branch under the trie root with a key of 'test' and a value of 'one'
trie.put(toU8a('test'), toU8a('one'));
// Store the root hash of the trie root node in a variable
const trieRootNodeHash = trie.getRoot();
// Store the root node object in a variable
const trieRootNode = trie.getNode(trieRootNodeHash);
// Show the node object of the root node hash
console.log(`Root node object: ${trieRootNode}`);
// Show the updated root hash value of the trie root node
console.log(`Updated root hash value: ${trie.getRoot()}`);
const branch = trie.get(toU8a('test'));
// Retrieve the value of a given key named 'test' in the trie
console.log(`Current value of key 'test': ${branch}`);
// Deletes the value of a given key named 'test' in the trie branch
trie.del(toU8a('test'));
// Retrieve the value of a given key named 'test' in the trie
console.log(`Updated value of key 'test' after deleting it: ${trie.get(toU8a('test'))}`);
// Set the root hash value of the trie root node (if necessary)
trie.setRoot(trieRootNodeHash);
// Show the node object of the root node hash
console.log(`Root node object: ${trie.getRoot()}`);
// Retrieve the value of a given key named 'test' in the trie
console.log(`Restored value of key 'test' after restoring root node: ${branch}`);
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,19 @@
{
"name": "02_get_set_del_trie_nodes",
"version": "0.1.0",
"description": "Example showing how to get, set, and delete nodes of a Patricia Trie",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/trie-db": "^0.32.1",
"@polkadot/db": "^0.32.2"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
@@ -0,0 +1,5 @@
# Duplicate Patricia Trie with Snapshot
The following example shows how to duplicate a Patricia Trie by taking a snapshot.
[include](index.js)
@@ -0,0 +1,24 @@
const Trie = require('@polkadot/trie-db').default;
async function main () {
const trie = new Trie();
// Use `back` to later store a snapshot of the `trie`
const back = new Trie();
// Open the database for each of the trie instances
trie.open();
back.open();
// Initial root value is valid
console.log(`Initial root Uint8Array value: ${trie.getRoot()}`);
// Create a snapshot of the `trie` data into `back`
trie.snapshot(back, () => {});
// Show value of snapshot's root is same as original trie's root
console.log(`Snapshot root value matches original trie root: ` +
`${back.getRoot() === trie.getRoot()}`);
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,19 @@
{
"name": "03_duplicate_trie_with_snapshot",
"version": "0.1.0",
"description": "Example showing how to duplicate Patricia Trie nodes with a snapshot",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/trie-db": "^0.32.1",
"@polkadot/db": "^0.32.2"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
@@ -0,0 +1,5 @@
# Show Size and Node Info of a Patricia Trie
The following example shows how to show the size and node information of a Patricia Trie.
[include](index.js)
+65
View File
@@ -0,0 +1,65 @@
const toU8a = require('@polkadot/util/u8a/toU8a').default;
const Trie = require('@polkadot/trie-db').default;
const {
isEmptyNode,
isKvNode,
isExtensionNode,
isLeafNode,
isBranchNode
} = require('@polkadot/trie-db/util/is');
async function main () {
const trie = new Trie();
// Use `back` to later store a snapshot of the `trie`
const back = new Trie();
// Open the database for each of the trie instances
trie.open();
back.open();
// Initial root value is valid
console.log(`Initial root Uint8Array value: ${trie.getRoot()}`);
// Create two branches under the trie root with
// key 'branch1' and 'branch2' and a values of 'one' and 'two'
trie.put(toU8a('test'), toU8a('one'));
trie.put(toU8a('test'), toU8a('two'));
// Store the root hash of the trie root node in a variable
const trieRootNodeHash = trie.getRoot();
// Store the root node object in a variable
const trieRootNode = trie.getNode(trieRootNodeHash);
// Show the node object of the root node hash
console.log(`Root node object: ${trieRootNode}`);
// Show information about the trie node
console.log(`Is root node object empty? : ${isEmptyNode(trieRootNode)}`);
console.log(`Is root node object a KV node? : ${isKvNode(trieRootNode)}`);
// Show information about the trie that is Merkle Patricia Trie specific
// Reference: https://github.com/ethereum/wiki/wiki/Patricia-Tree#optimization
console.log(`Is root node object an Extension node? : ${isExtensionNode(trieRootNode)}`);
console.log(`Is root node object an Leaf node? : ${isLeafNode(trieRootNode)}`);
console.log(`Is root node object an Branch node? : ${isBranchNode(trieRootNode)}`);
// Retrieve the value of a given key named 'test' in the trie
console.log(`Current value of key 'test': ${trie.get(toU8a('test'))}`);
// Create a snapshot of the `trie` data into `back`
trie.snapshot(back, () => {});
// Show that value of the snapshot's root is the same as the original trie's root
console.log(`Snapshot root value matches original trie root: ${back.getRoot() === trie.getRoot()}`);
// Deletes the value of a given key named 'test' in the trie branch
trie.del(toU8a('test'));
// Show size of the database for each of the trie instances
console.log(`Size of 'trie' database: ${trie.size()}`);
console.log(`Size of 'back' database: ${back.size()}`);
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,19 @@
{
"name": "04_show_size_trie_node_info",
"version": "0.1.0",
"description": "Example showing how to show size and node info of a Patricia Trie",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/trie-db": "^0.32.1",
"@polkadot/db": "^0.32.2"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
@@ -0,0 +1,5 @@
# Empty & Close & Drop a Patricia Trie
The following example shows how to empty, close, and drop a Patricia Trie.
[include](index.js)
+55
View File
@@ -0,0 +1,55 @@
const toU8a = require('@polkadot/util/u8a/toU8a').default;
const Trie = require('@polkadot/trie-db').default;
const {
isEmptyNode,
isKvNode
} = require('@polkadot/trie-db/util/is');
async function main () {
const trie = new Trie();
// Open the database for each of the trie instances
trie.open();
// Initial root value is valid
console.log(`Initial root Uint8Array value: ${trie.getRoot()}`);
// Create a branch under the trie root with a key of 'branch1' and 'branch2'
// and a value of 'one' and 'two'
trie.put(toU8a('branch1'), toU8a('one'));
trie.put(toU8a('branch2'), toU8a('two'));
// Retrieve the value of a given key named 'branch1' and 'branch2' in the trie
console.log(`Stored value of key 'branch1': ${trie.get(toU8a('branch1'))}`);
console.log(`Stored value of key 'branch2': ${trie.get(toU8a('branch2'))}`);
// Store the root hash of the trie root node in a variable
const trieRootNodeHash = trie.getRoot();
// Store the root node object in a variable
const trieRootNode = trie.getNode(trieRootNodeHash);
// Show information about the trie node
console.log(`Is root node object empty? : ${isEmptyNode(trieRootNode)}`);
console.log(`Is root node object a KV node? : ${isKvNode(trieRootNode)}`);
// Deletes the value of a given key named 'branch1' in the trie branch
trie.del(toU8a('branch1'));
// Retrieve the value of a given key named 'test' in the trie
console.log(`Stored value of key 'branch1': ${trie.get(toU8a('branch1'))}`);
// Empty, close, and drop the database for each of the trie instances
trie.empty();
// Retrieve the value of a given key named 'test' in the trie
console.log(`Stored value of key 'branch2': ${trie.get(toU8a('branch2'))}`);
// Close the trie
trie.close();
// Drop the trie
trie.drop();
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,19 @@
{
"name": "05_empty_close_drop_trie",
"version": "0.1.0",
"description": "Example showing how to empty, close, and drop a Patricia Trie",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/trie-db": "^0.32.1",
"@polkadot/db": "^0.32.2"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
+12
View File
@@ -0,0 +1,12 @@
# Trie-DB Examples
Here you will find a list of examples that takes you through the basics of creating a Patricia Trie, creating key/value pair branches, retrieving the value of a branch with its key, deleting branches, saving the root node hash to a variable and then later setting the root node hash to restore the trie to its previous state, duplicating the trie with a snapshot, showing the size of the trie and other node information, and emptying, closing, and dropping the trie.
## Running the examples
From within each folder run the following to install required dependencies and to execute the example:
```shell
yarn;
yarn start
```
@@ -0,0 +1,5 @@
# Encrypt & Decrypt Message using NaCl
The following example shows how to encrypt and decrypt a message with NaCl (pronouced "salt"), which is a Networking and Cryptography library used in util-crypto.
[include](index.js)
@@ -0,0 +1,24 @@
const { naclEncrypt } = require('@polkadot/util-crypto');
const { naclDecrypt } = require('@polkadot/util-crypto');
async function main () {
const secret = new Uint8Array(32);
const messagePreEncryption = new Uint8Array([1, 2, 3, 4, 5, 4, 3, 2, 1]);
const noncePreEncryption = new Uint8Array(24);
// Encrypt the message
const { encrypted, nonce } = naclEncrypt(messagePreEncryption, secret, noncePreEncryption);
// Show contents of the encrypted message
console.log(`Encrypted message: ${JSON.stringify(encrypted, null, 2)}`);
// Decrypt the message
const messageDecrypted = naclDecrypt(encrypted, nonce, secret);
// Convert each Uint8Array to a string for comparison
const isMatch = messagePreEncryption.toString === messageDecrypted.toString;
// Verify that the decrypted message matches the original message
console.log(`Does the decrypted message match the original message? ${isMatch}`);
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,18 @@
{
"name": "01_encrypt_decrypt_message_nacl",
"version": "0.1.0",
"description": "Example showing how to encrypt and decrypt a message using NaCl",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/util-crypto": "^0.32.2"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
@@ -0,0 +1,5 @@
# Sign & Verify Message using NaCl
The following example shows how to sign and verify a message with NaCl (pronouced "salt"), which is a Networking and Cryptography library used in util-crypto.
[include](index.js)
@@ -0,0 +1,32 @@
const stringToU8a = require('@polkadot/util/string/toU8a').default;
const { randomAsU8a } = require('@polkadot/util-crypto');
const { naclKeypairFromSeed } = require('@polkadot/util-crypto');
const { naclEncrypt } = require('@polkadot/util-crypto');
const { naclSign } = require('@polkadot/util-crypto');
const { naclVerify } = require('@polkadot/util-crypto');
async function main () {
// Create account seed for Alice as fallback if generated mnemonic not valid
const seedAlice = 'Alice'.padEnd(32, ' ');
// Generate new public/secret keypair for Alice from the supplied seed
const { secretKey, publicKey } = naclKeypairFromSeed(stringToU8a(seedAlice));
// Encrypt message. Create Uint8Array's filled with random bytes of specified length
const secret = randomAsU8a(32);
const messagePreEncryption = stringToU8a('please send me DOTs');
const noncePreEncryption = randomAsU8a(24);
const { encrypted, nonce } = naclEncrypt(messagePreEncryption, secret, noncePreEncryption);
// Sign the message with a valid signature
const messageSignature = naclSign(encrypted, secretKey);
// Validate that the message was correctly signed
const isValidSignature = naclVerify(encrypted, messageSignature, publicKey);
console.log(`Was the message correctly signed? ${isValidSignature}`);
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,18 @@
{
"name": "02_sign_verify_message_nacl",
"version": "0.1.0",
"description": "Example showing how to sign and verify a message using NaCl",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/util-crypto": "^0.32.2"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
@@ -0,0 +1,5 @@
# Create & Generate Mnemonic using BIP39
The following example shows how to create and generate mnemonics using BIP39.
[include](index.js)
@@ -0,0 +1,26 @@
const { mnemonicGenerate } = require('@polkadot/util-crypto');
const { mnemonicToSeed } = require('@polkadot/util-crypto');
const { mnemonicValidate } = require('@polkadot/util-crypto');
const { toSecret } = require('@polkadot/util-crypto');
const { naclKeypairFromSeed } = require('@polkadot/util-crypto');
async function main () {
// Create mnemonic string for Alice using BIP39
const mnemonicAlice = mnemonicGenerate();
// Validate the mnemic string that was generated
const isValidMnemonic = mnemonicValidate(mnemonicAlice);
console.log(`isValidMnemonic: ${isValidMnemonic}`);
// Create valid seed from mnemonic as u8a and convert it to a string
// FIXME - Replace with mnemonicToSeed once exposed
const seedAlice = mnemonicToSeed(mnemonicAlice);
// Generate new public/secret keypair for Alice from the supplied seed
const { secretKey, publicKey } = naclKeypairFromSeed(seedAlice);
// Encrypt, Sign and Validate the message. See Example 'Sign & Verify Message'
}
main().catch(console.error).finally(_ => process.exit());
@@ -0,0 +1,18 @@
{
"name": "02_sign_verify_message_nacl",
"version": "0.1.0",
"description": "Example showing how to sign and verify a message using NaCl",
"main": "index.js",
"author": "ltfschoen",
"license": "MIT",
"scripts": {
"clean": "rimraf node_modules",
"start": "node index.js"
},
"dependencies": {
"@polkadot/util-crypto": "^0.32.2"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}
+13
View File
@@ -0,0 +1,13 @@
# Util-Crypto Examples
Here you will find a list of examples that takes you through the basics of encrypting and decrypting messages using NaCl, signing a message with a seed and verifying it using NaCl, and generating and validating mnemonics for account seeds.
## Running the examples
From within each folder run the following to install required dependencies and to execute the example:
```shell
yarn;
yarn start
```