docs: add quick start guide to example section

This commit is contained in:
Tzu-Jung Lee 2018-08-08 12:13:42 -07:00
parent ee78f16ecc
commit 38ec2ba48c
2 changed files with 212 additions and 168 deletions

View file

@ -4,25 +4,15 @@ coming soon
## Installation
coming soon
## Usage
coming soon
## Running from Source
This project requires [Go v1.10](https://golang.org/doc/install) or higher.
``` bash
go get -u -v github.com/lbryio/claimtrie
```
## Examples
## Usage
Refer to [claimtrie](https://github.com/lbryio/claimtrie/blob/master/cmd/claimtrie) for an interactive CLI tool.
Refer to [claimtrie](https://github.com/lbryio/claimtrie/blob/master/cmd/claimtrie) for an interactive CLI tool as example.
``` quote
``` block
NAME:
claimtrie - A CLI tool for LBRY ClaimTrie
@ -33,15 +23,20 @@ VERSION:
0.0.1
COMMANDS:
add-claim, ac Claim a name with specified amount. (outPoint is generated randomly, if unspecified)
add-support, as Add support to a specified Claim. (outPoint is generated randomly, if unspecified)
spend-claim, sc Spend a specified Claim.
add-claim, ac Claim a name.
spend-claim, sc Spend a Claim.
update-claim, uc Update a Claim.
add-support, as Support a Claim.
spend-support, ss Spend a specified Support.
show, s Show the Key-Value pairs of the Stage or specified commit. (links nodes are showed if -a is also specified)
merkle, m Show the Merkle Hash of the Stage.
commit, c Commit the current Stage to commit database.
reset, r Reset the Stage to a specified commit.
show, s Show the status of nodes)
merkle, m Show the Merkle Hash of the ClaimTrie.
commit, c Commit the current changes to database.
reset, r Reset the Head commit and a specified commit (by Height).
log, l List the commits in the coommit database.
ipmort, i Import changes from datbase.
load, ld Load nodes from datbase.
save, sv Save nodes to datbase.
erase Erase datbase
shell, sh Enter interactive mode
help, h Shows a list of commands or help for one command
@ -50,6 +45,13 @@ GLOBAL OPTIONS:
--version, -v print the version
```
## Running from Source
This project requires [Go v1.10](https://golang.org/doc/install) or higher.
## Examples
## Testing
``` bash
@ -72,4 +74,4 @@ Our PGP key is [here](https://keybase.io/lbry/key.asc) if you need it.
## Contact
The primary contact for this project is [@roylee17](https://github.com/roylee17) (roylee@lbry.io)
The primary contact for this project is [@roylee17](https://github.com/roylee17) (roylee@lbry.io) or [@lyoshenka](https://github.com/lyoshenka) (grin@lbry.io)

View file

@ -4,7 +4,9 @@ coming soon
## Installation
coming soon
``` bash
go get -u github.com/lbryio/claimtrie/cmd/claimtrie
```
## Usage
@ -19,15 +21,20 @@ VERSION:
0.0.1
COMMANDS:
add-claim, ac Claim a name with specified amount. (outPoint is generated randomly, if unspecified)
add-support, as Add support to a specified Claim. (outPoint is generated randomly, if unspecified)
spend-claim, sc Spend a specified Claim.
add-claim, ac Claim a name.
spend-claim, sc Spend a Claim.
update-claim, uc Update a Claim.
add-support, as Support a Claim.
spend-support, ss Spend a specified Support.
show, s Show the Key-Value pairs of the Stage or specified commit. (links nodes are showed if -a is also specified)
merkle, m Show the Merkle Hash of the Stage.
commit, c Commit the current Stage to commit database.
reset, r Reset the Stage to a specified commit.
show, s Show the status of nodes)
merkle, m Show the Merkle Hash of the ClaimTrie.
commit, c Commit the current changes to database.
reset, r Reset the Head commit and a specified commit (by Height).
log, l List the commits in the coommit database.
ipmort, i Import changes from datbase.
load, ld Load nodes from datbase.
save, sv Save nodes to datbase.
erase Erase datbase
shell, sh Enter interactive mode
help, h Shows a list of commands or help for one command
@ -41,163 +48,198 @@ GLOBAL OPTIONS:
This project requires [Go v1.10](https://golang.org/doc/install) or higher.
``` bash
go get -u -v github.com/lbryio/claimtrie/cmd/claimtrie
go run ${GOPATH}/src/github.com/lbryio/claimtrie/cmd/claimtrie/main.go sh
```
Or build and run as executable
``` bash
go build ${GOPATH}/src/github.com/lbryio/claimtrie/cmd/claimtrie/main.go
./claimtrie
```
## Examples
Adding claims.
Import (replay) claim scripts saved from the LBRY mainnet.
We need to run the lbrycrd.go to produce the dataset.
Let it run for 15 - 30 mins until we sync 400K blocks of claim scripts to test with.
(It's currently hard coded to exit one 400k blocks are collected.)
``` block
claimtrie > add-claim
claimtrie > show
<BestBlock: 0>
Hello : {
"Hash": "91185db0db792a6f6ad60e01e99e27f5263b8c3225137ff3b33bd5d3ebe197bd",
"Tookover": 0,
"BestClaim": {
"OutPoint": "5fed5c7a39d47b4432b55d172b312df87142995e83ef28bf070859e94c916f30:48",
"ClaimID": "911771619d4e6656bc0f08e1dfab5827756ed39d",
"Amount": 44,
"EffectiveAmount": 44,
"Accepted": 0,
"ActiveAt": 0
},
"Claims": [
{
"OutPoint": "5fed5c7a39d47b4432b55d172b312df87142995e83ef28bf070859e94c916f30:48",
"ClaimID": "911771619d4e6656bc0f08e1dfab5827756ed39d",
"Amount": 44,
"EffectiveAmount": 44,
"Accepted": 0,
"ActiveAt": 0
},
{
"OutPoint": "db993d544e0cbea83cff2465d3a8615cfc0750d39aa904a60e8fafab7c315a50:80",
"ClaimID": "013df2835b1b8256ed019cc71df2dfb61fdce63c",
"Amount": 10,
"EffectiveAmount": 10,
"Accepted": 0,
"ActiveAt": 0
}
],
"Supports": []
}
claimtrie > commit
go get -u github.com/btcsuite/btcd
cd $GOPATH/src/github.com/btcsuite/btcd
git remote add lbryio git@github.com:lbryio/lbrycrd.go
git fetch --all
git checkout -b dev -m lbryio/dev
go build -i && ./btcd
```
Commit another claim.
Enter interactive mode
``` block
claimtrie > add-claim --amount 100
claimtrie > commit
```
``` bash
go run ${GOPATH}/src/github.com/lbryio/claimtrie/cmd/claimtrie/main.go sh
Show logs
opened "/Users/roylee17/Library/Application Support/Lbrycrd.go/data/trie.db"
opened "/Users/roylee17/Library/Application Support/Lbrycrd.go/data/nm.db"
opened "/Users/roylee17/Library/Application Support/Lbrycrd.go/data/commit.db"
``` block
claimtrie > log
height: 2, commit 9e2a2cf0e7f2a60e195ce46b261d6a953a3cbb68ef6b3274543ec8fdbf8a171b
height: 1, commit ce548249c28d61920d69ac759b82f53b5da52fa611f055c4f44c2d94703667a1
height: 0, commit 0000000000000000000000000000000000000000000000000000000000000001
```
Show current status.
``` block
claimtrie > show
<BestBlock: 2>
Hello : {
"Hash": "82629d2e9fb1eb8cc78e9d6712f217d5322f1cd9a3cdd15bf3923ee2d9376e94",
"Tookover": 1,
"BestClaim": {
"OutPoint": "0f2fb103891bdf34344d34a64403537653d344558ebd3138b45e770585950d6e:110",
"ClaimID": "128f9a84dddc87afdb747e04c6ce22726d2a90e7",
"Amount": 100,
"EffectiveAmount": 100,
"Accepted": 1,
"ActiveAt": 1
},
"Claims": [
{
"OutPoint": "5fed5c7a39d47b4432b55d172b312df87142995e83ef28bf070859e94c916f30:48",
"ClaimID": "911771619d4e6656bc0f08e1dfab5827756ed39d",
"Amount": 44,
"EffectiveAmount": 44,
"Accepted": 0,
"ActiveAt": 0
},
{
"OutPoint": "0f2fb103891bdf34344d34a64403537653d344558ebd3138b45e770585950d6e:110",
"ClaimID": "128f9a84dddc87afdb747e04c6ce22726d2a90e7",
"Amount": 100,
"EffectiveAmount": 100,
"Accepted": 1,
"ActiveAt": 1
},
{
"OutPoint": "db993d544e0cbea83cff2465d3a8615cfc0750d39aa904a60e8fafab7c315a50:80",
"ClaimID": "013df2835b1b8256ed019cc71df2dfb61fdce63c",
"Amount": 10,
"EffectiveAmount": 10,
"Accepted": 0,
"ActiveAt": 0
}
],
"Supports": []
}
```
Reset the history to height 1.
``` block
claimtrie > reset --height 1
claimtrie > show
<BestBlock: 1>
Hello : {
"Hash": "91185db0db792a6f6ad60e01e99e27f5263b8c3225137ff3b33bd5d3ebe197bd",
"Tookover": 0,
"BestClaim": {
"OutPoint": "5fed5c7a39d47b4432b55d172b312df87142995e83ef28bf070859e94c916f30:48",
"ClaimID": "911771619d4e6656bc0f08e1dfab5827756ed39d",
"Amount": 44,
"EffectiveAmount": 44,
"Accepted": 0,
"ActiveAt": 0
},
"Claims": [
{
"OutPoint": "5fed5c7a39d47b4432b55d172b312df87142995e83ef28bf070859e94c916f30:48",
"ClaimID": "911771619d4e6656bc0f08e1dfab5827756ed39d",
"Amount": 44,
"EffectiveAmount": 44,
"Accepted": 0,
"ActiveAt": 0
},
{
"OutPoint": "db993d544e0cbea83cff2465d3a8615cfc0750d39aa904a60e8fafab7c315a50:80",
"ClaimID": "013df2835b1b8256ed019cc71df2dfb61fdce63c",
"Amount": 10,
"EffectiveAmount": 10,
"Accepted": 0,
"ActiveAt": 0
}
],
"Supports": []
}
claimtrie >
```
Note: the storage part was just brought up. In case it missed something, or the program was shutdown cleanly, try erase the database to clean the status.
(It doesn't modify the ClaimScript we saved from BTCD.)
``` block
claimtrie > erase
```
Import claim scripts saved from lbrycrd.go (-v with verbose output)
``` block
claimtrie > i -ht 400000 -v -c
2018/08/07 19:43:14 102 +C 67ad533eb2676c9d36bfa100092af5358de747e08ef928c0c54a8b3891c2b76b:1 bdb4df1b86ada117a61e1737c6d2604e940f1fb4 50000000 [mindblown]
2018/08/07 19:43:14 125 +C 9b4afb7edf206f7d2fbd353add4a471887c92dba97145ee550ac06a4fa73bcd1:1 b48341bb3a5470abe3b661e40ad187ac61c3301a 300000000 [mindblown]
2018/08/07 19:43:14 984 +C 720ad1906617112924845a775e28e5176d491ca289992dc64b9a38d34b04ce08:0 982b7b306122e3c38c826549ca1f2370d3113ca1 100000000 [keynesvhayek]
2018/08/07 19:43:14 986 +C 90f3eb8682ee620bc5fcd7f37a5a3c83b38863c316797c36ec5022b81fc32331:1 61c91810c863394bd9b436c6cbfd19a5d8b9f3c4 100000000 [keynesvhayek]
...
```
show the commits
``` block
claimtrie >log
abbb24f008ec4a6b9c8a972cdaa779fb2ee10d763191c824848460ec3a5e3f21 at 400000
abbb24f008ec4a6b9c8a972cdaa779fb2ee10d763191c824848460ec3a5e3f21 at 399997
a4fe8f67ca7510daaf68a63bd2de3693bf5fd5504a38c600d52bb6e57547ce18 at 399996
a4fe8f67ca7510daaf68a63bd2de3693bf5fd5504a38c600d52bb6e57547ce18 at 399993
134672de8c8ef824c9ed76efcae2924ac20dc0627a123d0c746c10d0efa89203 at 399992
134672de8c8ef824c9ed76efcae2924ac20dc0627a123d0c746c10d0efa89203 at 399885
134672de8c8ef824c9ed76efcae2924ac20dc0627a123d0c746c10d0efa89203 at 399884
134672de8c8ef824c9ed76efcae2924ac20dc0627a123d0c746c10d0efa89203 at 399883
134672de8c8ef824c9ed76efcae2924ac20dc0627a123d0c746c10d0efa89203 at 399882
134672de8c8ef824c9ed76efcae2924ac20dc0627a123d0c746c10d0efa89203 at 399881
...
```
Show merkle hash of current commit.
``` block
claimtrie> merkle
abbb24f008ec4a6b9c8a972cdaa779fb2ee10d763191c824848460ec3a5e3f21 at 400000
```
Show particular nodes at specific height.
``` block
claimtrie > s -n @jack -ht 300000
<ClaimTrie Height 400000 >
[@jack] Height 300000, d0fa172e082e2c7d45df5e514a213a812812be04fb5d42c14b2711f88d65fc8d Tookover: 156270 Next: 415690
C cc3ad268eb9662046585975c2da4c214a0b7d11d78f5bd154ce9e74e5a868633:0 id: b8e04a32cdb977e96b80ff24324b1771c198038c accepted: 152716 active: 152716, amt: 99983800 effamt: 99983800
C 4c40d17a13e21661821b746e0c8b3771101fe7ad70444fb295feaa653b066f11:0 id: 413677be053754e735fea95dd8a1db65d63dcc01 accepted: 157311 active: 157343, amt: 99983800 effamt: 99983800
C dced82824e8d8cafc6d0e8ab58e80b5cacb8ff8317aadeb0ae0f34b6fac0432f:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 191763 active: 156270, amt: 999967600 effamt: 1001311967600 <B>
C a67db7518d32e001343ffa1d83ca4bf57b20584c8faaa14b4dba3ae99d6a4caa:0 id: dc4c3f7f3f80a13349d0205c177bd940e83c8a42 accepted: 198608 active: 199931, amt: 10000000 effamt: 10000000
C 0f56714baafa0c3639f60d197927f8efca06a6bace0d5b2b11c13f77a26db968:0 id: 112d4619c2ec119105ce25737e8b3bdc1efc29df accepted: 200056 active: 201424, amt: 1000000 effamt: 1000000
C 00e8ee6d1fc3d234f95e7f532f27a6336019cff6e5d9a156725b6d37c5c95f46:0 id: e12bb13d7e78f2a573c96c4229ac1b54b53f2186 accepted: 240389 active: 243017, amt: 10000000 effamt: 10000000
S 46c4fcb0f30d05e7780382a4fe999f69211a208318df592f162cef0837cf3903:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 156479 active: 156479, amt: 500000000000 effamt: 0
S 361b37b3d16c049dd7efeda5e02b90e0085ad03b49c97306810ac018eeeeafa3:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 156483 active: 156483, amt: 500000000000 effamt: 0
S 8b20b97b88ac17a24fbb7736f479f92c0ac727cda946bf76444f194bbeebada6:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 202938 active: 202938, amt: 100000000 effamt: 0
S 7d1951cac00feac7d7ea7569270a0c392e48937d23cf3a395c074b5d8c724785:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 216968 active: 216968, amt: 1000000 effamt: 0
S d050fb0e5a7366ab648c5b0dea057fc889b7a37c305567f17174241441d20895:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 216972 active: 216972, amt: 1000000 effamt: 0
S 7710f9d6b69c67002a8ea390823d773d5c875f4a1471a90c75ee00b10102e867:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 223846 active: 223846, amt: 100000000 effamt: 0
S 10e3f76735f483bd9f912080cf4952f7d512b16c20e242d73bd87b159cf6bb7b:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 228125 active: 228125, amt: 100000000 effamt: 0
S fe53337b37c1b1ac31eddec3cdc08e7467642529c18d92a18629f74ed1d6afae:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 228163 active: 228163, amt: 10000000 effamt: 0
```
Show a node at specified height, and also dump the changes replayed to produce it.
``` block
claimtrie > s -n @jack -ht 200000 -d
<ClaimTrie Height 400000 >
[@jack] Height 200000, d0fa172e082e2c7d45df5e514a213a812812be04fb5d42c14b2711f88d65fc8d Tookover: 156270 Next: 415690
C cc3ad268eb9662046585975c2da4c214a0b7d11d78f5bd154ce9e74e5a868633:0 id: b8e04a32cdb977e96b80ff24324b1771c198038c accepted: 152716 active: 152716, amt: 99983800 effamt: 99983800
C 4c40d17a13e21661821b746e0c8b3771101fe7ad70444fb295feaa653b066f11:0 id: 413677be053754e735fea95dd8a1db65d63dcc01 accepted: 157311 active: 157343, amt: 99983800 effamt: 99983800
C dced82824e8d8cafc6d0e8ab58e80b5cacb8ff8317aadeb0ae0f34b6fac0432f:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 191763 active: 156270, amt: 999967600 effamt: 1000999967600 <B>
C a67db7518d32e001343ffa1d83ca4bf57b20584c8faaa14b4dba3ae99d6a4caa:0 id: dc4c3f7f3f80a13349d0205c177bd940e83c8a42 accepted: 198608 active: 199931, amt: 10000000 effamt: 10000000
S 46c4fcb0f30d05e7780382a4fe999f69211a208318df592f162cef0837cf3903:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 156479 active: 156479, amt: 500000000000 effamt: 0
S 361b37b3d16c049dd7efeda5e02b90e0085ad03b49c97306810ac018eeeeafa3:0 id: 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 accepted: 156483 active: 156483, amt: 500000000000 effamt: 0
chgs[0] 152510 +C c768895f52035a4fafee54ff30795d1e0ceb5ed0f46dae4c3da6253b9d11c525:0 0000000000000000000000000000000000000000 100000000 [@jack]
chgs[1] 152716 -C c768895f52035a4fafee54ff30795d1e0ceb5ed0f46dae4c3da6253b9d11c525:0 0000000000000000000000000000000000000000 0 [@jack]
chgs[2] 152716 +U cc3ad268eb9662046585975c2da4c214a0b7d11d78f5bd154ce9e74e5a868633:0 b8e04a32cdb977e96b80ff24324b1771c198038c 99983800 [@jack]
chgs[3] 156157 +C 04a5901f845c7f21911538159d5fe541d2b4480336bb29115b805bcbab032bff:0 0000000000000000000000000000000000000000 1000000000 [@jack]
chgs[4] 156479 +S 46c4fcb0f30d05e7780382a4fe999f69211a208318df592f162cef0837cf3903:0 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 500000000000 [@jack]
chgs[5] 156483 +S 361b37b3d16c049dd7efeda5e02b90e0085ad03b49c97306810ac018eeeeafa3:0 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 500000000000 [@jack]
chgs[6] 157311 +C 3f275be2b58bc9a66b43d79d5b819059c1ea4c3132c57aef0b89a022aac2f09b:0 0000000000000000000000000000000000000000 100000000 [@jack]
chgs[7] 157311 -C 3f275be2b58bc9a66b43d79d5b819059c1ea4c3132c57aef0b89a022aac2f09b:0 0000000000000000000000000000000000000000 0 [@jack]
chgs[8] 157311 +U 4c40d17a13e21661821b746e0c8b3771101fe7ad70444fb295feaa653b066f11:0 413677be053754e735fea95dd8a1db65d63dcc01 99983800 [@jack]
chgs[9] 191752 -C 04a5901f845c7f21911538159d5fe541d2b4480336bb29115b805bcbab032bff:0 0000000000000000000000000000000000000000 0 [@jack]
chgs[10] 191752 +U 9e4588172b15cfc922aeed4a426acc17914552224c399e6179bb4d896ba77b4b:0 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 999983800 [@jack]
chgs[11] 191763 -C 9e4588172b15cfc922aeed4a426acc17914552224c399e6179bb4d896ba77b4b:0 0000000000000000000000000000000000000000 0 [@jack]
chgs[12] 191763 +U dced82824e8d8cafc6d0e8ab58e80b5cacb8ff8317aadeb0ae0f34b6fac0432f:0 251305ca93d4dbedb50dceb282ebcb7b07b7ac65 999967600 [@jack]
chgs[13] 198607 +C 439e17b2370bed8df0f00dba4a662f0634653a136e6b8e7c6b76ba071870f013:0 0000000000000000000000000000000000000000 10000000 [@jack]
chgs[14] 198608 -C 439e17b2370bed8df0f00dba4a662f0634653a136e6b8e7c6b76ba071870f013:0 0000000000000000000000000000000000000000 0 [@jack]
chgs[15] 198608 +U a67db7518d32e001343ffa1d83ca4bf57b20584c8faaa14b4dba3ae99d6a4caa:0 dc4c3f7f3f80a13349d0205c177bd940e83c8a42 10000000 [@jack]
```
Show all nodes (try with lower height, or it takes time to print) at specific height.
``` block
s -a -ht 100000
```
Reset the ClaimTrie to an earlier height.
``` block
r -ht 150000
```
Save the state to db.
``` block
sv
```
quit
``` block
q
```
Enter interactive mode.
``` bash
go run ${GOPATH}/src/github.com/lbryio/claimtrie/cmd/claimtrie/main.go sh
```
Load the state back.
``` block
claimtrie > ld
4891 of commits loaded. Head: 150000
194171 of nodes loaded.
Trie root: 1527b999092f171186ac6690f550bad939fc44e8b3128d1ea11ed6c3b74d8628.
```
The following are the corresponding commands in the CLI to reproduce the test.
Note that when a Toakeover happens, the {TakeoverHeight, BestClaim(OutPoint:Indx)} is pushed to the BestClaims stack.
This provides sufficient info to update and backtracking the BestClaim at any height.
```block
``` block
claimtrie > c -ht 12
claimtrie > ac -a 10
claimtrie > c -ht 13
@ -302,4 +344,4 @@ Our PGP key is [here](https://keybase.io/lbry/key.asc) if you need it.
## Contact
The primary contact for this project is [@roylee17](https://github.com/roylee17) (roylee@lbry.io)
The primary contact for this project is [@roylee17](https://github.com/roylee17) (roylee@lbry.io) or [@lyoshenka](https://github.com/lyoshenka) (grin@lbry.io)