Merge #30: Update README.md, add CONTRIBUTING.md, update docs

5a5cdca Small docs updates (Daniela Brozzoni)
4202320 Derive useful methods (Daniela Brozzoni)
4b0ade7 Add CONTRIBUTING.md (Daniela Brozzoni)
f68bae6 Update README.md (Daniela Brozzoni)

Pull request description:

  Based on #31
  Closes #28

ACKs for top commit:
  danielabrozzoni:
    self-ACK 5a5cdca

Tree-SHA512: db2500aa7520fe1772352e8d1053e34ba06dd11a5a83e6cbf5372f74bcd982e9908447a3e50f9afec76d5a360edca8de250b488b97b479ca94243cec3409c65b

Author: danielabrozzoni

CONTRIBUTING.md

@@ -0,0 +1,98 @@
+Contributing to rust-hwi
+===========================================
+The rust-hwi project operates an open contributor model where anyone is welcome to
+contribute towards development in the form of peer review, documentation,
+testing and patches.
+
+Anyone is invited to contribute without regard to technical experience,
+"expertise", OSS experience, age, or other concern. However, the development of
+cryptocurrencies demands a high-level of rigor, adversarial thinking, thorough
+testing and risk-minimization.
+Any bug may cost users real money. That being said, we deeply welcome people
+contributing for the first time to an open source project or picking up Rust while
+contributing. Don't be shy, you'll learn.
+
+Communications Channels
+-----------------------
+
+Communication about rust-hwi happens primarily on the [BDK Discord](https://discord.gg/dstn4dQ), in the #rust-hwi channel.
+
+Discussion about code base improvements happens in GitHub [issues](https://github.com/bitcoindevkit/rust-hwi/issues) and
+on [pull requests](https://github.com/bitcoindevkit/rust-hwi/pulls).
+
+Contribution Workflow
+---------------------
+
+The codebase is maintained using the "contributor workflow" where everyone
+without exception contributes patch proposals using "pull requests". This
+facilitates social contribution, easy testing and peer review.
+
+To contribute a patch, the worflow is a as follows:
+
+  1. Fork Repository
+  2. Create topic branch
+  3. Commit patches
+
+In general commits should be atomic and diffs should be easy to read.
+For this reason do not mix any formatting fixes or code moves with actual code
+changes. Further, each commit, individually, should compile and pass tests, in
+order to ensure git bisect and other automated tools function properly.
+
+When adding a new feature, thought must be given to the long term technical
+debt.
+Every new feature should be covered by unit tests where possible.
+
+When refactoring, structure your PR to make it easy to review and don't
+hesitate to split it into multiple small, focused PRs.
+
+The Minimal Supported Rust Version is 1.41.1 (enforced by our CI).
+
+Commits should cover both the issue fixed and the solution's rationale.
+These [guidelines](https://chris.beams.io/posts/git-commit/) should be kept in mind.
+
+To facilitate communication with other contributors, the project is making use
+of GitHub's "assignee" field. First check that no one is assigned and then
+comment suggesting that you're working on it. If someone is already assigned,
+don't hesitate to ask if the assigned party or previous commenters are still
+working on it if it has been awhile.
+
+Deprecation policy
+------------------
+
+Where possible, breaking existing APIs should be avoided. Instead, add new APIs and
+use [`#[deprecated]`](https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md)
+to discourage use of the old one.
+
+Deprecated APIs are typically maintained for one release cycle. In other words, an
+API that has been deprecated with the 0.10 release can be expected to be removed in the
+0.11 release. This allows for smoother upgrades without incurring too much technical
+debt inside this library.
+
+If you deprecated an API as part of a contribution, we encourage you to "own" that API
+and send a follow-up to remove it as part of the next release cycle.
+
+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.
+PR should be reviewed first on the conceptual level before focusing on code
+style or grammar fixes.
+
+Coding Conventions
+------------------
+
+This codebase uses spaces, not tabs.
+Use `cargo fmt` with the default settings to format code before committing.
+This is also enforced by the CI.
+
+Going further
+-------------
+
+You may be interested by Jon Atacks guide on [How to review Bitcoin Core PRs](https://github.com/jonatack/bitcoin-development/blob/master/how-to-review-bitcoin-core-prs.md)
+and [How to make Bitcoin Core PRs](https://github.com/jonatack/bitcoin-development/blob/master/how-to-make-bitcoin-core-prs.md).
+While there are differences between the projects in terms of context and
+maturity, many of the suggestions offered apply to this project.
+
+Overall, have fun :)

README.md

@@ -1,5 +1,12 @@
 # rust-hwi
-Rust wrapper for [HWI](https://github.com/bitcoin-core/HWI/).
+Rust wrapper for the [Bitcoin Hardware Wallet Interface](https://github.com/bitcoin-core/HWI/) library.
+
+<a href="https://crates.io/crates/hwi"><img alt="Crate Info" src="https://img.shields.io/crates/v/hwi.svg"/></a>
+<a href="https://docs.rs/hwi"><img alt="API Docs" src="https://img.shields.io/badge/docs.rs-hwi-green"/></a>
+<a href="https://blog.rust-lang.org/2020/02/27/Rust-1.41.1.html"><img alt="Rustc Version 1.41+" src="https://img.shields.io/badge/rustc-1.41%2B-lightgrey.svg"/></a>
+<a href="https://discord.gg/d7NkDKm"><img alt="Chat on Discord" src="https://img.shields.io/discord/753336465005608961?logo=discord"></a>
+
+This library internally uses PyO3 to call HWI's functions. It is not a re-implementation of HWI in native Rust.
 
 ## Prerequisites
 
@@ -24,7 +31,7 @@ brew install libusb
 
 - Clone the repo
 ```
-git clone https://github.com/MagicalBitcoin/rust-hwi.git && cd rust-hwi
+git clone https://github.com/bitcoindevkit/rust-hwi.git && cd rust-hwi
 ```
 
 - Create a virtualenv:
@@ -40,58 +47,38 @@ source venv/bin/activate
 pip install -r requirements.txt
 ```
 
-## Supported commands
-
-| Command | Supported? |
-|:---:|:---: |
-| enumerate | YES |
-| getmasterxpub | YES |
-| signtx | YES |
-| getxpub | YES |
-| signmessage | YES |
-| getkeypool | YES |
-| getdescriptors | YES |
-| displayaddress | YES | 
-| setup | Planned |
-| wipe | Planned |
-| restore | Planned |
-| backup | Planned |
-| promptpin | Planned |
-| sendpin | Planned |
-
-| Flag | Supported? |
-|:---:|:---:|
-| --device-path | YES |
-| --device-type | YES |
-| --password | Planned |
-| --stdinpass | NO |
-| --testnet | Planned |
-| --debug | Planned |
-| --fingerprint | YES |
-| --version | Planned |
-| --stdin | NO |
-| --interactive | Planned |
-| --expert | YES |
-
-## Tests
-
-At the moment you'll need a HW plugged in to be able to run tests.
-
-If you don't have a hardware wallet, you can try [coldcard simulator](https://github.com/Coldcard/firmware).
-
-To run tests you should:
-
-- Install requirements and activate the virtualenv, as specified before
-- Plug in a HW.
-- `cargo test`
-
-## Devices tested
-| Device | Tested |
-|:---:|:---:|
-| Ledger Nano X | NO
-| Ledger Nano S | YES
-| Trezor One | NO
-| Trezor Model T | YES
-| Digital BitBox | NO
-| KeepKey | NO
-| Coldcard | YES
+## Usage
+
+```rust
+use bitcoin::util::bip32::DerivationPath;
+use hwi::error::Error;
+use hwi::{interface, types, HWIClient};
+use std::str::FromStr;
+
+fn main() -> Result<(), Error> {
+    let devices = interface::HWIClient::enumerate()?;
+    let device = devices.first().expect("No devices found");
+    let client = HWIClient::get_client(
+        &device,
+        true,
+        types::HWIChain::Test,
+    )?;
+    let derivation_path = DerivationPath::from_str("m/44'/1'/0'/0/0").unwrap();
+    let s = client.sign_message("I love BDK wallet", &derivation_path)?;
+    println!("{:?}", s.signature);
+    Ok(())
+}
+```
+
+## Testing
+
+To run the tests, you need to have a hardware wallet plugged in. If you don't have a HW for testing, you can try:
+- [Coldcard simulator](https://github.com/Coldcard/firmware)
+- [Trezor simulator](https://docs.trezor.io/trezor-firmware/core/emulator/index.html)
+- [Ledger simulator](https://github.com/LedgerHQ/speculos)
+
+**Don't use a device with funds for testing!**
+
+Either use a testing device with no funds, or use a simulator.
+
+You can run the tests with `cargo test`.

src/interface.rs

@@ -59,6 +59,17 @@ impl Deref for HWIClient {
 
 impl HWIClient {
     /// Lists all HW devices currently connected.
+    /// ```no_run
+    /// # use hwi::HWIClient;
+    /// # use hwi::error::Error;
+    /// # fn main() -> Result<(), Error> {
+    /// let devices = HWIClient::enumerate()?;
+    /// for device in devices {
+    ///     println!("I can see a {} here 😄", device.model);
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn enumerate() -> Result<Vec<HWIDevice>, Error> {
         let libs = HWILib::initialize()?;
         Python::with_gil(|py| {
@@ -68,11 +79,28 @@ impl HWIClient {
         })
     }
 
-    /// Finds the Python object of the device corresponding to Device
-    /// # Arguements
-    /// * `device` - The device for which the Python object will be passed
-    /// * `expert` - Whether the device should be opened in expert mode (enables additional output for some actions)
-    /// * `chain` - The Chain this client will be using
+    /// Returns the HWIClient for a certain device. You can list all the available devices using
+    /// [`enumerate`](HWIClient::enumerate).
+    ///
+    /// Setting `expert` to `true` will enable additional output for some commands.
+    /// ```
+    /// # use hwi::HWIClient;
+    /// # use hwi::types::*;
+    /// # use hwi::error::Error;
+    /// # fn main() -> Result<(), Error> {
+    /// let devices = HWIClient::enumerate()?;
+    /// for device in devices {
+    ///     let client = HWIClient::get_client(&device, false, HWIChain::Test)?;
+    ///     let xpub = client.get_master_xpub(HWIAddressType::Tap, 0)?;
+    ///     println!(
+    ///         "I can see a {} here, and its xpub is {}",
+    ///         device.model,
+    ///         xpub.to_string()
+    ///     );
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn get_client(
         device: &HWIDevice,
         expert: bool,
@@ -92,7 +120,7 @@ impl HWIClient {
         })
     }
 
-    /// Returns the master xpub of a device.
+    /// Returns the master xpub of a device, given the address type and the account number.
     pub fn get_master_xpub(
         &self,
         addrtype: HWIAddressType,
@@ -109,9 +137,7 @@ impl HWIClient {
         })
     }
 
-    /// Returns a psbt signed.
-    /// # Arguments
-    /// * `psbt` - The PSBT to be signed.
+    /// Signs a PSBT.
     pub fn sign_tx(
         &self,
         psbt: &PartiallySignedTransaction,
@@ -128,10 +154,7 @@ impl HWIClient {
         })
     }
 
-    /// Returns the xpub of a device.
-    /// # Arguments
-    /// * `path` - The derivation path to derive the key.
-    /// * `expert` - Whether the device should be opened in expert mode (enables additional output for some actions)
+    /// Returns the xpub of a device. If `expert` is set, additional output is returned.
     pub fn get_xpub(
         &self,
         path: &DerivationPath,
@@ -150,9 +173,6 @@ impl HWIClient {
     }
 
     /// Signs a message.
-    /// # Arguments
-    /// * `message` - The message to sign.
-    /// * `path` - The derivation path to derive the key.
     pub fn sign_message(
         &self,
         message: &str,
@@ -171,10 +191,10 @@ impl HWIClient {
     }
 
     /// Returns an array of keys that can be imported in Bitcoin core using importmulti
-    /// # Arguments
+    ///
     /// * `keypool` - `keypool` value in result. Check bitcoin core importmulti documentation for further information
     /// * `internal` - Whether to use internal (change) or external keys
-    /// * `addr_type` - HWIAddressType to use
+    /// * `addr_type` - Address type to use
     /// * `addr_all` - Whether to return a multiple descriptors for every address type
     /// * `account` - Optional BIP43 account to use
     /// * `path` - The derivation path to derive the keys.
@@ -218,9 +238,7 @@ impl HWIClient {
         })
     }
 
-    /// Returns device descriptors
-    /// # Arguments
-    /// * `account` - Optional BIP43 account to use.
+    /// Returns device descriptors. You can optionally specify a BIP43 account to use.
     pub fn get_descriptors(&self, account: Option<u32>) -> Result<HWIDescriptor, Error> {
         Python::with_gil(|py| {
             let func_args = (&self.hw_client, account.unwrap_or(0));
@@ -234,9 +252,7 @@ impl HWIClient {
         })
     }
 
-    /// Returns an address given a descriptor.
-    /// # Arguments
-    /// * `descriptor` - The descriptor to use. HWI doesn't support descriptors checksums.
+    /// Returns an address given a descriptor. Note that HWI doesn't support descriptors checksums.
     pub fn display_address_with_desc(&self, descriptor: &str) -> Result<HWIAddress, Error> {
         Python::with_gil(|py| {
             let path = py.None();
@@ -251,10 +267,7 @@ impl HWIClient {
         })
     }
 
-    /// Returns an address given pat and address type
-    /// # Arguments
-    /// * `path` - The derivation path to use.
-    /// * `address_type` - Address type to use.
+    /// Returns an address given path and address type.
     pub fn display_address_with_path(
         &self,
         path: &DerivationPath,
@@ -274,9 +287,9 @@ impl HWIClient {
     }
 
     /// Install the udev rules to the local machine.
-    /// The rules will be copied from the source to the location.
-    /// The default source location is "./udev"
-    /// The default destination location is "/lib/udev/rules.d"
+    ///
+    /// The rules will be copied from the source to the location; the default source location is
+    /// `./udev`, the default destination location is `/lib/udev/rules.d`
     pub fn install_udev_rules(source: Option<&str>, location: Option<&str>) -> Result<(), Error> {
         Python::with_gil(|py| {
             let libs = HWILib::initialize()?;