Blockchain Commons Gordian Envelope for Rust

by Wolf McNally and Blockchain Commons

Introduction

Gordian Envelope is a structured format for hierarchical binary data focused on privacy. The Rust implementation provides a feature-rich, production-ready reference implementation.

Envelopes are designed to facilitate "smart documents" with a number of unique features:

• Hierarchical structure: Easy representation of a variety of semantic structures, from simple key-value pairs to complex property graphs
• Merkle-like digest tree: Built-in integrity verification at any level of the structure
• Deterministic representation: Uses CBOR with deterministic encoding rules for consistent serialization
• Privacy-focused: The holder of a document can selectively encrypt or elide specific parts without invalidating the structure, signatures, or digest tree
• Progressive trust: Holders can reveal information incrementally to build trust with verifiers

Getting Started

[dependencies]
bc-envelope = "0.34.0"

Basic usage examples:

use bc_envelope::prelude::*;

// Create a simple envelope with a string subject
let envelope = Envelope::new("Hello, world!");

// Add assertions to an envelope
let envelope = envelope
    .add_assertion("created", "2025-04-03")
    .add_assertion("author", "Alice");

// Selectively elide information
let elided = envelope.elide(|e| !e.extract_object_for_predicate::<String>("author").unwrap().eq("Alice"));

// Sign an envelope
let signed = envelope.add_signature(&private_key);

// Verify a signature
let verified = signed.verify_signature_from(&public_key)?;

Features and Components

Gordian Envelope includes several powerful features, all configurable through Cargo features:

By default, all features are enabled. You can select a subset for your specific needs.

Specification

Gordian Envelope is formally specified in the IETF Internet Draft, which is currently in the community review stage.

Extensions to the base specification are documented in the Blockchain Commons Research repository:

• BCR-2023-003: Envelope Known Value
• BCR-2023-004: Envelope Symmetric Encryption
• BCR-2023-005: Envelope Compression
• BCR-2023-006: Envelope Attachment
• BCR-2023-012: Envelope Expression
• BCR-2023-013: Envelope Crypto
• BCR-2024-003: Envelope (Full Specification)
• BCR-2024-006: Envelope Graph
• BCR-2024-007: Envelope Decorrelation

Gordian Principles

Gordian Envelope implements the Gordian Principles:

• Independence: Holders control their own data and can selectively disclose information without relying on third parties
• Privacy: Built-in support for elision, encryption, and decorrelation allows precise information control
• Resilience: Support for social recovery (SSKR), signatures, and encryption provides robust security
• Openness: Fully open-source, well-documented, with open standards and test vectors

Status - Community Review

Gordian Envelope is currently in community review. We appreciate your testing and feedback on:

• API usability
• Integration with your use cases
• Performance
• Bug reports

Comments can be posted to the Gordian Developer Community.

Because this library is still in community review, it should not be used for production tasks until it has received further testing and auditing.

See Blockchain Commons' Development Phases.

Dependencies

• dcbor: Deterministic CBOR for consistent serialization
• bc-crypto: Cryptographic primitives
• bc-components: Common cryptographic components
• bc-ur: Uniform Resources for encoding and decoding

Other Implementations

Gordian Envelope is also available in:

• Swift
• Command-line tool

Contributing

We encourage public contributions through issues and pull requests! Please review CONTRIBUTING.md for details on our development process. All contributions to this repository require a GPG signed Contributor License Agreement.

Financial Support

Gordian Envelope is a project of Blockchain Commons, a "not-for-profit" social benefit corporation committed to open source & open development. Our work is funded entirely by donations and collaborative partnerships with people like you. Every contribution will be spent on building open tools, technologies, and techniques that sustain and advance blockchain and internet security infrastructure and promote an open web.

To financially support further development of Gordian Envelope and other projects, please consider becoming a Patron of Blockchain Commons through ongoing monthly patronage as a GitHub Sponsor. You can also support Blockchain Commons with bitcoins at our BTCPay Server.

Version History

0.34.0 - September 16, 2025

• Migrate to thiserror v2.
• Remove all dependency on anyhow.
• Align to dependencies.

0.33.0 - July 3, 2025

• Align to dependencies.
• Code formatting improvements.
• Expose EnvelopeCase and EnvelopeSummary in public API.

Discussions

The best place to talk about Blockchain Commons and its projects is in our GitHub Discussions areas:

• Gordian Developer Community: For developers working with Gordian specifications
• Blockchain Commons Discussions: For general Blockchain Commons topics

Credits

The following people directly contributed to this repository:

Responsible Disclosure

We want to keep all our software safe for everyone. If you have discovered a security vulnerability, we appreciate your help in disclosing it to us in a responsible manner. Please see our security policy for details.

License

Gordian Envelope is licensed under the BSD-2-Clause-Patent license. See LICENSE for details.