|
1 | 1 | # Bitcoin Core JSON-RPC types |
2 | 2 |
|
3 | | -This crate provides data types return by Bitcoin Core's JSON-RPC API. Each type is specific to the |
| 3 | +This crate provides data types returned by Bitcoin Core's JSON-RPC API. Each type is specific to the |
4 | 4 | version of Core e.g., if you run the `getblockchaininfo` method against a Bitcoin Core v28 instance |
5 | 5 | you will get back the data described by `types::v28::GetBlockChainInfo`. In a similar fashion any |
6 | 6 | method `corerpcmethod` will return type `CoreRpcMethod` - snake-case as is conventional in Rust. |
7 | 7 |
|
8 | | -## Status |
| 8 | +The version specific structs _do not_ use types from `rust-bitcoin`. For any type that can be |
| 9 | +represented using types from `rust-bitcoin` we provide a version non-specific type in |
| 10 | +`model::CoreRpcMethod` and an `into_model()` method on the version specific type. |
9 | 11 |
|
10 | | -This crate is Work In Progress - not all methods for all Core versions are done yet. The single |
11 | | -source of truth (SSOT) for a methods status can be found in the version specific module e.g., |
12 | | -`types/src/v17/mod.rs`. The HTML version can be found online and has nice drop down menus. |
| 12 | +The crate supports **all** documented Core RPC methods. |
13 | 13 |
|
14 | | -See for example: https://docs.rs/corepc-types/0.5.0/corepc_types/v18/index.html |
| 14 | +(Note there are a bunch of undocumented methods that are not yet supported, coming soon.) |
15 | 15 |
|
16 | | -### As of `v0.5.0` |
| 16 | +## Known issues |
17 | 17 |
|
18 | | -- All types to support `rust-miniscript` exist for Core versions 17-28 inclusive. |
19 | | -- Support for Core Versions v17 and v18 is more fully fleshed out. |
20 | | -- Nice docs and `verify` tool for v17 and v18 only. |
| 18 | +The types include docs from Core however the docs used are from the _first_ Core version in which |
| 19 | +the method appeared. As an example, this means if you look at docs for v29 `createwallet` you will |
| 20 | +see docs that originate in Core v17 so may or may not be stale. We hope to fix this at some stage. |
| 21 | +For accurate documentation of the method you are best to run `bitcoin-cli help createwallet` against |
| 22 | +a Core node of the desired version. |
21 | 23 |
|
22 | 24 | ### Testing and Verification |
23 | 25 |
|
24 | | -In order to prove the data structures we do integration testing in `integration_test`. The tests are |
25 | | -version specific e.g., `cargo test --features=0_18_1`. In CI we test against all supported versions. |
26 | | -If you are using this crate in CI you may want to imitate the job structure. See the `Integration` |
27 | | -job in `.github/workflows/rust.yaml`. |
| 26 | +Each type is integration tested, however only typically with a single test. We hope to improve |
| 27 | +test coverage by using test vectors taken from Core source code ... at some stage. |
28 | 28 |
|
29 | | -In order to back up method status our claims we provide the `verify` tool that parses the SSOT and |
30 | | -checks the claims. Run it using `verify v17` (also `verify all`). |
31 | | - |
32 | | -The tool only currently verifies the `v17` and `v18` modules. |
| 29 | +If you experience any issues please let us know, we have done our best but this crate needs battle |
| 30 | +testing in the wild. |
33 | 31 |
|
34 | 32 | ## Minimum Supported Rust Version (MSRV) |
35 | 33 |
|
|
0 commit comments