Blockchain Commons

Docs for Developers

Latest News: Updated envelope home page with all features & extensions (10/14/26). Wrote new pages to highlight radical recursion and salt (9/30/26).

Gordian Envelope is a specification for the achitecture of a “smart document”. It builds on the binary format of the IETF CBOR standard 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 thanks to its radically recursive design, documents can ultimately be as complex as needed. Gordian Envelope’s hashed elision privacy features are built on a Merkle-like 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 Envelope via regular monthly meetings; subscribe to our announcements-only mailing list or join our Signal channel if you’d like to get involved. You can also contact us if you’d prefer to get more information first.

Gordian 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 an 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 Is Gordian Envelope Important?

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.

Hashed Elision

Envelope Feature. Any element of a Gordian Envelope can be removed while signatures of the envelope remain valid.

Radical Recursion

Envelope Feature. It’s envelopes all the way down. Every node in Gordian Envelope can contain nodes or leaves below it.

Encrypted State Continuation (ESC)

Envelope GSTP Extension. GSTP communication with envelopes allows state to be stored in an encrypted form as part of the communication, rather than depending on local or network storage.

Gordian Sealed Transaction Protocol (GSTP)

Envelope Request/Response Extension. GSTP is an envelope-based communication protocol that supports pubkey identification and ESC state storage to allow usage of unreliable and insecure transmission methods.

Inclusion Proofs

Envelope Hashed Elision Extension. After data is removed with hashed elision, the original information can be revealed with a hash (and possibly a Merkle path) proving that the info was in the envelope prior to redaction.

Permits

Envelope Security Extension. Envelopes can be locked with symmetric keys, pub keys, SSKR, or even multiple methods at the same time.

Request & Response

Envelope Communication Extension. A simple request and response protocol allows serialized communication using envelopes.

Salt

Envelope Privacy Extension. Data can be salted to avoid correlation through guesses of common words.

Envelope Videos

Envelope Teaser:
Understanding Envelope I:
Understanding Envelope II:

See the Gordian Envelope playlist for more.

Libraries

Envelope Core Libraries

Language Repo Contributor Status
Rust bc-envelope-rust Blockchain Commons  
Swift BCSwiftEnvelope Blockchain Commons  
TypeScript bc-envelope-ts Leonardo Custodio (Parity)  

Envelope Pattern Libraries

Language Repo Contributor Status
Rust bc-envelope-pattern-rust Blockchain Commons  
TypeScript bc-envelope-pattern-ts Leonardo Custodio (Parity)  

Envelope GSTP Libraries

Language Repo Contributor Status
Rust gstp-rust Blockchain Commons  
TypeScript bc-gstp-ts Leonardo Custodio (Parity)  

dCBOR Core Libraries

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

dCBOR Parse Libraries

Language Repo Contributor Status
Rust bc-dcbor-parse-rust Blockchain Commons  
TypeScript bc-dcbor-parse-ts Leonardo Custodio (Parity)  

dCBOR Pattern Libraries

Language Repo Contributor Status
Rust bc-dcbor-pattern-rust Blockchain Commons  
TypeScript bc-dcbor-pattern-ts Leonardo Custodio (Parity)  

Intro:

Envelope Features:

Envelope Extensions:

Industry Intros:

Learning Envelope from the Command Line:

Developer Resources:

Developer Extension Resources:

Developer Reference Apps:

Specs & Research Papers:

Use Cases: