From ac1fdda8a03ae477f7247ed930dedbc1f87b3d40 Mon Sep 17 00:00:00 2001 From: Brannon King Date: Tue, 31 Aug 2021 15:53:55 -0400 Subject: [PATCH] sanitizing readmes for lbcd --- blockchain/README.md | 68 +----- btcec/README.md | 61 +---- btcjson/README.md | 64 +----- chaincfg/README.md | 81 +------ connmgr/README.md | 20 +- database/README.md | 26 +-- docs/README.md | 296 ------------------------- docs/code_contribution_guidelines.md | 319 --------------------------- docs/conf.py | 6 +- docs/configuration.md | 42 ++-- docs/configuring_tor.md | 32 +-- docs/contact.md | 15 -- docs/controlling.md | 12 +- docs/developer_resources.md | 37 ---- docs/index.md | 48 +--- docs/installation.md | 76 ------- docs/json_rpc_api.md | 132 ++++++----- docs/mining.md | 14 +- docs/table_of_content.md | 13 -- docs/update.md | 8 - docs/using_docker.md | 160 -------------- docs/wallet.md | 5 - integration/README.md | 5 - integration/rpctest/README.md | 14 -- integration/rpctest/btcd.go | 2 +- mempool/README.md | 19 +- mining/README.md | 15 +- netsync/README.md | 12 - params.go | 2 +- peer/README.md | 23 +- release/README.md | 181 --------------- release/release.sh | 108 --------- rpcclient/README.md | 37 +--- txscript/README.md | 54 +---- wire/README.md | 43 +--- 35 files changed, 145 insertions(+), 1905 deletions(-) delete mode 100644 docs/README.md delete mode 100644 docs/code_contribution_guidelines.md delete mode 100644 docs/contact.md delete mode 100644 docs/developer_resources.md delete mode 100644 docs/installation.md delete mode 100644 docs/table_of_content.md delete mode 100644 docs/update.md delete mode 100644 docs/using_docker.md delete mode 100644 docs/wallet.md delete mode 100644 release/README.md delete mode 100755 release/release.sh diff --git a/blockchain/README.md b/blockchain/README.md index 2237780c10..cb9ddb45d3 100644 --- a/blockchain/README.md +++ b/blockchain/README.md @@ -1,30 +1,9 @@ blockchain ========== -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/blockchain) -Package blockchain implements bitcoin block handling and chain selection rules. -The test coverage is currently only around 60%, but will be increasing over -time. See `test_coverage.txt` for the gocov coverage report. Alternatively, if -you are running a POSIX OS, you can run the `cov_report.sh` script for a -real-time report. Package blockchain is licensed under the liberal ISC license. - -There is an associated blog post about the release of this package -[here](https://blog.conformal.com/btcchain-the-bitcoin-chain-package-from-bctd/). - -This package has intentionally been designed so it can be used as a standalone -package for any projects needing to handle processing of blocks into the bitcoin -block chain. - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/blockchain -``` - -## Bitcoin Chain Processing Overview +### Bitcoin Chain Processing Overview Before a block is allowed into the block chain, it must go through an intensive series of validation rules. The following list serves as a general outline of @@ -57,47 +36,4 @@ is by no means exhaustive: transaction values - Run the transaction scripts to verify the spender is allowed to spend the coins - - Insert the block into the block database - -## Examples - -* [ProcessBlock Example](https://pkg.go.dev/github.com/btcsuite/btcd/blockchain#example-BlockChain-ProcessBlock) - Demonstrates how to create a new chain instance and use ProcessBlock to - attempt to add a block to the chain. This example intentionally - attempts to insert a duplicate genesis block to illustrate how an invalid - block is handled. - -* [CompactToBig Example](https://pkg.go.dev/github.com/btcsuite/btcd/blockchain#example-CompactToBig) - Demonstrates how to convert the compact "bits" in a block header which - represent the target difficulty to a big integer and display it using the - typical hex notation. - -* [BigToCompact Example](https://pkg.go.dev/github.com/btcsuite/btcd/blockchain#example-BigToCompact) - Demonstrates how to convert a target difficulty into the - compact "bits" in a block header which represent that target difficulty. - -## GPG Verification Key - -All official release tags are signed by Conformal so users can ensure the code -has not been tampered with and is coming from the btcsuite developers. To -verify the signature perform the following: - -- Download the public key from the Conformal website at - https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt - -- Import the public key into your GPG keyring: - ```bash - gpg --import GIT-GPG-KEY-conformal.txt - ``` - -- Verify the release tag with the following command where `TAG_NAME` is a - placeholder for the specific tag: - ```bash - git tag -v TAG_NAME - ``` - -## License - - -Package blockchain is licensed under the [copyfree](http://copyfree.org) ISC -License. + - Insert the block into the block database \ No newline at end of file diff --git a/btcec/README.md b/btcec/README.md index a6dd2cf285..0cf57a8051 100644 --- a/btcec/README.md +++ b/btcec/README.md @@ -1,68 +1,11 @@ btcec ===== -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://pkg.go.dev/github.com/btcsuite/btcd/btcec?status.png)](https://pkg.go.dev/github.com/btcsuite/btcd/btcec) -Package btcec implements elliptic curve cryptography needed for working with +btcec implements elliptic curve cryptography needed for working with Bitcoin (secp256k1 only for now). It is designed so that it may be used with the standard crypto/ecdsa packages provided with go. A comprehensive suite of test is provided to ensure proper functionality. Package btcec was originally based on work from ThePiachu which is licensed under the same terms as Go, but it has -signficantly diverged since then. The btcsuite developers original is licensed -under the liberal ISC license. - -Although this package was primarily written for btcd, it has intentionally been -designed so it can be used as a standalone package for any projects needing to -use secp256k1 elliptic curve cryptography. - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/btcec -``` - -## Examples - -* [Sign Message](https://pkg.go.dev/github.com/btcsuite/btcd/btcec#example-package--SignMessage) - Demonstrates signing a message with a secp256k1 private key that is first - parsed form raw bytes and serializing the generated signature. - -* [Verify Signature](https://pkg.go.dev/github.com/btcsuite/btcd/btcec#example-package--VerifySignature) - Demonstrates verifying a secp256k1 signature against a public key that is - first parsed from raw bytes. The signature is also parsed from raw bytes. - -* [Encryption](https://pkg.go.dev/github.com/btcsuite/btcd/btcec#example-package--EncryptMessage) - Demonstrates encrypting a message for a public key that is first parsed from - raw bytes, then decrypting it using the corresponding private key. - -* [Decryption](https://pkg.go.dev/github.com/btcsuite/btcd/btcec#example-package--DecryptMessage) - Demonstrates decrypting a message using a private key that is first parsed - from raw bytes. - -## GPG Verification Key - -All official release tags are signed by Conformal so users can ensure the code -has not been tampered with and is coming from the btcsuite developers. To -verify the signature perform the following: - -- Download the public key from the Conformal website at - https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt - -- Import the public key into your GPG keyring: - ```bash - gpg --import GIT-GPG-KEY-conformal.txt - ``` - -- Verify the release tag with the following command where `TAG_NAME` is a - placeholder for the specific tag: - ```bash - git tag -v TAG_NAME - ``` - -## License - -Package btcec is licensed under the [copyfree](http://copyfree.org) ISC License -except for btcec.go and btcec_test.go which is under the same license as Go. - +signficantly diverged since then. \ No newline at end of file diff --git a/btcjson/README.md b/btcjson/README.md index 48f322635e..9d9813337a 100644 --- a/btcjson/README.md +++ b/btcjson/README.md @@ -1,70 +1,8 @@ btcjson ======= -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/btcjson) Package btcjson implements concrete types for marshalling to and from the bitcoin JSON-RPC API. A comprehensive suite of tests is provided to ensure -proper functionality. - -Although this package was primarily written for the btcsuite, it has -intentionally been designed so it can be used as a standalone package for any -projects needing to marshal to and from bitcoin JSON-RPC requests and responses. - -Note that although it's possible to use this package directly to implement an -RPC client, it is not recommended since it is only intended as an infrastructure -package. Instead, RPC clients should use the -[btcrpcclient](https://github.com/btcsuite/btcrpcclient) package which provides -a full blown RPC client with many features such as automatic connection -management, websocket support, automatic notification re-registration on -reconnect, and conversion from the raw underlying RPC types (strings, floats, -ints, etc) to higher-level types with many nice and useful properties. - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/btcjson -``` - -## Examples - -* [Marshal Command](https://pkg.go.dev/github.com/btcsuite/btcd/btcjson#example-MarshalCmd) - Demonstrates how to create and marshal a command into a JSON-RPC request. - -* [Unmarshal Command](https://pkg.go.dev/github.com/btcsuite/btcd/btcjson#example-UnmarshalCmd) - Demonstrates how to unmarshal a JSON-RPC request and then unmarshal the - concrete request into a concrete command. - -* [Marshal Response](https://pkg.go.dev/github.com/btcsuite/btcd/btcjson#example-MarshalResponse) - Demonstrates how to marshal a JSON-RPC response. - -* [Unmarshal Response](https://pkg.go.dev/github.com/btcsuite/btcd/btcjson#example-package--UnmarshalResponse) - Demonstrates how to unmarshal a JSON-RPC response and then unmarshal the - result field in the response to a concrete type. - -## GPG Verification Key - -All official release tags are signed by Conformal so users can ensure the code -has not been tampered with and is coming from the btcsuite developers. To -verify the signature perform the following: - -- Download the public key from the Conformal website at - https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt - -- Import the public key into your GPG keyring: - ```bash - gpg --import GIT-GPG-KEY-conformal.txt - ``` - -- Verify the release tag with the following command where `TAG_NAME` is a - placeholder for the specific tag: - ```bash - git tag -v TAG_NAME - ``` - -## License - -Package btcjson is licensed under the [copyfree](http://copyfree.org) ISC -License. +proper functionality. \ No newline at end of file diff --git a/chaincfg/README.md b/chaincfg/README.md index 72fac2e7dc..da3254c74d 100644 --- a/chaincfg/README.md +++ b/chaincfg/README.md @@ -1,85 +1,8 @@ chaincfg ======== -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/chaincfg) Package chaincfg defines chain configuration parameters for the three standard -Bitcoin networks and provides the ability for callers to define their own custom -Bitcoin networks. - -Although this package was primarily written for btcd, it has intentionally been -designed so it can be used as a standalone package for any projects needing to -use parameters for the standard Bitcoin networks or for projects needing to -define their own network. - -## Sample Use - -```Go -package main - -import ( - "flag" - "fmt" - "log" - - "github.com/btcsuite/btcutil" - "github.com/btcsuite/btcd/chaincfg" -) - -var testnet = flag.Bool("testnet", false, "operate on the testnet Bitcoin network") - -// By default (without -testnet), use mainnet. -var chainParams = &chaincfg.MainNetParams - -func main() { - flag.Parse() - - // Modify active network parameters if operating on testnet. - if *testnet { - chainParams = &chaincfg.TestNet3Params - } - - // later... - - // Create and print new payment address, specific to the active network. - pubKeyHash := make([]byte, 20) - addr, err := btcutil.NewAddressPubKeyHash(pubKeyHash, chainParams) - if err != nil { - log.Fatal(err) - } - fmt.Println(addr) -} -``` - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/chaincfg -``` - -## GPG Verification Key - -All official release tags are signed by Conformal so users can ensure the code -has not been tampered with and is coming from the btcsuite developers. To -verify the signature perform the following: - -- Download the public key from the Conformal website at - https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt - -- Import the public key into your GPG keyring: - ```bash - gpg --import GIT-GPG-KEY-conformal.txt - ``` - -- Verify the release tag with the following command where `TAG_NAME` is a - placeholder for the specific tag: - ```bash - git tag -v TAG_NAME - ``` - -## License - -Package chaincfg is licensed under the [copyfree](http://copyfree.org) ISC -License. +LBRY networks and provides the ability for callers to define their own custom +LBRY networks. \ No newline at end of file diff --git a/connmgr/README.md b/connmgr/README.md index b1aa3cc7d0..5237bf46f2 100644 --- a/connmgr/README.md +++ b/connmgr/README.md @@ -1,13 +1,11 @@ connmgr ======= -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/connmgr) -Package connmgr implements a generic Bitcoin network connection manager. +Package connmgr implements a generic network connection manager. -## Overview +### Overview Connection Manager handles all the general connection concerns such as maintaining a set number of outbound connections, sourcing peers, banning, @@ -18,20 +16,10 @@ connection requests from a source or a set of given addresses, dial them and notify the caller on connections. The main intended use is to initialize a pool of active connections and maintain them to remain connected to the P2P network. -In addition the connection manager provides the following utilities: +In addition, the connection manager provides the following utilities: - Notifications on connections or disconnections - Handle failures and retry new addresses from the source - Connect only to specified addresses - Permanent connections with increasing backoff retry timers -- Disconnect or Remove an established connection - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/connmgr -``` - -## License - -Package connmgr is licensed under the [copyfree](http://copyfree.org) ISC License. +- Disconnect or Remove an established connection \ No newline at end of file diff --git a/database/README.md b/database/README.md index 21563d1af8..3f900d9159 100644 --- a/database/README.md +++ b/database/README.md @@ -1,9 +1,7 @@ database ======== -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/database) Package database provides a block and metadata storage database. @@ -32,26 +30,4 @@ storage, and strict checksums in key areas to ensure data integrity. - Nested buckets - Iteration support including cursors with seek capability - Supports registration of backend databases -- Comprehensive test coverage - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/database -``` - -## Examples - -* [Basic Usage Example](https://pkg.go.dev/github.com/btcsuite/btcd/database#example-package--BasicUsage) - Demonstrates creating a new database and using a managed read-write - transaction to store and retrieve metadata. - -* [Block Storage and Retrieval Example](https://pkg.go.dev/github.com/btcsuite/btcd/database#example-package--BlockStorageAndRetrieval) - Demonstrates creating a new database, using a managed read-write transaction - to store a block, and then using a managed read-only transaction to fetch the - block. - -## License - -Package database is licensed under the [copyfree](http://copyfree.org) ISC -License. +- Comprehensive test coverage \ No newline at end of file diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index c24ead5372..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,296 +0,0 @@ -### Table of Contents -1. [About](#About) -2. [Getting Started](#GettingStarted) - 1. [Installation](#Installation) - 1. [Windows](#WindowsInstallation) - 2. [Linux/BSD/MacOSX/POSIX](#PosixInstallation) - 1. [Gentoo Linux](#GentooInstallation) - 2. [Configuration](#Configuration) - 3. [Controlling and Querying btcd via btcctl](#BtcctlConfig) - 4. [Mining](#Mining) -3. [Help](#Help) - 1. [Startup](#Startup) - 1. [Using bootstrap.dat](#BootstrapDat) - 2. [Network Configuration](#NetworkConfig) - 3. [Wallet](#Wallet) -4. [Contact](#Contact) - 1. [IRC](#ContactIRC) - 2. [Mailing Lists](#MailingLists) -5. [Developer Resources](#DeveloperResources) - 1. [Code Contribution Guidelines](#ContributionGuidelines) - 2. [JSON-RPC Reference](#JSONRPCReference) - 3. [The btcsuite Bitcoin-related Go Packages](#GoPackages) - - - -### 1. About - -btcd is a full node bitcoin implementation written in [Go](http://golang.org), -licensed under the [copyfree](http://www.copyfree.org) ISC License. - -This project is currently under active development and is in a Beta state. It -is extremely stable and has been in production use since October 2013. - -It properly downloads, validates, and serves the block chain using the exact -rules (including consensus bugs) for block acceptance as Bitcoin Core. We have -taken great care to avoid btcd causing a fork to the block chain. It includes a -full block validation testing framework which contains all of the 'official' -block acceptance tests (and some additional ones) that is run on every pull -request to help ensure it properly follows consensus. Also, it passes all of -the JSON test data in the Bitcoin Core code. - -It also properly relays newly mined blocks, maintains a transaction pool, and -relays individual transactions that have not yet made it into a block. It -ensures all individual transactions admitted to the pool follow the rules -required by the block chain and also includes more strict checks which filter -transactions based on miner requirements ("standard" transactions). - -One key difference between btcd and Bitcoin Core is that btcd does *NOT* include -wallet functionality and this was a very intentional design decision. See the -blog entry [here](https://web.archive.org/web/20171125143919/https://blog.conformal.com/btcd-not-your-moms-bitcoin-daemon) -for more details. This means you can't actually make or receive payments -directly with btcd. That functionality is provided by the -[btcwallet](https://github.com/btcsuite/btcwallet) and -[Paymetheus](https://github.com/btcsuite/Paymetheus) (Windows-only) projects -which are both under active development. - - - -### 2. Getting Started - - - -**2.1 Installation** - -The first step is to install btcd. See one of the following sections for -details on how to install on the supported operating systems. - - - -**2.1.1 Windows Installation**
- -* Install the MSI available at: https://github.com/btcsuite/btcd/releases -* Launch btcd from the Start Menu - - - -**2.1.2 Linux/BSD/MacOSX/POSIX Installation** - - -- Install Go according to the installation instructions here: - http://golang.org/doc/install - -- Ensure Go was installed properly and is a supported version: - -```bash -$ go version -$ go env GOROOT GOPATH -``` - -NOTE: The `GOROOT` and `GOPATH` above must not be the same path. It is -recommended that `GOPATH` is set to a directory in your home directory such as -`~/goprojects` to avoid write permission issues. It is also recommended to add -`$GOPATH/bin` to your `PATH` at this point. - -- Run the following commands to obtain btcd, all dependencies, and install it: - -```bash -$ git clone https://github.com/btcsuite/btcd $GOPATH/src/github.com/btcsuite/btcd -$ cd $GOPATH/src/github.com/btcsuite/btcd -$ GO111MODULE=on go install -v . ./cmd/... -``` - -- btcd (and utilities) will now be installed in ```$GOPATH/bin```. If you did - not already add the bin directory to your system path during Go installation, - we recommend you do so now. - -**Updating** - -- Run the following commands to update btcd, all dependencies, and install it: - -```bash -$ cd $GOPATH/src/github.com/btcsuite/btcd -$ git pull && GO111MODULE=on go install -v . ./cmd/... -``` - - - -**2.1.2.1 Gentoo Linux Installation** - -* Install Layman and enable the Bitcoin overlay. - * https://gitlab.com/bitcoin/gentoo -* Copy or symlink `/var/lib/layman/bitcoin/Documentation/package.keywords/btcd-live` to `/etc/portage/package.keywords/` -* Install btcd: `$ emerge net-p2p/btcd` - - - -**2.2 Configuration** - -btcd has a number of [configuration](http://godoc.org/github.com/btcsuite/btcd) -options, which can be viewed by running: `$ btcd --help`. - - - -**2.3 Controlling and Querying btcd via btcctl** - -btcctl is a command line utility that can be used to both control and query btcd -via [RPC](http://www.wikipedia.org/wiki/Remote_procedure_call). btcd does -**not** enable its RPC server by default; You must configure at minimum both an -RPC username and password or both an RPC limited username and password: - -* btcd.conf configuration file -``` -[Application Options] -rpcuser=myuser -rpcpass=SomeDecentp4ssw0rd -rpclimituser=mylimituser -rpclimitpass=Limitedp4ssw0rd -``` -* btcctl.conf configuration file -``` -[Application Options] -rpcuser=myuser -rpcpass=SomeDecentp4ssw0rd -``` -OR -``` -[Application Options] -rpclimituser=mylimituser -rpclimitpass=Limitedp4ssw0rd -``` -For a list of available options, run: `$ btcctl --help` - - - -**2.4 Mining** - -btcd supports the `getblocktemplate` RPC. -The limited user cannot access this RPC. - - -**1. Add the payment addresses with the `miningaddr` option.** - -``` -[Application Options] -rpcuser=myuser -rpcpass=SomeDecentp4ssw0rd -miningaddr=12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX -miningaddr=1M83ju3EChKYyysmM2FXtLNftbacagd8FR -``` - -**2. Add btcd's RPC TLS certificate to system Certificate Authority list.** - -`cgminer` uses [curl](http://curl.haxx.se/) to fetch data from the RPC server. -Since curl validates the certificate by default, we must install the `btcd` RPC -certificate into the default system Certificate Authority list. - -**Ubuntu** - -1. Copy rpc.cert to /usr/share/ca-certificates: `# cp /home/user/.btcd/rpc.cert /usr/share/ca-certificates/btcd.crt` -2. Add btcd.crt to /etc/ca-certificates.conf: `# echo btcd.crt >> /etc/ca-certificates.conf` -3. Update the CA certificate list: `# update-ca-certificates` - -**3. Set your mining software url to use https.** - -`$ cgminer -o https://127.0.0.1:9245 -u rpcuser -p rpcpassword` - - - -### 3. Help - - - -**3.1 Startup** - -Typically btcd will run and start downloading the block chain with no extra -configuration necessary, however, there is an optional method to use a -`bootstrap.dat` file that may speed up the initial block chain download process. - - - -**3.1.1 bootstrap.dat** - -* [Using bootstrap.dat](https://github.com/btcsuite/btcd/tree/master/docs/using_bootstrap_dat.md) - - - -**3.1.2 Network Configuration** - -* [What Ports Are Used by Default?](https://github.com/btcsuite/btcd/tree/master/docs/default_ports.md) -* [How To Listen on Specific Interfaces](https://github.com/btcsuite/btcd/tree/master/docs/configure_peer_server_listen_interfaces.md) -* [How To Configure RPC Server to Listen on Specific Interfaces](https://github.com/btcsuite/btcd/tree/master/docs/configure_rpc_server_listen_interfaces.md) -* [Configuring btcd with Tor](https://github.com/btcsuite/btcd/tree/master/docs/configuring_tor.md) - - - -**3.1 Wallet** - -btcd was intentionally developed without an integrated wallet for security -reasons. Please see [btcwallet](https://github.com/btcsuite/btcwallet) for more -information. - - - - -### 4. Contact - - - -**4.1 IRC** - -* [irc.freenode.net](irc://irc.freenode.net), channel `#btcd` - - - -**4.2 Mailing Lists** - -* btcd: discussion - of btcd and its packages. -* btcd-commits: - readonly mail-out of source code changes. - - - -### 5. Developer Resources - - - -* [Code Contribution Guidelines](https://github.com/btcsuite/btcd/tree/master/docs/code_contribution_guidelines.md) - - - -* [JSON-RPC Reference](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md) - * [RPC Examples](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md#ExampleCode) - - - -* The btcsuite Bitcoin-related Go Packages: - * [btcrpcclient](https://github.com/btcsuite/btcd/tree/master/rpcclient) - Implements a - robust and easy to use Websocket-enabled Bitcoin JSON-RPC client - * [btcjson](https://github.com/btcsuite/btcd/tree/master/btcjson) - Provides an extensive API - for the underlying JSON-RPC command and return values - * [wire](https://github.com/btcsuite/btcd/tree/master/wire) - Implements the - Bitcoin wire protocol - * [peer](https://github.com/btcsuite/btcd/tree/master/peer) - - Provides a common base for creating and managing Bitcoin network peers. - * [blockchain](https://github.com/btcsuite/btcd/tree/master/blockchain) - - Implements Bitcoin block handling and chain selection rules - * [blockchain/fullblocktests](https://github.com/btcsuite/btcd/tree/master/blockchain/fullblocktests) - - Provides a set of block tests for testing the consensus validation rules - * [txscript](https://github.com/btcsuite/btcd/tree/master/txscript) - - Implements the Bitcoin transaction scripting language - * [btcec](https://github.com/btcsuite/btcd/tree/master/btcec) - Implements - support for the elliptic curve cryptographic functions needed for the - Bitcoin scripts - * [database](https://github.com/btcsuite/btcd/tree/master/database) - - Provides a database interface for the Bitcoin block chain - * [mempool](https://github.com/btcsuite/btcd/tree/master/mempool) - - Package mempool provides a policy-enforced pool of unmined bitcoin - transactions. - * [btcutil](https://github.com/btcsuite/btcutil) - Provides Bitcoin-specific - convenience functions and types - * [chainhash](https://github.com/btcsuite/btcd/tree/master/chaincfg/chainhash) - - Provides a generic hash type and associated functions that allows the - specific hash algorithm to be abstracted. - * [connmgr](https://github.com/btcsuite/btcd/tree/master/connmgr) - - Package connmgr implements a generic Bitcoin network connection manager. diff --git a/docs/code_contribution_guidelines.md b/docs/code_contribution_guidelines.md deleted file mode 100644 index c0a7eecc5f..0000000000 --- a/docs/code_contribution_guidelines.md +++ /dev/null @@ -1,319 +0,0 @@ -# Code contribution guidelines - -Developing cryptocurrencies is an exciting endeavor that touches a wide variety -of areas such as wire protocols, peer-to-peer networking, databases, -cryptography, language interpretation (transaction scripts), RPC, and -websockets. They also represent a radical shift to the current fiscal system -and as a result provide an opportunity to help reshape the entire financial -system. There are few projects that offer this level of diversity and impact -all in one code base. - -However, as exciting as it is, one must keep in mind that cryptocurrencies -represent real money and introducing bugs and security vulnerabilities can have -far more dire consequences than in typical projects where having a small bug is -minimal by comparison. In the world of cryptocurrencies, even the smallest bug -in the wrong area can cost people a significant amount of money. For this -reason, the btcd suite has a formalized and rigorous development process which -is outlined on this page. - -We highly encourage code contributions, however it is imperative that you adhere -to the guidelines established on this page. - -## Minimum Recommended Skillset - -The following list is a set of core competencies that we recommend you possess -before you really start attempting to contribute code to the project. These are -not hard requirements as we will gladly accept code contributions as long as -they follow the guidelines set forth on this page. That said, if you don't have -the following basic qualifications you will likely find it quite difficult to -contribute. - -- A reasonable understanding of bitcoin at a high level (see the - [Required Reading](#ReqReading) section for the original white paper) -- Experience in some type of C-like language -- An understanding of data structures and their performance implications -- Familiarity with unit testing -- Debugging experience -- Ability to understand not only the area you are making a change in, but also - the code your change relies on, and the code which relies on your changed code - -Building on top of those core competencies, the recommended skill set largely -depends on the specific areas you are looking to contribute to. For example, -if you wish to contribute to the cryptography code, you should have a good -understanding of the various aspects involved with cryptography such as the -security and performance implications. - -## Required Reading - -- [Effective Go](http://golang.org/doc/effective_go.html) - The entire btcd - suite follows the guidelines in this document. For your code to be accepted, - it must follow the guidelines therein. -- [Original Satoshi Whitepaper](http://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&ved=0CCkQFjAA&url=http%3A%2F%2Fbitcoin.org%2Fbitcoin.pdf&ei=os3VUuH8G4SlsASV74GoAg&usg=AFQjCNEipPLigou_1MfB7DQjXCNdlylrBg&sig2=FaHDuT5z36GMWDEnybDJLg&bvm=bv.59378465,d.b2I) - This is the white paper that started it all. Having a solid - foundation to build on will make the code much more comprehensible. - -## Development Practices - -Developers are expected to work in their own trees and submit pull requests when -they feel their feature or bug fix is ready for integration into the master -branch. - -## Share Early, Share Often - -We firmly believe in the share early, share often approach. The basic premise -of the approach is to announce your plans **before** you start work, and once -you have started working, craft your changes into a stream of small and easily -reviewable commits. - -This approach has several benefits: - -- Announcing your plans to work on a feature **before** you begin work avoids - duplicate work -- It permits discussions which can help you achieve your goals in a way that is - consistent with the existing architecture -- It minimizes the chances of you spending time and energy on a change that - might not fit with the consensus of the community or existing architecture and - potentially be rejected as a result -- Incremental development helps ensure you are on the right track with regards - to the rest of the community -- The quicker your changes are merged to master, the less time you will need to - spend rebasing and otherwise trying to keep up with the main code base - -## Testing - -One of the major design goals of all core btcd packages is to aim for complete -test coverage. This is financial software so bugs and regressions can cost -people real money. For this reason every effort must be taken to ensure the -code is as accurate and bug-free as possible. Thorough testing is a good way to -help achieve that goal. - -Unless a new feature you submit is completely trivial, it will probably be -rejected unless it is also accompanied by adequate test coverage for both -positive and negative conditions. That is to say, the tests must ensure your -code works correctly when it is fed correct data as well as incorrect data -(error paths). - -Go provides an excellent test framework that makes writing test code and -checking coverage statistics straight forward. For more information about the -test coverage tools, see the [golang cover blog post](http://blog.golang.org/cover). - -A quick summary of test practices follows: - -- All new code should be accompanied by tests that ensure the code behaves - correctly when given expected values, and, perhaps even more importantly, that - it handles errors gracefully -- When you fix a bug, it should be accompanied by tests which exercise the bug - to both prove it has been resolved and to prevent future regressions - -## Code Documentation and Commenting - -- At a minimum every function must be commented with its intended purpose and - any assumptions that it makes - - Function comments must always begin with the name of the function per - [Effective Go](http://golang.org/doc/effective_go.html) - - Function comments should be complete sentences since they allow a wide - variety of automated presentations such as [go.dev](https://go.dev) - - The general rule of thumb is to look at it as if you were completely - unfamiliar with the code and ask yourself, would this give me enough - information to understand what this function does and how I'd probably want - to use it? -- Exported functions should also include detailed information the caller of the - function will likely need to know and/or understand: - -**WRONG** - -```Go -// convert a compact uint32 to big.Int -func CompactToBig(compact uint32) *big.Int { -``` - -**RIGHT** - -```Go -// CompactToBig converts a compact representation of a whole number N to a -// big integer. The representation is similar to IEEE754 floating point -// numbers. -// -// Like IEEE754 floating point, there are three basic components: the sign, -// the exponent, and the mantissa. They are broken out as follows: -// -// * the most significant 8 bits represent the unsigned base 256 exponent -// * bit 23 (the 24th bit) represents the sign bit -// * the least significant 23 bits represent the mantissa -// -// ------------------------------------------------- -// | Exponent | Sign | Mantissa | -// ------------------------------------------------- -// | 8 bits [31-24] | 1 bit [23] | 23 bits [22-00] | -// ------------------------------------------------- -// -// The formula to calculate N is: -// N = (-1^sign) * mantissa * 256^(exponent-3) -// -// This compact form is only used in bitcoin to encode unsigned 256-bit numbers -// which represent difficulty targets, thus there really is not a need for a -// sign bit, but it is implemented here to stay consistent with bitcoind. -func CompactToBig(compact uint32) *big.Int { -``` - -- Comments in the body of the code are highly encouraged, but they should - explain the intention of the code as opposed to just calling out the - obvious - -**WRONG** - -```Go -// return err if amt is less than 5460 -if amt < 5460 { - return err -} -``` - -**RIGHT** - -```Go -// Treat transactions with amounts less than the amount which is considered dust -// as non-standard. -if amt < 5460 { - return err -} -``` - -**NOTE:** The above should really use a constant as opposed to a magic number, -but it was left as a magic number to show how much of a difference a good -comment can make. - -## Model Git Commit Messages - -This project prefers to keep a clean commit history with well-formed commit -messages. This section illustrates a model commit message and provides a bit -of background for it. This content was originally created by Tim Pope and made -available on his website, however that website is no longer active, so it is -being provided here. - -Here’s a model Git commit message: - -```text -Short (50 chars or less) summary of changes - -More detailed explanatory text, if necessary. Wrap it to about 72 -characters or so. In some contexts, the first line is treated as the -subject of an email and the rest of the text as the body. The blank -line separating the summary from the body is critical (unless you omit -the body entirely); tools like rebase can get confused if you run the -two together. - -Write your commit message in the present tense: "Fix bug" and not "Fixed -bug." This convention matches up with commit messages generated by -commands like git merge and git revert. - -Further paragraphs come after blank lines. - -- Bullet points are okay, too -- Typically a hyphen or asterisk is used for the bullet, preceded by a - single space, with blank lines in between, but conventions vary here -- Use a hanging indent -``` - -Prefix the summary with the subsystem/package when possible. Many other -projects make use of the code and this makes it easier for them to tell when -something they're using has changed. Have a look at [past -commits](https://github.com/btcsuite/btcd/commits/master) for examples of -commit messages. - -Here are some of the reasons why wrapping your commit messages to 72 columns is -a good thing. - -- git log doesn’t do any special special wrapping of the commit messages. With - the default pager of less -S, this means your paragraphs flow far off the edge - of the screen, making them difficult to read. On an 80 column terminal, if we - subtract 4 columns for the indent on the left and 4 more for symmetry on the - right, we’re left with 72 columns. -- git format-patch --stdout converts a series of commits to a series of emails, - using the messages for the message body. Good email netiquette dictates we - wrap our plain text emails such that there’s room for a few levels of nested - reply indicators without overflow in an 80 column terminal. - -## Code Approval Process - -This section describes the code approval process that is used for code -contributions. This is how to get your changes into btcd. - -## Code Review - -All code which is submitted will need to be reviewed before inclusion into the -master branch. This process is performed by the project maintainers and usually -other committers who are interested in the area you are working in as well. - -## Code Review Timeframe - -The timeframe for a code review will vary greatly depending on factors such as -the number of other pull requests which need to be reviewed, the size and -complexity of the contribution, how well you followed the guidelines presented -on this page, and how easy it is for the reviewers to digest your commits. For -example, if you make one monolithic commit that makes sweeping changes to things -in multiple subsystems, it will obviously take much longer to review. You will -also likely be asked to split the commit into several smaller, and hence more -manageable, commits. - -Keeping the above in mind, most small changes will be reviewed within a few -days, while large or far reaching changes may take weeks. This is a good reason -to stick with the [Share Early, Share Often](#ShareOften) development practice -outlined above. - -## What is the review looking for? - -The review is mainly ensuring the code follows the [Development Practices](#DevelopmentPractices) -and [Code Contribution Standards](#Standards). However, there are a few other -checks which are generally performed as follows: - -- The code is stable and has no stability or security concerns -- The code is properly using existing APIs and generally fits well into the - overall architecture -- The change is not something which is deemed inappropriate by community - consensus - -## Rework Code (if needed) - -After the code review, the change will be accepted immediately if no issues are -found. If there are any concerns or questions, you will be provided with -feedback along with the next steps needed to get your contribution merged with -master. In certain cases the code reviewer(s) or interested committers may help -you rework the code, but generally you will simply be given feedback for you to -make the necessary changes. - -This process will continue until the code is finally accepted. - -## Acceptance - -Once your code is accepted, it will be integrated with the master branch. -Typically it will be rebased and fast-forward merged to master as we prefer to -keep a clean commit history over a tangled weave of merge commits. However, -regardless of the specific merge method used, the code will be integrated with -the master branch and the pull request will be closed. - -Rejoice as you will now be listed as a [contributor](https://github.com/btcsuite/btcd/graphs/contributors)! - -## Contribution Standards - -## Contribution Checklist - -- [  ] All changes are Go version 1.3 compliant -- [  ] The code being submitted is commented according to the - [Code Documentation and Commenting](#CodeDocumentation) section -- [  ] For new code: Code is accompanied by tests which exercise both - the positive and negative (error paths) conditions (if applicable) -- [  ] For bug fixes: Code is accompanied by new tests which trigger - the bug being fixed to prevent regressions -- [  ] Any new logging statements use an appropriate subsystem and - logging level -- [  ] Code has been formatted with `go fmt` -- [  ] Running `go test` does not fail any tests -- [  ] Running `go vet` does not report any issues -- [  ] Running [golint](https://github.com/golang/lint) does not - report any **new** issues that did not already exist - -## Licensing of Contributions - -All contributions must be licensed with the -[ISC license](https://github.com/btcsuite/btcd/blob/master/LICENSE). This is -the same license as all of the code in the btcd suite. diff --git a/docs/conf.py b/docs/conf.py index b5fc6b7155..145c0ac5c6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,9 +18,9 @@ # -- Project information ----------------------------------------------------- -project = 'btcd' -copyright = '2020, btcd' -author = 'btcsuite developers' +project = 'lbcd' +copyright = '2021, lbcd' +author = 'LBRY developers' # The full version, including alpha/beta/rc tags release = 'beta' diff --git a/docs/configuration.md b/docs/configuration.md index c6f95b274c..5ece75e87e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,11 +1,11 @@ # Configuration -btcd has a number of [configuration](https://pkg.go.dev/github.com/btcsuite/btcd) -options, which can be viewed by running: `$ btcd --help`. +lbcd has a number of configuration +options, which can be viewed by running: `$ lbcd --help`. ## Peer server listen interface -btcd allows you to bind to specific interfaces which enables you to setup +lbcd allows you to bind to specific interfaces which enables you to setup configurations with varying levels of complexity. The listen parameter can be specified on the command line as shown below with the -- prefix or in the configuration file without the -- prefix (as can all long command line options). @@ -32,7 +32,7 @@ Command Line Examples: |--listen=127.0.0.1:8337 --listen=[::1]:8333|IPv4 localhost on port 8337 and IPv6 localhost on port 8333| |--listen=:8333 --listen=:8337|all interfaces on ports 8333 and 8337| -The following config file would configure btcd to only listen on localhost for both IPv4 and IPv6: +The following config file would configure lbcd to only listen on localhost for both IPv4 and IPv6: ```text [Application Options] @@ -41,17 +41,17 @@ listen=127.0.0.1:8333 listen=[::1]:8333 ``` -In addition, if you are starting btcd with TLS and want to make it +In addition, if you are starting lbcd with TLS and want to make it available via a hostname, then you will need to generate the TLS certificates for that host. For example, ``` -gencerts --host=myhostname.example.com --directory=/home/me/.btcd/ +gencerts --host=myhostname.example.com --directory=/home/me/.lbcd/ ``` ## RPC server listen interface -btcd allows you to bind the RPC server to specific interfaces which enables you +lbcd allows you to bind the RPC server to specific interfaces which enables you to setup configurations with varying levels of complexity. The `rpclisten` parameter can be specified on the command line as shown below with the -- prefix or in the configuration file without the -- prefix (as can all long command line @@ -92,7 +92,7 @@ Command Line Examples: |--rpclisten=127.0.0.1:8337 --listen=[::1]:8334|IPv4 localhost on port 8337 and IPv6 localhost on port 8334| |--rpclisten=:8334 --listen=:8337|all interfaces on ports 8334 and 8337| -The following config file would configure the btcd RPC server to listen to all interfaces on the default port, including external interfaces, for both IPv4 and IPv6: +The following config file would configure the lbcd RPC server to listen to all interfaces on the default port, including external interfaces, for both IPv4 and IPv6: ```text [Application Options] @@ -102,21 +102,21 @@ rpclisten= ## Default ports -While btcd is highly configurable when it comes to the network configuration, +While lbcd is highly configurable when it comes to the network configuration, the following is intended to be a quick reference for the default ports used so port forwarding can be configured as required. -btcd provides a `--upnp` flag which can be used to automatically map the bitcoin +lbcd by default will automatically map the peer-to-peer listening port if your router supports UPnP. If your router does -not support UPnP, or you don't wish to use it, please note that only the bitcoin +not support UPnP, or you don't wish to use it, please note that only the peer-to-peer port should be forwarded unless you specifically want to allow RPC -access to your btcd from external sources such as in more advanced network -configurations. +access to your lbcd from external sources such as in more advanced network +configurations. You can disable UPnP with the `--noupnp` daemon option. |Name|Port| |----|----| -|Default Bitcoin peer-to-peer port|TCP 8333| -|Default RPC port|TCP 8334| +|Default peer-to-peer port|TCP 9246| +|Default RPC port|TCP 9245| ## Using bootstrap.dat @@ -129,7 +129,7 @@ on the last time it was updated. See [this](https://bitcointalk.org/index.php?topic=145386.0) thread on bitcointalk for more details. -**NOTE:** Using bootstrap.dat is entirely optional. Btcd will download the +**NOTE:** Using bootstrap.dat is entirely optional. lbcd will download the block chain from other peers through the Bitcoin protocol with no extra configuration needed. @@ -165,14 +165,14 @@ checkpoints for the known-good block chain at periodic intervals. This ensures that not only is it a valid chain, but it is the same chain that everyone else is using. -### How do I use bootstrap.dat with btcd? +### How do I use bootstrap.dat with lbcd? -btcd comes with a separate utility named `addblock` which can be used to import +lbcd comes with a separate utility named `addblock` which can be used to import `bootstrap.dat`. This approach is used since the import is a one-time operation and we prefer to keep the daemon itself as lightweight as possible. -1. Stop btcd if it is already running. This is required since addblock needs to - access the database used by btcd and it will be locked if btcd is using it. +1. Stop lbcd if it is already running. This is required since addblock needs to + access the database used by lbcd and it will be locked if lbcd is using it. 2. Note the path to the downloaded bootstrap.dat file. 3. Run the addblock utility with the `-i` argument pointing to the location of boostrap.dat: @@ -180,7 +180,7 @@ and we prefer to keep the daemon itself as lightweight as possible. **Windows:** ```bat -"%PROGRAMFILES%\Btcd Suite\Btcd\addblock" -i C:\Path\To\bootstrap.dat +"%PROGRAMFILES%\lbcd Suite\lbcd\addblock" -i C:\Path\To\bootstrap.dat ``` **Linux/Unix/BSD/POSIX:** diff --git a/docs/configuring_tor.md b/docs/configuring_tor.md index ecb03bfc32..6f8f821a08 100644 --- a/docs/configuring_tor.md +++ b/docs/configuring_tor.md @@ -1,9 +1,9 @@ # Configuring TOR -btcd provides full support for anonymous networking via the +lbcd provides full support for anonymous networking via the [Tor Project](https://www.torproject.org/), including [client-only](#Client) and [hidden service](#HiddenService) configurations along with -[stream isolation](#TorStreamIsolation). In addition, btcd supports a hybrid, +[stream isolation](#TorStreamIsolation). In addition, lbcd supports a hybrid, [bridge mode](#Bridge) which is not anonymous, but allows it to operate as a bridge between regular nodes and hidden service nodes without routing the regular connections through Tor. @@ -15,15 +15,15 @@ hidden service for this reason. ## Client-only -Configuring btcd as a Tor client is straightforward. The first step is +Configuring lbcd as a Tor client is straightforward. The first step is obviously to install Tor and ensure it is working. Once that is done, all that -typically needs to be done is to specify the `--proxy` flag via the btcd command -line or in the btcd configuration file. Typically the Tor proxy address will be +typically needs to be done is to specify the `--proxy` flag via the lbcd command +line or in the lbcd configuration file. Typically the Tor proxy address will be 127.0.0.1:9050 (if using standalone Tor) or 127.0.0.1:9150 (if using the Tor Browser Bundle). If you have Tor configured to require a username and password, you may specify them with the `--proxyuser` and `--proxypass` flags. -By default, btcd assumes the proxy specified with `--proxy` is a Tor proxy and +By default, lbcd assumes the proxy specified with `--proxy` is a Tor proxy and hence will send all traffic, including DNS resolution requests, via the specified proxy. @@ -34,7 +34,7 @@ not be reachable for inbound connections unless you also configure a Tor ### Command line example ```bash -./btcd --proxy=127.0.0.1:9050 +./lbcd --proxy=127.0.0.1:9050 ``` ### Config file example @@ -51,7 +51,7 @@ The first step is to configure Tor to provide a hidden service. Documentation for this can be found on the Tor project website [here](https://www.torproject.org/docs/tor-hidden-service.html.en). However, there is no need to install a web server locally as the linked instructions -discuss since btcd will act as the server. +discuss since lbcd will act as the server. In short, the instructions linked above entail modifying your `torrc` file to add something similar to the following, restarting Tor, and opening the @@ -59,12 +59,12 @@ add something similar to the following, restarting Tor, and opening the address. ```text -HiddenServiceDir /var/tor/btcd +HiddenServiceDir /var/tor/lbcd HiddenServicePort 8333 127.0.0.1:8333 ``` Once Tor is configured to provide the hidden service and you have obtained your -generated .onion address, configuring btcd as a Tor hidden service requires +generated .onion address, configuring lbcd as a Tor hidden service requires three flags: * `--proxy` to identify the Tor (SOCKS 5) proxy to use for outgoing traffic. @@ -76,7 +76,7 @@ three flags: ### Command line example ```bash -./btcd --proxy=127.0.0.1:9050 --listen=127.0.0.1 --externalip=fooanon.onion +./lbcd --proxy=127.0.0.1:9050 --listen=127.0.0.1 --externalip=fooanon.onion ``` ### Config file example @@ -91,13 +91,13 @@ externalip=fooanon.onion ## Bridge mode (not anonymous) -btcd provides support for operating as a bridge between regular nodes and hidden +lbcd provides support for operating as a bridge between regular nodes and hidden service nodes. In particular this means only traffic which is directed to or from a .onion address is sent through Tor while other traffic is sent normally. _As a result, this mode is **NOT** anonymous._ This mode works by specifying an onion-specific proxy, which is pointed at Tor, -by using the `--onion` flag via the btcd command line or in the btcd +by using the `--onion` flag via the lbcd command line or in the lbcd configuration file. If you have Tor configured to require a username and password, you may specify them with the `--onionuser` and `--onionpass` flags. @@ -111,7 +111,7 @@ routed via Tor due to the `--onion` flag. ### Command line example ```bash -./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion +./lbcd --onion=127.0.0.1:9050 --externalip=fooanon.onion ``` ### Config file example @@ -128,13 +128,13 @@ externalip=fooanon.onion Tor stream isolation forces Tor to build a new circuit for each connection making it harder to correlate connections. -btcd provides support for Tor stream isolation by using the `--torisolation` +lbcd provides support for Tor stream isolation by using the `--torisolation` flag. This option requires --proxy or --onionproxy to be set. ### Command line example ```bash -./btcd --proxy=127.0.0.1:9050 --torisolation +./lbcd --proxy=127.0.0.1:9050 --torisolation ``` ### Config file example diff --git a/docs/contact.md b/docs/contact.md deleted file mode 100644 index 88b425e8bc..0000000000 --- a/docs/contact.md +++ /dev/null @@ -1,15 +0,0 @@ -# Contact - -## IRC - -* [irc.freenode.net](irc://irc.freenode.net), channel `#btcd` - -## Mailing Lists - -* [btcd](mailto:btcd+subscribe@opensource.conformal.com): discussion of btcd and its packages. -* [btcd-commits](mailto:btcd-commits+subscribe@opensource.conformal.com): readonly mail-out of source code changes. - -## Issue Tracker - -The [integrated github issue tracker](https://github.com/btcsuite/btcd/issues) -is used for this project. diff --git a/docs/controlling.md b/docs/controlling.md index 93ab403b2e..a187e412b2 100644 --- a/docs/controlling.md +++ b/docs/controlling.md @@ -1,11 +1,11 @@ -# Controlling and querying btcd via btcctl +# Controlling and querying lbcd via lbcctl -btcctl is a command line utility that can be used to both control and query btcd -via [RPC](http://www.wikipedia.org/wiki/Remote_procedure_call). btcd does +lbcctl is a command line utility that can be used to both control and query lbcd +via [RPC](http://www.wikipedia.org/wiki/Remote_procedure_call). lbcd does **not** enable its RPC server by default; You must configure at minimum both an RPC username and password or both an RPC limited username and password: -* btcd.conf configuration file +* lbcd.conf configuration file ```bash [Application Options] @@ -15,7 +15,7 @@ rpclimituser=mylimituser rpclimitpass=Limitedp4ssw0rd ``` -* btcctl.conf configuration file +* lbcctl.conf configuration file ```bash [Application Options] @@ -31,4 +31,4 @@ rpclimituser=mylimituser rpclimitpass=Limitedp4ssw0rd ``` -For a list of available options, run: `$ btcctl --help` +For a list of available options, run: `$ lbcctl --help` diff --git a/docs/developer_resources.md b/docs/developer_resources.md deleted file mode 100644 index cec8ce9972..0000000000 --- a/docs/developer_resources.md +++ /dev/null @@ -1,37 +0,0 @@ -# Developer Resources - -* [Code Contribution Guidelines](https://github.com/btcsuite/btcd/tree/master/docs/code_contribution_guidelines.md) - -* [JSON-RPC Reference](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md) - * [RPC Examples](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md#ExampleCode) - -* The btcsuite Bitcoin-related Go Packages: - * [btcrpcclient](https://github.com/btcsuite/btcd/tree/master/rpcclient) - Implements a - robust and easy to use Websocket-enabled Bitcoin JSON-RPC client - * [btcjson](https://github.com/btcsuite/btcd/tree/master/btcjson) - Provides an extensive API - for the underlying JSON-RPC command and return values - * [wire](https://github.com/btcsuite/btcd/tree/master/wire) - Implements the - Bitcoin wire protocol - * [peer](https://github.com/btcsuite/btcd/tree/master/peer) - - Provides a common base for creating and managing Bitcoin network peers. - * [blockchain](https://github.com/btcsuite/btcd/tree/master/blockchain) - - Implements Bitcoin block handling and chain selection rules - * [blockchain/fullblocktests](https://github.com/btcsuite/btcd/tree/master/blockchain/fullblocktests) - - Provides a set of block tests for testing the consensus validation rules - * [txscript](https://github.com/btcsuite/btcd/tree/master/txscript) - - Implements the Bitcoin transaction scripting language - * [btcec](https://github.com/btcsuite/btcd/tree/master/btcec) - Implements - support for the elliptic curve cryptographic functions needed for the - Bitcoin scripts - * [database](https://github.com/btcsuite/btcd/tree/master/database) - - Provides a database interface for the Bitcoin block chain - * [mempool](https://github.com/btcsuite/btcd/tree/master/mempool) - - Package mempool provides a policy-enforced pool of unmined bitcoin - transactions. - * [btcutil](https://github.com/btcsuite/btcutil) - Provides Bitcoin-specific - convenience functions and types - * [chainhash](https://github.com/btcsuite/btcd/tree/master/chaincfg/chainhash) - - Provides a generic hash type and associated functions that allows the - specific hash algorithm to be abstracted. - * [connmgr](https://github.com/btcsuite/btcd/tree/master/connmgr) - - Package connmgr implements a generic Bitcoin network connection manager. diff --git a/docs/index.md b/docs/index.md index 9d980626d4..a3792a6fa7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,57 +1,11 @@ -# btcd +# lbcd -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd) - -btcd is an alternative full node bitcoin implementation written in Go (golang). - -This project is currently under active development and is in a Beta state. It -is extremely stable and has been in production use since October 2013. - -It properly downloads, validates, and serves the block chain using the exact -rules (including consensus bugs) for block acceptance as Bitcoin Core. We have -taken great care to avoid btcd causing a fork to the block chain. It includes a -full block validation testing framework which contains all of the 'official' -block acceptance tests (and some additional ones) that is run on every pull -request to help ensure it properly follows consensus. Also, it passes all of -the JSON test data in the Bitcoin Core code. - -It also properly relays newly mined blocks, maintains a transaction pool, and -relays individual transactions that have not yet made it into a block. It -ensures all individual transactions admitted to the pool follow the rules -required by the block chain and also includes more strict checks which filter -transactions based on miner requirements ("standard" transactions). - -One key difference between btcd and Bitcoin Core is that btcd does *NOT* include -wallet functionality and this was a very intentional design decision. See the -blog entry [here](https://web.archive.org/web/20171125143919/https://blog.conformal.com/btcd-not-your-moms-bitcoin-daemon) -for more details. This means you can't actually make or receive payments -directly with btcd. That functionality is provided by the -[btcwallet](https://github.com/btcsuite/btcwallet) and -[Paymetheus](https://github.com/btcsuite/Paymetheus) (Windows-only) projects -which are both under active development. - -## Documentation - -Documentation is a work-in-progress. It is available at [btcd.readthedocs.io](https://btcd.readthedocs.io). ## Contents -* [Installation](installation.md) -* [Update](update.md) * [Configuration](configuration.md) * [Configuring TOR](configuring_tor.md) -* [Docker](using_docker.md) * [Controlling](controlling.md) * [Mining](mining.md) -* [Wallet](wallet.md) -* [Developer resources](developer_resources.md) * [JSON RPC API](json_rpc_api.md) -* [Code contribution guidelines](code_contribution_guidelines.md) -* [Contact](contact.md) - -## License - -btcd is licensed under the [copyfree](http://copyfree.org) ISC License. - diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index c3c206060b..0000000000 --- a/docs/installation.md +++ /dev/null @@ -1,76 +0,0 @@ -# Installation - -The first step is to install btcd. See one of the following sections for -details on how to install on the supported operating systems. - -## Requirements - -[Go](http://golang.org) 1.11 or newer. - -## GPG Verification Key - -All official release tags are signed by Conformal so users can ensure the code -has not been tampered with and is coming from the btcsuite developers. To -verify the signature perform the following: - -* Download the Conformal public key: - https://raw.githubusercontent.com/btcsuite/btcd/master/release/GIT-GPG-KEY-conformal.txt - -* Import the public key into your GPG keyring: - - ```bash - gpg --import GIT-GPG-KEY-conformal.txt - ``` - -* Verify the release tag with the following command where `TAG_NAME` is a - placeholder for the specific tag: - - ```bash - git tag -v TAG_NAME - ``` - -## Windows Installation - -* Install the MSI available at: [btcd windows installer](https://github.com/btcsuite/btcd/releases) -* Launch btcd from the Start Menu - -## Linux/BSD/MacOSX/POSIX Installation - -* Install Go according to the [installation instructions](http://golang.org/doc/install) -* Ensure Go was installed properly and is a supported version: - -```bash -go version -go env GOROOT GOPATH -``` - -NOTE: The `GOROOT` and `GOPATH` above must not be the same path. It is -recommended that `GOPATH` is set to a directory in your home directory such as -`~/goprojects` to avoid write permission issues. It is also recommended to add -`$GOPATH/bin` to your `PATH` at this point. - -* Run the following commands to obtain btcd, all dependencies, and install it: - -```bash -git clone https://github.com/btcsuite/btcd $GOPATH/src/github.com/btcsuite/btcd -cd $GOPATH/src/github.com/btcsuite/btcd -GO111MODULE=on go install -v . ./cmd/... -``` - -* btcd (and utilities) will now be installed in ```$GOPATH/bin```. If you did - not already add the bin directory to your system path during Go installation, - we recommend you do so now. - -## Gentoo Linux Installation - -* [Install Layman](https://gitlab.com/bitcoin/gentoo) and enable the Bitcoin overlay. -* Copy or symlink `/var/lib/layman/bitcoin/Documentation/package.keywords/btcd-live` to `/etc/portage/package.keywords/` -* Install btcd: `$ emerge net-p2p/btcd` - -## Startup - -Typically btcd will run and start downloading the block chain with no extra -configuration necessary, however, there is an optional method to use a -`bootstrap.dat` file that may speed up the initial block chain download process. - -* [Using bootstrap.dat](https://github.com/btcsuite/btcd/blob/master/docs/configuration.md#using-bootstrapdat) diff --git a/docs/json_rpc_api.md b/docs/json_rpc_api.md index bf3c0f2b5b..5493c42913 100644 --- a/docs/json_rpc_api.md +++ b/docs/json_rpc_api.md @@ -27,26 +27,18 @@ ### 1. Overview -btcd provides a [JSON-RPC](http://json-rpc.org/wiki/specification) API that is +lbcd provides a [JSON-RPC](http://json-rpc.org/wiki/specification) API that is fully compatible with the original bitcoind/bitcoin-qt. There are a few key -differences between btcd and bitcoind as far as how RPCs are serviced: -* Unlike bitcoind that has the wallet and chain intermingled in the same process - which leads to several issues, btcd intentionally splits the wallet and chain - services into independent processes. See the blog post - [here](https://blog.conformal.com/btcd-not-your-moms-bitcoin-daemon/) for - further details on why they were separated. This means that if you are - talking directly to btcd, only chain-related RPCs are available. However both - chain-related and wallet-related RPCs are available via - [btcwallet](https://github.com/btcsuite/btcwallet). -* btcd is secure by default which means that the RPC connection is TLS-enabled +differences between lbcd and bitcoind as far as how RPCs are serviced: +* lbcd is secure by default which means that the RPC connection is TLS-enabled by default -* btcd provides access to the API through both +* lbcd provides access to the API through both [HTTP POST](http://en.wikipedia.org/wiki/POST_%28HTTP%29) requests and [Websockets](http://en.wikipedia.org/wiki/WebSocket) -Websockets are the preferred transport for btcd RPC and are used by applications +Websockets are the preferred transport for lbcd RPC and are used by applications such as [btcwallet](https://github.com/btcsuite/btcwallet) for inter-process -communication with btcd. The websocket connection endpoint for btcd is +communication with lbcd. The websocket connection endpoint for lbcd is `wss://your_ip_or_domain:9245/ws`. In addition to the [standard API](#Methods), an [extension API](#WSExtMethods) @@ -64,7 +56,7 @@ The original bitcoind/bitcoin-qt JSON-RPC API documentation is available at [htt ### 2. HTTP POST Versus Websockets -The btcd RPC server supports both [HTTP POST](http://en.wikipedia.org/wiki/POST_%28HTTP%29) +The lbcd RPC server supports both [HTTP POST](http://en.wikipedia.org/wiki/POST_%28HTTP%29) requests and the preferred [Websockets](http://en.wikipedia.org/wiki/WebSocket). All of the [standard](#Methods) and [extension](#ExtensionMethods) methods described in this documentation can be accessed through both. As the name @@ -72,7 +64,7 @@ indicates, the [Websocket-specific extension](#WSExtMethods) methods can only be accessed when connected via Websockets. As mentioned in the [overview](#Overview), the websocket connection endpoint for -btcd is `wss://your_ip_or_domain:9245/ws`. +lbcd is `wss://your_ip_or_domain:9245/ws`. The most important differences between the two transports as it pertains to the JSON-RPC API are: @@ -92,18 +84,18 @@ JSON-RPC API are: **3.1 Authentication Overview**
The following authentication details are needed before establishing a connection -to a btcd RPC server: - -* **rpcuser** is the full-access username configured for the btcd RPC server -* **rpcpass** is the full-access password configured for the btcd RPC server -* **rpclimituser** is the limited username configured for the btcd RPC server -* **rpclimitpass** is the limited password configured for the btcd RPC server -* **rpccert** is the PEM-encoded X.509 certificate (public key) that the btcd - server is configured with. It is automatically generated by btcd and placed - in the btcd home directory (which is typically `%LOCALAPPDATA%\Btcd` on - Windows and `~/.btcd` on POSIX-like OSes) - -**NOTE:** As mentioned above, btcd is secure by default which means the RPC +to a lbcd RPC server: + +* **rpcuser** is the full-access username configured for the lbcd RPC server +* **rpcpass** is the full-access password configured for the lbcd RPC server +* **rpclimituser** is the limited username configured for the lbcd RPC server +* **rpclimitpass** is the limited password configured for the lbcd RPC server +* **rpccert** is the PEM-encoded X.509 certificate (public key) that the lbcd + server is configured with. It is automatically generated by lbcd and placed + in the lbcd home directory (which is typically `%LOCALAPPDATA%\lbcd` on + Windows and `~/.lbcd` on POSIX-like OSes) + +**NOTE:** As mentioned above, lbcd is secure by default which means the RPC server is not running unless configured with a **rpcuser** and **rpcpass** and/or a **rpclimituser** and **rpclimitpass**, and uses TLS authentication for all connections. @@ -117,7 +109,7 @@ two, mutually exclusive, methods. **3.2 HTTP Basic Access Authentication**
-The btcd RPC server uses HTTP [basic access authentication](http://en.wikipedia.org/wiki/Basic_access_authentication) with the **rpcuser** +The lbcd RPC server uses HTTP [basic access authentication](http://en.wikipedia.org/wiki/Basic_access_authentication) with the **rpcuser** and **rpcpass** detailed above. If the supplied credentials are invalid, you will be disconnected immediately upon making the connection. @@ -139,8 +131,8 @@ authenticated will cause the websocket to be closed immediately. ### 4. Command-line Utility -btcd comes with a separate utility named `btcctl` which can be used to issue -these RPC commands via HTTP POST requests to btcd after configuring it with the +lbcd comes with a separate utility named `lbcctl` which can be used to issue +these RPC commands via HTTP POST requests to lbcd after configuring it with the information in the [Authentication](#Authentication) section above. It can also be used to communicate with any server/daemon/service which provides a JSON-RPC API compatible with the original bitcoind/bitcoin-qt client. @@ -182,11 +174,11 @@ the method name for further details such as parameter and return information. | 22 | [getrawtransaction](#getrawtransaction) | Y | Returns information about a transaction given its hash. | | 23 | [help](#help) | Y | Returns a list of all commands or help for a specified command. | | 24 | [ping](#ping) | N | Queues a ping to be sent to each connected peer. | -| 25 | [sendrawtransaction](#sendrawtransaction) | Y | Submits the serialized, hex-encoded transaction to the local peer and relays it to the network.
btcd does not yet implement the `allowhighfees` parameter, so it has no effect | -| 26 | [setgenerate](#setgenerate) | N | Set the server to generate coins (mine) or not.
NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function. | -| 27 | [stop](#stop) | N | Shutdown btcd. | +| 25 | [sendrawtransaction](#sendrawtransaction) | Y | Submits the serialized, hex-encoded transaction to the local peer and relays it to the network.
lbcd does not yet implement the `allowhighfees` parameter, so it has no effect | +| 26 | [setgenerate](#setgenerate) | N | Set the server to generate coins (mine) or not.
NOTE: Since lbcd does not have the wallet integrated to provide payment addresses, lbcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function. | +| 27 | [stop](#stop) | N | Shutdown lbcd. | | 28 | [submitblock](#submitblock) | Y | Attempts to submit a new serialized, hex-encoded block to the network. | -| 29 | [validateaddress](#validateaddress) | Y | Verifies the given address is valid. NOTE: Since btcd does not have a wallet integrated, btcd will only return whether the address is valid or not. | +| 29 | [validateaddress](#validateaddress) | Y | Verifies the given address is valid. NOTE: Since lbcd does not have a wallet integrated, lbcd will only return whether the address is valid or not. | | 30 | [verifychain](#verifychain) | N | Verifies the block chain database. | @@ -373,7 +365,7 @@ the method name for further details such as parameter and return information. | Method | getinfo | | Parameters | None | | Description | Returns a JSON object containing various state info. | -| Notes | NOTE: Since btcd does NOT contain wallet functionality, wallet-related fields are not returned. See getinfo in btcwallet for a version which includes that information. | +| Notes | NOTE: Since lbcd does NOT contain wallet functionality, wallet-related fields are not returned. See getinfo in btcwallet for a version which includes that information. | | Returns | `{ (json object)`
  `"version": n, (numeric) the version of the server`
  `"protocolversion": n, (numeric) the latest supported protocol version`
  `"blocks": n, (numeric) the number of blocks processed`
  `"timeoffset": n, (numeric) the time offset`
  `"connections": n, (numeric) the number of connected peers`
  `"proxy": "host:port", (string) the proxy used by the server`
  `"difficulty": n.nn, (numeric) the current target difficulty`
  `"testnet": true or false, (boolean) whether or not server is using testnet`
  `"relayfee": n.nn, (numeric) the minimum relay fee for non-free transactions in BTC/KB`
`}` | | Example Return | `{`
  `"version": 70000`
  `"protocolversion": 70001, `
  `"blocks": 298963,`
  `"timeoffset": 0,`
  `"connections": 17,`
  `"proxy": "",`
  `"difficulty": 8000872135.97,`
  `"testnet": false,`
  `"relayfee": 0.00001,`
`}` | [Return to Overview](#MethodOverview)
@@ -435,7 +427,7 @@ the method name for further details such as parameter and return information. | Parameters | None | | Description | Returns data about each connected network peer as an array of json objects. | | Returns | `[`
  `{`
    `"addr": "host:port", (string) the ip address and port of the peer`
    `"services": "00000001", (string) the services supported by the peer`
    `"lastrecv": n, (numeric) time the last message was received in seconds since 1 Jan 1970 GMT`
    `"lastsend": n, (numeric) time the last message was sent in seconds since 1 Jan 1970 GMT`
    `"bytessent": n, (numeric) total bytes sent`
    `"bytesrecv": n, (numeric) total bytes received`
    `"conntime": n, (numeric) time the connection was made in seconds since 1 Jan 1970 GMT`
    `"pingtime": n, (numeric) number of microseconds the last ping took`
    `"pingwait": n, (numeric) number of microseconds a queued ping has been waiting for a response`
    `"version": n, (numeric) the protocol version of the peer`
    `"subver": "useragent", (string) the user agent of the peer`
    `"inbound": true_or_false, (boolean) whether or not the peer is an inbound connection`
    `"startingheight": n, (numeric) the latest block height the peer knew about when the connection was established`
    `"currentheight": n, (numeric) the latest block height the peer is known to have relayed since connected`
    `"syncnode": true_or_false, (boolean) whether or not the peer is the sync peer`
  `}, ...`
`]` | -| Example Return | `[`
  `{`
    `"addr": "178.172.xxx.xxx:8333",`
    `"services": "00000001",`
    `"lastrecv": 1388183523,`
    `"lastsend": 1388185470,`
    `"bytessent": 287592965,`
    `"bytesrecv": 780340,`
    `"conntime": 1388182973,`
    `"pingtime": 405551,`
    `"pingwait": 183023,`
    `"version": 70001,`
    `"subver": "/btcd:0.4.0/",`
    `"inbound": false,`
    `"startingheight": 276921,`
    `"currentheight": 276955,`
    `"syncnode": true,`
  `}`
`]` | +| Example Return | `[`
  `{`
    `"addr": "178.172.xxx.xxx:8333",`
    `"services": "00000001",`
    `"lastrecv": 1388183523,`
    `"lastsend": 1388185470,`
    `"bytessent": 287592965,`
    `"bytesrecv": 780340,`
    `"conntime": 1388182973,`
    `"pingtime": 405551,`
    `"pingwait": 183023,`
    `"version": 70001,`
    `"subver": "/lbcd:0.4.0/",`
    `"inbound": false,`
    `"startingheight": 276921,`
    `"currentheight": 276955,`
    `"syncnode": true,`
  `}`
`]` | [Return to Overview](#MethodOverview)
*** @@ -483,7 +475,7 @@ the method name for further details such as parameter and return information. | Method | getrawmempool | | Parameters | 1. verbose (boolean, optional, default=false) | | Description | Returns an array of hashes for all of the transactions currently in the memory pool.
The `verbose` flag specifies that each transaction is returned as a JSON object. | -| Notes | Since btcd does not perform any mining, the priority related fields `startingpriority` and `currentpriority` that are available when the `verbose` flag is set are always 0. | +| Notes | Since lbcd does not perform any mining, the priority related fields `startingpriority` and `currentpriority` that are available when the `verbose` flag is set are always 0. | | Returns (verbose=false) | `[ (json array of string)`
  `"transactionhash", (string) hash of the transaction`
  `...`
`]` | | Returns (verbose=true) | `{ (json object)`
  `"transactionhash": { (json object)`
    `"size": n, (numeric) transaction size in bytes`
    `"vsize": n, (numeric) transaction virtual size`
    `"weight": n, (numeric) The transaction's weight (between vsize*4-3 and vsize*4)`
    `"fee" : n, (numeric) transaction fee in bitcoins`
    `"time": n, (numeric) local time transaction entered pool in seconds since 1 Jan 1970 GMT`
    `"height": n, (numeric) block height when transaction entered the pool`
    `"startingpriority": n, (numeric) priority when transaction entered the pool`
    `"currentpriority": n, (numeric) current priority`
    `"depends": [ (json array) unconfirmed transactions used as inputs for this transaction`
      `"transactionhash", (string) hash of the parent transaction`
      `...`
    `]`
  `}, ...`
`}` | | Example Return (verbose=false) | `[`
  `"3480058a397b6ffcc60f7e3345a61370fded1ca6bef4b58156ed17987f20d4e7",`
  `"cbfe7c056a358c3a1dbced5a22b06d74b8650055d5195c1c2469e6b63a41514a"`
`]` | @@ -498,7 +490,7 @@ the method name for further details such as parameter and return information. | Method | setgenerate | | Parameters | 1. generate (boolean, required) - `true` to enable generation, `false` to disable it
2. genproclimit (numeric, optional) - the number of processors (cores) to limit generation to or `-1` for default | | Description | Set the server to generate coins (mine) or not. | -| Notes | NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function. | +| Notes | NOTE: Since lbcd does not have the wallet integrated to provide payment addresses, lbcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function. | | Returns | Nothing | [Return to Overview](#MethodOverview)
@@ -510,7 +502,7 @@ the method name for further details such as parameter and return information. | Method | sendrawtransaction | | Parameters | 1. signedhex (string, required) serialized, hex-encoded signed transaction
2. allowhighfees (boolean, optional, default=false) whether or not to allow insanely high fees | | Description | Submits the serialized, hex-encoded transaction to the local peer and relays it to the network. | -| Notes | btcd does not yet implement the `allowhighfees` parameter, so it has no effect | +| Notes | lbcd does not yet implement the `allowhighfees` parameter, so it has no effect | | Returns | `"hash" (string) the hash of the transaction` | | Example Return | `"1697a19cede08694278f19584e8dcc87945f40c6b59a942dd8906f133ad3f9cc"` | [Return to Overview](#MethodOverview)
@@ -533,8 +525,8 @@ the method name for further details such as parameter and return information. | ----------- | --------------------------- | | Method | stop | | Parameters | None | -| Description | Shutdown btcd. | -| Returns | `"btcd stopping."` (string) | +| Description | Shutdown lbcd. | +| Returns | `"lbcd stopping."` (string) | [Return to Overview](#MethodOverview)
*** @@ -555,8 +547,8 @@ the method name for further details such as parameter and return information. | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Method | verifychain | | Parameters | 1. checklevel (numeric, optional, default=3) - how in-depth the verification is (0=least amount of checks, higher levels are clamped to the highest supported level)
2. numblocks (numeric, optional, default=288) - the number of blocks starting from the end of the chain to verify | -| Description | Verifies the block chain database.
The actual checks performed by the `checklevel` parameter is implementation specific. For btcd this is:
`checklevel=0` - Look up each block and ensure it can be loaded from the database.
`checklevel=1` - Perform basic context-free sanity checks on each block. | -| Notes | Btcd currently only supports `checklevel` 0 and 1, but the default is still 3 for compatibility. Per the information in the Parameters section above, higher levels are automatically clamped to the highest supported level, so this means the default is effectively 1 for btcd. | +| Description | Verifies the block chain database.
The actual checks performed by the `checklevel` parameter is implementation specific. For lbcd this is:
`checklevel=0` - Look up each block and ensure it can be loaded from the database.
`checklevel=1` - Perform basic context-free sanity checks on each block. | +| Notes | lbcd currently only supports `checklevel` 0 and 1, but the default is still 3 for compatibility. Per the information in the Parameters section above, higher levels are automatically clamped to the highest supported level, so this means the default is effectively 1 for lbcd. | | Returns | `true` or `false` (boolean) | | Example Return | `true` | [Return to Overview](#MethodOverview)
@@ -570,13 +562,13 @@ the method name for further details such as parameter and return information. **6.1 Method Overview**
-The following is an overview of the RPC methods which are implemented by btcd, but not the original bitcoind client. Click the method name for further details such as parameter and return information. +The following is an overview of the RPC methods which are implemented by lbcd, but not the original bitcoind client. Click the method name for further details such as parameter and return information. | # | Method | Safe for limited user? | Description | | --- | ----------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------- | | 1 | [debuglevel](#debuglevel) | N | Dynamically changes the debug logging level. | | 2 | [getbestblock](#getbestblock) | Y | Get block height and hash of best block in the main chain. | None | -| 3 | [getcurrentnet](#getcurrentnet) | Y | Get bitcoin network btcd is running on. | None | +| 3 | [getcurrentnet](#getcurrentnet) | Y | Get bitcoin network lbcd is running on. | None | | 4 | [searchrawtransactions](#searchrawtransactions) | Y | Query for transactions related to a particular address. | None | | 5 | [node](#node) | N | Attempts to add or remove a peer. | None | | 6 | [generate](#generate) | N | When in simnet or regtest mode, generate a set number of blocks. | None | @@ -594,10 +586,10 @@ The following is an overview of the RPC methods which are implemented by btcd, b | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Method | debuglevel | | Parameters | 1. _levelspec_ (string) | -| Description | Dynamically changes the debug logging level.
The levelspec can either a debug level or of the form `=,=,...`
The valid debug levels are `trace`, `debug`, `info`, `warn`, `error`, and `critical`.
The valid subsystems are `AMGR`, `ADXR`, `BCDB`, `BMGR`, `BTCD`, `CHAN`, `DISC`, `PEER`, `RPCS`, `SCRP`, `SRVR`, and `TXMP`.
Additionally, the special keyword `show` can be used to get a list of the available subsystems. | +| Description | Dynamically changes the debug logging level.
The levelspec can either a debug level or of the form `=,=,...`
The valid debug levels are `trace`, `debug`, `info`, `warn`, `error`, and `critical`.
The valid subsystems are `AMGR`, `ADXR`, `BCDB`, `BMGR`, `lbcd`, `CHAN`, `DISC`, `PEER`, `RPCS`, `SCRP`, `SRVR`, and `TXMP`.
Additionally, the special keyword `show` can be used to get a list of the available subsystems. | | Returns | string | | Example Return | `Done.` | -| Example `show` Return | `Supported subsystems [AMGR ADXR BCDB BMGR BTCD CHAN DISC PEER RPCS SCRP SRVR TXMP]` | +| Example `show` Return | `Supported subsystems [AMGR ADXR BCDB BMGR lbcd CHAN DISC PEER RPCS SCRP SRVR TXMP]` | [Return to Overview](#ExtMethodOverview)
*** @@ -620,7 +612,7 @@ The following is an overview of the RPC methods which are implemented by btcd, b | -------------- | -------------------------------------------------- | | Method | getcurrentnet | | Parameters | None | -| Description | Get bitcoin network btcd is running on. | +| Description | Get bitcoin network lbcd is running on. | | Returns | numeric | | Example Return | `3652501241` (mainnet)
`118034699` (testnet3) | [Return to Overview](#ExtMethodOverview)
@@ -670,9 +662,9 @@ The following is an overview of the RPC methods which are implemented by btcd, b | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Method | version | | Parameters | None | -| Description | Returns the version of the JSON-RPC API built into this release of btcd. | -| Returns | `{ (json object)`
  `"btcdjsonrpcapi": {`
    `"versionstring": "x.y.z", (string) the version of the JSON-RPC API`
    `"major": x, (numeric) the major version of the JSON-RPC API`
    `"minor": y, (numeric) the minor version of the JSON-RPC API`
    `"patch": z, (numeric) the patch version of the JSON-RPC API`
    `"prerelease": "", (string) prerelease info for the JSON-RPC API`
    `"buildmetadata": "" (string) metadata about the server build`
  `}`
`}` | -| Example Return | `{`
  `"btcdjsonrpcapi": {`
    `"versionstring": "1.0.0",`
    `"major": 1, `
    `"minor": 0,`
    `"patch": 0,`
    `"prerelease": "",`
    `"buildmetadata": ""`
  `}`
`}` | +| Description | Returns the version of the JSON-RPC API built into this release of lbcd. | +| Returns | `{ (json object)`
  `"lbcdjsonrpcapi": {`
    `"versionstring": "x.y.z", (string) the version of the JSON-RPC API`
    `"major": x, (numeric) the major version of the JSON-RPC API`
    `"minor": y, (numeric) the minor version of the JSON-RPC API`
    `"patch": z, (numeric) the patch version of the JSON-RPC API`
    `"prerelease": "", (string) prerelease info for the JSON-RPC API`
    `"buildmetadata": "" (string) metadata about the server build`
  `}`
`}` | +| Example Return | `{`
  `"lbcdjsonrpcapi": {`
    `"versionstring": "1.0.0",`
    `"major": 1, `
    `"minor": 0,`
    `"patch": 0,`
    `"prerelease": "",`
    `"buildmetadata": ""`
  `}`
`}` | [Return to Overview](#MethodOverview)
*** @@ -792,7 +784,7 @@ user. Click the method name for further details such as parameter and return in | Method | notifyspent | | Notifications | [redeemingtx](#redeemingtx) | | Parameters | 1. Outpoints (JSON array, required)
 `[ (JSON array)`
  `{ (JSON object)`
   `"hash":"data", (string) the hex-encoded bytes of the outpoint hash`
   `"index":n (numeric) the txout index of the outpoint`
  `},`
  `...`
 `]` | -| Description | *DEPRECATED, for similar functionality see [loadtxfilter](#loadtxfilter)*
Send a redeemingtx notification when a transaction spending an outpoint appears in mempool (if relayed to this btcd instance) and when such a transaction first appears in a newly-attached block. | +| Description | *DEPRECATED, for similar functionality see [loadtxfilter](#loadtxfilter)*
Send a redeemingtx notification when a transaction spending an outpoint appears in mempool (if relayed to this lbcd instance) and when such a transaction first appears in a newly-attached block. | | Returns | Nothing | [Return to Overview](#WSExtMethodOverview)
@@ -893,7 +885,7 @@ user. Click the method name for further details such as parameter and return in ### 8. Notifications (Websocket-specific) -btcd uses standard JSON-RPC notifications to notify clients of changes, rather than requiring clients to poll btcd for updates. JSON-RPC notifications are a subset of requests, but do not contain an ID. The notification type is categorized by the `method` field and additional details are sent as a JSON array in the `params` field. +lbcd uses standard JSON-RPC notifications to notify clients of changes, rather than requiring clients to poll lbcd for updates. JSON-RPC notifications are a subset of requests, but do not contain an ID. The notification type is categorized by the `method` field and additional details are sent as a JSON array in the `params` field. @@ -1088,7 +1080,7 @@ This section provides examples of using the RPC interface using Go and the The following is an example Go application which uses the [rpcclient](https://github.com/btcsuite/btcd/tree/master/rpcclient) package to connect with -a btcd instance via Websockets, issues [getblockcount](#getblockcount) to +a lbcd instance via Websockets, issues [getblockcount](#getblockcount) to retrieve the current block height, and displays it. ```Go @@ -1105,10 +1097,10 @@ import ( func main() { // Load the certificate for the TLS connection which is automatically - // generated by btcd when it starts the RPC server and doesn't already + // generated by lbcd when it starts the RPC server and doesn't already // have one. - btcdHomeDir := btcutil.AppDataDir("lbcd", false) - certs, err := ioutil.ReadFile(filepath.Join(btcdHomeDir, "rpc.cert")) + lbcdHomeDir := btcutil.AppDataDir("lbcd", false) + certs, err := ioutil.ReadFile(filepath.Join(lbcdHomeDir, "rpc.cert")) if err != nil { log.Fatal(err) } @@ -1150,7 +1142,7 @@ Which results in: The following is an example Go application which uses the [rpcclient](https://github.com/btcsuite/btcd/tree/master/rpcclient) package to connect with -a btcd instance via Websockets, issues [getblock](#getblock) to retrieve +a lbcd instance via Websockets, issues [getblock](#getblock) to retrieve information about the Genesis block, and display a few details about it. ```Go @@ -1169,10 +1161,10 @@ import ( func main() { // Load the certificate for the TLS connection which is automatically - // generated by btcd when it starts the RPC server and doesn't already + // generated by lbcd when it starts the RPC server and doesn't already // have one. - btcdHomeDir := btcutil.AppDataDir("lbcd", false) - certs, err := ioutil.ReadFile(filepath.Join(btcdHomeDir, "rpc.cert")) + lbcdHomeDir := btcutil.AppDataDir("lbcd", false) + certs, err := ioutil.ReadFile(filepath.Join(lbcdHomeDir, "rpc.cert")) if err != nil { log.Fatal(err) } @@ -1240,7 +1232,7 @@ Notifications (Websocket-specific)**
The following is an example Go application which uses the [rpcclient](https://github.com/btcsuite/btcd/tree/master/rpcclient) package to connect with -a btcd instance via Websockets and registers for +a lbcd instance via Websockets and registers for [blockconnected](#blockconnected) and [blockdisconnected](#blockdisconnected) notifications with [notifyblocks](#notifyblocks). It also sets up handlers for the notifications. @@ -1272,10 +1264,10 @@ func main() { } // Load the certificate for the TLS connection which is automatically - // generated by btcd when it starts the RPC server and doesn't already + // generated by lbcd when it starts the RPC server and doesn't already // have one. - btcdHomeDir := btcutil.AppDataDir("lbcd", false) - certs, err := ioutil.ReadFile(filepath.Join(btcdHomeDir, "rpc.cert")) + lbcdHomeDir := btcutil.AppDataDir("lbcd", false) + certs, err := ioutil.ReadFile(filepath.Join(lbcdHomeDir, "rpc.cert")) if err != nil { log.Fatal(err) } @@ -1337,7 +1329,7 @@ Example output: **9.2.1 Using notifyblocks to be Notified of Block Connects and Disconnects**
The following is example node.js code which uses [ws](https://github.com/einaros/ws) -(can be installed with `npm install ws`) to connect with a btcd instance, +(can be installed with `npm install ws`) to connect with a lbcd instance, issues [notifyblocks](#notifyblocks) to register for [blockconnected](#blockconnected) and [blockdisconnected](#blockdisconnected) notifications, and displays all incoming messages. @@ -1347,14 +1339,14 @@ var fs = require('fs'); var WebSocket = require('ws'); // Load the certificate for the TLS connection which is automatically -// generated by btcd when it starts the RPC server and doesn't already +// generated by lbcd when it starts the RPC server and doesn't already // have one. -var cert = fs.readFileSync('/path/to/btcd/appdata/rpc.cert'); +var cert = fs.readFileSync('/path/to/lbcd/appdata/rpc.cert'); var user = "yourusername"; var password = "yourpassword"; -// Initiate the websocket connection. The btcd generated certificate acts as +// Initiate the websocket connection. The lbcd generated certificate acts as // its own certificate authority, so it needs to be specified in the 'ca' array // for the certificate to properly validate. var ws = new WebSocket('wss://127.0.0.1:9245/ws', { diff --git a/docs/mining.md b/docs/mining.md index 29a3e89858..2d258733f7 100644 --- a/docs/mining.md +++ b/docs/mining.md @@ -1,6 +1,6 @@ # Mining -btcd supports the `getblocktemplate` RPC. +lbcd supports the `getblocktemplate` RPC. The limited user cannot access this RPC. ## Add the payment addresses with the `miningaddr` option @@ -13,18 +13,20 @@ miningaddr=12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX miningaddr=1M83ju3EChKYyysmM2FXtLNftbacagd8FR ``` -## Add btcd's RPC TLS certificate to system Certificate Authority list +## Add lbcd's RPC TLS certificate to system Certificate Authority list -`cgminer` uses [curl](http://curl.haxx.se/) to fetch data from the RPC server. -Since curl validates the certificate by default, we must install the `btcd` RPC +Various miners use [curl](http://curl.haxx.se/) to fetch data from the RPC server. +Since curl validates the certificate by default, we must install the `lbcd` RPC certificate into the default system Certificate Authority list. ## Ubuntu -1. Copy rpc.cert to /usr/share/ca-certificates: `# cp /home/user/.btcd/rpc.cert /usr/share/ca-certificates/btcd.crt` -2. Add btcd.crt to /etc/ca-certificates.conf: `# echo btcd.crt >> /etc/ca-certificates.conf` +1. Copy rpc.cert to /usr/share/ca-certificates: `# cp /home/user/.lbcd/rpc.cert /usr/share/ca-certificates/lbcd.crt` +2. Add lbcd.crt to /etc/ca-certificates.conf: `# echo lbcd.crt >> /etc/ca-certificates.conf` 3. Update the CA certificate list: `# update-ca-certificates` ## Set your mining software url to use https `cgminer -o https://127.0.0.1:8334 -u rpcuser -p rpcpassword` + +Alternatively, you can disable TLS with the `--notls` option for the server. diff --git a/docs/table_of_content.md b/docs/table_of_content.md deleted file mode 100644 index 85f08a97b3..0000000000 --- a/docs/table_of_content.md +++ /dev/null @@ -1,13 +0,0 @@ -# Contents - -* [Installation](installation.md) -* [Update](update.md) -* [Configuration](configuration.md) -* [Configuring TOR](configuring_tor.md) -* [Controlling](controlling.md) -* [Mining](mining.md) -* [Wallet](wallet.md) -* [Developer resources](developer_resources.md) -* [JSON RPC API](json_rpc_api.md) -* [Code contribution guidelines](code_contribution_guidelines.md) -* [Contact](contact.md) diff --git a/docs/update.md b/docs/update.md deleted file mode 100644 index 1fb847cf9f..0000000000 --- a/docs/update.md +++ /dev/null @@ -1,8 +0,0 @@ -# Update - -* Run the following commands to update btcd, all dependencies, and install it: - -```bash -cd $GOPATH/src/github.com/btcsuite/btcd -git pull && GO111MODULE=on go install -v . ./cmd/... -``` diff --git a/docs/using_docker.md b/docs/using_docker.md deleted file mode 100644 index 0809abc1c8..0000000000 --- a/docs/using_docker.md +++ /dev/null @@ -1,160 +0,0 @@ -# Using Docker - -- [Using Docker](#using-docker) - - [Introduction](#introduction) - - [Docker volumes](#docker-volumes) - - [Known error messages when starting the btcd container](#known-error-messages-when-starting-the-btcd-container) - - [Examples](#examples) - - [Preamble](#preamble) - - [Full node without RPC port](#full-node-without-rpc-port) - - [Full node with RPC port](#full-node-with-rpc-port) - - [Full node with RPC port running on TESTNET](#full-node-with-rpc-port-running-on-testnet) - -## Introduction - -With Docker you can easily set up *btcd* to run your Bitcoin full node. You can find the official *btcd* Docker images on Docker Hub [btcsuite/btcd](https://hub.docker.com/r/btcsuite/btcd). The Docker source file of this image is located at [Dockerfile](https://github.com/btcsuite/btcd/blob/master/Dockerfile). - -This documentation focuses on running Docker container with *docker-compose.yml* files. These files are better to read and you can use them as a template for your own use. For more information about Docker and Docker compose visit the official [Docker documentation](https://docs.docker.com/). - -## Docker volumes - -**Special diskspace hint**: The following examples are using a Docker managed volume. The volume is named *btcd-data* This will use a lot of disk space, because it contains the full Bitcoin blockchain. Please make yourself familiar with [Docker volumes](https://docs.docker.com/storage/volumes/). - -The *btcd-data* volume will be reused, if you upgrade your *docker-compose.yml* file. Keep in mind, that it is not automatically removed by Docker, if you delete the btcd container. If you don't need the volume anymore, please delete it manually with the command: - -```bash -docker volume ls -docker volume rm btcd-data -``` - -For binding a local folder to your *btcd* container please read the [Docker documentation](https://docs.docker.com/). The preferred way is to use a Docker managed volume. - -## Known error messages when starting the btcd container - -We pass all needed arguments to *btcd* as command line parameters in our *docker-compose.yml* file. It doesn't make sense to create a *btcd.conf* file. This would make things too complicated. Anyhow *btcd* will complain with following log messages when starting. These messages can be ignored: - -```bash -Error creating a default config file: open /sample-btcd.conf: no such file or directory -... -[WRN] BTCD: open /root/.btcd/btcd.conf: no such file or directory -``` - -## Examples - -### Preamble - -All following examples uses some defaults: - -- container_name: btcd - Name of the docker container that is be shown by e.g. ```docker ps -a``` - -- hostname: btcd **(very important to set a fixed name before first start)** - The internal hostname in the docker container. By default, docker is recreating the hostname every time you change the *docker-compose.yml* file. The default hostnames look like *ef00548d4fa5*. This is a problem when using the *btcd* RPC port. The RPC port is using a certificate to validate the hostname. If the hostname changes you need to recreate the certificate. To avoid this, you should set a fixed hostname before the first start. This ensures, that the docker volume is created with a certificate with this hostname. - -- restart: unless-stopped - Starts the *btcd* container when Docker starts, except that when the container is stopped (manually or otherwise), it is not restarted even after Docker restarts. - -To use the following examples create an empty directory. In this directory create a file named *docker-compose.yml*, copy and paste the example into the *docker-compose.yml* file and run it. - -```bash -mkdir ~/btcd-docker -cd ~/btcd-docker -touch docker-compose.yaml -nano docker-compose.yaml (use your favourite editor to edit the compose file) -docker-compose up (creates and starts a new btcd container) -``` - -With the following commands you can control *docker-compose*: - -```docker-compose up -d``` (creates and starts the container in background) - -```docker-compose down``` (stops and delete the container. **The docker volume btcd-data will not be deleted**) - -```docker-compose stop``` (stops the container) - -```docker-compose start``` (starts the container) - -```docker ps -a``` (list all running and stopped container) - -```docker volume ls``` (lists all docker volumes) - -```docker logs btcd``` (shows the log ) - -```docker-compose help``` (brings up some helpful information) - -### Full node without RPC port - -Let's start with an easy example. If you just want to create a full node without the need of using the RPC port, you can use the following example. This example will launch *btcd* and exposes only the default p2p port 8333 to the outside world: - -```yaml -version: "2" - -services: - btcd: - container_name: btcd - hostname: btcd - image: btcsuite/btcd:latest - restart: unless-stopped - volumes: - - btcd-data:/root/.btcd - ports: - - 8333:8333 - -volumes: - btcd-data: -``` - -### Full node with RPC port - -To use the RPC port of *btcd* you need to specify a *username* and a very strong *password*. If you want to connect to the RPC port from the internet, you need to expose port 8334(RPC) as well. - -```yaml -version: "2" - -services: - btcd: - container_name: btcd - hostname: btcd - image: btcsuite/btcd:latest - restart: unless-stopped - volumes: - - btcd-data:/root/.btcd - ports: - - 8333:8333 - - 8334:8334 - command: [ - "--rpcuser=[CHOOSE_A_USERNAME]", - "--rpcpass=[CREATE_A_VERY_HARD_PASSWORD]" - ] - -volumes: - btcd-data: -``` - -### Full node with RPC port running on TESTNET - -To run a node on testnet, you need to provide the *--testnet* argument. The ports for testnet are 18333 (p2p) and 18334 (RPC): - -```yaml -version: "2" - -services: - btcd: - container_name: btcd - hostname: btcd - image: btcsuite/btcd:latest - restart: unless-stopped - volumes: - - btcd-data:/root/.btcd - ports: - - 18333:18333 - - 18334:18334 - command: [ - "--testnet", - "--rpcuser=[CHOOSE_A_USERNAME]", - "--rpcpass=[CREATE_A_VERY_HARD_PASSWORD]" - ] - -volumes: - btcd-data: -``` diff --git a/docs/wallet.md b/docs/wallet.md deleted file mode 100644 index cc123aa7d5..0000000000 --- a/docs/wallet.md +++ /dev/null @@ -1,5 +0,0 @@ -# Wallet - -btcd was intentionally developed without an integrated wallet for security -reasons. Please see [btcwallet](https://github.com/btcsuite/btcwallet) for more -information. diff --git a/integration/README.md b/integration/README.md index 5f6f14eace..686e160d58 100644 --- a/integration/README.md +++ b/integration/README.md @@ -1,13 +1,8 @@ integration =========== -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) This contains integration tests which make use of the [rpctest](https://github.com/btcsuite/btcd/tree/master/integration/rpctest) package to programmatically drive nodes via RPC. - -## License - -This code is licensed under the [copyfree](http://copyfree.org) ISC License. diff --git a/integration/rpctest/README.md b/integration/rpctest/README.md index 79f45bc857..8ccfc8795a 100644 --- a/integration/rpctest/README.md +++ b/integration/rpctest/README.md @@ -1,9 +1,7 @@ rpctest ======= -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/integration/rpctest) Package rpctest provides a btcd-specific RPC testing harness crafting and executing integration tests by driving a `btcd` instance via the `RPC` @@ -16,15 +14,3 @@ This package was designed specifically to act as an RPC testing harness for `btcd`. However, the constructs presented are general enough to be adapted to any project wishing to programmatically drive a `btcd` instance of its systems/integration tests. - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/integration/rpctest -``` - -## License - -Package rpctest is licensed under the [copyfree](http://copyfree.org) ISC -License. - diff --git a/integration/rpctest/btcd.go b/integration/rpctest/btcd.go index f3d7ac2792..e3bd41788c 100644 --- a/integration/rpctest/btcd.go +++ b/integration/rpctest/btcd.go @@ -49,7 +49,7 @@ func btcdExecutablePath() (string, error) { outputPath += ".exe" } cmd := exec.Command( - "go", "build", "-o", outputPath, "github.com/btcsuite/lbcd", + "go", "build", "-o", outputPath, "github.com/lbryio/lbcd", ) err = cmd.Run() if err != nil { diff --git a/mempool/README.md b/mempool/README.md index 5f1e4a4cd1..ec58ca3a92 100644 --- a/mempool/README.md +++ b/mempool/README.md @@ -1,9 +1,7 @@ mempool ======= -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/mempool) Package mempool provides a policy-enforced pool of unmined bitcoin transactions. @@ -33,11 +31,6 @@ proceed. Typically, this will involve things such as relaying the transactions to other peers on the network and notifying the mining process that new transactions are available. -This package has intentionally been designed so it can be used as a standalone -package for any projects needing the ability create an in-memory pool of bitcoin -transactions that are not only valid by consensus rules, but also adhere to a -configurable policy. - ## Feature Overview The following is a quick overview of the major features. It is not intended to @@ -70,14 +63,4 @@ be an exhaustive list. - The starting priority for the transaction - Manual control of transaction removal - Recursive removal of all dependent transactions - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/mempool -``` - -## License - -Package mempool is licensed under the [copyfree](http://copyfree.org) ISC -License. + \ No newline at end of file diff --git a/mining/README.md b/mining/README.md index 3abd195355..40a30a2060 100644 --- a/mining/README.md +++ b/mining/README.md @@ -1,21 +1,8 @@ mining ====== -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/mining) ## Overview -This package is currently a work in progress. - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/mining -``` - -## License - -Package mining is licensed under the [copyfree](http://copyfree.org) ISC -License. +This package is currently a work in progress. \ No newline at end of file diff --git a/netsync/README.md b/netsync/README.md index a4966815fd..22f51701bf 100644 --- a/netsync/README.md +++ b/netsync/README.md @@ -1,9 +1,7 @@ netsync ======= -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/netsync) ## Overview @@ -13,13 +11,3 @@ download, keep the chain and unconfirmed transaction pool in sync, and announce new blocks connected to the chain. Currently the sync manager selects a single sync peer that it downloads all blocks from until it is up to date with the longest chain the sync peer is aware of. - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/netsync -``` - -## License - -Package netsync is licensed under the [copyfree](http://copyfree.org) ISC License. diff --git a/params.go b/params.go index e224ed03bb..1f85ebc7fb 100644 --- a/params.go +++ b/params.go @@ -37,7 +37,7 @@ var mainNetParams = params{ // details. var regressionNetParams = params{ Params: &chaincfg.RegressionNetParams, - rpcPort: "19245", + rpcPort: "29245", } // testNet3Params contains parameters specific to the test network (version 3) diff --git a/peer/README.md b/peer/README.md index 217f5dc3dc..517613194c 100644 --- a/peer/README.md +++ b/peer/README.md @@ -1,16 +1,11 @@ peer ==== -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/peer) Package peer provides a common base for creating and managing bitcoin network peers. -This package has intentionally been designed so it can be used as a standalone -package for any projects needing a full featured bitcoin peer base to build on. - ## Overview This package builds upon the wire package, which provides the fundamental @@ -54,20 +49,4 @@ A quick overview of the major features peer provides are as follows: filtering and address randomization - Ability to wait for shutdown/disconnect - Comprehensive test coverage - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/peer -``` - -## Examples - -* [New Outbound Peer Example](https://pkg.go.dev/github.com/btcsuite/btcd/peer#example-package--NewOutboundPeer) - Demonstrates the basic process for initializing and creating an outbound peer. - Peers negotiate by exchanging version and verack messages. For demonstration, - a simple handler for the version message is attached to the peer. - -## License - -Package peer is licensed under the [copyfree](http://copyfree.org) ISC License. + \ No newline at end of file diff --git a/release/README.md b/release/README.md deleted file mode 100644 index 7128ef1f16..0000000000 --- a/release/README.md +++ /dev/null @@ -1,181 +0,0 @@ -# `btcd`'s Reproducible Build System - -This package contains the build script that the `btcd` project uses in order to -build binaries for each new release. As of `go1.13`, with some new build flags, -binaries are now reproducible, allowing developers to build the binary on -distinct machines, and end up with a byte-for-byte identical binary. -Every release should note which Go version was used to build the release, so -that version should be used for verifying the release. - -## Building a New Release - -### Tagging and pushing a new tag (for maintainers) - -Before running release scripts, a few things need to happen in order to finally -create a release and make sure there are no mistakes in the release process. - -First, make sure that before the tagged commit there are modifications to the -[CHANGES](../CHANGES) file committed. -The CHANGES file should be a changelog that roughly mirrors the release notes. -Generally, the PRs that have been merged since the last release have been -listed in the CHANGES file and categorized. -For example, these changes have had the following format in the past: -``` -Changes in X.YY.Z (Month Day Year): - - Protocol and Network-related changes: - - PR Title One (#PRNUM) - - PR Title Two (#PRNUMTWO) - ... - - RPC changes: - - Crypto changes: - ... - - - Contributors (alphabetical order): - - Contributor A - - Contributor B - - Contributor C - ... -``` - -If the previous tag is, for example, `vA.B.C`, then you can get the list of -contributors (from `vA.B.C` until the current `HEAD`) using the following command: -```bash -git log vA.B.C..HEAD --pretty="%an" | sort | uniq -``` -After committing changes to the CHANGES file, the tagged release commit -should be created. - -The tagged commit should be a commit that bumps version numbers in `version.go` -and `cmd/btcctl/version.go`. -For example (taken from [f3ec130](https://github.com/btcsuite/btcd/commit/f3ec13030e4e828869954472cbc51ac36bee5c1d)): -```diff -diff --git a/cmd/btcctl/version.go b/cmd/btcctl/version.go -index 2195175c71..f65cacef7e 100644 ---- a/cmd/btcctl/version.go -+++ b/cmd/btcctl/version.go -@@ -18,7 +18,7 @@ const semanticAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr - const ( - appMajor uint = 0 - appMinor uint = 20 -- appPatch uint = 0 -+ appPatch uint = 1 - - // appPreRelease MUST only contain characters from semanticAlphabet - // per the semantic versioning spec. -diff --git a/version.go b/version.go -index 92fd60fdd4..fba55b5a37 100644 ---- a/version.go -+++ b/version.go -@@ -18,7 +18,7 @@ const semanticAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr - const ( - appMajor uint = 0 - appMinor uint = 20 -- appPatch uint = 0 -+ appPatch uint = 1 - - // appPreRelease MUST only contain characters from semanticAlphabet - // per the semantic versioning spec. -``` - -Next, this commit should be signed by the maintainer using `git commit -S`. -The commit should be tagged and signed with `git tag -s`, and should be -pushed using `git push origin TAG`. - -### Building a release on macOS/Linux/Windows (WSL) - -No prior set up is needed on Linux or macOS is required in order to build the -release binaries. However, on Windows, the only way to build the release -binaries at the moment is by using the Windows Subsystem Linux. One can build -the release binaries following these steps: - -1. `git clone https://github.com/btcsuite/btcd.git` -2. `cd btcd` -3. `./release/release.sh # is the name of the next release/tag` - -This will then create a directory of the form `btcd-` containing archives -of the release binaries for each supported operating system and architecture, -and a manifest file containing the hash of each archive. - -### Pushing a release (for maintainers) - -Now that the directory `btcd-` is created, the manifest file needs to be -signed by a maintainer and the release files need to be published to GitHub. - -Sign the `manifest-.txt` file like so: -```sh -gpg --sign --detach-sig manifest-.txt -``` -This will create a file named `manifest-.txt.sig`, which will must -be included in the release files later. - -#### Note before publishing -Before publishing, go through the reproducible build process that is outlined -in this document with the files created from `release/release.sh`. This includes -verifying commit and tag signatures using `git verify-commit` and git `verify-tag` -respectively. - -Now that we've double-checked everything and have all of the necessary files, -it's time to publish release files on GitHub. -Follow [this documentation](https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository) -to create a release using the GitHub UI, and make sure to write release notes -which roughly follow the format of [previous release notes](https://github.com/btcsuite/btcd/releases/tag/v0.20.1-beta). -This is different from the [CHANGES](../CHANGES) file, which should be before the -tagged commit in the git history. -Much of the information in the release notes will be the same as the CHANGES -file. -It's important to include the Go version used to produce the release files in -the release notes, so users know the correct version of Go to use to reproduce -and verify the build. -When following the GitHub documentation, include every file in the `btcd-` -directory. - -At this point, a signed commit and tag on that commit should be pushed to the main -branch. The directory created from running `release/release.sh` should be included -as release files in the GitHub release UI, and the `manifest-.txt` file -signature, called `manifest-.txt.sig`, should also be included. -A release notes document should be created and written in the GitHub release UI. -Once all of this is done, feel free to click `Publish Release`! - -## Verifying a Release - -With `go1.13`, it's now possible for third parties to verify release binaries. -Before this version of `go`, one had to trust the release manager(s) to build the -proper binary. With this new system, third parties can now _independently_ run -the release process, and verify that all the hashes of the release binaries -match exactly that of the release binaries produced by said third parties. - -To verify a release, one must obtain the following tools (many of these come -installed by default in most Unix systems): `gpg`/`gpg2`, `shashum`, and -`tar`/`unzip`. - -Once done, verifiers can proceed with the following steps: - -1. Acquire the archive containing the release binaries for one's specific - operating system and architecture, and the manifest file along with its - signature. -2. Verify the signature of the manifest file with `gpg --verify - manifest-.txt.sig`. This will require obtaining the PGP keys which - signed the manifest file, which are included in the release notes. -3. Recompute the `SHA256` hash of the archive with `shasum -a 256 `, - locate the corresponding one in the manifest file, and ensure they match - __exactly__. - -At this point, verifiers can use the release binaries acquired if they trust -the integrity of the release manager(s). Otherwise, one can proceed with the -guide to verify the release binaries were built properly by obtaining `shasum` -and `go` (matching the same version used in the release): - -4. Extract the release binaries contained within the archive, compute their - hashes as done above, and note them down. -5. Ensure `go` is installed, matching the same version as noted in the release - notes. -6. Obtain a copy of `btcd`'s source code with `git clone - https://github.com/btcsuite/btcd` and checkout the source code of the - release with `git checkout `. -7. Proceed to verify the tag with `git verify-tag ` and compile the - binaries from source for the intended operating system and architecture with - `BTCDBUILDSYS=OS-ARCH ./release/release.sh `. -8. Extract the archive found in the `btcd-` directory created by the - release script and recompute the `SHA256` hash of the release binaries (btcd - and btcctl) with `shasum -a 256 `. These should match __exactly__ - as the ones noted above. \ No newline at end of file diff --git a/release/release.sh b/release/release.sh deleted file mode 100755 index 93c4a3e75a..0000000000 --- a/release/release.sh +++ /dev/null @@ -1,108 +0,0 @@ -#!/bin/bash - -# Copyright (c) 2016 Company 0, LLC. -# Copyright (c) 2016-2020 The btcsuite developers -# Use of this source code is governed by an ISC -# license that can be found in the LICENSE file. - -# Simple bash script to build basic lbcd tools for all the platforms we support -# with the golang cross-compiler. - -set -e - -# If no tag specified, use date + version otherwise use tag. -if [[ $1x = x ]]; then - DATE=`date +%Y%m%d` - VERSION="01" - TAG=$DATE-$VERSION -else - TAG=$1 -fi - -go mod vendor -tar -cvzf vendor.tar.gz vendor - -PACKAGE=lbcd -MAINDIR=$PACKAGE-$TAG -mkdir -p $MAINDIR - -cp vendor.tar.gz $MAINDIR/ -rm vendor.tar.gz -rm -r vendor - -PACKAGESRC="$MAINDIR/$PACKAGE-source-$TAG.tar" -git archive -o $PACKAGESRC HEAD -gzip -f $PACKAGESRC > "$PACKAGESRC.gz" - -cd $MAINDIR - -# If LBCDBUILDSYS is set the default list is ignored. Useful to release -# for a subset of systems/architectures. -SYS=${LBCDBUILDSYS:-" - darwin-amd64 - dragonfly-amd64 - freebsd-386 - freebsd-amd64 - freebsd-arm - illumos-amd64 - linux-386 - linux-amd64 - linux-armv6 - linux-armv7 - linux-arm64 - linux-ppc64 - linux-ppc64le - linux-mips - linux-mipsle - linux-mips64 - linux-mips64le - linux-s390x - netbsd-386 - netbsd-amd64 - netbsd-arm - netbsd-arm64 - openbsd-386 - openbsd-amd64 - openbsd-arm - openbsd-arm64 - solaris-amd64 - windows-386 - windows-amd64 -"} - -# Use the first element of $GOPATH in the case where GOPATH is a list -# (something that is totally allowed). -PKG="github.com/lbryio/lbcd" -COMMIT=$(git describe --abbrev=40 --dirty) - -for i in $SYS; do - OS=$(echo $i | cut -f1 -d-) - ARCH=$(echo $i | cut -f2 -d-) - ARM= - - if [[ $ARCH = "armv6" ]]; then - ARCH=arm - ARM=6 - elif [[ $ARCH = "armv7" ]]; then - ARCH=arm - ARM=7 - fi - - mkdir $PACKAGE-$i-$TAG - cd $PACKAGE-$i-$TAG - - echo "Building:" $OS $ARCH $ARM - env CGO_ENABLED=0 GOOS=$OS GOARCH=$ARCH GOARM=$ARM go build -v -trimpath -ldflags="-s -w -buildid=" github.com/lbryio/lbcd - env CGO_ENABLED=0 GOOS=$OS GOARCH=$ARCH GOARM=$ARM go build -v -trimpath -ldflags="-s -w -buildid=" github.com/lbryio/lbcd/cmd/lbcctl - cd .. - - if [[ $OS = "windows" ]]; then - zip -r $PACKAGE-$i-$TAG.zip $PACKAGE-$i-$TAG - else - tar -cvzf $PACKAGE-$i-$TAG.tar.gz $PACKAGE-$i-$TAG - fi - - rm -r $PACKAGE-$i-$TAG -done - -shasum -a 256 * > manifest-$TAG.txt diff --git a/rpcclient/README.md b/rpcclient/README.md index 08b16f7560..c5a42063a4 100644 --- a/rpcclient/README.md +++ b/rpcclient/README.md @@ -1,13 +1,11 @@ rpcclient ========= -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/rpcclient) rpcclient implements a Websocket-enabled Bitcoin JSON-RPC client package written in [Go](http://golang.org/). It provides a robust and easy to use client for -interfacing with a Bitcoin RPC server that uses a btcd/bitcoin core compatible +interfacing with a Bitcoin RPC server that uses a lbcd/bitcoin core compatible Bitcoin JSON-RPC API. ## Status @@ -16,26 +14,11 @@ This package is currently under active development. It is already stable and the infrastructure is complete. However, there are still several RPCs left to implement and the API is not stable yet. -## Documentation - -* [API Reference](https://pkg.go.dev/github.com/btcsuite/btcd/rpcclient) -* [btcd Websockets Example](https://github.com/btcsuite/btcd/tree/master/rpcclient/examples/btcdwebsockets) - Connects to a btcd RPC server using TLS-secured websockets, registers for - block connected and block disconnected notifications, and gets the current - block count -* [btcwallet Websockets Example](https://github.com/btcsuite/btcd/tree/master/rpcclient/examples/btcwalletwebsockets) - Connects to a btcwallet RPC server using TLS-secured websockets, registers for - notifications about changes to account balances, and gets a list of unspent - transaction outputs (utxos) the wallet can sign -* [Bitcoin Core HTTP POST Example](https://github.com/btcsuite/btcd/tree/master/rpcclient/examples/bitcoincorehttp) - Connects to a bitcoin core RPC server using HTTP POST mode with TLS disabled - and gets the current block count - ## Major Features -* Supports Websockets (btcd/btcwallet) and HTTP POST mode (bitcoin core) -* Provides callback and registration functions for btcd/btcwallet notifications -* Supports btcd extensions +* Supports Websockets (lbcd/lbcwallet) and HTTP POST mode (bitcoin core) +* Provides callback and registration functions for lbcd/lbcwallet notifications +* Supports lbcd extensions * Translates to and from higher-level and easier to use Go types * Offers a synchronous (blocking) and asynchronous API * When running in Websockets mode (the default): @@ -43,14 +26,4 @@ implement and the API is not stable yet. * Outstanding commands are automatically reissued * Registered notifications are automatically reregistered * Back-off support on reconnect attempts - -## Installation - -```bash -$ go get -u github.com/btcsuite/btcd/rpcclient -``` - -## License - -Package rpcclient is licensed under the [copyfree](http://copyfree.org) ISC -License. + \ No newline at end of file diff --git a/txscript/README.md b/txscript/README.md index 004c586d61..e0b8fdd644 100644 --- a/txscript/README.md +++ b/txscript/README.md @@ -1,63 +1,15 @@ txscript ======== -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) -[![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://pkg.go.dev/github.com/btcsuite/btcd/txscript?status.png)](https://pkg.go.dev/github.com/btcsuite/btcd/txscript) - Package txscript implements the bitcoin transaction script language. There is a comprehensive test suite. -This package has intentionally been designed so it can be used as a standalone -package for any projects needing to use or validate bitcoin transaction scripts. +This package has been augmented to include support for LBRY's custom claim operations. +See https://lbry.tech/spec ## Bitcoin Scripts Bitcoin provides a stack-based, FORTH-like language for the scripts in the bitcoin transactions. This language is not turing complete although it is still fairly powerful. A description of the language -can be found at https://en.bitcoin.it/wiki/Script - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/txscript -``` - -## Examples - -* [Standard Pay-to-pubkey-hash Script](https://pkg.go.dev/github.com/btcsuite/btcd/txscript#example-PayToAddrScript) - Demonstrates creating a script which pays to a bitcoin address. It also - prints the created script hex and uses the DisasmString function to display - the disassembled script. - -* [Extracting Details from Standard Scripts](https://pkg.go.dev/github.com/btcsuite/btcd/txscript#example-ExtractPkScriptAddrs) - Demonstrates extracting information from a standard public key script. - -* [Manually Signing a Transaction Output](https://pkg.go.dev/github.com/btcsuite/btcd/txscript#example-SignTxOutput) - Demonstrates manually creating and signing a redeem transaction. - -## GPG Verification Key - -All official release tags are signed by Conformal so users can ensure the code -has not been tampered with and is coming from the btcsuite developers. To -verify the signature perform the following: - -- Download the public key from the Conformal website at - https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt - -- Import the public key into your GPG keyring: - ```bash - gpg --import GIT-GPG-KEY-conformal.txt - ``` - -- Verify the release tag with the following command where `TAG_NAME` is a - placeholder for the specific tag: - ```bash - git tag -v TAG_NAME - ``` - -## License - -Package txscript is licensed under the [copyfree](http://copyfree.org) ISC -License. +can be found at https://en.bitcoin.it/wiki/Script \ No newline at end of file diff --git a/wire/README.md b/wire/README.md index 8660bbfd54..c14a364049 100644 --- a/wire/README.md +++ b/wire/README.md @@ -1,26 +1,14 @@ wire ==== -[![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions) -[![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) -[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/btcsuite/btcd/wire) -======= - Package wire implements the bitcoin wire protocol. A comprehensive suite of tests with 100% test coverage is provided to ensure proper functionality. There is an associated blog post about the release of this package [here](https://blog.conformal.com/btcwire-the-bitcoin-wire-protocol-package-from-btcd/). -This package has intentionally been designed so it can be used as a standalone -package for any projects needing to interface with bitcoin peers at the wire -protocol level. - -## Installation and Updating - -```bash -$ go get -u github.com/btcsuite/btcd/wire -``` +This package has been augmented from the original btcd implementation. +The block header was modified to contain the claimtrie hash. ## Bitcoin Message Overview @@ -85,29 +73,4 @@ from a remote peer is: if err != nil { // Log and handle the error } -``` - -## GPG Verification Key - -All official release tags are signed by Conformal so users can ensure the code -has not been tampered with and is coming from the btcsuite developers. To -verify the signature perform the following: - -- Download the public key from the Conformal website at - https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt - -- Import the public key into your GPG keyring: - ```bash - gpg --import GIT-GPG-KEY-conformal.txt - ``` - -- Verify the release tag with the following command where `TAG_NAME` is a - placeholder for the specific tag: - ```bash - git tag -v TAG_NAME - ``` - -## License - -Package wire is licensed under the [copyfree](http://copyfree.org) ISC -License. +``` \ No newline at end of file