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.
Whether you're a developer, security researcher, or digital identity enthusiast, these tutorials provide the tools to understand XIDs and their applications in secure, privacy-preserving identity management.
- The
envelopeCLI tool, which can be installed from the bc-envelope-cli-rust repository - Basic familiarity with command-line tools
- No prior knowledge of XIDs or Gordian Envelope is required
This repository contains both conceptual documentation and hands-on tutorials.
Start by exploring the theoretical foundations:
- XID Fundamentals - Understanding the basics of eXtensible IDentifiers
- Gordian Envelope Basics - The data structure that powers XIDs
- Data Minimization Principles - How to control information disclosure
- Elision Cryptography - Techniques for selective disclosure
- Fair Witness Approach - Making trustworthy assertions
- Pseudonymous Trust Building - Building trust without revealing identity
- Public Participation Profiles - Using XIDs in community contexts
- Key Management Essentials - Securing and managing cryptographic keys
Then follow these tutorials for practical experience:
- Creating Your First XID - Learn to create a basic pseudonymous identity
- Understanding XID Structure - Explore how XIDs are structured
- Self-Attestation with XIDs - Create structured self-claims with verifiable evidence
- Peer Endorsement with XIDs - Build a network of trust through independent verification
- Key Management with XIDs - Master secure key management for XIDs
See the Learning Path for a recommended approach to 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.
Get started with XIDs by:
- Install the
envelopeCLI tool:cargo install envelope-cli - Clone this repository:
git clone https://github.com/BlockchainCommons/XID-Quickstart.git - Navigate to the tutorials directory:
cd XID-Quickstart/tutorials - Start with the first tutorial: Creating Your First XID
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 ellision-first philosophy? What are the raimifications 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 converstation), but we do not yet suggest using this work in any type of deployed system.
The XID is a decentralized self-sovereign identifier that's built on the concept of data minimization. It allows you to 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. 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.
Working with XIDs can give you hands-on experience with how you can cryptographically elide data while maintaining verifiability through signatures. More than that, it can demonstrate how to maintain a stable identifier even through key rotation, device additions, and recovery scenarios.
If self-sovereign identity and the desire to protect and empower users are improtant to you, then we hope you'll find XIDs an important next step in making ethical, autonomous, self-soveriegn identity a reality.
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. You can also support Blockchain Commons with bitcoins at our BTCPay Server.