Skip to main content

qualia_core_db/did_qi/
mod.rs

1//! Qualia Identifier (`did:qi`) runtime for ☉ Human-Centric Internet instruments.
2//!
3//! This is a DID-Core shaped method runtime: create / read / update / deactivate.
4//! It is **not** `did:q42` (Q42 Resource Coordinate), **not** `did:hcai`, and **not**
5//! Gate B. Git objects are in-process; UTXO attestation verifies caller-supplied
6//! Bitcoin-family transaction bytes. There is no network, Chronik, DHT, or git daemon.
7//!
8//! Canonical document bytes use QCDE-1 (RFC 8785 profile) in [`document`]. The DID
9//! method-specific-id is multibase Bitcoin base58btc (`z` prefix) of the 32-byte
10//! SHA-256 genesis payload digest.
11
12mod document;
13mod document_decode;
14mod git_object;
15mod id;
16mod mailbox_bind;
17mod method;
18mod service;
19mod utxo;
20#[cfg(test)]
21mod vectors;
22
23pub use document::{
24    canonical_digest, encode_canonical, encode_genesis, encode_jsonld_cold, encode_signed,
25    encode_unsigned, genesis_digest, sha256_32, signed_git_object_id, unsigned_digest, AkaEntry,
26    QiDocument, CREATED_UNIX_VECTOR, MAX_AKA, MAX_AKA_LEN, MAX_CANONICAL, MAX_SERVICES, MAX_SIGNED,
27    MAX_UNSIGNED,
28};
29pub use document_decode::{
30    decode_canonical, extract_proof_sig, ingest_unsigned_json, reject_forbidden_locators,
31};
32pub use git_object::{
33    blob_object_id, encode_blob, tag_name, GitObjectStore, GIT_STORE_CAP, MAX_BLOB, MAX_RECORD,
34};
35pub use id::{format_did, parse_did, DidQi, MAX_DID_TEXT};
36pub use mailbox_bind::publish_qi_document;
37pub use method::{create, deactivate, read, read_generation, update};
38pub use service::{
39    check_relay_only, CscpMailbox, Disclosure, LocatorClass, RelayHint, MAX_HINTS, SERVICE_TYPE,
40};
41pub use utxo::{
42    admit_chain, apply_utxo_attestation, chain_admitted, encode_commitment_tx, extract_op_return,
43    parse_chain_id, txid_display, verify_commitment, ChainId, Outpoint, UtxoCommitment,
44    CONSTITUTION_MAINNET, CONSTITUTION_TESTNET, LIVE_KIND, OP_RETURN, QI_MAGIC, TOMBSTONE_OPCODE,
45};
46
47/// DID method name. Bound in prose to the Human-Centric Internet (HCInet).
48pub const METHOD_NAME: &str = "qi";
49
50/// Fail-closed errors. Hot paths return these without allocating.
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub enum QiError {
53    InvalidPrefix,
54    RejectedMethod,
55    MalformedId,
56    BufferTooSmall,
57    Encoding,
58    NotFound,
59    StaleGeneration,
60    Deactivated,
61    BadSignature,
62    InvalidKey,
63    DirectLocatorForbidden,
64    StoreFull,
65    CanonicalTooLarge,
66    CommitmentMismatch,
67    MalformedTx,
68    MalformedDocument,
69    ControllerMismatch,
70    MalformedChainId,
71    TombstoneRequiresDeactivate,
72    UnsupportedChain,
73}
74
75impl QiError {
76    /// Spec §4 ASCII token. Variants without a listed token keep a stable extra name.
77    pub fn token(self) -> &'static str {
78        match self {
79            QiError::InvalidPrefix
80            | QiError::RejectedMethod
81            | QiError::MalformedId
82            | QiError::Encoding
83            | QiError::MalformedDocument => "invalid_did",
84            QiError::NotFound => "not_found",
85            QiError::BadSignature | QiError::InvalidKey | QiError::ControllerMismatch => {
86                "invalid_proof"
87            }
88            QiError::StaleGeneration => "stale_generation",
89            QiError::Deactivated => "deactivated",
90            QiError::DirectLocatorForbidden => "direct_locator_forbidden",
91            QiError::CommitmentMismatch => "utxo_commitment_mismatch",
92            QiError::UnsupportedChain => "unsupported_chain",
93            QiError::CanonicalTooLarge => "document_too_large",
94            QiError::BufferTooSmall | QiError::StoreFull => "buffer_full",
95            QiError::MalformedTx => "malformed_tx",
96            QiError::MalformedChainId => "malformed_chain_id",
97            QiError::TombstoneRequiresDeactivate => "tombstone_requires_deactivate",
98        }
99    }
100}
101
102/// In-process document store. Implementations keep a fixed slot cap.
103pub trait QiStore {
104    /// Stores `payload` for `id` at `generation`.
105    fn put(&mut self, id: &DidQi, generation: u64, payload: &[u8]) -> Result<(), QiError>;
106    /// Reads `id` into `out`.
107    fn get(&self, id: &DidQi, out: &mut [u8]) -> Result<(u64, usize), QiError>;
108}
109
110#[cfg(test)]
111mod tests {
112    use super::*;
113
114    #[test]
115    fn method_name_is_qi_not_q42_or_hcai() {
116        assert_eq!(METHOD_NAME, "qi");
117        assert_ne!(METHOD_NAME, "q42");
118        assert_ne!(METHOD_NAME, "hcai");
119        assert_ne!(METHOD_NAME, "hci");
120    }
121
122    #[test]
123    fn spec_error_tokens_are_stable() {
124        assert_eq!(QiError::MalformedId.token(), "invalid_did");
125        assert_eq!(QiError::RejectedMethod.token(), "invalid_did");
126        assert_eq!(QiError::NotFound.token(), "not_found");
127        assert_eq!(QiError::BadSignature.token(), "invalid_proof");
128        assert_eq!(QiError::StaleGeneration.token(), "stale_generation");
129        assert_eq!(QiError::Deactivated.token(), "deactivated");
130        assert_eq!(
131            QiError::DirectLocatorForbidden.token(),
132            "direct_locator_forbidden"
133        );
134        assert_eq!(
135            QiError::CommitmentMismatch.token(),
136            "utxo_commitment_mismatch"
137        );
138        assert_eq!(QiError::UnsupportedChain.token(), "unsupported_chain");
139        assert_eq!(QiError::CanonicalTooLarge.token(), "document_too_large");
140        assert_eq!(QiError::BufferTooSmall.token(), "buffer_full");
141    }
142}