github.com/lbryio/lbcd@v0.22.119/README.md (about) 1 # lbcd 2 3 [](https://github.com/lbryio/lbcd/actions) 4 [](https://coveralls.io/github/lbryio/lbcd?branch=master) 5 [](http://copyfree.org) 6 <!--[](https://pkg.go.dev/github.com/lbryio/lbcd)--> 7 8 **lbcd** is a full node implementation of LBRY's blockchain written in Go (golang). 9 10 Software stack developed by LBRY teams has been all migrated to **lbcd**. 11 12 We're working with exchanges and pool oerators to migrate from **lbrycrd** to **lbcd**. 13 14 If you're integrating with **lbcd+lbcwallet**, please check the Wiki for current [supported RPCs](wiki/RPC-availability). 15 16 Note: **lbcd** does *NOT* include wallet functionality. That functionality is provided by the 17 [lbcwallet](https://github.com/lbryio/lbcwallet) and the [LBRY SDK](https://github.com/lbryio/lbry-sdk). 18 19 ## Requirements 20 21 All common operating systems are supported. lbcd requires at least 8GB of RAM 22 and at least 100GB of disk storage. Both RAM and disk requirements increase slowly over time. 23 Using a fast NVMe disk is recommended. 24 25 ## Installation 26 27 Acquire binary files from [releases](https://github.com/lbryio/lbcd/releases) 28 29 For compilation, [Go](http://golang.org) 1.19 or newer is required. 30 Install Go according to its [installation instructions](http://golang.org/doc/install). 31 32 ``` sh 33 # lbcd (full node) 34 $ go install github.com/lbryio/lbcd@latest 35 36 # lbcctl (rpc client utility) 37 $ go install github.com/lbryio/lbcd/cmd/lbcctl@latest 38 ``` 39 40 ## Usage 41 42 Default application folder `${LBCDDIR}`: 43 44 - Linux: `~/.lbcd/` 45 - MacOS: `/Users/<username>/Library/Application Support/Lbcd/` 46 47 ### Start the **lbcd** 48 49 ``` sh 50 ./lbcd 51 ``` 52 53 **lbcd** loads config file at `"${LBCDDIR}/lbcd.conf"`. 54 55 If no config is found, it creates a [default one](sample-lbcd.conf), which includes all available options with default settings except randomly generated *RPC credentials* (see below). 56 57 ### RPC server 58 59 RPC credentials (`rpcuser` and `rpcpass`) is required to enable RPC server. It can be specify in the `"${LBCDDIR}/lbcd.conf"`, using command line options: 60 61 ``` sh 62 ./lbcd --rpcuser=rpcuser --rpcpass=rpcpass 63 64 2022-07-28 12:28:19.627 [INF] RPCS: RPC server listening on 0.0.0.0:9245 65 2022-07-28 12:28:19.627 [INF] RPCS: RPC server listening on [::]:9245 66 ``` 67 68 ### Working with TLS (Default) 69 70 By default, **lbcd** runs RPC server with TLS enabled, and generates the `rpc.cert` and `rpc.key` under `${LBCDDIR}`, if not exist already. 71 72 To interact with the RPC server, a client has to either specify the `rpc.cert`, or disable the certification verification for TLS. 73 74 Interact with **lbcd** RPC using `lbcctl` 75 76 ``` sh 77 $ ./lbcctl --rpccert "${LBCDDIR}/rpc.cert" getblockcount 78 79 # or disable the certificate verification 80 $ ./lbcctl --skipverify getblockcount 81 82 1200062 83 ``` 84 85 Interact with **lbcd** RPC using `curl` 86 87 ``` sh 88 $ curl --user rpcuser:rpcpass \ 89 --cacert "${LBCDDIR}/rpc.cert" \ 90 --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getblockcount", "params": []}' \ 91 -H 'content-type: text/plain;' \ 92 https://127.0.0.1:9245/ 93 94 # or disable the certificate verification 95 $ curl --user rpcuser:rpcpass \ 96 --insecure \ 97 --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getblockcount", "params": []}' \ 98 -H 'content-type: text/plain;' \ 99 https://127.0.0.1:9245/ 100 ``` 101 102 ``` json 103 {"jsonrpc":"1.0","result":1200062,"error":null,"id":"curltest"} 104 ``` 105 106 ### Working without TLS 107 108 TLS can be disabled using the `--notls` option: 109 110 ``` sh 111 $ ./lbcd --notls 112 ``` 113 114 ``` sh 115 $ ./lbcctl --notls getblockcount 116 117 1200062 118 ``` 119 120 ``` sh 121 $ curl --user rpcuser:rpcpass \ 122 --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getblockcount", "params": []}' \ 123 -H 'content-type: text/plain;' \ 124 http://127.0.0.1:9245/ 125 ``` 126 127 ``` json 128 {"jsonrpc":"1.0","result":1200062,"error":null,"id":"curltest"} 129 ``` 130 131 ## Using Snapshots (optional) 132 133 [Snapshots](https://snapshots.lbry.com/blockchain/) are created bi-weekly to help new users catch up current block height. 134 135 The snapshots are archived and compressed in [zstd](https://facebook.github.io/zstd/) format for it's compression ratio and speed. 136 137 Download the snapshot, and uncompress it: 138 139 ``` sh 140 time curl -O https://snapshots.lbry.com/blockchain/lbcd_snapshot_1199527_v0.22.105_2022-07-27.tar.zst 141 zstd -d --stdout lbcd_snapshot_1199527_v0.22.105_2022-07-27.tar.zst | tar xf - -C "${LBCDDIR}" 142 ``` 143 144 If preferred, a user can download and uncompress the snapshot on the fly: 145 By the time the download is finished, the snapshots should be almost uncompressed already. 146 147 ``` sh 148 mkdir -p "${LBCDDIR}" 149 150 time curl https://snapshots.lbry.com/blockchain/lbcd_snapshot_1199527_v0.22.105_2022-07-27.tar.zst | zstd -d --stdout | tar xf - -C "${LBCDDIR}" 151 152 # % Total % Received % Xferd Average Speed Time Time Time Current 153 # Dload Upload Total Spent Left Speed 154 # 100 64.9G 100 64.9G 0 0 37.0M 0 0:29:49 0:29:49 --:--:-- 33.0M 155 # 156 # real 29m49.962s 157 # user 6m53.710s 158 # sys 8m56.545s 159 ``` 160 161 ## Working with RPCs 162 163 Using `lbcctl -l` to list available RPCs: 164 165 ``` sh 166 $ lbcctl -l 167 168 Chain Server Commands: 169 addnode "addr" "add|remove|onetry" 170 createrawtransaction [{"txid":"value","vout":n},...] {"address":amount,...} (locktime) 171 debuglevel "levelspec" 172 decoderawtransaction "hextx" 173 decodescript "hexscript" 174 deriveaddresses "descriptor" ({"value":value}) 175 fundrawtransaction "hextx" {"changeaddress":changeaddress,"changeposition":changeposition,"changetype":changetype,"includewatching":includewatching,"lockunspents":lockunspents,"feerate":feerate,"subtractfeefromoutputs":[subtractfeefromoutput,...],"replaceable":replaceable,"conftarget":conftarget,"estimatemode":estimatemode} (iswitness) 176 generate numblocks 177 178 [skipped] 179 180 Wallet Server Commands (--wallet): 181 addmultisigaddress nrequired ["key",...] ("account") 182 addwitnessaddress "address" 183 backupwallet "destination" 184 createmultisig nrequired ["key",...] 185 createnewaccount "account" 186 createwallet "walletname" (disableprivatekeys=false blank=false passphrase="" avoidreuse=false) 187 dumpprivkey "address" 188 dumpwallet "filename" 189 encryptwallet "passphrase" 190 estimatefee numblocks 191 estimatepriority numblocks 192 estimatesmartfee conftarget (estimatemode="CONSERVATIVE") 193 getaccount "address" 194 getaccountaddress "account" 195 getaddressesbyaccount "account" 196 197 [skipped] 198 ``` 199 200 Using `lbcctl help rpcname` to show the RPC spec: 201 202 ``` sh 203 $ lbcctl help getblock 204 205 getblock "hash" (verbosity=1) 206 207 Returns information about a block given its hash. 208 209 Arguments: 210 1. hash (string, required) The hash of the block 211 2. verbosity (numeric, optional, default=1) Specifies whether the block data should be returned as a hex-encoded string (0), as parsed data with a slice of TXIDs (1), or as parsed data with parsed transaction data (2) 212 213 Result (verbosity=0): 214 "value" (string) Hex-encoded bytes of the serialized block 215 216 Result (verbosity=1): 217 { 218 "getblockverboseresultbase": { (object) 219 "hash": "value", (string) The hash of the block (same as provided) 220 "confirmations": n, (numeric) The number of confirmations 221 "strippedsize": n, (numeric) The size of the block without witness data 222 "size": n, (numeric) The size of the block 223 "weight": n, (numeric) The weight of the block 224 "height": n, (numeric) The height of the block in the block chain 225 "version": n, (numeric) The block version 226 "versionHex": "value", (string) The block version in hexadecimal 227 "merkleroot": "value", (string) Root hash of the merkle tree 228 "time": n, (numeric) The block time in seconds since 1 Jan 1970 GMT 229 "mediantime": n, (numeric) The median block time in seconds since 1 Jan 1970 GMT 230 "nonce": n, (numeric) The block nonce 231 "bits": "value", (string) The bits which represent the block difficulty 232 "difficulty": n.nnn, (numeric) The proof-of-work difficulty as a multiple of the minimum difficulty 233 "chainwork": "value", (string) Expected number of hashes required to produce the chain up to this block (in hex) 234 "previousblockhash": "value", (string) The hash of the previous block 235 "nextblockhash": "value", (string) The hash of the next block (only if there is one) 236 "nameclaimroot": "value", (string) Root hash of the claim trie 237 "nTx": n, (numeric) The number of transactions (aka, count of TX) 238 }, 239 "tx": ["value",...], (array of string) The transaction hashes (only when verbosity=1) 240 } 241 ``` 242 243 ## **lbcd** & **lbcwallet** 244 245 *Wallet* related functianlities and RPCs are provided by a separate programe - [**lbcwallet**](https://github.com/lbryio/lbcwallet). 246 247 Once setup, lbcwallet can serve wallet related RPCs as well as proxy lbcd RPCs to an assocated lbcd now. 248 It's sufficient for user to connect just the **lbcwallet** instead of both. 249 250 ``` mermaid 251 sequenceDiagram 252 actor C as lbcctl 253 participant W as lbcwallet (port: 9244) 254 participant D as lbcd (port: 9245) 255 256 rect rgb(200,200,200) 257 Note over C,D: lbcctl getblockcount 258 C ->>+ D: getblockcount 259 D -->>- C: response 260 end 261 262 rect rgb(200,200,200) 263 Note over C,W: lbcctl --wallet balance 264 C ->>+ W: getbalance 265 W -->>- C: response 266 end 267 268 rect rgb(200,200,200) 269 Note over C,D: lbcctl --wallet getblockcount (lbcd RPC service proxied by lbcwallet) 270 C ->>+ W: getblockcount 271 W ->>+ D: getblockcount 272 D -->>- W: response 273 W -->>- C: response 274 end 275 ``` 276 277 While **lbcd** can run standalone as a full node, **lbcwallet** requires an associated **lbcd** instance for scanning and sync'ing block data. 278 279 ``` mermaid 280 sequenceDiagram 281 participant W as lbcwallet (RPC port: 9244) 282 participant D as lbcd (RPC port: 9245, P2P port: 9246) 283 participant D2 as other lbcd node(s) (P2P port: 9246) 284 285 rect rgb(200,200,200) 286 Note over W,D: Asynchronous websocket notifications 287 W ->> D: subscribe to notifications 288 D -->> W: notification 289 D -->> W: notification 290 end 291 292 rect rgb(200,200,200) 293 Note over W,D: lbcd RPCs 294 W ->>+ D: getblockheader 295 D ->>- W: response 296 end 297 298 rect rgb(200,200,200) 299 Note over D,D2: P2P messages over port 9246 300 D -->> D2: P2P message 301 D2 -->> D: P2P message 302 end 303 304 ``` 305 306 ## Data integrity 307 308 **lbcd** is not immune to data loss. It expects a clean shutdown via SIGINT or 309 SIGTERM. SIGKILL, immediate VM kills, and sudden power loss can cause data 310 corruption, thus requiring chain resynchronization for recovery. 311 312 ## Security 313 314 We take security seriously. Please contact [security](mailto:security@lbry.com) regarding any security issues. 315 Our PGP key is [here](https://lbry.com/faq/pgp-key) if you need it. 316 317 We maintain a mailing list for notifications of upgrades, security issues, 318 and soft/hard forks. To join, visit [fork list](https://lbry.com/forklist) 319 320 ## Contributing 321 322 Contributions to this project are welcome, encouraged, and compensated. 323 The [integrated github issue tracker](https://github.com/lbryio/lbcd/issues) 324 is used for this project. All pull requests will be considered. 325 326 <!-- ## Release Verification 327 Please see our [documentation on the current build/verification 328 process](https://github.com/lbryio/lbcd/tree/master/release) for all our 329 releases for information on how to verify the integrity of published releases 330 using our reproducible build system. 331 --> 332 333 ## License 334 335 lbcd is licensed under the [copyfree](http://copyfree.org) ISC License.