Crate bc_ur

Blockchain Commons Uniform Resources (“UR”) for Rust

Uniform Resources (URs) are URI-encoded CBOR structures developed by Blockchain Commons. This crate is an opinionated wrapper around the ur crate by Dominik Spicher, and is intended primarily for use in higher-level Blockchain Commmons projects like Gordian Envelope.

It is a requirement of the UR specification that the CBOR encoded as URs conform to Gordian dCBOR, which is a deterministic profile of CBOR currently specified in this IETF Internet Draft. The dependency dcbor crate can be used directly for that purpose. This crate provides the traits UREncodable, URDecodable, and URCodable that are built on traits from the dcbor crate such as CBORTaggedEncodable and CBORTaggedDecodable. It is strongly recommended that adopters of URs implement these traits for their types.

This crate does not currenly provide opinionated affordances for multi-part URs using fountain codes, but the dependency ur crate can be used directly for that purpose.

Getting Started

Add the following to your Cargo.toml:

[dependencies]
bc-ur = "0.1.3"

Specification

The primary specification for URs is BCR-2020-005: Uniform Resources and the Swift implementation URKit.

Usage

Encode a CBOR structure as a UR.

use dcbor::*;
use bc_ur::*;
let cbor = vec![1, 2, 3].cbor();
let ur = UR::new("test", &cbor).unwrap();
let ur_string = ur.string();
assert_eq!(ur_string, "ur:test/lsadaoaxjygonesw");

Decode a UR back to a CBOR structure.

use dcbor::*;
use bc_ur::*;
let ur_string = "ur:test/lsadaoaxjygonesw";
let ur = UR::from_ur_string(ur_string).unwrap();
assert_eq!(ur.ur_type, "test");
assert_eq!(&ur.cbor, &vec![1, 2, 3].cbor());

Structs

• UR
  A Uniform Resource (UR) is a URI-encoded CBOR object.

Traits

• URCodable
  A type that can be encoded to and decoded from a UR.
• URDecodable
  A type that can be decoded from a UR.
• UREncodable
  A type that can be encoded to a UR.