Architect: Christopher Allen
Developer: Wolf McNally
The Gordian system is all about user agency & security. It's intended to support the self-sovereign control of digital assets in a way that's safe, secure, and private by enabling responsible key management, cutting through a traditionally knotty problem in Bitcoin development.. The Gordian system is built on a foundation of Principles that have been fulfilled in an Architecture that is embodied in Reference Apps and supported by Reference Libraries.
- Gordian Principles. A mission statement of four core principles that support self-sovereign control of digital assets.
- Gordian Architecture. The design for both the overall architecture and the individual specifications that make it possible.
- Gordian Reference Apps. A set of applications that demonstrate the Gordian Architecture, its Principles, its specifications, and its Libraries.
- Gordian Reference Libraries. A set of libraries that allow developers to incorporate Gordian specifications and expand the Gordian ecosystem.
- #SmartCustody. Educational programs meant to support the Gordian Principles.
The ultimate goal of the Gordian System is to create a community of developers who have followed the examples of the Gordian Reference Apps and used the Gordian Reference Libraries to build their own applications that embody the Gordian Architecture and fulfill the Gordian Principles.
This repo contains a table of contents for various the Gordian system projects and features. Please see individual repos and pages for more information.
You can also join our Signal Group, GitHub Discussions, or low-volume announcement list for Gordian Developers.
Blockchain Commons' interoperable specifications are meant to support four core principles that put the user first and that enable responsible key management:
- Independence. Gordian improves user freedom from involuntary oversight or external control.
- Privacy. Gordian protects against coercion with non-correlation, privacy, and pseudonymity.
- Resilience. Gordian protects users to decrease the likelihood of them losing their funds via any means.
- Openness. Gordian supports open infrastructure that allows developers to create their own applications.
Look at individual Blockchain Commons reference apps for guidance on how each acts as a model for these principles and #SmartCustody Case Studies for how professional hardware & software apps do so.
The Gordian Architecture puts the Gordian Principles into use through an overall design that covers everything that from the high-level architecture of a Gordian ecosystem through the specification and UX best practices that make it possible.
- Gordian Macro-Architecture. The ecosystem architecture depends on functional partition, separating services and confidential data.
- The Macro-Architecture is built primarily to support Privacy through these features.
- It is also built on a concept of Openness where different Services from different developers will interoperate freely.
- Data Format. CBOR is used as the canonical data structure for the Gordian Architecture.
- Encoding Specifications. Bytewords, URs, and (optionally) Animated or Static QRs ensure that Gordian services are interoperable.
- The Encoding Specifications are how the Gordian System ensures Openness in its Macro-Architure.
- Backup Specifications. UR specifications make it easy to backup confidential data.
- Supporting backups of data improves the Resilience of that data.
- Communication Specifications. Further UR specifications such as Gordian Envelope and request/responses aid interoperable communication.
- Like the Encoding Specifications, Communication Specifications help to suport the Openness of the architecture.
- They also ensure Independence because they assure the portability of data.
- Secure UX Designs. UX best practices form another layer of support for the Gordian Principles.
- Good UX designs help Resilience by proofing a user against mistake or con-men attacks of various sorts.
- They also improve Independence by making it easier for a user to control their own destiny.
Please see The Gordian Architecture for more in-depth discussion of all the architectural elements and Gordian Architecture Roles for examples of functions that can be partitioned within the Macro-architecture. Also see Collaborative Seed Recovery (CSR) Overview for our largest current architectual project in 2022 and Collaborative Key Management (CKM) Overview for our planned next step in 2023-2024.
Together, these elements (in particular: a network coordinator such as Gordian Coordinator; a signing device such as Gordian Seed Tool; encoding specifications such URs; and communication specifications such as envelope, request, and response) comprise what we consider a Minimal Viable Architecture (MVA) for Gordian, and thus for safe, self-sovereign architecture. They're the minimum that's needed to properly support users.
Use Cases further describe the intent of Blockchain Commons' architecture.
Gordian Envelope:
- Use Case Overview
- Educational & Credential Industry Use Cases — Using Envelopes to store & transmit credentials.
- Wellness Use Cases — Using Envelopes to share very sensitive data.
- Data Distribution Use Cases — Using Envelopes for user-related data releases.
- Software & AI Industry Use Cases — Using Gordian Envelopes to release software.
- Financial Industry Use Cases — Using Envelopes to store assets.
Collaborative Seed Recovery:
- Use Cases — A short listing of CSR-focused use cases.
Collaborative Key Management:
- Use Cases — More future-looking use cases that span CSR and CKM.
This video overview covers many of the technologies found in the Gordian Architecture:
Gordian Reference Apps demonstrate the elements of how the Gordian Architecture and how they can be used to fulfill the Gordian Principles. Our Gordian Reference Apps undergoing the most development currently include:
- Gordian Coordinator. A Networked transaction coordinator.
- Demonstrates Independence and Privacy by empowering users to create their own transactions, potentially in a non-Networked way.
- Demonstrates Openness through use of Communication Specifications such as URs.
- Improves Resilience through support for multi-sigs.
- Gordian Seed Tool. An Airgapped seed vault & signing device.
- Allows for Independence and Resilience by storing user assets in a Closely Held device.
- Demonstrates Openness through the use of Communication Specifications such as URs.
- Improves Resilience through Sharding and Backup Specifications.
- SpotBit. A Micro-pricing service.
- Demonstrates the Openness of a digital-asset ecosystem that supports Microservices.
- Improves Privacy through the user of a Torgap.
- Improves Independence by removing centralization of price-lookups.
Please see The Gordian Reference Apps for a complete list of past and present reference apps, links to their repos, and an example of how they can be combined into a Macro-Architecture. Links to CLI apps are also included.
The Gordian Reference Libraries allow you to easily use many of the specifications that lay the foundation for the Gordian Architecture. Our foundational libraries are usually written in C or C++, but many have many converted in other languages such as Java, Python, and Swift.
The core libraries are:
- bc-bytewords. A library for encoding binary data into Bytewords. A Gordian Encoding Specification.
- bc-lifehash. A library for creating Lifehash visual hashes. A Gordian UX Design.
- bc-sskr. A library for sharding a secret and converting it to Bytewords or URs. A Gordian Backup Specification.
- bc-ur. A library for encoding binary data as URs. A Gordian Encoding Specification.
Please see The Gordian Reference Libraries for a complete list of libraries in a variety of languages.
- This document details the dependencies between many of our reference libraries and apps in the Swift/iOS/macOS ecosystem. Many of the higher-level libraries are written in Swift, while there are a number of important lower-level libraries that are written in C or C++.
Please see the SmartCustody repo for articles on Multisigs, Timelocks, and other SmartCustody topics.
The following words & phrased are used in Gordian documents:
- Airgap. A Partition between two Services, such that they are not Networked on the same network. (Often, at least one Service is not Networked at all). See Airgap (Wikpedia).
- Animated QRs. An animation of a QR made up of several frames. Used for transmitting data larger than the max possible with Quick Response (QR) Codes. See Animated QRs Page.
- ByteWords. An Encoding Specification that represents binary data as English words. Used in the Gordian System primarily to represent CBOR in URs. See ByteWords Spec.
- CBOR. A Data Format, the canonical data representation for the Gordian System. It represents data in a binary format. See RFC 8949.
- Closely Held Device. A hardware device such as a phone or a hardware wallet that is privately held by an individual, that has a small attack surface due to careful and consistent sandboxing, and that is not constantly Networked in the way that a full computer tends to be.
- Collaborative Key Management (CKM). A Service for the collaborative generation and usage of keys. See CKM Overview.
- Collaborative Seed Recovery (CSR). A Service to improve Resilience by storing Shares of keys or seeds that are created by Sharding. See CSR Overview.
- Data Format. A Specification for a structure to store data.
- Encoding. A conversion of data into a specific form. See Encoding (Techopedia).
- Encoding Specification. A Specification for Encoding. See Gordian Encoding Specifications.
- Envelope. A communication Specification for a Smart Document that supports the storage, backup, encryption & authentication of data, with explicit support for Merkle-based selective disclosure.
- Functional Partition. The philosophy of separating different functions as different parts of an interoperable ecosystem, and also dividing data up into different locations, all to improve Resilience. This is done with Partitions and could include Airgaps or Torgaps.
- Gordian Architecture. A suggested design for a data-asset ecosystem using The Gordian System. It incudes Macro-Architecture, Data Formats, Specifications, and UX Designs. See Gordian Architecture Overview.
- Gordian Macro-Architecture. The interoperable design of a system of Services, applications, and hardware devices that builds upon the Gordian Principles. The macro-architectural is built upon a foundational idea of Functional Partition. Part of teh Gordian System. See Gordian Macro-Architecture Overview.
- Gordian Principles. Four fundamental precepts at the heart of the Gordian System: Independence, Privacy, Resilience, and Openness. See Gordian Principles Overview (Above).
- Independence. The ability to work in a self-sovereign way without centralization. A Gordian Principle.
- Privacy. Protection of personal data and usage against correlation and censorship. A Gordian Principle.
- Resilience. The ability to prevent loss of assets or data, including resilience against theft and resilience against accidental loss. A Gordian Principle.
- Openness. Interoperability of systems and easy portability of data. A Gordian Principle.
- Gordian System. An overall design for a data ecosystem that includes Architecture, Reference Apps, Libraries, and Specifications that are intended to support the Gordian Principles. See Gordian System Overview (This Page).
- Lifehash. A UX Design that creates a visual hash as part of an OIB to allow for visual identification of data. See Lifehash.info.
- Microservice. A Service that provides a capability which is very specific and/or infrequently used. See Gordian Macro-Architecture Overview.
- Networked. Directly connected to an online network.
- Object Identity Block (OIB). A UX Design for an array of data that can together allow a user to easily and uniquely identify data. Can include a Lifehash. See Digests for Digital Objects Paper.
- Partition. A division between two or more Services. A partition could be as simple as ensuring those Services are on different machines, but can also include an Airgap or Torgap.
- Progressive Trust. The concept of gradually building trust over time. See Musings of a Trust Architect: Progressive Trust.
- Quick Connect. A UX Design for a URI or QR Code that can be used to securely connect together two devices that are separated by a Partition. See Quick Connect API.
- Quick Response (QR) Code. An Encoding Specification that represents data in a graphical format. URs are built to allow for efficient encoding as a QR Code. With them, Gordian Animated QRs can support animation of larger data sets using foundation codes. See QR Code (Wikipedia) & UR Spec
- Reference App. An application that shows an example of the usage of a Specification, usually built with a Reference Library. Gordian Reference Apps are part of the Gordian System. See Gordian Reference Apps.
- Reference Library. A library that provides an API for using a Specification. Gordian Reference Libraries are part of the Gordian System. See Gordian Reference Libraries.
- Service. An application providing a specific capability as part of the Functional Partition of a digital-asset ecosystem. Includes Microservices.
- Share. A fraction of a seed or a key created by an algorithm such as Shamir's Secret Sharing or VSS. Intended to improve Resilience of data. See UR Definition for SSKR.
- Sharding. The process of creating Shares from seeds or keys. See UR Definition for SSKR.
- SmartCustody. Documents, instructions, and Specifications intended to improve the Resilience of digital assets, either at the personal or the ecosystem level. See SmartCustody Repo.
- Specification. A specific design intended to support communication, data, or backup Encoding and backup, to ensure the Openness of interoperability, to support UX Design, or to ensure other Gordian Principles. Part of the Gordian System. See Gordian Specifications in Blockchain Commons Research Repo & Crypto Commons Docs.
- Torgap. A Partition between two Services, created to ensure that they are anonymous to each other. See Torgap Repo.
- Uniform Resources (URs). An Encoding Specification of a URI for data. It is created by representating data as CBOR and then encoding it with minimal Bytewords. URs are also built to allow efficient Encoding as QR Codes. URs allow for interoperable communication. See UR Spec.
- Uniform Resource Identifier (URI). A unique sequence for identifying a resource. A UR is a URI. See URI (Wikipedia).
- UX Design. A methodology for presenting data to a user. See Secure UX Designs.
All of these Gordian topics can be discussed in our two Gordian discussion areas:
Gordian Developer Community. For standards and open-source developers who want to talk about interoperable wallet specifications, please use the Discussions area of the Gordian Developer Community repo. This is where you talk about Gordian specifications such as Gordian Envelope, bc-shamir, Sharded Secret Key Reconstruction, and bc-ur as well as the larger Gordian Architecture, its Principles of independence, privacy, resilience, and openness, and its macro-architectural ideas such as functional partition (including airgapping, the original name of this community).
Please see individual projects for current status.
Unless otherwise noted (either in this /README.md or in the file's header comments) the contents of this repository are Copyright © 2020 by Blockchain Commons, LLC, and are licensed under the spdx:BSD-2-Clause Plus Patent License.
In most cases, the authors, copyright, and license for each file reside in header comments in the source code. When it does not, we have attempted to attribute it accurately in the table below.
This table below also establishes provenance (repository of origin, permalink, and commit id) for files included from repositories that are outside of this repo. Contributors to these files are listed in the commit history for each repository, first with changes found in the commit history of this repo, then in changes in the commit history of their repo of their origin.
| File | From | Commit | Authors & Copyright (c) | License |
|---|
The Gordian system is a project of Blockchain Commons. We are proudly 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 the Gordian system 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.
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.
As an open-source, open-development community, Blockchain Commons does not have the resources to provide direct support of our projects. Please consider the discussions area as a locale where you might get answers to questions. Alternatively, please use this repository's issues feature. Unfortunately, we can not make any promises on response time.
If your company requires support to use our projects, please feel free to contact us directly about options. We may be able to offer you a contract for support from one of our contributors, or we might be able to point you to another entity who can offer the contractual support that you need.
The following people directly contributed to this repository. You can add your name here by getting involved. The first step is learning how to contribute from our CONTRIBUTING.md documentation.
| Name | Role | Github | GPG Fingerprint | |
|---|---|---|---|---|
| Christopher Allen | Principal Architect | @ChristopherA | <[email protected]> | FDFE 14A5 4ECB 30FC 5D22 74EF F8D3 6C91 3574 05ED |
We want to keep all of 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. We are unfortunately not able to offer bug bounties at this time.
We do ask that you offer us good faith and use best efforts not to leak information or harm any user, their data, or our developer community. Please give us a reasonable amount of time to fix the issue before you publish it. Do not defraud our users or us in the process of discovery. We promise not to bring legal action against researchers who point out a problem provided they do their best to follow the these guidelines.
Please report suspected security vulnerabilities in private via email to [email protected] (do not use this email for support). Please do NOT create publicly viewable issues for suspected security vulnerabilities.
The following keys may be used to communicate sensitive information to developers:
| Name | Fingerprint |
|---|---|
| Christopher Allen | FDFE 14A5 4ECB 30FC 5D22 74EF F8D3 6C91 3574 05ED |
You can import a key by running the following command with that individual’s fingerprint: gpg --recv-keys "<fingerprint>" Ensure that you put quotes around fingerprints that contain spaces.