diff --git a/bitcoin/CONTRIBUTING.md b/bitcoin/CONTRIBUTING.md new file mode 100644 index 0000000..25637b4 --- /dev/null +++ b/bitcoin/CONTRIBUTING.md @@ -0,0 +1,443 @@ +Contributing to Bitcoin Core +============================ + +The Bitcoin Core project operates an open contributor model where anyone is +welcome to contribute towards development in the form of peer review, testing +and patches. This document explains the practical process and guidelines for +contributing. + +First, in terms of structure, there is no particular concept of "Bitcoin Core +developers" in the sense of privileged people. Open source often naturally +revolves around a meritocracy where contributors earn trust from the developer +community over time. Nevertheless, some hierarchy is necessary for practical +purposes. As such, there are repository maintainers who are responsible for +merging pull requests, the [release cycle](/doc/release-process.md), and +moderation. + +Getting Started +--------------- + +New contributors are very welcome and needed. + +Reviewing and testing is highly valued and the most effective way you can contribute +as a new contributor. It also will teach you much more about the code and +process than opening pull requests. Please refer to the [peer review](#peer-review) +section below. + +Before you start contributing, familiarize yourself with the Bitcoin Core build +system and tests. Refer to the documentation in the repository on how to build +Bitcoin Core and how to run the unit tests, functional tests, and fuzz tests. + +There are many open issues of varying difficulty waiting to be fixed. +If you're looking for somewhere to start contributing, check out the +[good first issue](https://github.com/bitcoin/bitcoin/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) +list or changes that are +[up for grabs](https://github.com/bitcoin/bitcoin/issues?utf8=%E2%9C%93&q=label%3A%22Up+for+grabs%22). +Some of them might no longer be applicable. So if you are interested, but +unsure, you might want to leave a comment on the issue first. + +You may also participate in the [Bitcoin Core PR Review Club](https://bitcoincore.reviews/). + +### Good First Issue Label + +The purpose of the `good first issue` label is to highlight which issues are +suitable for a new contributor without a deep understanding of the codebase. + +However, good first issues can be solved by anyone. If they remain unsolved +for a longer time, a frequent contributor might address them. + +You do not need to request permission to start working on an issue. However, +you are encouraged to leave a comment if you are planning to work on it. This +will help other contributors monitor which issues are actively being addressed +and is also an effective way to request assistance if and when you need it. + +Communication Channels +---------------------- + +Most communication about Bitcoin Core development happens on IRC, in the +`#bitcoin-core-dev` channel on Libera Chat. The easiest way to participate on IRC is +with the web client, [web.libera.chat](https://web.libera.chat/#bitcoin-core-dev). Chat +history logs can be found +on [https://www.erisian.com.au/bitcoin-core-dev/](https://www.erisian.com.au/bitcoin-core-dev/) +and [https://gnusha.org/bitcoin-core-dev/](https://gnusha.org/bitcoin-core-dev/). + +Discussion about codebase improvements happens in GitHub issues and pull +requests. + +The developer +[mailing list](https://groups.google.com/g/bitcoindev) +should be used to discuss complicated or controversial consensus or P2P protocol changes before working on +a patch set. +Archives can be found on [https://gnusha.org/pi/bitcoindev/](https://gnusha.org/pi/bitcoindev/). + + +Contributor Workflow +-------------------- + +The codebase is maintained using the "contributor workflow" where everyone +without exception contributes patch proposals using "pull requests" (PRs). This +facilitates social contribution, easy testing and peer review. + +To contribute a patch, the workflow is as follows: + + 1. Fork repository ([only for the first time](https://docs.github.com/en/get-started/quickstart/fork-a-repo)) + 1. Create topic branch + 1. Commit patches + +For GUI-related issues or pull requests, the https://github.com/bitcoin-core/gui repository should be used. +For all other issues and pull requests, the https://github.com/bitcoin/bitcoin node repository should be used. + +The master branch for all monotree repositories is identical. + +As a rule of thumb, everything that only modifies `src/qt` is a GUI-only pull +request. However: + +* For global refactoring or other transversal changes the node repository + should be used. +* For GUI-related build system changes, the node repository should be used + because the change needs review by the build systems reviewers. +* Changes in `src/interfaces` need to go to the node repository because they + might affect other components like the wallet. + +For large GUI changes that include build system and interface changes, it is +recommended to first open a pull request against the GUI repository. When there +is agreement to proceed with the changes, a pull request with the build system +and interfaces changes can be submitted to the node repository. + +The project coding conventions in the [developer notes](doc/developer-notes.md) +must be followed. + +### Committing Patches + +In general, [commits should be atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention) +and diffs should be easy to read. For this reason, do not mix any formatting +fixes or code moves with actual code changes. + +Make sure each individual commit is hygienic: that it builds successfully on its +own without warnings, errors, regressions, or test failures. + +Commit messages should be verbose by default consisting of a short subject line +(50 chars max), a blank line and detailed explanatory text as separate +paragraph(s), unless the title alone is self-explanatory (like "Correct typo +in init.cpp") in which case a single title line is sufficient. Commit messages should be +helpful to people reading your code in the future, so explain the reasoning for +your decisions. Further explanation [here](https://chris.beams.io/posts/git-commit/). + +If a particular commit references another issue, please add the reference. For +example: `refs #1234` or `fixes #4321`. Using the `fixes` or `closes` keywords +will cause the corresponding issue to be closed when the pull request is merged. + +Commit messages should never contain any `@` mentions (usernames prefixed with "@"). + +Please refer to the [Git manual](https://git-scm.com/doc) for more information +about Git. + + - Push changes to your fork + - Create pull request + +### Creating the Pull Request + +The title of the pull request should be prefixed by the component or area that +the pull request affects. Valid areas as: + + - `consensus` for changes to consensus critical code + - `doc` for changes to the documentation + - `qt` or `gui` for changes to bitcoin-qt + - `log` for changes to log messages + - `mining` for changes to the mining code + - `net` or `p2p` for changes to the peer-to-peer network code + - `refactor` for structural changes that do not change behavior + - `rpc`, `rest` or `zmq` for changes to the RPC, REST or ZMQ APIs + - `contrib` or `cli` for changes to the scripts and tools + - `test`, `qa` or `ci` for changes to the unit tests, QA tests or CI code + - `util` or `lib` for changes to the utils or libraries + - `wallet` for changes to the wallet code + - `build` for changes to CMake + - `guix` for changes to the GUIX reproducible builds + +Examples: + + consensus: Add new opcode for BIP-XXXX OP_CHECKAWESOMESIG + net: Automatically create onion service, listen on Tor + qt: Add feed bump button + log: Fix typo in log message + +The body of the pull request should contain sufficient description of *what* the +patch does, and even more importantly, *why*, with justification and reasoning. +You should include references to any discussions (for example, other issues or +mailing list discussions). + +The description for a new pull request should not contain any `@` mentions. The +PR description will be included in the commit message when the PR is merged and +any users mentioned in the description will be annoyingly notified each time a +fork of Bitcoin Core copies the merge. Instead, make any username mentions in a +subsequent comment to the PR. + +### Translation changes + +Note that translations should not be submitted as pull requests. Please see +[Translation Process](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md) +for more information on helping with translations. + +### Work in Progress Changes and Requests for Comments + +If a pull request is not to be considered for merging (yet), please +prefix the title with [WIP] or use [Tasks Lists](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#task-lists) +in the body of the pull request to indicate tasks are pending. + +### Address Feedback + +At this stage, one should expect comments and review from other contributors. You +can add more commits to your pull request by committing them locally and pushing +to your fork. + +You are expected to reply to any review comments before your pull request is +merged. You may update the code or reject the feedback if you do not agree with +it, but you should express so in a reply. If there is outstanding feedback and +you are not actively working on it, your pull request may be closed. + +Please refer to the [peer review](#peer-review) section below for more details. + +### Squashing Commits + +If your pull request contains fixup commits (commits that change the same line of code repeatedly) or too fine-grained +commits, you may be asked to [squash](https://git-scm.com/docs/git-rebase#_interactive_mode) your commits +before it will be reviewed. The basic squashing workflow is shown below. + + git checkout your_branch_name + git rebase -i HEAD~n + # n is normally the number of commits in the pull request. + # Set commits (except the one in the first line) from 'pick' to 'squash', save and quit. + # On the next screen, edit/refine commit messages. + # Save and quit. + git push -f # (force push to GitHub) + +Please update the resulting commit message, if needed. It should read as a +coherent message. In most cases, this means not just listing the interim +commits. + +If your change contains a merge commit, the above workflow may not work and you +will need to remove the merge commit first. See the next section for details on +how to rebase. + +Please refrain from creating several pull requests for the same change. +Use the pull request that is already open (or was created earlier) to amend +changes. This preserves the discussion and review that happened earlier for +the respective change set. + +The length of time required for peer review is unpredictable and will vary from +pull request to pull request. + +### Rebasing Changes + +When a pull request conflicts with the target branch, you may be asked to rebase it on top of the current target branch. + + git fetch https://github.com/bitcoin/bitcoin # Fetch the latest upstream commit + git rebase FETCH_HEAD # Rebuild commits on top of the new base + +This project aims to have a clean git history, where code changes are only made in non-merge commits. This simplifies +auditability because merge commits can be assumed to not contain arbitrary code changes. Merge commits should be signed, +and the resulting git tree hash must be deterministic and reproducible. The script in +[/contrib/verify-commits](/contrib/verify-commits) checks that. + +After a rebase, reviewers are encouraged to sign off on the force push. This should be relatively straightforward with +the `git range-diff` tool explained in the [productivity +notes](/doc/productivity.md#diff-the-diffs-with-git-range-diff). To avoid needless review churn, maintainers will +generally merge pull requests that received the most review attention first. + +Pull Request Philosophy +----------------------- + +Patchsets should always be focused. For example, a pull request could add a +feature, fix a bug, or refactor code; but not a mixture. Please also avoid super +pull requests which attempt to do too much, are overly large, or overly complex +as this makes review difficult. + + +### Features + +When adding a new feature, thought must be given to the long term technical debt +and maintenance that feature may require after inclusion. Before proposing a new +feature that will require maintenance, please consider if you are willing to +maintain it (including bug fixing). If features get orphaned with no maintainer +in the future, they may be removed by the Repository Maintainer. + + +### Refactoring + +Refactoring is a necessary part of any software project's evolution. The +following guidelines cover refactoring pull requests for the project. + +There are three categories of refactoring: code-only moves, code style fixes, and +code refactoring. In general, refactoring pull requests should not mix these +three kinds of activities in order to make refactoring pull requests easy to +review and uncontroversial. In all cases, refactoring PRs must not change the +behaviour of code within the pull request (bugs must be preserved as is). + +Project maintainers aim for a quick turnaround on refactoring pull requests, so +where possible keep them short, uncomplex and easy to verify. + +Pull requests that refactor the code should not be made by new contributors. It +requires a certain level of experience to know where the code belongs to and to +understand the full ramification (including rebase effort of open pull requests). + +Trivial pull requests or pull requests that refactor the code with no clear +benefits may be immediately closed by the maintainers to reduce unnecessary +workload on reviewing. + + +"Decision Making" Process +------------------------- + +The following applies to code changes to the Bitcoin Core project (and related +projects such as libsecp256k1), and is not to be confused with overall Bitcoin +Network Protocol consensus changes. + +Whether a pull request is merged into Bitcoin Core rests with the project merge +maintainers. + +Maintainers will take into consideration if a patch is in line with the general +principles of the project; meets the minimum standards for inclusion; and will +judge the general consensus of contributors. + +In general, all pull requests must: + + - Have a clear use case, fix a demonstrable bug or serve the greater good of + the project (for example refactoring for modularisation); + - Be well peer-reviewed; + - Have unit tests, functional tests, and fuzz tests, where appropriate; + - Follow code style guidelines ([C++](doc/developer-notes.md), [functional tests](test/functional/README.md)); + - Not break the existing test suite; + - Where bugs are fixed, where possible, there should be unit tests + demonstrating the bug and also proving the fix. This helps prevent regression. + - Change relevant comments and documentation when behaviour of code changes. + +Patches that change Bitcoin consensus rules are considerably more involved than +normal because they affect the entire ecosystem and so must be preceded by +extensive mailing list discussions and have a numbered BIP. While each case will +be different, one should be prepared to expend more time and effort than for +other kinds of patches because of increased peer review and consensus building +requirements. + + +### Peer Review + +Anyone may participate in peer review which is expressed by comments in the pull +request. Typically reviewers will review the code for obvious errors, as well as +test out the patch set and opine on the technical merits of the patch. Project +maintainers take into account the peer review when determining if there is +consensus to merge a pull request (remember that discussions may have been +spread out over GitHub, mailing list and IRC discussions). + +Code review is a burdensome but important part of the development process, and +as such, certain types of pull requests are rejected. In general, if the +**improvements** do not warrant the **review effort** required, the PR has a +high chance of being rejected. It is up to the PR author to convince the +reviewers that the changes warrant the review effort, and if reviewers are +"Concept NACK'ing" the PR, the author may need to present arguments and/or do +research backing their suggested changes. + +#### Conceptual Review + +A review can be a conceptual review, where the reviewer leaves a comment + * `Concept (N)ACK`, meaning "I do (not) agree with the general goal of this pull + request", + * `Approach (N)ACK`, meaning `Concept ACK`, but "I do (not) agree with the + approach of this change". + +A `NACK` needs to include a rationale why the change is not worthwhile. +NACKs without accompanying reasoning may be disregarded. + +#### Code Review + +After conceptual agreement on the change, code review can be provided. A review +begins with `ACK BRANCH_COMMIT`, where `BRANCH_COMMIT` is the top of the PR +branch, followed by a description of how the reviewer did the review. The +following language is used within pull request comments: + + - "I have tested the code", involving change-specific manual testing in + addition to running the unit, functional, or fuzz tests, and in case it is + not obvious how the manual testing was done, it should be described; + - "I have not tested the code, but I have reviewed it and it looks + OK, I agree it can be merged"; + - A "nit" refers to a trivial, often non-blocking issue. + +Project maintainers reserve the right to weigh the opinions of peer reviewers +using common sense judgement and may also weigh based on merit. Reviewers that +have demonstrated a deeper commitment and understanding of the project over time +or who have clear domain expertise may naturally have more weight, as one would +expect in all walks of life. + +Where a patch set affects consensus-critical code, the bar will be much +higher in terms of discussion and peer review requirements, keeping in mind that +mistakes could be very costly to the wider community. This includes refactoring +of consensus-critical code. + +Where a patch set proposes to change the Bitcoin consensus, it must have been +discussed extensively on the mailing list and IRC, be accompanied by a widely +discussed BIP and have a generally widely perceived technical consensus of being +a worthwhile change based on the judgement of the maintainers. + +### Finding Reviewers + +As most reviewers are themselves developers with their own projects, the review +process can be quite lengthy, and some amount of patience is required. If you find +that you've been waiting for a pull request to be given attention for several +months, there may be a number of reasons for this, some of which you can do something +about: + + - It may be because of a feature freeze due to an upcoming release. During this time, + only bug fixes are taken into consideration. If your pull request is a new feature, + it will not be prioritized until after the release. Wait for the release. + - It may be because the changes you are suggesting do not appeal to people. Rather than + nits and critique, which require effort and means they care enough to spend time on your + contribution, thundering silence is a good sign of widespread (mild) dislike of a given change + (because people don't assume *others* won't actually like the proposal). Don't take + that personally, though! Instead, take another critical look at what you are suggesting + and see if it: changes too much, is too broad, doesn't adhere to the + [developer notes](doc/developer-notes.md), is dangerous or insecure, is messily written, etc. + Identify and address any of the issues you find. Then ask e.g. on IRC if someone could give + their opinion on the concept itself. + - It may be because your code is too complex for all but a few people, and those people + may not have realized your pull request even exists. A great way to find people who + are qualified and care about the code you are touching is the + [Git Blame feature](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/tracking-changes-in-a-file). Simply + look up who last modified the code you are changing and see if you can find + them and give them a nudge. Don't be incessant about the nudging, though. + - Finally, if all else fails, ask on IRC or elsewhere for someone to give your pull request + a look. If you think you've been waiting for an unreasonably long time (say, + more than a month) for no particular reason (a few lines changed, etc.), + this is totally fine. Try to return the favor when someone else is asking + for feedback on their code, and the universe balances out. + - Remember that the best thing you can do while waiting is give review to others! + + +Backporting +----------- + +Security and bug fixes can be backported from `master` to release +branches. +Maintainers will do backports in batches and +use the proper `Needs backport (...)` labels +when needed (the original author does not need to worry about it). + +A backport should contain the following metadata in the commit body: + +``` +Github-Pull: # +Rebased-From: +``` + +Have a look at [an example backport PR]( +https://github.com/bitcoin/bitcoin/pull/16189). + +Also see the [backport.py script]( +https://github.com/bitcoin-core/bitcoin-maintainer-tools#backport). + +Copyright +--------- + +By contributing to this repository, you agree to license your work under the +MIT license unless specified otherwise in `contrib/debian/copyright` or at +the top of the file itself. Any work contributed where you are not the original +author must contain its license header with the original author(s) and source. diff --git a/bitcoin/INSTALL.md b/bitcoin/INSTALL.md new file mode 100644 index 0000000..4cead03 --- /dev/null +++ b/bitcoin/INSTALL.md @@ -0,0 +1 @@ +See [doc/build-\*.md](/doc) \ No newline at end of file diff --git a/bitcoin/README.md b/bitcoin/README.md new file mode 100644 index 0000000..c5b6ce4 --- /dev/null +++ b/bitcoin/README.md @@ -0,0 +1,79 @@ +Bitcoin Core integration/staging tree +===================================== + +https://bitcoincore.org + +For an immediately usable, binary version of the Bitcoin Core software, see +https://bitcoincore.org/en/download/. + +What is Bitcoin Core? +--------------------- + +Bitcoin Core connects to the Bitcoin peer-to-peer network to download and fully +validate blocks and transactions. It also includes a wallet and graphical user +interface, which can be optionally built. + +Further information about Bitcoin Core is available in the [doc folder](/doc). + +License +------- + +Bitcoin Core is released under the terms of the MIT license. See [COPYING](COPYING) for more +information or see https://opensource.org/licenses/MIT. + +Development Process +------------------- + +The `master` branch is regularly built (see `doc/build-*.md` for instructions) and tested, but it is not guaranteed to be +completely stable. [Tags](https://github.com/bitcoin/bitcoin/tags) are created +regularly from release branches to indicate new official, stable release versions of Bitcoin Core. + +The https://github.com/bitcoin-core/gui repository is used exclusively for the +development of the GUI. Its master branch is identical in all monotree +repositories. Release branches and tags do not exist, so please do not fork +that repository unless it is for development reasons. + +The contribution workflow is described in [CONTRIBUTING.md](CONTRIBUTING.md) +and useful hints for developers can be found in [doc/developer-notes.md](doc/developer-notes.md). + +Testing +------- + +Testing and code review is the bottleneck for development; we get more pull +requests than we can review and test on short notice. Please be patient and help out by testing +other people's pull requests, and remember this is a security-critical project where any mistake might cost people +lots of money. + +### Automated Testing + +Developers are strongly encouraged to write [unit tests](src/test/README.md) for new code, and to +submit new unit tests for old code. Unit tests can be compiled and run +(assuming they weren't disabled during the generation of the build system) with: `ctest`. Further details on running +and extending unit tests can be found in [/src/test/README.md](/src/test/README.md). + +There are also [regression and integration tests](/test), written +in Python. +These tests can be run (if the [test dependencies](/test) are installed) with: `build/test/functional/test_runner.py` +(assuming `build` is your build directory). + +The CI (Continuous Integration) systems make sure that every pull request is built for Windows, Linux, and macOS, +and that unit/sanity tests are run automatically. + +### Manual Quality Assurance (QA) Testing + +Changes should be tested by somebody other than the developer who wrote the +code. This is especially important for large or high-risk changes. It is useful +to add a test plan to the pull request description if testing the changes is +not straightforward. + +Translations +------------ + +Changes to translations as well as new translations can be submitted to +[Bitcoin Core's Transifex page](https://www.transifex.com/bitcoin/bitcoin/). + +Translations are periodically pulled from Transifex and merged into the git repository. See the +[translation process](doc/translation_process.md) for details on how this works. + +**Important**: We do not accept translation changes as GitHub pull requests because the next +pull from Transifex would automatically overwrite them again. diff --git a/bitcoin/SECURITY.md b/bitcoin/SECURITY.md new file mode 100644 index 0000000..fd4c61d --- /dev/null +++ b/bitcoin/SECURITY.md @@ -0,0 +1,20 @@ +# Security Policy + +## Supported Versions + +See our website for versions of Bitcoin Core that are currently supported with +security updates: https://bitcoincore.org/en/lifecycle/#schedule + +## Reporting a Vulnerability + +To report security issues send an email to security@bitcoincore.org (not for support). + +The following keys may be used to communicate sensitive information to developers: + +| Name | Fingerprint | +|------|-------------| +| Pieter Wuille | 133E AC17 9436 F14A 5CF1 B794 860F EB80 4E66 9320 | +| Michael Ford | E777 299F C265 DD04 7930 70EB 944D 35F9 AC3D B76A | +| Ava Chow | 1528 1230 0785 C964 44D3 334D 1756 5732 E08E 5E41 | + +You can import a key by running the following command with that individual’s fingerprint: `gpg --keyserver hkps://keys.openpgp.org --recv-keys ""` Ensure that you put quotes around fingerprints containing spaces. diff --git a/bitcoin/doc/JSON-RPC-interface.md b/bitcoin/doc/JSON-RPC-interface.md new file mode 100644 index 0000000..10d8ee5 --- /dev/null +++ b/bitcoin/doc/JSON-RPC-interface.md @@ -0,0 +1,214 @@ +# JSON-RPC Interface + +The headless daemon `bitcoind` has the JSON-RPC API enabled by default, the GUI +`bitcoin-qt` has it disabled by default. This can be changed with the `-server` +option. In the GUI it is possible to execute RPC methods in the Debug Console +Dialog. + +## Endpoints + +There are two JSON-RPC endpoints on the server: + +1. `/` +2. `/wallet//` + +### `/` endpoint + +This endpoint is always active. +It can always service non-wallet requests and can service wallet requests when +exactly one wallet is loaded. + +### `/wallet//` endpoint + +This endpoint is only activated when the wallet component has been compiled in. +It can service both wallet and non-wallet requests. +It MUST be used for wallet requests when two or more wallets are loaded. + +This is the endpoint used by bitcoin-cli when a `-rpcwallet=` parameter is passed in. + +Best practice would dictate using the `/wallet//` endpoint for ALL +requests when multiple wallets are in use. + +### Examples + +```sh +# Get block count from the / endpoint when rpcuser=alice and rpcport=38332 +$ curl --user alice --data-binary '{"jsonrpc": "2.0", "id": "0", "method": "getblockcount", "params": []}' -H 'content-type: application/json' localhost:38332/ + +# Get balance from the /wallet/walletname endpoint when rpcuser=alice, rpcport=38332 and rpcwallet=desc-wallet +$ curl --user alice --data-binary '{"jsonrpc": "2.0", "id": "0", "method": "getbalance", "params": []}' -H 'content-type: application/json' localhost:38332/wallet/desc-wallet + +``` + +## Parameter passing + +The JSON-RPC server supports both _by-position_ and _by-name_ [parameter +structures](https://www.jsonrpc.org/specification#parameter_structures) +described in the JSON-RPC specification. For extra convenience, to avoid the +need to name every parameter value, all RPC methods accept a named parameter +called `args`, which can be set to an array of initial positional values that +are combined with named values. + +Examples: + +```sh +# "params": ["mywallet", false, false, "", false, false, true] +bitcoin-cli createwallet mywallet false false "" false false true + +# "params": {"wallet_name": "mywallet", "load_on_startup": true} +bitcoin-cli -named createwallet wallet_name=mywallet load_on_startup=true + +# "params": {"args": ["mywallet"], "load_on_startup": true} +bitcoin-cli -named createwallet mywallet load_on_startup=true +``` + +## Versioning + +The RPC interface might change from one major version of Bitcoin Core to the +next. This makes the RPC interface implicitly versioned on the major version. +The version tuple can be retrieved by e.g. the `getnetworkinfo` RPC in +`version`. + +Usually deprecated features can be re-enabled during the grace-period of one +major version via the `-deprecatedrpc=` command line option. The release notes +of a new major release come with detailed instructions on what RPC features +were deprecated and how to re-enable them temporarily. + +## JSON-RPC 1.1 vs 2.0 + +The server recognizes [JSON-RPC v2.0](https://www.jsonrpc.org/specification) requests +and responds accordingly. A 2.0 request is identified by the presence of +`"jsonrpc": "2.0"` in the request body. If that key + value is not present in a request, +the legacy JSON-RPC v1.1 protocol is followed instead, which was the only available +protocol in v27.0 and prior releases. + +|| 1.1 | 2.0 | +|-|-|-| +| Request marker | `"version": "1.1"` (or none) | `"jsonrpc": "2.0"` | +| Response marker | (none) | `"jsonrpc": "2.0"` | +| `"error"` and `"result"` fields in response | both present | only one is present | +| HTTP codes in response | `200` unless there is any kind of RPC error (invalid parameters, method not found, etc) | Always `200` unless there is an actual HTTP server error (request parsing error, endpoint not found, etc) | +| Notifications: requests that get no reply | (not supported) | Supported for requests that exclude the "id" field. Returns HTTP status `204` "No Content" | + +## Security + +The RPC interface allows other programs to control Bitcoin Core, +including the ability to spend funds from your wallets, affect consensus +verification, read private data, and otherwise perform operations that +can cause loss of money, data, or privacy. This section suggests how +you should use and configure Bitcoin Core to reduce the risk that its +RPC interface will be abused. + +- **Securing the executable:** Anyone with physical or remote access to + the computer, container, or virtual machine running Bitcoin Core can + compromise either the whole program or just the RPC interface. This + includes being able to record any passphrases you enter for unlocking + your encrypted wallets or changing settings so that your Bitcoin Core + program tells you that certain transactions have multiple + confirmations even when they aren't part of the best block chain. For + this reason, you should not use Bitcoin Core for security sensitive + operations on systems you do not exclusively control, such as shared + computers or virtual private servers. + +- **Securing local network access:** By default, the RPC interface can + only be accessed by a client running on the same computer and only + after the client provides a valid authentication credential (username + and passphrase). Any program on your computer with access to the file + system and local network can obtain this level of access. + Additionally, other programs on your computer can attempt to provide + an RPC interface on the same port as used by Bitcoin Core in order to + trick you into revealing your authentication credentials. For this + reason, it is important to only use Bitcoin Core for + security-sensitive operations on a computer whose other programs you + trust. + +- **Securing remote network access:** You may optionally allow other + computers to remotely control Bitcoin Core by setting the `rpcallowip` + and `rpcbind` configuration parameters. These settings are only meant + for enabling connections over secure private networks or connections + that have been otherwise secured (e.g. using a VPN or port forwarding + with SSH or stunnel). **Do not enable RPC connections over the public + Internet.** Although Bitcoin Core's RPC interface does use + authentication, it does not use encryption, so your login credentials + are sent as clear text that can be read by anyone on your network + path. Additionally, the RPC interface has not been hardened to + withstand arbitrary Internet traffic, so changing the above settings + to expose it to the Internet (even using something like a Tor onion + service) could expose you to unconsidered vulnerabilities. See + `bitcoind -help` for more information about these settings and other + settings described in this document. + + Related, if you use Bitcoin Core inside a Docker container, you may + need to expose the RPC port to the host system. The default way to + do this in Docker also exposes the port to the public Internet. + Instead, expose it only on the host system's localhost, for example: + `-p 127.0.0.1:8332:8332` + +- **Secure authentication:** By default, when no `rpcpassword` is specified, Bitcoin Core generates unique + login credentials each time it restarts and puts them into a file + readable only by the user that started Bitcoin Core, allowing any of + that user's RPC clients with read access to the file to login + automatically. The file is `.cookie` in the Bitcoin Core + configuration directory, and using these credentials is the preferred + RPC authentication method. If you need to generate static login + credentials for your programs, you can use the script in the + `share/rpcauth` directory in the Bitcoin Core source tree. As a final + fallback, you can directly use manually-chosen `rpcuser` and + `rpcpassword` configuration parameters---but you must ensure that you + choose a strong and unique passphrase (and still don't use insecure + networks, as mentioned above). + +- **Secure string handling:** The RPC interface does not guarantee any + escaping of data beyond what's necessary to encode it as JSON, + although it does usually provide serialized data using a hex + representation of the bytes. If you use RPC data in your programs or + provide its data to other programs, you must ensure any problem strings + are properly escaped. For example, the `createwallet` RPC accepts + arguments such as `wallet_name` which is a string and could be used + for a path traversal attack without application level checks. Multiple + websites have been manipulated because they displayed decoded hex strings + that included HTML `