Skip to content

Commit 57fcb33

Browse files
apoelstraapoelstra
committed
Merge rust-bitcoin#4844: Add a bunch of project management docs
9d11812 docs: Add a bunch of project management docs (Tobin C. Harding) e053538 docs: Rename address file (Tobin C. Harding) Pull request description: Add a bunch of docs while reading over rust-bitcoin#550. FTR after discussion offline between Andrew and myself we are attempting to create a `docs/` directory that holds specifications on current and future work as well as API nuances etc. Devs can then read the 'specs' when coding instead of trawling through enormous issues discussions. Furthermore any issue that gets unwieldy will be moved to a GitHub discussions because they have threading. We took inspiration from: https://github.com/jj-vcs/jj/tree/main/docs Close rust-bitcoin#550 ACKs for top commit: apoelstra: ACK 9d11812; successfully ran local tests Tree-SHA512: 5fea7aa85a412fff8fa5ea352e5d2e5ada4bfca1c3035c95f8c5ba516ece0776890c4e9885db4cf5d575577299cc7478fb5ce8dc2db23a8cb82fafd21d397fc8
2 parents 898af5a + 9d11812 commit 57fcb33

File tree

7 files changed

+267
-3
lines changed

7 files changed

+267
-3
lines changed

docs/address.md renamed to docs/addresses.md

File renamed without changes.

‎docs/crates.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# rust-bitcoin stack of crates
2+
3+
The `rust-bitcoin` project is in the, very long, process of crate
4+
smashing. The original single `rust-bitcoin` crate has already been
5+
broken into a number of pieces and this work is ongoing. Both current
6+
and future crates are documented here. Future crates typically have an
7+
entry in [roadmap.md] and likely also a file of their own.
8+
9+
## Current crates
10+
11+
- `addresses`: **Empty** placeholder (see future crates below).
12+
- `base58`: Bitcoin base58 encoding and decoding (for pre-segwit addresses).
13+
- `bitcoin`: The `rust-bitcoin` crate.
14+
- `chacha20_poly135`: ChaCha20 stream cipher with the Poly1305 MAC.
15+
- `hashes`: Rust Bitcoin hashes library.
16+
- `internals`: Used internally by crates in this repo.
17+
- `io`: Rust Bitcoin I/O library (to support `no_std`).
18+
- `p2p`: Rust Bitcoin peer to peer message types.
19+
- `primitives`: Rust Bitcoin primitive types.
20+
- `units`: Rust Bitcoin unit types.
21+
22+
### Crates in our stack but in different repositories
23+
24+
A few crates are in different repositories, primarily because they were either started by different
25+
people or they have a (slightly) different set of maintainers and/or merge policy.
26+
27+
- `secp256k1`: https://github.com/rust-bitcoin/rust-secp256k1
28+
- `bech32`: https://github.com/rust-bitcoin/rust-bech32
29+
- `hex-conservative`: https://github.com/rust-bitcoin/hex-conservative
30+
- `miniscript`: https://github.com/rust-bitcoin/rust-miniscript
31+
32+
## Future crates
33+
34+
- `addresses`: Bitcoin addresses (see [address.md])
35+
- `bip-32`: BIP-32 (and maybe BIP-380) support (see [bip-32.md])
36+
- `psbt`: PSBTv2 support (see [psbt.md])
37+
- `keys`/`crypto`: Cryptography stuff or maybe just keys (see [keys.md])
38+
39+
## Re-export policy
40+
41+
See `./policy.md`.
42+
43+
[addresses.md]: ./addresses.md
44+
[bip-32.md]: ./bip-32.md
45+
[keys.md]: ./keys.md
46+
[psbt.md]: ./psbt.md

‎docs/crypto.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Bitcoin keys / Bitcoin crypto
2+
3+
Either `bitcoin-keys` and just have keys in it or `bitcoin-crypto` and
4+
have the other stuff from `bitcoin::crypto` in it.
5+
6+
## `secp256k1`
7+
8+
Both `bitcoin-keys` and `bitcoin-crypto` would depend on `secp256k1`.
9+
10+
Other things that use secp directly or indirectly through keys/crypto:
11+
12+
- `addresses` (for keys only)
13+
- `bip-32` (for keys only)
14+
- `psbt` for keys and signing
15+
- Taproot script extension methods
16+
- `bitcoin::taproot` module (uses secp directly)
17+
- `bitcoin::sign_message` module (uses secp directly)
18+
19+
Taproot stuff is quite entangled in various places throughout the
20+
codebase which in turn entangles secp.
21+
22+
## Keys
23+
24+
Public and private keys.
25+
26+
The reason for splitting this out is so that other crates can depend on keys without depending on
27+
`bitcoin` e.g., `addresses`.
28+
29+
(Note plural for crate name and singular for current module name, in line with what we did for
30+
`address` module and `addresses` crate.)
31+
32+
Current public types in `bitcoin::cryto::key`:
33+
34+
- `XOnlyPublicKey`
35+
- `PublicKey`
36+
- `SortKey`
37+
- `PubkeyHash`
38+
- `WPubkeyHash`
39+
- `CompressedPublicKey`
40+
- `PrivateKey`
41+
- `TweakedPublicKey`
42+
- `TweakedKeypair`
43+
- `SerializedXOnlyPublicKey`
44+
- Various error types
45+
- `TapTweak` trait
46+
47+
### Current obvious complications
48+
49+
Looking at `bitcoin::crypto::key` there are some obvious things that will need fixing.
50+
51+
#### `NetworkKind`
52+
53+
Currently we are using `bitcoin::network::NetworkKind` in `PriviateKey`.
54+
55+
- Used to get the first byte of WIF format
56+
- Passed to functions that create addresses e.g., `Address::p2pkh(key, network)`
57+
58+
#### `ScriptBuf`
59+
60+
Possibly ok if we have a dependency on `primitives`. Only used for sciptcode.
61+
62+
#### Taproot stuff
63+
64+
`TapNodeHash` and `TapTweakHash` are used to implement the `TapTweak` trait on `UntweakedPublickey`
65+
and `UntweakedKeypair`.

‎docs/keys.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Bitcoin keys / Bitcoin crypto
2+
3+
Either `bitcoin-keys` and just have keys in it or `bitcoin-crypto` and
4+
have the other stuff from `bitcoin::crypto` in it.
5+
6+
For now we use term 'keys', above is an open question.
7+
8+
## On `secp256k1`
9+
10+
Both `bitcoin-keys` and `bitcoin-crypto` would depend on `secp256k1`.
11+
12+
Other things that use secp directly or indirectly through keys/crypto:
13+
14+
- `addresses` (for keys only)
15+
- `bip-32` (for keys only)
16+
- `psbt` for keys and signing
17+
- Taproot script extension methods
18+
- `bitcoin::taproot` module (uses secp directly)
19+
- `bitcoin::sign_message` module (uses secp directly)
20+
21+
## Related to keys
22+
23+
Public and private keys.
24+
25+
The reason for splitting this out is so that other crates can depend on keys without depending on
26+
`bitcoin` e.g., `addresses`.
27+
28+
(Note plural for crate name and singular for current module name, in line with what we did for
29+
`address` module and `addresses` crate.)
30+
31+
Current public types in `bitcoin::cryto::key`:
32+
33+
- `XOnlyPublicKey`
34+
- `PublicKey`
35+
- `SortKey`
36+
- `PubkeyHash`
37+
- `WPubkeyHash`
38+
- `CompressedPublicKey`
39+
- `PrivateKey`
40+
- `TweakedPublicKey`
41+
- `TweakedKeypair`
42+
- `SerializedXOnlyPublicKey`
43+
- Various error types
44+
- `TapTweak` trait
45+
46+
### Current obvious complications
47+
48+
Looking at `bitcoin::crypto::key` there are some obvious things that will need fixing.
49+
50+
#### `NetworkKind`
51+
52+
Currently we are using `bitcoin::network::NetworkKind` in `PriviateKey`.
53+
54+
- Used to get the first byte of WIF format
55+
- Passed to functions that create addresses e.g., `Address::p2pkh(key, network)`
56+
57+
#### `ScriptBuf`
58+
59+
Possibly ok if we have a dependency on `primitives`. Only used for sciptcode.
60+
61+
#### Taproot stuff
62+
63+
`TapNodeHash` and `TapTweakHash` are used to implement the `TapTweak` trait on `UntweakedPublickey`
64+
and `UntweakedKeypair`.

‎docs/policy.md‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,76 @@ use crate::prelude::*; // *NOT* OK
4747
use crate::prelude::{DisplayHex, String, Vec} // OK
4848
```
4949

50+
## Re-exports
51+
52+
Types should _not_ be re-exported unless it is _really_ helpful. I.e., we considered re-exporting
53+
types from modules where they appear in the public API but decided against it.
54+
55+
### pub extern crates
56+
57+
Any crate `foo` which exposes a type from crate `bar` MUST publicly re-export `bar` crate at the
58+
root.
59+
60+
61+
For example:
62+
63+
```rust
64+
/// Re-export the `hex-conservative` crate.
65+
pub extern crate hex;
66+
```
67+
68+
Note, can use this exact doc format.
69+
70+
### Special treatment of `bitcoin`, `primitives`, `units`
71+
72+
`bitcoin`, `primitives`, and `units` should each be a superset of the crates below.
73+
74+
E.g for any `units::Foo`, there will be a `primitives::Foo`, and `bitcoin::Foo`. This goes for all
75+
types and modules.
76+
77+
For these three crates:
78+
79+
- Non-error re-exports use `doc(inline)`.
80+
- Error re-exports use `doc(no_inline)`.
81+
- Error types that are directly in the API are re-exported.
82+
- Other error types are available in an `error` module.
83+
84+
For example in `units`:
85+
86+
```rust
87+
88+
pub mod foo {
89+
// SomeError is 'directly' in the API but FooError is not.
90+
pub use self::error::SomeError;
91+
92+
/// A FooBar type.
93+
pub struct FooBar { ... };
94+
95+
/// Some function.
96+
pub some_function() -> SomeError {
97+
// Example rror logic
98+
SomeError::Foo(FooError { ... })
99+
}
100+
101+
pub mod error {
102+
/// Example error used 'directly' in the public API.
103+
pub enum SomeError { ... };
104+
105+
/// Abstracts the details of a foo-related error.
106+
pub struct FooError { ... };
107+
}
108+
}
109+
```
110+
111+
Then in `primitives` (and in `bitcoin`) in `lib.rs`:
112+
113+
```rust
114+
#[doc(inline)]
115+
pub use units::{foo, FooBar};
116+
#[doc(no_inline)]
117+
pub use units::foo::SomeError;
118+
```
119+
50120
## Return `Self`
51121

52122
Use `Self` as the return type instead of naming the type. When constructing the return value use
@@ -89,7 +159,6 @@ impl From<foo::Error> for LongDescriptiveError {
89159
}
90160
```
91161

92-
93162
## Errors
94163

95164
Return as much context as possible with errors e.g., if an error was encountered parsing a string

‎docs/roadmap.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,28 @@
11
# `rust-bitcoin` repository roadmap
22

33
* ~Release `units v1.0.0-rc.0`~
4+
* Create `bitcoin-consensus-encoding` `v0.1.0` (see [#4782])
5+
* Release `bitcoin-consensus-encoding` `v1.0.0-rc.0`
46
* Release `primitives v1.0.0-rc.0`
57
* Implement script tagging
68
* Add support for consensus encoding to `primitives`
79
* Release `bitcoin v0.33.0-rc.0`
8-
* Split out an address crate (see [address.md])
10+
* Split out an address crate (see [addresses.md])
911
* BIP-32 and BIP-380 (see [bip-32.md])
1012
* PSBTv2 (see [psbt.md])
13+
* Split out a crypto/keys crate. Includes discussion of `secp256k1`. See [crypto.md]
1114
* Make it possible for `bitcoin` to depend on `miniscript` (see [#2882])
1215
- Requires [bip-32.md] and [psbt.md]
16+
* Disentangle and stabalize Taproot stuff (see [taproot.md])
1317

1418
## RC cycle
1519

1620
We want to do a long release candidate cycle to give time for downstream testing and feedback on the
1721
API of the 1.0 crates. At a minimum this will be 6 months from the release `primitives-1.0-rc.0`.
1822

19-
[address.md]: ./address.md
23+
[addresses.md]: ./addresses.md
2024
[bip-32.md]: ./bip-32.md
25+
[crypto.md]: ./crypto.md
2126
[psbt.md]: ./psbt.md
27+
[taproot.md]: ./taproot.md
2228
[#2882]: <https://github.com/rust-bitcoin/rust-bitcoin/issues/2882>

‎docs/taproot.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Taproot
2+
3+
The `Taproot` code was left in `bitcoin` during the creation of
4+
`primitives` because it is not as close to stable.
5+
6+
Furthermore the Taproot stuff is quite entangled in various places
7+
throughout the codebase which in turn entangles the `secp256k1`
8+
dependency.
9+
10+
We likely need to tease apart the Taproot stuff and disentangle the
11+
bits we aren't yet willing to stabalize. Because of the entanglement
12+
this effects various other crates (`psbt`, `crypto`) as well as the
13+
stabalization efforts of script extension methods.
14+

0 commit comments

Comments
 (0)