Skip to main content

clm_rust_core/layer4/
payment.rs

1//! Payment PCard — Multi-Rail Abstraction Engine
2//! Polymorphic payment processing across Stripe, QRIS, Indonesian Banks, and Cryptocurrency On-Chain.
3
4use crate::layer0::vocabulary::{HANDLE_MCARD_PAYMENT_INVOICE, HANDLE_MCARD_PAYMENT_RAIL, HANDLE_MCARD_PAYMENT_RECEIPT, HASH_PREFIX_SHA256};
5use rand::RngCore;
6use serde::{Deserialize, Serialize};
7use std::path::{Path, PathBuf};
8use rusqlite::Connection;
9
10#[derive(Debug, Clone, Serialize, Deserialize)]
11pub struct PaymentRailRecord {
12    pub rail_id: String,
13    pub rail_type: String,
14    pub handle: String,
15    pub content_hash: String,
16}
17
18#[derive(Debug, Clone, Serialize, Deserialize)]
19pub struct PaymentInvoiceRecord {
20    pub invoice_id: String,
21    pub handle: String,
22    pub buyer_did: String,
23    pub merchant_did: String,
24    pub amount: f64,
25    pub currency: String,
26    pub content_hash: String,
27}
28
29#[derive(Debug, Clone, Serialize, Deserialize)]
30pub struct PaymentReceiptRecord {
31    pub tx_id: String,
32    pub handle: String,
33    pub invoice_id: String,
34    pub invoice_hash: String,
35    pub buyer_did: String,
36    pub merchant_did: String,
37    pub rail_id: String,
38    pub rail_type: String,
39    pub amount: f64,
40    pub currency: String,
41    pub status: String,
42    pub content_hash: String,
43}
44
45fn resolve_db_path(db_name_or_path: &str, clm_root: Option<&str>) -> PathBuf {
46    let p = Path::new(db_name_or_path);
47    if p.is_absolute() || db_name_or_path.contains('/') || db_name_or_path.ends_with(".db") {
48        p.to_path_buf()
49    } else {
50        let root = clm_root.map(PathBuf::from).unwrap_or_else(|| {
51            crate::layer0::environment::var(crate::layer0::vocabulary_env::ENV_CLM_ROOT).map(PathBuf::from).unwrap_or_else(|_| PathBuf::from("."))
52        });
53        root.join("db").join(db_name_or_path)
54    }
55}
56
57fn init_db_tables(conn: &Connection) -> Result<(), String> {
58    let _ = conn.busy_timeout(std::time::Duration::from_millis(u64::from(crate::layer0::runtime_contract::SQLITE_BUSY_TIMEOUT_MS)));
59    conn.execute_batch(crate::layer0::runtime_contract::SQLITE_DDL_V3_1).map_err(|e| e.to_string())?;
60
61    // Idempotent migration from legacy `hash` column
62    let has_hash: bool = conn
63        .query_row(
64            "SELECT count(*) > 0 FROM pragma_table_info('handle_registry') WHERE name = 'hash'",
65            [],
66            |r| r.get(0),
67        )
68        .unwrap_or(false);
69    if has_hash {
70        let has_curr: bool = conn
71            .query_row(
72                "SELECT count(*) > 0 FROM pragma_table_info('handle_registry') WHERE name = 'current_hash'",
73                [],
74                |r| r.get(0),
75            )
76            .unwrap_or(false);
77        if !has_curr {
78            let _ = conn.execute_batch("ALTER TABLE handle_registry RENAME COLUMN hash TO current_hash;");
79        }
80    }
81    Ok(())
82}
83
84/// Registers a payment rail configuration under `mcard:payment/rail/{rail_id}`.
85pub fn register_payment_rail(
86    db_name_or_path: &str,
87    clm_root: Option<&str>,
88    rail_id: &str,
89    rail_type: &str,
90    _config_json: Option<&str>,
91) -> Result<PaymentRailRecord, String> {
92    let handle = format!("{HANDLE_MCARD_PAYMENT_RAIL}{}", rail_id);
93    let db_path = resolve_db_path(db_name_or_path, clm_root);
94    if let Some(parent) = db_path.parent() {
95        let _ = std::fs::create_dir_all(parent);
96    }
97    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
98    init_db_tables(&conn)?;
99
100    let content_json = serde_json::json!({
101        "rail_id": rail_id,
102        "rail_type": rail_type,
103        "status": "active",
104    }).to_string();
105
106    let content_hash = format!("{HASH_PREFIX_SHA256}{:x}", sha2::Sha256::digest(content_json.as_bytes()));
107
108    crate::layer2::record_store::insert_new_content(&conn, &content_hash, content_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
109
110    let now = chrono::Utc::now().to_rfc3339();
111    conn.execute(
112        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
113         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
114        rusqlite::params![handle, content_hash, now],
115    ).map_err(|e| e.to_string())?;
116
117    Ok(PaymentRailRecord {
118        rail_id: rail_id.to_string(),
119        rail_type: rail_type.to_string(),
120        handle,
121        content_hash,
122    })
123}
124
125/// Creates a payment invoice under `mcard:payment/invoice/{invoice_id}`.
126pub fn create_payment_invoice(
127    db_name_or_path: &str,
128    clm_root: Option<&str>,
129    buyer_did: &str,
130    merchant_did: &str,
131    amount: f64,
132    currency: &str,
133) -> Result<PaymentInvoiceRecord, String> {
134    let mut inv_bytes = [0u8; 12];
135    rand::thread_rng().fill_bytes(&mut inv_bytes);
136    let invoice_id = format!("inv_{}", hex::encode(inv_bytes));
137    let handle = format!("{HANDLE_MCARD_PAYMENT_INVOICE}{}", invoice_id);
138
139    let db_path = resolve_db_path(db_name_or_path, clm_root);
140    if let Some(parent) = db_path.parent() {
141        let _ = std::fs::create_dir_all(parent);
142    }
143    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
144    init_db_tables(&conn)?;
145
146    let content_json = serde_json::json!({
147        "invoice_id": invoice_id,
148        "buyer_did": buyer_did,
149        "merchant_did": merchant_did,
150        "amount": amount,
151        "currency": currency,
152        "created_at": chrono::Utc::now().to_rfc3339(),
153    }).to_string();
154
155    let content_hash = format!("{HASH_PREFIX_SHA256}{:x}", sha2::Sha256::digest(content_json.as_bytes()));
156
157    crate::layer2::record_store::insert_new_content(&conn, &content_hash, content_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
158
159    let now = chrono::Utc::now().to_rfc3339();
160    conn.execute(
161        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
162         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
163        rusqlite::params![handle, content_hash, now],
164    ).map_err(|e| e.to_string())?;
165
166    Ok(PaymentInvoiceRecord {
167        invoice_id,
168        handle,
169        buyer_did: buyer_did.to_string(),
170        merchant_did: merchant_did.to_string(),
171        amount,
172        currency: currency.to_string(),
173        content_hash,
174    })
175}
176
177/// Processes a payment through a Payment PCard rail and mints a VCard receipt under `mcard:payment/receipt/{tx_id}`.
178pub fn process_payment_pcard(
179    db_name_or_path: &str,
180    clm_root: Option<&str>,
181    invoice_id: &str,
182    rail_id: &str,
183    _payment_payload: Option<&str>,
184) -> Result<PaymentReceiptRecord, String> {
185    let db_path = resolve_db_path(db_name_or_path, clm_root);
186    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
187    init_db_tables(&conn)?;
188
189    let inv_handle = format!("{HANDLE_MCARD_PAYMENT_INVOICE}{}", invoice_id);
190    let record = crate::layer2::record_store::read_handle_record(&conn, &inv_handle)
191        .map_err(|error| error.to_string())?.ok_or("invoice is missing")?;
192    let inv_hash = record.hash;
193    let inv_content = String::from_utf8(record.content).map_err(|error| error.to_string())?;
194
195    let inv_val: serde_json::Value = serde_json::from_str(&inv_content).map_err(|e| e.to_string())?;
196    let buyer_did = inv_val.get("buyer_did").and_then(|x| x.as_str()).unwrap_or(crate::layer0::vocabulary_identities::DID_KEY_UNKNOWN);
197    let merchant_did = inv_val.get("merchant_did").and_then(|x| x.as_str()).unwrap_or(crate::layer0::vocabulary_identities::DID_KEY_UNKNOWN);
198    let amount = inv_val.get("amount").and_then(|x| x.as_f64()).unwrap_or(0.0);
199    let currency = inv_val.get("currency").and_then(|x| x.as_str()).unwrap_or("USD");
200
201    let rail_handle = format!("{HANDLE_MCARD_PAYMENT_RAIL}{}", rail_id);
202    let rail_type = crate::layer2::record_store::read_handle_text(&conn, &rail_handle)
203        .map_err(|error| error.to_string())?.map(|content| {
204            let value: serde_json::Value = serde_json::from_str(&content).unwrap_or_default();
205            value.get("rail_type").and_then(|value| value.as_str()).unwrap_or(rail_id).to_string()
206        }).unwrap_or_else(|| rail_id.to_string());
207
208    let mut tx_bytes = [0u8; 16];
209    rand::thread_rng().fill_bytes(&mut tx_bytes);
210    let tx_id = format!("tx_{}", hex::encode(tx_bytes));
211    let handle = format!("{HANDLE_MCARD_PAYMENT_RECEIPT}{}", tx_id);
212
213    let receipt_json = serde_json::json!({
214        "tx_id": tx_id,
215        "invoice_id": invoice_id,
216        "invoice_hash": inv_hash,
217        "buyer_did": buyer_did,
218        "merchant_did": merchant_did,
219        "rail_id": rail_id,
220        "rail_type": rail_type,
221        "amount": amount,
222        "currency": currency,
223        "status": "settled",
224        "timestamp": chrono::Utc::now().to_rfc3339(),
225    }).to_string();
226
227    let content_hash = format!("{HASH_PREFIX_SHA256}{:x}", sha2::Sha256::digest(receipt_json.as_bytes()));
228
229    crate::layer2::record_store::insert_new_content(&conn, &content_hash, receipt_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
230
231    let now = chrono::Utc::now().to_rfc3339();
232    conn.execute(
233        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
234         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
235        rusqlite::params![handle, content_hash, now],
236    ).map_err(|e| e.to_string())?;
237
238    Ok(PaymentReceiptRecord {
239        tx_id,
240        handle,
241        invoice_id: invoice_id.to_string(),
242        invoice_hash: inv_hash,
243        buyer_did: buyer_did.to_string(),
244        merchant_did: merchant_did.to_string(),
245        rail_id: rail_id.to_string(),
246        rail_type,
247        amount,
248        currency: currency.to_string(),
249        status: "settled".to_string(),
250        content_hash,
251    })
252}
253
254/// Verifies if a payment receipt is valid, immutable, and settled in SQLite.
255pub fn verify_payment_receipt(
256    db_name_or_path: &str,
257    clm_root: Option<&str>,
258    tx_id: &str,
259) -> Result<bool, String> {
260    let handle = format!("{HANDLE_MCARD_PAYMENT_RECEIPT}{}", tx_id);
261    let db_path = resolve_db_path(db_name_or_path, clm_root);
262
263    if !db_path.exists() {
264        return Ok(false);
265    }
266
267    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
268    let Some(content) = crate::layer2::record_store::read_handle_text(&conn, handle.as_ref())
269        .map_err(|error| error.to_string())? else { return Ok(false); };
270
271    let v: serde_json::Value = serde_json::from_str(&content).map_err(|e| e.to_string())?;
272    let status = v.get("status").and_then(|x| x.as_str()).unwrap_or("");
273    let inv_hash = v.get("invoice_hash").and_then(|x| x.as_str()).unwrap_or("");
274
275    Ok(status == "settled" && !inv_hash.is_empty())
276}
277
278use sha2::Digest;
279
280// ── Unit Tests ─────────────────────────────────────────────────────────────────
281
282#[cfg(test)]
283mod tests {
284    use super::*;
285
286    #[test]
287    fn test_multi_rail_payment_flow() {
288        let tmp_db = std::env::temp_dir().join("clm_test_payment_flow.db");
289        let _ = std::fs::remove_file(&tmp_db);
290        let db_str = tmp_db.to_str().unwrap();
291
292        // 1. Register rails
293        let stripe = register_payment_rail(db_str, None, "stripe_global", "stripe", None).unwrap();
294        assert_eq!(stripe.handle, "mcard:payment/rail/stripe_global");
295
296        let qris = register_payment_rail(db_str, None, "qris_indo", "qris", None).unwrap();
297        assert_eq!(qris.handle, "mcard:payment/rail/qris_indo");
298
299        // 2. Create invoice
300        let buyer = "did:key:z6MkBuyer123";
301        let merchant = "did:key:z6MkMerchant456";
302        let inv = create_payment_invoice(db_str, None, buyer, merchant, 250.0, "USD").unwrap();
303        assert!(inv.handle.starts_with("mcard:payment/invoice/inv_"));
304
305        // 3. Process payment
306        let receipt = process_payment_pcard(db_str, None, &inv.invoice_id, "stripe_global", None).unwrap();
307        assert!(receipt.handle.starts_with("mcard:payment/receipt/tx_"));
308        assert_eq!(receipt.status, "settled");
309
310        // 4. Verify receipt
311        let is_valid = verify_payment_receipt(db_str, None, &receipt.tx_id).unwrap();
312        assert!(is_valid);
313
314        let _ = std::fs::remove_file(&tmp_db);
315    }
316}