Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 15 additions & 17 deletions .github/workflows/rust.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,52 +7,50 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Set up Rust
uses: hecrj/setup-rust-action@v1
uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt
rust-version: stable
- uses: actions/checkout@v2
- uses: actions/checkout@v6
- run: cargo fmt --all -- --check

lint:
runs-on: ubuntu-latest
steps:
- name: Set up Rust
uses: hecrj/setup-rust-action@v1
uses: dtolnay/rust-toolchain@stable
with:
components: clippy
- uses: actions/checkout@v2
- uses: actions/checkout@v6
- run: cargo clippy --all-targets --all-features -- -D clippy::all

compile:
runs-on: ubuntu-latest
steps:
- name: Set up Rust
uses: hecrj/setup-rust-action@v1
- uses: actions/checkout@v2
uses: dtolnay/rust-toolchain@stable
- uses: actions/checkout@v6
- run: cargo check --all

test:
needs: [codestyle, lint, compile]
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macOS-latest]
rust: [stable, 1.63.0]
os: [ubuntu-latest, macOS-latest]
rust: [stable, "1.63"]
exclude:
- os: macOS-latest
rust: 1.63.0
rust: "1.63"
runs-on: ${{ matrix.os }}

steps:
- name: Setup Rust
uses: hecrj/setup-rust-action@v1
uses: dtolnay/rust-toolchain@master
with:
rust-version: ${{ matrix.rust }}
toolchain: ${{ matrix.rust }}
- name: Checkout
uses: actions/checkout@v2
- name: Fixes for MSRV
if: matrix.rust == '1.63.0'
run: |
cargo update
uses: actions/checkout@v6
- name: Pin dependencies for MSRV
if: matrix.rust == '1.63'
run: cargo update -p cc --precise 1.1.31
- name: Test
run: cargo test

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might want to include --all-features as we don't default to including std as a default feature.

47 changes: 47 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,52 @@
# bitcoin_uri Changelog

## Unreleased

### Breaking changes

- MSRV is 1.63, now declared in `rust-version`, and `bitcoin` must be at
least 0.32.102. 1.63 matches `bitcoin-payment-instructions`, which this
crate is meant to be a dependency of.
- The body address is now optional, so a body-less URI such as
`bitcoin:?sp=...` parses. `Uri::body` returns `Option<&Address<V>>`.
- `Uri` is now owned and has no lifetime parameter: `Uri<V>` instead of
`Uri<'a, NetVal, Extras>`.
- Removed the `Extras` type parameter and the `DeserializeParams`,
`DeserializationState`, `SerializeParams`, and `Param` traits/types. An
extension now reads its parameters straight off the parsed `Uri` via the
`Params` multimap instead of plugging a type into the parser.
- Removed the `non-compliant-bytes` feature and the optional `either`
dependency. A non-UTF-8 parameter value is now an access-time error on the
typed accessor that needs it, not a separate API.

### Added

- `Params`/`ParamEntry`: an ordered, case-insensitive multimap of the raw
query parameters, preserving source order and percent-encoding, with
`ParamEntry::decoded_value` for on-demand RFC 3986 decoding.
- `AccessError`, returned when a value is read: its percent-decoded bytes
may not be valid UTF-8.
- Parse-time `Error`, separate from `AccessError`. Invalid
percent-encoding in any value fails the parse; a value that decodes to
bytes that are not UTF-8 fails only when it is read.
- `Uri::require_network`/`is_valid_for_network` over the body and the
`bc`/`tb`/`bcrt` parameters. A value under one of those keys must be a
segwit address of the key's network, or parsing fails with
`Error::InvalidHrpValue`.
- `NetworkError`, kept separate from the parse `Error`.
- `Uri::unsatisfied_requirements`, reporting the `req-` parameters a client
does not understand, plus `ParamEntry::requirement`/`is_required`.
- An `extension_params` example showing a consumer reading `pj`/`sp`/
`lightning` off a parsed URI with `get` + `decoded_value`.
- `Display` of a parsed `Uri` writes back the exact string it was parsed
from, and `Uri::source_str` returns it.
- `UriBuilder`, assembling a `Uri` from typed parts. Its output parses back
to the same parameters: keys and raw values must be RFC 3986 query
characters, and `build` checks each `bc`/`tb`/`bcrt` address against the
network its key names and the body against that network, rejecting a
URI that mixes networks.
- `BuildError`, wrapping `NetworkError` for build-time network mismatch.

## 0.1.0

- Fork from [Kixunil/bip21 @ `eae7201`](https://github.com/Kixunil/bip21/commit/eae72026cc5838bb169949641948b8c1cef99cbe) v0.5.0.
Expand Down
14 changes: 6 additions & 8 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
[package]
name = "bitcoin_uri"
version = "0.1.0"
version = "0.2.0"
authors = ["Dan Gould <d@ngould.dev>"]
edition = "2018"
edition = "2021"
rust-version = "1.63"
description = "Rust-idiomatic, compliant, flexible and performant bitcoin URI crate."
repository = "https://github.com/payjoin/bitcoin_uri"
readme = "README.md"
Expand All @@ -11,19 +12,16 @@ categories = ["cryptography::cryptocurrencies", "encoding", "rust-patterns", "va
license = "MITNFA"

[package.metadata.docs.rs]
features = ["std", "non-compliant-bytes"]
features = ["std"]
rustdoc-args = ["--cfg", "docsrs"]

[features]
# Implements std::error::Error for error types
std = ["percent-encoding-rfc3986/std", "bitcoin/std"]
# Enables non-BIP21-compliant feature of using raw bytes instead of validated UTF-8 strings.
non-compliant-bytes = ["either"]

[dependencies]
either = { version = "1.6.1", optional = true }
percent-encoding-rfc3986 = "0.1.3"
bitcoin = { version = "0.32.0", default-features = false }
bitcoin = { version = "0.32.102", default-features = false }

[dev-dependencies]
bitcoin = { version = "0.32.0", features = ["std"] }
bitcoin = { version = "0.32.102", features = ["std"] }
30 changes: 13 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,30 @@
# Rust implementation of BIP21 bitcoin URIs
# Rust implementation of BIP 321 bitcoin URIs

Rust-idiomatic, compliant, flexible and performant bitcoin URI crate.

## About

**Important:** while lot of work went into polishing the crate it's still considered
early-development!
**Important:** this is the 0.2 line, a rewrite against
[issue #12](https://github.com/payjoin/bitcoin_uri/issues/12). Its API is not
yet stable. 0.1 remains the published, stable crate.

* Rust-idiomatic: uses strong types, standard traits and other things
* Compliant: implements all requirements of BIP21, including protections to not forget about
`req-`. (But see features.)
* Flexible: enables parsing/serializing additional arguments not defined by BIP21.
* Performant: uses zero-copy deserialization and lazy evaluation wherever possible.

Serialization and deserialization is inspired by `serde` with these important differences:

* Deserialization signals if the field is known so that `req-` fields can be rejected.
* Much simpler API - we don't need all the features.
* Use of [`Param<'a>`] to enable lazy evaluation.
* Rust-idiomatic: owned types, no lifetime parameter.
* Compliant: parses the full BIP 321 shape, including a body-less URI, and
reports `req-` parameters a client does not understand through
`Uri::unsatisfied_requirements` rather than enforcing them itself.
* Flexible: an extension reads whatever parameters it needs straight off the
parsed `Uri`; this crate never needs to know what they mean.
* Performant: values stay percent-encoded until something decodes them.

The crate is `no_std` but does require `alloc`.

## Features
## Features

* `std` enables integration with `std` - mainly `std::error::Error`.
* `non-compliant-bytes` - enables use of non-compliant API that can parse non-UTF-8 URI values.

## MSRV

1.63.0
1.63

## License

Expand Down
56 changes: 56 additions & 0 deletions examples/extension_params.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
//! Reading extension parameters off a parsed URI.
//!
//! `bitcoin_uri` is a tokenizer: it parses the BIP 321 shape and hands back
//! every parameter still percent-encoded, without knowing what any of them
//! mean. An extension (payjoin's `pj`, a silent-payment `sp`, a BOLT 11
//! `lightning` invoice, anything else) reads whatever it needs straight off
//! the parsed [`Uri`] with [`Uri::get`]/[`Uri::get_all`] and decodes it with
//! [`ParamEntry::decoded_value`]. This example walks a body-less URI that
//! carries three unrelated extensions at once.
//!
//! Run with: `cargo run --example extension_params`

use bitcoin_uri::Uri;

fn main() {
// A body-less URI (BIP 321 allows one): no on-chain address, just three
// extension parameters, one of them marked `req-`.
let input = "bitcoin:?sp=sp1qsilentpaymentaddress\
&lightning=lnbc420bogusinvoice\
&req-pj=https://example.com/pay%3Ftoken%3Dabc";

let uri: Uri<_> = input.parse().expect("valid BIP 321 URI");

// No body, so this is an extension-only payment request.
assert!(uri.body().is_none());

// A silent-payment wallet reads `sp` without the crate knowing what it is.
if let Some(entry) = uri.get("sp") {
let address = entry.decoded_value().expect("sp has a value").expect("valid UTF-8");
println!("sp: {address}");
}

// `lightning` carries a BOLT 11 invoice (BOLT 12 offers use `lno`). The
// value comes back in the case it arrived in, which is uppercase if it
// came from a QR code.
if let Some(entry) = uri.get("lightning") {
let invoice = entry.decoded_value().expect("lightning has a value").expect("valid UTF-8");
println!("lightning: {invoice}");
}

// `get` matches by base key, so it finds `req-pj` when asked for `pj`.
// `decoded_value` applies RFC 3986 percent-decoding on demand, turning
// `%3F` back into `?` and `%3D` into `=`.
if let Some(entry) = uri.get("pj") {
let endpoint = entry.decoded_value().expect("pj has a value").expect("valid UTF-8");
println!("pj endpoint: {endpoint} (required: {})", entry.is_required());
}

// A consumer declares the extensions it understands; anything `req-` it
// does not understand means it MUST reject the URI. Here it handles `pj`
// and `sp` but not, say, a hypothetical `req-foo`.
let understood = ["pj", "sp", "lightning"];
let unsatisfied = uri.unsatisfied_requirements(&understood).count();
assert_eq!(unsatisfied, 0, "every required extension is understood");
println!("all {} parameters understood; safe to act on", uri.params().len());
}
Loading
Loading