Skip to main content

qualia_core_db/did_qi/
utxo.rs

1//! Bitcoin-family UTXO attestation for Qualia Identifier documents (spec §17).
2//!
3//! Parses OP_RETURN commitments from **caller-supplied** transaction bytes.
4//! Live: `OP_RETURN 0x23 0x51 0x49 0x01 || unsignedDigest`.
5//! Tombstone: `OP_RETURN 0x23 0x51 0x49 0xFF || 32 zero octets`.
6//! No Chronik, no node, no network. Chain id is CAIP-2 `bip122:<32-hex>`.
7
8use super::document::{sha256_32, QiDocument};
9use super::id::DidQi;
10use super::method::{load_canonical_digest, read};
11use super::{QiError, QiStore};
12
13pub const OP_RETURN: u8 = 0x6a;
14pub const QI_MAGIC: [u8; 2] = [0x51, 0x49];
15pub const LIVE_KIND: u8 = 0x01;
16/// Registered tombstone kind in the 35-byte OP_RETURN push (`0xFF`).
17pub const TOMBSTONE_OPCODE: u8 = 0xFF;
18pub const MAX_CAIP2: usize = 72;
19
20/// Bitcoin mainnet genesis, first 16 bytes of block hash (CAIP-2 `bip122`).
21pub const CONSTITUTION_MAINNET: &[u8] = b"bip122:000000000019d6689c085ae165831e93";
22/// Bitcoin testnet3 genesis identifier (distinct ledger, same DID).
23pub const CONSTITUTION_TESTNET: &[u8] = b"bip122:000000000933ea01ad0ee984209779ba";
24
25/// True when `chain` is an admitted BIP-122 constitution identifier (spec §17.1).
26pub fn chain_admitted(chain: &[u8]) -> bool {
27    chain == CONSTITUTION_MAINNET || chain == CONSTITUTION_TESTNET
28}
29
30/// Parse then admit. Well-formed but unlisted `bip122:` ids are `unsupported_chain`.
31pub fn admit_chain(chain: &[u8]) -> Result<ChainId, QiError> {
32    let id = parse_chain_id(chain)?;
33    if !chain_admitted(id.as_bytes()) {
34        return Err(QiError::UnsupportedChain);
35    }
36    Ok(id)
37}
38
39/// Bitcoin RPC display encoding of a 32-byte SHA-256d digest (byte-reversed hex).
40pub fn txid_display(digest: &[u8; 32]) -> [u8; 64] {
41    let mut out = [0u8; 64];
42    const HEX: &[u8; 16] = b"0123456789abcdef";
43    let mut i = 0;
44    while i < 32 {
45        let b = digest[31 - i];
46        out[i * 2] = HEX[(b >> 4) as usize];
47        out[i * 2 + 1] = HEX[(b & 0x0f) as usize];
48        i += 1;
49    }
50    out
51}
52
53#[derive(Clone, Copy, Debug, PartialEq, Eq)]
54pub struct ChainId {
55    pub bytes: [u8; MAX_CAIP2],
56    pub len: u8,
57}
58
59impl ChainId {
60    /// Raw chain-id bytes.
61    pub fn as_bytes(&self) -> &[u8] {
62        &self.bytes[..self.len as usize]
63    }
64
65    /// `true` when this is a BIP-122 chain id.
66    pub fn is_bip122(&self) -> bool {
67        self.as_bytes().starts_with(b"bip122:")
68    }
69}
70
71/// Parses a chain id; `QiError` on malformed input.
72pub fn parse_chain_id(s: &[u8]) -> Result<ChainId, QiError> {
73    if s.len() < 8 || s.len() > MAX_CAIP2 || !s.starts_with(b"bip122:") {
74        return Err(QiError::MalformedChainId);
75    }
76    let hex = &s[7..];
77    if hex.len() != 32 && hex.len() != 64 {
78        return Err(QiError::MalformedChainId);
79    }
80    let mut i = 0;
81    while i < hex.len() {
82        match hex[i] {
83            b'0'..=b'9' | b'a'..=b'f' | b'A'..=b'F' => {}
84            _ => return Err(QiError::MalformedChainId),
85        }
86        i += 1;
87    }
88    let mut id = ChainId {
89        bytes: [0u8; MAX_CAIP2],
90        len: s.len() as u8,
91    };
92    id.bytes[..s.len()].copy_from_slice(s);
93    Ok(id)
94}
95
96#[derive(Clone, Copy, Debug, PartialEq, Eq)]
97pub struct Outpoint {
98    pub txid: [u8; 32],
99    pub vout: u32,
100}
101
102#[derive(Clone, Copy, Debug, PartialEq, Eq)]
103pub struct UtxoCommitment {
104    pub outpoint: Outpoint,
105    pub digest: [u8; 32],
106    pub tombstone: bool,
107}
108
109fn compact_size(tx: &[u8], i: &mut usize) -> Result<u64, QiError> {
110    if *i >= tx.len() {
111        return Err(QiError::MalformedTx);
112    }
113    let first = tx[*i];
114    *i += 1;
115    match first {
116        0xfd => read_int(tx, i, 2),
117        0xfe => read_int(tx, i, 4),
118        0xff => read_int(tx, i, 8),
119        n => Ok(n as u64),
120    }
121}
122
123fn read_int(tx: &[u8], i: &mut usize, n: usize) -> Result<u64, QiError> {
124    if *i + n > tx.len() {
125        return Err(QiError::MalformedTx);
126    }
127    let mut v = 0u64;
128    let mut k = 0;
129    while k < n {
130        v |= (tx[*i + k] as u64) << (8 * k);
131        k += 1;
132    }
133    *i += n;
134    Ok(v)
135}
136
137fn skip_bytes(tx: &[u8], i: &mut usize, n: u64) -> Result<(), QiError> {
138    let n = n as usize;
139    if *i + n > tx.len() {
140        return Err(QiError::MalformedTx);
141    }
142    *i += n;
143    Ok(())
144}
145
146fn parse_qi_op_return(script: &[u8]) -> Result<Option<([u8; 32], bool)>, QiError> {
147    if script.len() != 37 || script[0] != OP_RETURN || script[1] != 0x23 {
148        return Ok(None);
149    }
150    if script[2] != QI_MAGIC[0] || script[3] != QI_MAGIC[1] {
151        return Ok(None);
152    }
153    let mut digest = [0u8; 32];
154    digest.copy_from_slice(&script[5..37]);
155    match script[4] {
156        LIVE_KIND => Ok(Some((digest, false))),
157        TOMBSTONE_OPCODE => Ok(Some((digest, true))),
158        _ => Err(QiError::MalformedTx),
159    }
160}
161
162fn dsha256(bytes: &[u8]) -> [u8; 32] {
163    sha256_32(&sha256_32(bytes))
164}
165
166/// Extracts the UTXO commitment from a transaction's OP_RETURN.
167pub fn extract_op_return(tx: &[u8]) -> Result<UtxoCommitment, QiError> {
168    if tx.len() < 10 {
169        return Err(QiError::MalformedTx);
170    }
171    let mut i = 4;
172    let mut segwit = false;
173    if tx.len() > 6 && tx[4] == 0x00 && tx[5] == 0x01 {
174        segwit = true;
175        i = 6;
176    }
177    let vin = compact_size(tx, &mut i)?;
178    if vin == 0 || vin > 16 {
179        return Err(QiError::MalformedTx);
180    }
181    let mut n_in = 0u64;
182    while n_in < vin {
183        skip_bytes(tx, &mut i, 32)?;
184        let _ = read_int(tx, &mut i, 4)?;
185        let script_len = compact_size(tx, &mut i)?;
186        skip_bytes(tx, &mut i, script_len)?;
187        let _ = read_int(tx, &mut i, 4)?;
188        n_in += 1;
189    }
190    let vout_count = compact_size(tx, &mut i)?;
191    if vout_count == 0 || vout_count > 16 {
192        return Err(QiError::MalformedTx);
193    }
194    let mut found: Option<(u32, [u8; 32], bool)> = None;
195    let mut v = 0u32;
196    while v < vout_count as u32 {
197        let _value = read_int(tx, &mut i, 8)?;
198        let script_len = compact_size(tx, &mut i)? as usize;
199        if i + script_len > tx.len() {
200            return Err(QiError::MalformedTx);
201        }
202        let script = &tx[i..i + script_len];
203        i += script_len;
204        if let Some((digest, tombstone)) = parse_qi_op_return(script)? {
205            if found.is_some() {
206                return Err(QiError::MalformedTx);
207            }
208            found = Some((v, digest, tombstone));
209        }
210        v += 1;
211    }
212    if segwit {
213        let mut n_in = 0u64;
214        while n_in < vin {
215            let items = compact_size(tx, &mut i)?;
216            let mut k = 0u64;
217            while k < items {
218                let n = compact_size(tx, &mut i)?;
219                skip_bytes(tx, &mut i, n)?;
220                k += 1;
221            }
222            n_in += 1;
223        }
224    }
225    if i + 4 != tx.len() {
226        return Err(QiError::MalformedTx);
227    }
228    let (vout, digest, tombstone) = found.ok_or(QiError::MalformedTx)?;
229    Ok(UtxoCommitment {
230        outpoint: Outpoint {
231            txid: dsha256(tx),
232            vout,
233        },
234        digest,
235        tombstone,
236    })
237}
238
239/// Verifies a commitment digest in `tx`; returns the outpoint.
240pub fn verify_commitment(tx: &[u8], digest: &[u8; 32]) -> Result<Outpoint, QiError> {
241    let c = extract_op_return(tx)?;
242    if c.tombstone || &c.digest != digest {
243        return Err(QiError::CommitmentMismatch);
244    }
245    Ok(c.outpoint)
246}
247
248/// Encodes a commitment transaction.
249pub fn encode_commitment_tx(
250    prev_txid: &[u8; 32],
251    prev_vout: u32,
252    digest: &[u8; 32],
253    tombstone: bool,
254    out: &mut [u8],
255) -> Result<usize, QiError> {
256    let script_len = 37usize;
257    let need = 4 + 1 + 32 + 4 + 1 + 4 + 1 + 8 + 1 + script_len + 4;
258    if out.len() < need {
259        return Err(QiError::BufferTooSmall);
260    }
261    let mut i = 0;
262    out[i..i + 4].copy_from_slice(&1u32.to_le_bytes());
263    i += 4;
264    out[i] = 1;
265    i += 1;
266    out[i..i + 32].copy_from_slice(prev_txid);
267    i += 32;
268    out[i..i + 4].copy_from_slice(&prev_vout.to_le_bytes());
269    i += 4;
270    out[i] = 0;
271    i += 1;
272    out[i..i + 4].copy_from_slice(&0xffff_ffffu32.to_le_bytes());
273    i += 4;
274    out[i] = 1;
275    i += 1;
276    out[i..i + 8].copy_from_slice(&0u64.to_le_bytes());
277    i += 8;
278    out[i] = script_len as u8;
279    i += 1;
280    out[i] = OP_RETURN;
281    i += 1;
282    out[i] = 0x23;
283    i += 1;
284    out[i] = QI_MAGIC[0];
285    i += 1;
286    out[i] = QI_MAGIC[1];
287    i += 1;
288    if tombstone {
289        out[i] = TOMBSTONE_OPCODE;
290        i += 1;
291        out[i..i + 32].copy_from_slice(&[0u8; 32]);
292        i += 32;
293    } else {
294        out[i] = LIVE_KIND;
295        i += 1;
296        out[i..i + 32].copy_from_slice(digest);
297        i += 32;
298    }
299    out[i..i + 4].copy_from_slice(&0u32.to_le_bytes());
300    i += 4;
301    Ok(i)
302}
303
304/// Applies a UTXO attestation into store `S`.
305pub fn apply_utxo_attestation<S: QiStore>(
306    store: &mut S,
307    id: &DidQi,
308    chain: &[u8],
309    tx: &[u8],
310) -> Result<u64, QiError> {
311    admit_chain(chain)?;
312    let (digest, generation) = load_canonical_digest(store, id)?;
313    let c = extract_op_return(tx)?;
314    if c.tombstone {
315        let mut current = QiDocument::empty();
316        read(store, id, &mut current)?;
317        if !current.deactivated {
318            return Err(QiError::TombstoneRequiresDeactivate);
319        }
320        return Ok(generation);
321    }
322    if c.digest != digest {
323        return Err(QiError::CommitmentMismatch);
324    }
325    Ok(generation)
326}
327
328#[cfg(test)]
329mod tests {
330    use super::super::document::QiDocument;
331    use super::super::git_object::GitObjectStore;
332    use super::super::method::{create, deactivate, read, update};
333    use super::super::service::{CscpMailbox, Disclosure};
334    use super::*;
335    use ed25519_dalek::SigningKey;
336
337    fn sk() -> [u8; 32] {
338        [5u8; 32]
339    }
340
341    fn sample_doc() -> QiDocument {
342        let pk = SigningKey::from_bytes(&sk()).verifying_key().to_bytes();
343        let mut doc = QiDocument::empty();
344        doc.services[0] = CscpMailbox::mailbox(pk, Disclosure::ApprovedRelaysOnly);
345        doc.service_count = 1;
346        doc
347    }
348
349    fn tx_for(digest: &[u8; 32], tombstone: bool) -> ([u8; 160], usize) {
350        let mut tx = [0u8; 160];
351        let n = encode_commitment_tx(&[0x11; 32], 0, digest, tombstone, &mut tx).unwrap();
352        (tx, n)
353    }
354
355    #[test]
356    fn op_return_commitment_matches_wrong_fails_tombstone_deactivates() {
357        let mut store = GitObjectStore::new();
358        let id = create(&mut store, &sk(), &sample_doc()).unwrap();
359        let (digest, gen) = load_canonical_digest(&store, &id).unwrap();
360        assert_eq!(gen, 0);
361
362        let (tx, n) = tx_for(&digest, false);
363        let outpoint = verify_commitment(&tx[..n], &digest).unwrap();
364        assert_eq!(outpoint.vout, 0);
365        let extracted = extract_op_return(&tx[..n]).unwrap();
366        assert_eq!(extracted.digest, digest);
367        assert!(!extracted.tombstone);
368        assert_eq!(
369            apply_utxo_attestation(&mut store, &id, CONSTITUTION_MAINNET, &tx[..n]).unwrap(),
370            0
371        );
372
373        let mut wrong = digest;
374        wrong[0] ^= 0xff;
375        let (bad, bn) = tx_for(&wrong, false);
376        assert_eq!(
377            verify_commitment(&bad[..bn], &digest),
378            Err(QiError::CommitmentMismatch)
379        );
380        assert_eq!(
381            apply_utxo_attestation(&mut store, &id, CONSTITUTION_MAINNET, &bad[..bn]),
382            Err(QiError::CommitmentMismatch)
383        );
384
385        let (tomb, tn) = tx_for(&digest, true);
386        let t = extract_op_return(&tomb[..tn]).unwrap();
387        assert!(t.tombstone);
388        assert_eq!(
389            apply_utxo_attestation(&mut store, &id, CONSTITUTION_MAINNET, &tomb[..tn]),
390            Err(QiError::TombstoneRequiresDeactivate)
391        );
392        let mut live = QiDocument::empty();
393        read(&store, &id, &mut live).unwrap();
394        assert!(!live.deactivated);
395        assert_eq!(live.service_count, 1);
396
397        deactivate(&mut store, &sk(), &id).unwrap();
398        let (digest2, gen2) = load_canonical_digest(&store, &id).unwrap();
399        assert_eq!(gen2, 1);
400        let (tomb2, tn2) = tx_for(&digest2, true);
401        let g =
402            apply_utxo_attestation(&mut store, &id, CONSTITUTION_MAINNET, &tomb2[..tn2]).unwrap();
403        assert_eq!(g, 1);
404        let mut out = QiDocument::empty();
405        read(&store, &id, &mut out).unwrap();
406        assert!(out.deactivated);
407        assert_eq!(out.service_count, 0);
408        assert_eq!(
409            update(&mut store, &sk(), &id, &sample_doc()),
410            Err(QiError::Deactivated)
411        );
412    }
413
414    #[test]
415    fn caip2_bip122_parses_bitcoin_family() {
416        let s = b"bip122:000000000019d6689c085ae165831e93";
417        let id = parse_chain_id(s).unwrap();
418        assert!(id.is_bip122());
419        assert_eq!(parse_chain_id(b"eip155:1"), Err(QiError::MalformedChainId));
420        assert_eq!(parse_chain_id(b"did:btc:x"), Err(QiError::MalformedChainId));
421        assert!(chain_admitted(CONSTITUTION_MAINNET));
422        assert!(chain_admitted(CONSTITUTION_TESTNET));
423        assert_eq!(
424            admit_chain(b"bip122:ffffffffffffffffffffffffffffffff"),
425            Err(QiError::UnsupportedChain)
426        );
427        assert_eq!(admit_chain(b"eip155:1"), Err(QiError::MalformedChainId));
428        assert_eq!(QiError::UnsupportedChain.token(), "unsupported_chain");
429    }
430
431    #[test]
432    fn vector1_txid_display_is_byte_reversed() {
433        let hex = b"010000000111111111111111111111111111111111111111111111111111111111111111110000000000ffffffff010000000000000000256a2351490173432eeabe01888f4770654fcd9a85b59605a2b3eb9d82b16b700c17345c674400000000";
434        let mut tx = [0u8; 128];
435        let n = hex.len() / 2;
436        let mut i = 0;
437        while i < n {
438            tx[i] = hex_byte(hex[i * 2], hex[i * 2 + 1]);
439            i += 1;
440        }
441        let c = extract_op_return(&tx[..n]).unwrap();
442        assert_eq!(
443            &txid_display(&c.outpoint.txid)[..],
444            b"e9dfb2471de55f2d1702a5dd1c560a28c4a632640d5f8d0648613b69f6a5a176"
445        );
446        let mut wire = [0u8; 32];
447        let wh = b"76a1a5f6693b6148068d5f0d6432a6c4280a561cdda502172d5fe51d47b2dfe9";
448        i = 0;
449        while i < 32 {
450            wire[i] = hex_byte(wh[i * 2], wh[i * 2 + 1]);
451            i += 1;
452        }
453        assert_eq!(c.outpoint.txid, wire);
454    }
455
456    #[test]
457    fn spec_vector_live_tx_parses() {
458        // Vector 1 raw tx (spec §20.1); unsignedDigest of that published document.
459        let hex = b"010000000111111111111111111111111111111111111111111111111111111111111111110000000000ffffffff010000000000000000256a2351490173432eeabe01888f4770654fcd9a85b59605a2b3eb9d82b16b700c17345c674400000000";
460        let mut tx = [0u8; 128];
461        let n = hex.len() / 2;
462        let mut i = 0;
463        while i < n {
464            tx[i] = hex_byte(hex[i * 2], hex[i * 2 + 1]);
465            i += 1;
466        }
467        let c = extract_op_return(&tx[..n]).unwrap();
468        assert!(!c.tombstone);
469        assert_eq!(c.outpoint.vout, 0);
470        assert_eq!(&c.digest[..4], &[0x73, 0x43, 0x2e, 0xea]);
471    }
472
473    fn hex_byte(a: u8, b: u8) -> u8 {
474        fn n(c: u8) -> u8 {
475            match c {
476                b'0'..=b'9' => c - b'0',
477                b'a'..=b'f' => c - b'a' + 10,
478                _ => 0,
479            }
480        }
481        (n(a) << 4) | n(b)
482    }
483}