Skip to content
Closed
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
28 changes: 10 additions & 18 deletions .github/workflows/rust.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,52 +7,44 @@ 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]
exclude:
- os: macOS-latest
rust: 1.63.0
rust: [stable, "1.85"]
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: Test
run: cargo test
40 changes: 40 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,45 @@
# bitcoin_uri Changelog

## Unreleased

### Breaking changes

- MSRV is now 1.85, and the `bitcoin` dependency is 0.32.102, to track
rust-payjoin.
- 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.
- Parse-time `Error` and access-time `AccessError`, kept separate: a `Uri`
parses as long as it is structurally valid, and decoding an individual
value can fail later without failing the parse.
- `Uri::require_network`/`is_valid_for_network` over the body and `bc=`/`tb=`
addresses, with parse-time rejection of an HRP param on the wrong network.
- `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`.
- Byte-exact `Display` for a parsed `Uri` (bech32 bodies survive QR
uppercase), plus `Uri::source_str` for the original string.
- `UriBuilder`, assembling a `Uri` from typed parts whose `Display`
re-parses to the same parameters. `build` takes a network and rejects
mixed-network URIs.
- `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
12 changes: 5 additions & 7 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"
rust-version = "1.85"
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.85

## License

Expand Down
53 changes: 53 additions & 0 deletions examples/extension_params.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
//! 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` offer, 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=LNO1BOGUSOFFER\
&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") {
println!("sp: {}", entry.raw_value.as_deref().unwrap_or(""));
}

// `lightning` carries a BOLT 12 offer; bech32 is case-sensitive, so the
// value is handed back in the exact case it arrived.
if let Some(entry) = uri.get("lightning") {
println!("lightning: {}", entry.raw_value.as_deref().unwrap_or(""));
}

// `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