Blockchain Commons

Docs for Developers

Latest News: zewif, zewif-zcashd, and zmigrate crates released (3/30/25). New Meetings page created (3/18/25). Reports of first three Zcash meetings available from ZeWIF page (3/14/25). Major revisions to the UR pages (2/26/25). Updates to the SSKR page, including new, better detailed test vectors (2/12/25).

The Gordian Stack is a layered set of specifications founded on the CBOR data format and built up from that, step by step, to support digital-asset management in a way that fulfills the Gordian Principles. These developer pages contain developer resources that explain the elements in the Stack, and their importance, and make it easy for you to adopt them. For more support, you can also attend our Gordian Meetings, usually on the first Wednesday of the month.

bc-stack

The heart of the Gordian Stack is the Gordian Envelope, a simple data-storage mechanism that organizes content into semantic triples. You don’t need to know about the underlying elements to use Envelopes, so as a developer you can jump straight in and be confident that everything under Envelope is correctly abstracted to maintain layer divisions.

The Animated QR specification, built on Multipart Uniform Resources (MURs), is the other major entry point to the Gordian Stack, since it allows for the transmission of large data sets, such as Bitcoin’s PSBTs, across Airgaps.

Following is a description of the major layers of the Gordian Stack, in descending order.

If you have any questions or want more resources for any specific element in the Stack, please let us know via email or file an Issue at the repo for this website.

The Core Stack

Blockchain Commons’ Core Stack includes its two major user-facing innovations, Collaborative Seed Recovery (CSR) and Envelope, plus the binary encoding scheme that enables them both (dCBOR).

Core: Identifier Layer

Digital identifiers are required to say who’s who on the internet, but there’s a lot more to them than that. Blockchain Commons has been involved with identification since our work founding the Rebooting the Web of Trust workshops.

  • Cliques. Identity on the internet has usually been locked into the Single Signature Paradigm. Cliques instead imagine edge identifiers and cryptographic cliques that exist to denote relationships.
  • XIDs. Extensible Identifiers. A napkin sketch of how you can use Gordian Envelope and dCBOR to create create DID-like controller docs.

Core: CSR Layer

The Storage Layer allows for the secure & resilient remote storage of sharded digital assets.

  • Collaborative Seed Recovery (CSR). CSR supports the sharding of seeds using SSKR and their storage in independent storage servers such as the Gordian Depository. Communication with Depositories occur via GSTP, an Envelope functionality.

Core: Envelope Layer

Digital-asset storage uses Gordian Envelope, Blockchain Commons’ smart document system, which allows for hashed data elision, encryption, and much more.

  • Envelope. Gordian Envelopes are a binary storage format built in CBOR that can be encoded with URs, Blockchain Commons’ foundational plain-text encoding system, as ur:envelope. They’re built around recursive storage and support for hashed elision, which allows for provable redaction of data to allow data minimization. Extensions support even more functionality.

  • Seeds & SSKR. Seeds and SSKR shares can be stored in Envelopes. This goes beyond simpler storage techniques such as ur:seed and ur:sskr because it can include metadata to help identify a seed and also allows the use of Envelope functionality such as elision and encryption.

  • Other Envelope Extensions. Other Envelope extensions include existence proofs, encryption, signatures, compression, salting, known values, attachments, diffing & merging, and expressions. Envelope’s features can be used or not as a developer prefers: you only pay for what you use.

Envelope's Expressions & Communication

Envelope’s Expressions are an extension that enables secure communication.

Expressions. Expressions are Envelope functions. They are a specified way to request that a specific action be undertaken when an Evelope is accessed.

Request/Response. Request/Response packages up Expressions so that they can be sent to a remote recipient as a Request, who can then send a Response tied to the original request. This allows for interoperable communication using Envelopes when further security is not required.

Gordian Sealed Transaction Protocol (GSTP). GSTP builds on top of Request/Response for those times when security is required. It not only supports encryption and signatures but also uniquely supports Encrypted State Continuations (ESC) to securely encapsulate state information. It’s used by the Gordian Depository as part of CSR.

Encrypted State Continuation (ESC). ESC is a feature of GSTP that allows for the storage of local state in a secure way as part of the communication messages. It supports constrained environments, load-balanced servers, time-differentiated environments, and more.

Core: CBOR Layer

The CBOR layer defines the deterministic binary data serialization format for the Gordian Stack.

  • CBOR. The heart of Gordian’s data format is CBOR, a data format defined by IETF RFC 8949. It supports the organized and tagged formatting of data.

  • CDE. Determinism is a requirement for the Gordian Stack. It was loosely described in RFC 8949, but needed further detailing. Blockchain Commons’ work with CBOR led to one of CBOR’s original authors further describing how CBOR could be used deterministically in the CBOR Common Deterministic Encoding (CDE) Internet-Draft.

  • dCBOR. CDE allows for the creation of application profiles, which lay out specific rules for deterministic encoding. dCBOR is Blockchain Common’s CDE application profile used by Gordian Envelope. To support Envelope, it includes specific rules for things such as numeric encoding.

The UX Stack

The UX Stack includes graphical and text encodings that further empower the Core Stack.

UX: OIB Layer

It’s important to be able to identify a seed, no matter how it’s stored or transmitted.

  • Object Identity Block (OIB). The OIB suggests best practices for organizing and displaying data that can help users toidentify seeds. An OIB includes an icon, a name, abbreviated digest, and Lifehashes.
  • LifeHash. The LifeHash is a graphical element in an OIB. It creates a visual hash of a seed that should be distinct and relatively unique.

UX: UR Layer

The UR layer encodes structured CBOR binary data into plain text strings. It’s a method for sending plain-text strings or for efficiently encoding data into QRs. It’s used by Envelopes, Animated QRs, and other higher level capabilities.

  • Bytewords. The foundation of URs are ByteWords, which are a set of 256 carefully chosen words which each translate a byte (from 0x00 to 0xff) into a four-letter English word. A four-word checksum for data then improves resilience.
  • Uniform Resources (URs). Bytewords can be reduced in size by using the “minimal” form, which uses only the first and last letter of each word, which are always unique. URs therefore convert CBOR binary data into well-formed URIs by converting the data into minimal Bytewords and then preceding it with a ur: string followed by an appropriate tag for the data type. The result is self-identifying and transport-independent.
  • Multipart UR (MURs). URs include support for multipart URs, which divide and sequence UR data and which can be used with fountain codes to transmit the data even if a channel is unreliable.

UR’s Animated QRs

URs are formatted as a plain-text URIs, but they’re optimized to allow efficient encoding as QR codes.

  • Animated QRs. MURs are the foundation of Animated QRs, a method for transmitting data across an airgap when that data would be too large for a standard QR code. MURs’ fountain codes allow for individual frames to be missed without requiring all the frames to be resent. Due to Animated QR’s application for signing PSBTs over airgaps, they’ve become one of Blockchain Commons’ most successful releases.

The Crypto Stack

The Crypto Stack features the cryptographic elements in Blockchain Commons’ stack, including seeds, sharding, and DKG systems.

Crypto: CKM Layer

The CKM layer is an area for future development. It will shift from the CSR model of creating a key and then splitting it to the CKM model of keeping a key split at all times.

  • Collaborative Key Management (CKM). A next-generation key-management solution, CKM uses Secure Multi Party Computation (SMPC) to keep a key separated, rather than having it all in one place. Currently, ZF FROST is the only production-ready implemention of CKM, so it’s likely CKM and FROST will go hand in hand.

  • Distributed Key Generation (DKG). A cryptographic process where portions of a key are kept separate in separate locations, never combining them until necessary.

  • FROST. FROST is a Schnorr-based signature system that offers more robust multisigs. It also has the advantage of optionally integrating Distributed Key Generation (DKG), where portions of a key are held by different devices.
  • MuSIG2. MuSIG 2 is another Schnorr-based signature method for creating multisigs. Although it doesn’t support threshold signing like FROST does, it instead offers strong accountability.

Crypto: Sharding Layer

Sharding is a process by which a key is separated into parts that can then be recombined to reconstruct the key.

  • SSKR. Sharded Secret Key Reconstruction (SSKR) is Blockchain Commons’ methodology & library for empowing secret sharding, currently focused on a variant of Shamir’s Secret Sharing with expansions for two-level shares. URs allow the encoding of SSKR shares as ur:sskr (though Envelopes are now preferred).
  • VSS. Verifiable Secret Sharing (VSS) is a next-generation sharding method where the existence of shards can be verified without having to reconstuct the secret.

Crypto: Seed Layer

Much of Blockchain Commons’ work is focused on providing users with secure & resilient protection of their cryptographi secrets.

  • Aymmetric Keys. Private and public keys are generated from seeds using specific derivation paths. They enable encryption and signing.

  • Seeds. Seeds are the foundation of digital-asset security, as they’re used to generate signing keys and auth keys, often in a hierarchical manner. URs allow the encoding of seeds as ur:seed, but Envelopes are now preferred because they can store metadata and also allow for encryption or elision. Blockchain Commons’ seedtool-cli-rust and Seedtool for iOS offer best practices for the management of seeds.
  • Entropy. The randomness used to create seeds is Entropy.

Cryptographic secrets can be stored in one of two ways: as simple text-based URs, or as more descriptive Envelopes.

Architectural Overview

The Gordian Stack is built atop a carefully considered architecture that works to uphold human dignity and choice on the internet.

Chain-Specific Work

Blockchain Commons’ specifications aren’t built for any specific blockchain. (In fact, most don’t require a blockchain at all!) However, we’ve also done work with certain blockchains to help bring their digital-asset management into harmony with the Gordian principles, while a lot of the long-term members of the Gordian Developers community are Bitcoin-focused.

Other Future Development

A few other technologies are currently in early stages of development or integration.

  • The Discovery Layer. A discovery layer is planned that will allow end-users to find and identify Gordian Depositories or other online services.

For More Info

Our Gordian Developer community is actively working with this resources! Join us in Discussions or at our monthly meetings!