feat(contracts): expert cooldown, spending limits, vouchers, webhook events (#240-#243)

contracts/Cargo.toml

@@ -13,6 +13,7 @@ soroban-sdk = "21.0.0"
 [dev-dependencies]
 soroban-sdk = { version = "21.0.0", features = ["testutils"] }
 proptest = { version = "1.4.0", default-features = false, features = ["std"] }
+ed25519-dalek = { version = "2.1.1", features = ["rand_core"] }
 
 [[test]]
 name = "fuzz_claimable"

contracts/src/crypto.rs

@@ -0,0 +1,67 @@
+//! Off-chain signed session invitations — Issue #242.
+//!
+//! Experts pre-sign voucher payloads off-chain so seekers can open sessions
+//! without a separate on-chain expert confirmation transaction.
+
+use soroban_sdk::{contracttype, xdr::ToXdr, Address, Bytes, BytesN, Env};
+
+use crate::{DataKey, Error};
+
+/// Signed session invitation issued by an expert off-chain.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SessionVoucher {
+    pub expert: Address,
+    pub rate_per_second: i128,
+    pub max_duration: u64,
+    pub expiry: u64,
+    pub nonce: u64,
+}
+
+/// Canonical byte sequence signed by the expert wallet.
+pub fn voucher_message(env: &Env, voucher: &SessionVoucher) -> Bytes {
+    let mut message = Bytes::new(env);
+    message.append(&voucher.expert.to_xdr(env));
+    message.append(&voucher.rate_per_second.to_xdr(env));
+    message.append(&voucher.max_duration.to_xdr(env));
+    message.append(&voucher.expiry.to_xdr(env));
+    message.append(&voucher.nonce.to_xdr(env));
+    message
+}
+
+/// Verify an ed25519 signature over the canonical voucher message.
+pub fn verify_voucher_signature(
+    env: &Env,
+    voucher: &SessionVoucher,
+    public_key: &BytesN<32>,
+    signature: &BytesN<64>,
+) -> Result<(), Error> {
+    let message = voucher_message(env, voucher);
+    env.crypto()
+        .ed25519_verify(public_key, &message, signature);
+    Ok(())
+}
+
+pub fn voucher_pubkey(env: &Env, expert: &Address) -> Option<BytesN<32>> {
+    env.storage()
+        .persistent()
+        .get(&DataKey::ExpertVoucherPubkey(expert.clone()))
+}
+
+pub fn set_voucher_pubkey(env: &Env, expert: &Address, public_key: BytesN<32>) {
+    env.storage()
+        .persistent()
+        .set(&DataKey::ExpertVoucherPubkey(expert.clone()), &public_key);
+}
+
+pub fn is_nonce_consumed(env: &Env, expert: &Address, nonce: u64) -> bool {
+    env.storage()
+        .persistent()
+        .has(&DataKey::VoucherNonceConsumed(expert.clone(), nonce))
+}
+
+pub fn consume_nonce(env: &Env, expert: &Address, nonce: u64) {
+    env.storage()
+        .persistent()
+        .set(&DataKey::VoucherNonceConsumed(expert.clone(), nonce), &true);
+}

contracts/src/disputes.rs

@@ -1,98 +1,64 @@
-//! Expert-initiated session cancellation with partial refund (#238).
+//! Expert cooldown after dispute loss — Issue #240.
+//!
+//! When arbitration awards more to the seeker than the expert, the expert
+//! enters a temporary cooldown during which they cannot accept new sessions.
+//! Cooldown expiry is tracked by ledger sequence in temporary storage.
 
-use soroban_sdk::{token, Address, Env, String};
+use soroban_sdk::{Address, Env};
 
-use crate::{
-    events, DataKey, Error, SessionStatus, SkillSphereContract, MIN_SESSION_ESCROW,
-};
+use crate::DataKey;
 
-/// Cancels an active or paused session on behalf of the expert.
-///
-/// Accrued (claimable) earnings are paid to the expert; the remaining
-/// escrow balance is refunded to the seeker.  The cancellation reason
-/// CID is stored for transparency and the session status becomes
-/// `CancelledByExpert`.
-pub fn cancel_session_by_expert(
-    env: &Env,
-    expert: Address,
-    session_id: u64,
-    reason_cid: String,
-) -> Result<(i128, i128), Error> {
-    SkillSphereContract::assert_not_locked(env)?;
-    SkillSphereContract::set_reentrancy_lock(env, true);
-
-    expert.require_auth();
-
-    if !SkillSphereContract::is_valid_ipfs_cid(&reason_cid) {
-        SkillSphereContract::set_reentrancy_lock(env, false);
-        return Err(Error::InvalidCid);
-    }
+/// Stellar closes a ledger roughly every 5 seconds; seven days ≈ 120_960 ledgers.
+pub const DEFAULT_EXPERT_COOLDOWN_LEDGERS: u32 = 7 * 24 * 60 * 12;
 
-    let mut session = SkillSphereContract::get_session_or_error(env, session_id)?;
+/// Returns the configured cooldown length in ledgers (admin-set, default 7 days).
+pub fn cooldown_ledgers(env: &Env) -> u32 {
+    env.storage()
+        .instance()
+        .get(&DataKey::ExpertCooldownLedgers)
+        .unwrap_or(DEFAULT_EXPERT_COOLDOWN_LEDGERS)
+}
 
-    if expert != session.expert {
-        SkillSphereContract::set_reentrancy_lock(env, false);
-        return Err(Error::Unauthorized);
-    }
+/// Admin-only setter invoked from `lib.rs`.
+pub fn set_cooldown_ledgers(env: &Env, ledgers: u32) {
+    env.storage()
+        .instance()
+        .set(&DataKey::ExpertCooldownLedgers, &ledgers);
+}
 
-    if !matches!(
-        session.status,
-        SessionStatus::Active | SessionStatus::Paused
-    ) {
-        SkillSphereContract::set_reentrancy_lock(env, false);
-        return Err(Error::InvalidSessionState);
+/// True when the expert still has an active post-loss cooldown.
+pub fn is_expert_on_cooldown(env: &Env, expert: &Address) -> bool {
+    if let Some(until_ledger) = env
+        .storage()
+        .temporary()
+        .get::<DataKey, u32>(&DataKey::ExpertCooldownUntil(expert.clone()))
+    {
+        return env.ledger().sequence() < until_ledger;
     }
+    false
+}
 
-    let now = env.ledger().timestamp();
-    let effective_time = SkillSphereContract::bounded_time(&session, now);
-    let claimable = SkillSphereContract::claimable_amount_for_session(&session, effective_time);
-    let remaining = session.balance.saturating_sub(claimable);
-
-    session.balance = 0;
-    session.accrued_amount = 0;
-    session.last_settlement_timestamp = effective_time as u32;
-    session.status = SessionStatus::CancelledByExpert;
-    SkillSphereContract::save_session(env, &session);
-
+/// Returns the ledger sequence after which the expert may accept sessions again.
+pub fn expert_cooldown_until(env: &Env, expert: &Address) -> Option<u32> {
     env.storage()
-        .persistent()
-        .set(&DataKey::SessionCancelReason(session_id), &reason_cid);
-
-    let token_client = token::Client::new(env, &session.token);
-
-    let mut expert_payout = claimable;
-    let mut seeker_refund = remaining;
-    if expert_payout < MIN_SESSION_ESCROW {
-        expert_payout = 0;
-    }
-    if seeker_refund < MIN_SESSION_ESCROW {
-        seeker_refund = 0;
-    }
+        .temporary()
+        .get(&DataKey::ExpertCooldownUntil(expert.clone()))
+}
 
-    if expert_payout > 0 {
-        token_client.transfer(
-            &env.current_contract_address(),
-            &session.expert,
-            &expert_payout,
-        );
-    }
-    if seeker_refund > 0 {
-        token_client.transfer(
-            &env.current_contract_address(),
-            &session.seeker,
-            &seeker_refund,
-        );
+/// Apply cooldown when the seeker receives a strictly larger award than the expert.
+pub fn apply_cooldown_if_expert_lost(
+    env: &Env,
+    expert: &Address,
+    seeker_award_bps: u32,
+    expert_award_bps: u32,
+) {
+    if seeker_award_bps <= expert_award_bps {
+        return;
     }
 
-    events::publish_expert_cancel(
-        env,
-        session_id,
-        expert,
-        expert_payout,
-        seeker_refund,
-        reason_cid,
-    );
-
-    SkillSphereContract::set_reentrancy_lock(env, false);
-    Ok((expert_payout, seeker_refund))
+    let ledgers = cooldown_ledgers(env);
+    let until = env.ledger().sequence().saturating_add(ledgers);
+    env.storage()
+        .temporary()
+        .set(&DataKey::ExpertCooldownUntil(expert.clone()), &until);
 }

contracts/src/errors.rs

@@ -62,10 +62,13 @@ pub enum Error {
     SessionFrozen = 48,
     SwapFailed = 49,
 
-    // #236 / #239 / #237 / #238
-    RateLimitExceeded = 50,
-    TokenNotWhitelisted = 51,
-    TokenAlreadyWhitelisted = 52,
-    TokenNotInWhitelist = 53,
+    // #240 / #241 / #242
+    ExpertOnCooldown = 50,
+    SpendingLimitExceeded = 51,
+    VoucherExpired = 52,
+    VoucherNonceUsed = 53,
+    InvalidVoucherSignature = 54,
+    VoucherPubkeyNotSet = 55,
+    InvalidVoucher = 56,
 
 }