Latest News: Added Executive Summary and Feature List pages (4/24/24). Released IETF Envelope I-D v7 (3/31/24). Added Multisig Custody use case for Request & Response (2/28/24). Published Envelope Request & Response Implementation Guide (2/20/24).

Gordian Envelope is a specification for the achitecture of a “smart document”. It uses CBOR to support the secure, reliable, and deterministic storage and transmission of data such as seeds, keys, decentralized identifiers, and verifiable credentials in a way that enables privacy while preserving structure. The format is very simple and compact, with minimal overhead, but documents can ultimately be as complex as needed. Gordian Envelope’s privacy features are built on a hashed Merkle Tree that supports cryptography and privacy-related methodologies such as progressive trust and Merkle-based selective disclosure.

Blockchain Commons is currently working with multiple companies on the development and deployment of Gordian Envelopes via regular biweekly meetings; contact us if you’d like to be involved. Envelope is also on the experimental track as an Informational Draft for the IETF. Further, ongoing discussions are occurring with the W3C Credentials Community Group.

The Envelope as Metaphor

The name “envelope” was chosen for this smart-document architecture because that provides an excellent metaphor for its capabilities.

These capabilities include:

  • Envelopes can have things written on them. Plaintext parts of a Gordian Envelope can be read by anyone.
  • Envelopes can have routing instructions. That plaintext information can include data on how to use the Gordian Envelope, such as how to open or close it.
  • Envelopes can contain things. Things can be placed within the structure of a Gordian Envelope.
  • Envelopes can contain envelopes. The Gordian Envelope structure is fully recursive: any part of an envelope can actually be another envelope.
  • Envelopes can have a seal. A signature can be made for the contents of a Gordian Envelope, verifying their authenticity and that they haven’t been changed.
  • Envelopes can be certified. Beyond just guarding against changes, a Gordian Envelope signature can also act as a certification of the envelope’s contents by some authority.
  • Envelopes can be closed. Encryption allows any part of a Gordian Envelope to be protected from prying eyes.
  • Envelopes can have windows. Selective disclosure allows for some parts of a Gordian Envelope to be readable while others have been redacted. Merkle proofs can proof that those parts were present in the original envelope.
  • Different recipients can open envelopes in different ways. Just as people might use letter openers, their fingers, or a machine to open a normal envelope, special permits can grant people different ways to open a Gordian Envelope.

Why Are Envelopes Important?

The Gordian Envelope is intended as a more privacy-focused encoding architecture than existing data formats such as JWT and JSON-LD. We believe it has a better security architecture than JWT and that it doesn’t fall victim to the barriers of canonicalization complexity found in JSON-LD — which should together permit better security reviews of the Gordian Envelope design.

However, new features of Gordian Envelope not available in JWT or JSON-LD offer some of the best arguments for using the Smart Document structure.

Envelope Videos

Intro to Envelopes:
MVA & Ciphers:

See the Gordian Envelope playlist for more.


Envelope Libraries

Language Repo Contributor Status
Rust bc-envelope-rust Blockchain Commons  
Swift BCSwiftEnvelope Blockchain Commons  

dCBOR Libraries

Language Repo Contributor Status
Ruby cbor-dcbor gem @cabo  
Rust bc-dcbor-rust Blockchain Commons  
Swift BCSwiftDCBOR Blockchain Commons  
TypeScript bc-dcbor-ts Blockchain Commons  


Industry Intros:

Developer Resources:

Developer Extension Resources:

Developer Reference Apps:

Use Cases: