A Tutorial Series for eXtensible IDentifiers (XIDs)
XID-Quickstart is a tutorial series for learning about eXtensible IDentifiers (XIDs) using Gordian Envelope technology. This repository contains conceptual documentation and hands-on examples to guide you through creating, understanding, and working with XIDs to support secure, privacy-preserving identity management.
A XID is a decentralized self-sovereign identifier that's built on the concept of data minimization. It allows you to initially share only the minimum necessary information about an identity, and then to slowly disclose additional information through the process of progressive trust.
A XID can be a foundation for attestation frameworks and fair witness models. But it's a transformational technology that goes beyond current designs: it puts privacy and moreso user agency first in a way that the rest of the identity and credentials community generally doesn't, in part due to their failure to adhere to early self-sovereign principles.
If self-sovereign identity and the desire to protect and empower users are important to you, then we hope you'll find XIDs a crucial next step in making ethical, autonomous, self-sovereign identity a reality.
Working with XIDs in this tutorial will give you hands-on experience with how you can maintain a stable identifier even through key rotation, device additions, and recovery scenarios. It will also demonstrate how to cryptographically elide data while maintaining verifiability through signatures.
This repository contains conceptual documentation, hands-on tutorials, and examples used by those tutorials.
- Basic familiarity with command-line tools
- The
envelopeCLI tool, which can be installed from the bc-envelope-cli-rust repository
No prior knowledge of XIDs or Gordian Envelope is required.
- Install the
envelopeCLI tool:cargo install bc-envelope-cli - Clone this repository:
git clone https://github.com/BlockchainCommons/XID-Quickstart.git - Optionally, review the core concepts from
concepts/README.mduntil you're ready to get hands-on - Navigate to the tutorials directory:
cd XID-Quickstart/tutorials - Start with the first tutorial: Creating Your First XID
The concepts guide covers ten foundational concepts for XIDs, organized into:
- Core technical concepts (XIDs, Gordian Envelopes, cryptography)
- Trust and identity frameworks
- Practical implementation guidance
The guide includes a visual concept map and multiple learning paths.
The tutorials provide practical experience with XIDs:
- Creating Your First XID - Create a pseudonymous identity
- Understanding XID Structure - Internal structure and components
- Self-Attestation with XIDs - Make verifiable claims about yourself
- Peer Endorsement with XIDs - Third-party verification methods
- Key Management with XIDs - Key rotation and recovery strategies
See also the concept map and Learning Path for alternative ways to navigate these materials.
The examples directory contains complete scripts implementing the functionality covered in each tutorial. These scripts can be used to see the full implementation or as a reference when working through the tutorials.
Fundamentally, Blockchain Commons' current work with XIDs is experimental. This is more a sandbox for play with XIDs than a proper tutorial, we're just sharing what our play looks like in case you want to play with XIDs yourself.
But please be aware, XIDs are in an early development stage, and our experiments may not be the best way to do things. It's especially important to note that the methodologies that we're working with here have not been security tested. What does it really mean to have an elision-first philosophy? What are the ramifications of including, then eliding private keys? Is the current XID structure the best one from a security point of view?
These are the type of questions we're asking here, and indeed we've refined and revisited some of our answers as we iterated these documents.
We welcome your experiments and your feedback (as issues, PRs, or in direct conversation), but we do not yet suggest using this work in any type of deployed system.
These tutorials are currently in an experimental state. While usable for learning purposes, the underlying technologies and APIs may change significantly as development continues.
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.
Originally developed by Christopher Allen. Maintained by the Blockchain Commons team.
The Gordian Principles describe the requirements for our Gordian-compliant reference apps, including:
- Independence: DIDs and keys must remain in users' control
- Privacy: Tools must not share data without explicit permission
- Resilience: Solutions must be able to recover from failures
- Openness: Open-source code base and development
XIDs build on these principles by providing a stable identity that remains under your control, even as your cryptographic keys change over time.
This tutorial content is licensed under a Creative Commons Attribution 4.0 International License with script examples in BSD-2-Clause Plus Patent License.
These tutorials are 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 these tutorials and other projects, please consider becoming a Patron of Blockchain Commons through ongoing monthly patronage as a GitHub Sponsor.