Marketplace

The SmartPoints marketplace (ADR-088 Layer 5) manages service discovery, retention, metering, and lifecycle for service engagements between Scopes.

Engagement Lifecycle

Every marketplace engagement follows six phases:

Discovery --> Negotiation --> Retention --> Engagement --> Completion --> Dissolution

Phase	Description
Discovery	Consumer finds services via DHT and reputation
Negotiation	Parties exchange terms
Retention	Quarx escrowed, service begins
Engagement	Service operates, usage metered
Completion	Artifacts delivered, escrow released
Dissolution	SmartPoint pair destroyed, keys zeroed

Discovery

The spt-discovery crate provides a Kademlia-style DHT for distributed service discovery. Providers publish ServiceRecord entries; consumers search by capability, type, and minimum reputation.

Publishing a Service

use spt_discovery::{ServiceRecord, ServiceType, ServiceRegistry};

let registry = ServiceRegistry::new();

let mut record = ServiceRecord::new(
    "did:spt:alice".into(),
    ServiceType::CodingAgent("rust-coder".into()),
    vec!["rust".into(), "code-review".into()],
);
record.reputation = 0.9;
registry.register(record)?;

Searching for Services

use spt_discovery::DiscoveryQuery;

let query = DiscoveryQuery::new()
    .with_capabilities(vec!["rust".into()])
    .with_min_reputation(0.5);

let results = registry.search(&query);
for scored in &results.matches {
    println!("{}: score={}", scored.record.provider_did, scored.score);
}

Reputation

The ReputationTracker computes provider reputation from engagement history. Each completed engagement produces an Engagement record with a satisfaction score. The reputation is a weighted rolling average.

use spt_discovery::{ReputationTracker, Engagement};

let tracker = ReputationTracker::new();
tracker.record_engagement(Engagement {
    provider_did: "did:spt:alice".into(),
    consumer_did: "did:spt:bob".into(),
    satisfaction: 0.95,
    // ...
})?;

let score = tracker.get_reputation("did:spt:alice")?;

Retention Lifecycle

Once a service is selected, the spt-marketplace crate manages retention through escrow and contract management.

Retention States

Proposed --> Active --> Completing --> Completed --> Dissolved
                |
                +--> Disputed
                |
                +--> Breached

State	Description
Proposed	Terms offered, not yet accepted
Active	Escrow funded, service operating
Completing	Final delivery in progress
Completed	Artifacts delivered, escrow released
Dissolved	SmartPoint pair destroyed
Disputed	Disagreement, mediation required
Breached	Terms violated, escrow may be forfeited

Creating a Retention

use spt_marketplace::{RetentionManager, RetentionTerms};

let manager = RetentionManager::new();

let terms = RetentionTerms {
    provider_did: "did:spt:alice".into(),
    consumer_did: "did:spt:bob".into(),
    service_type: "coding-agent".into(),
    quarx_budget: 1000,
    ttl_seconds: 86400,
    capabilities: vec!["rust".into(), "testing".into()],
};

let contract = manager.propose(terms)?;
let active = manager.activate(&contract.id)?;

Quarx Metering

Quarx is a metering unit, not a currency. There is no trading, no speculation, and no exchange. Quarx tracks resource consumption within retention contracts.

Quarx Ledger

use spt_marketplace::{QuarxLedger, QuarxTransaction};

let ledger = QuarxLedger::new();

// Fund escrow
ledger.credit("did:spt:bob", 1000)?;

// Meter usage
let meter = QuarxMeter::new(&contract);
meter.record_operation(MeteredOperation {
    operation_type: "inference".into(),
    quarx_cost: 5,
    // ...
})?;

Usage Tracking

The QuarxMeter records each operation with its quarx cost. The UsageSummary provides aggregated metrics for a retention contract.

Circuit Breakers

The CircuitBreaker protects consumers from runaway costs. It monitors spend rate and can suspend a retention if the burn rate exceeds thresholds.

use spt_marketplace::{CircuitBreaker, SpendTracker};

let tracker = SpendTracker::new(1000); // budget: 1000 quarx
let breaker = CircuitBreaker::new(tracker);

// Check before each operation
if breaker.is_open() {
    // Budget exceeded, circuit is open
    return Err("Budget exhausted");
}

The SpendTracker provides real-time budget monitoring. When spend exceeds the configured threshold (e.g., 90% of budget), the circuit opens and blocks further operations until the contract is renegotiated or the budget is increased.

Dissolution

When a retention completes or is terminated, dissolution ensures clean teardown:

1. Final usage summary is computed
2. Escrow is settled (released or forfeited)
3. Memory sharing policy is enforced (shared artifacts, if any, are transferred)
4. SmartPoint pair is destroyed
5. Keys are zeroed via zeroize
6. A DissolutionReceipt is issued

Key Types

Type	Crate	Description
ServiceRecord	spt-discovery	Service listing with capabilities
ServiceType	spt-discovery	Enum of service categories
ServiceRegistry	spt-discovery	In-memory registry with search
DiscoveryQuery	spt-discovery	Query builder for service search
DhtNode	spt-discovery	Kademlia-style DHT node
ReputationTracker	spt-discovery	Engagement-based reputation
RetentionManager	spt-marketplace	Retention lifecycle
RetentionContract	spt-marketplace	Active service contract
RetentionTerms	spt-marketplace	Proposed engagement terms
QuarxLedger	spt-marketplace	Quarx balance tracking
QuarxMeter	spt-marketplace	Per-operation metering
EscrowManager	spt-marketplace	Escrow creation and settlement
CircuitBreaker	spt-marketplace	Budget protection
SpendTracker	spt-marketplace	Real-time spend monitoring
NegotiationProtocol	spt-marketplace	Terms exchange protocol
DissolutionReceipt	spt-marketplace	Teardown confirmation