feat: architecture docs, prometheus metrics, job views, completion ce…

contracts/escrow/src/lib.rs

@@ -356,6 +356,17 @@ pub struct PaymentSplit {
     pub reason: soroban_sdk::String,
 }
 
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CompletionCertificate {
+    pub job_id: u64,
+    pub client: Address,
+    pub freelancer: Address,
+    pub amount: i128,
+    pub completed_at: u64,
+    pub metadata_uri: soroban_sdk::String,
+}
+
 #[contracttype]
 #[derive(Clone)]
 pub enum DataKey {
@@ -423,6 +434,12 @@ pub enum DataKey {
     // ── Payment splits ───────────────────────────────────────────────────────
     PaymentSplitCount(u64),
     PaymentSplit(u64, u32),
+    // ── Job view counter ─────────────────────────────────────────────────────
+    JobViewCount(u64),
+    JobViewDedup(u64, Address),
+    // ── Completion certificates ──────────────────────────────────────────────
+    CertificateCount(Address),
+    Certificate(Address, u64),
 }
 
 #[contracterror]
@@ -957,6 +974,24 @@ impl EscrowContract {
         let key = DataKey::UserCompletedJobs(freelancer.clone());
         env.storage().persistent().set(&key, &(user_count + 1));
         env.storage().persistent().extend_ttl(&key, 10000, 10000);
+
+        let cert_count: u64 = env.storage().persistent().get(&DataKey::CertificateCount(freelancer.clone())).unwrap_or(0);
+        let cert = CompletionCertificate {
+            job_id,
+            client: job.client.clone(),
+            freelancer: freelancer.clone(),
+            amount: job.amount,
+            completed_at: current_ledger(&env),
+            metadata_uri: soroban_sdk::String::from_str(&env, ""),
+        };
+        env.storage().persistent().set(&DataKey::Certificate(freelancer.clone(), cert_count), &cert);
+        env.storage().persistent().extend_ttl(&DataKey::Certificate(freelancer.clone(), cert_count), 10000, 10000);
+        env.storage().persistent().set(&DataKey::CertificateCount(freelancer.clone()), &(cert_count + 1));
+
+        env.events().publish(
+            (soroban_sdk::Symbol::new(&env, "certificate_minted"),),
+            (job_id, freelancer.clone(), cert_count),
+        );
     }
 
     pub fn cancel_job(env: Env, client: Address, job_id: u64) {
@@ -3213,6 +3248,40 @@ impl EscrowContract {
         }
         result
     }
+
+    pub fn record_job_view(e: Env, viewer: Address, job_id: u64) {
+        let dedup_key = DataKey::JobViewDedup(job_id, viewer.clone());
+        if e.storage().temporary().has(&dedup_key) {
+            return;
+        }
+        e.storage().temporary().set(&dedup_key, &true);
+        e.storage().temporary().extend_ttl(&dedup_key, 17_280, 17_280);
+
+        let count_key = DataKey::JobViewCount(job_id);
+        let current: u64 = e.storage().persistent().get(&count_key).unwrap_or(0);
+        e.storage().persistent().set(&count_key, &(current + 1));
+        e.storage().persistent().extend_ttl(&count_key, ACTIVE_JOB_LIFETIME_THRESHOLD, ACTIVE_JOB_BUMP_AMOUNT);
+    }
+
+    pub fn get_job_views(e: Env, job_id: u64) -> u64 {
+        e.storage().persistent().get(&DataKey::JobViewCount(job_id)).unwrap_or(0)
+    }
+
+    pub fn get_certificates(e: Env, freelancer: Address, start: u64, limit: u64) -> Vec<CompletionCertificate> {
+        let total: u64 = e.storage().persistent().get(&DataKey::CertificateCount(freelancer.clone())).unwrap_or(0);
+        let mut result: Vec<CompletionCertificate> = Vec::new(&e);
+        let end = if start + limit > total { total } else { start + limit };
+        for i in start..end {
+            if let Some(cert) = e.storage().persistent().get::<DataKey, CompletionCertificate>(&DataKey::Certificate(freelancer.clone(), i)) {
+                result.push_back(cert);
+            }
+        }
+        result
+    }
+
+    pub fn get_certificate_count(e: Env, freelancer: Address) -> u64 {
+        e.storage().persistent().get(&DataKey::CertificateCount(freelancer)).unwrap_or(0)
+    }
 }
 
 /// Core dispute resolution logic shared by `resolve_dispute` and `batch_resolve_disputes`.

contracts/escrow/src/test.rs

@@ -811,3 +811,113 @@ fn test_post_job_valid_duration_within_bounds() {
     );
     assert_eq!(job_id, 1);
 }
+
+#[test]
+fn test_record_job_view_increments_count() {
+    let env = Env::default();
+    let (_admin, client, freelancer, token, contract_id) = setup_test(&env);
+    let escrow = new_escrow(&env, &contract_id);
+    let desc_hash = BytesN::from_array(&env, &[1u8; 32]);
+    let deadline: u64 = 1000;
+    let amount: i128 = 100_0000000;
+
+    let job_id = escrow.post_job(&client, &amount, &desc_hash, &100u32, &deadline, &token, &dummy_title(&env), &dummy_category(&env));
+    assert_eq!(escrow.get_job_views(&job_id), 0);
+
+    escrow.record_job_view(&freelancer, &job_id);
+    assert_eq!(escrow.get_job_views(&job_id), 1);
+
+    escrow.record_job_view(&client, &job_id);
+    assert_eq!(escrow.get_job_views(&job_id), 2);
+}
+
+#[test]
+fn test_record_job_view_deduplicates_same_viewer() {
+    let env = Env::default();
+    let (_admin, client, freelancer, token, contract_id) = setup_test(&env);
+    let escrow = new_escrow(&env, &contract_id);
+    let desc_hash = BytesN::from_array(&env, &[1u8; 32]);
+    let deadline: u64 = 1000;
+    let amount: i128 = 100_0000000;
+
+    let job_id = escrow.post_job(&client, &amount, &desc_hash, &100u32, &deadline, &token, &dummy_title(&env), &dummy_category(&env));
+
+    escrow.record_job_view(&freelancer, &job_id);
+    escrow.record_job_view(&freelancer, &job_id);
+    escrow.record_job_view(&freelancer, &job_id);
+    assert_eq!(escrow.get_job_views(&job_id), 1);
+}
+
+#[test]
+fn test_completion_certificate_minted_on_approve() {
+    let env = Env::default();
+    let (_admin, client, freelancer, token, contract_id) = setup_test(&env);
+    let escrow = new_escrow(&env, &contract_id);
+    let desc_hash = BytesN::from_array(&env, &[1u8; 32]);
+    let deadline: u64 = 1000;
+    let amount: i128 = 100_0000000;
+
+    assert_eq!(escrow.get_certificate_count(&freelancer), 0);
+
+    let job_id = escrow.post_job(&client, &amount, &desc_hash, &100u32, &deadline, &token, &dummy_title(&env), &dummy_category(&env));
+    escrow.accept_job(&freelancer, &job_id);
+    escrow.submit_work(&freelancer, &job_id);
+    escrow.approve_work(&client, &job_id);
+
+    assert_eq!(escrow.get_certificate_count(&freelancer), 1);
+
+    let certs = escrow.get_certificates(&freelancer, &0u64, &10u64);
+    assert_eq!(certs.len(), 1);
+    let cert = certs.get(0).unwrap();
+    assert_eq!(cert.job_id, job_id);
+    assert_eq!(cert.client, client);
+    assert_eq!(cert.freelancer, freelancer);
+    assert_eq!(cert.amount, amount);
+}
+
+#[test]
+fn test_multiple_certificates_across_jobs() {
+    let env = Env::default();
+    let (_admin, client, freelancer, token, contract_id) = setup_test(&env);
+    let escrow = new_escrow(&env, &contract_id);
+    let desc_hash = BytesN::from_array(&env, &[1u8; 32]);
+    let deadline: u64 = 1000;
+    let amount: i128 = 50_0000000;
+
+    for _ in 0..3 {
+        let job_id = escrow.post_job(&client, &amount, &desc_hash, &100u32, &deadline, &token, &dummy_title(&env), &dummy_category(&env));
+        escrow.accept_job(&freelancer, &job_id);
+        escrow.submit_work(&freelancer, &job_id);
+        escrow.approve_work(&client, &job_id);
+    }
+
+    assert_eq!(escrow.get_certificate_count(&freelancer), 3);
+    let certs = escrow.get_certificates(&freelancer, &0u64, &10u64);
+    assert_eq!(certs.len(), 3);
+}
+
+#[test]
+fn test_get_certificates_pagination() {
+    let env = Env::default();
+    let (_admin, client, freelancer, token, contract_id) = setup_test(&env);
+    let escrow = new_escrow(&env, &contract_id);
+    let desc_hash = BytesN::from_array(&env, &[1u8; 32]);
+    let deadline: u64 = 1000;
+    let amount: i128 = 50_0000000;
+
+    for _ in 0..5 {
+        let job_id = escrow.post_job(&client, &amount, &desc_hash, &100u32, &deadline, &token, &dummy_title(&env), &dummy_category(&env));
+        escrow.accept_job(&freelancer, &job_id);
+        escrow.submit_work(&freelancer, &job_id);
+        escrow.approve_work(&client, &job_id);
+    }
+
+    let page1 = escrow.get_certificates(&freelancer, &0u64, &2u64);
+    assert_eq!(page1.len(), 2);
+
+    let page2 = escrow.get_certificates(&freelancer, &2u64, &2u64);
+    assert_eq!(page2.len(), 2);
+
+    let page3 = escrow.get_certificates(&freelancer, &4u64, &2u64);
+    assert_eq!(page3.len(), 1);
+}