# NeuraMesh marketplace architecture

## Goal

Provide a discovery and execution market for standardized, capacity-backed compute claims without coupling market browsing, asset ownership, workload execution, evidence, and settlement into one trusted service.

## Bounded contexts

### 1. Discovery

**Responsibility:** searchable, comparable market metadata.

Inputs:

- `CapacityPool` events from Sui;
- signed provider capability documents;
- attestation state;
- delivery windows and outstanding capacity;
- workload compatibility and regional routing metadata.

Outputs:

- read-only market catalog;
- quote requests;
- route candidates for human or agent buyers.

The discovery index is not authoritative for ownership or settlement. Clients verify current object state against Sui before constructing a transaction.

### 2. Claims and ownership

**Responsibility:** authoritative issuance and ownership state.

Sui Move objects:

- `CapacityPool` — provider, node, hardware class, region, delivery window, capacity cap, outstanding units, collateral, active state;
- `ComputeClaim` — pool binding, terms, quantity, issuance time;
- `ComputeReservation` — claimant, workload reference, quantity, status, timestamps, result reference.

Invariants:

- claim issuance cannot exceed declared pool capacity;
- split and merge preserve total units;
- merge requires matching pool and delivery terms;
- redemption requires the correct pool and active delivery window;
- settlement releases outstanding pool capacity exactly once.

### 3. Execution orchestration

**Responsibility:** turn a redeemed reservation into an isolated workload run.

Components:

- event listener for new reservations;
- capability matcher;
- provider scheduler;
- workload fetcher;
- isolated runtime adapter;
- metering collector;
- result uploader;
- settlement transaction builder.

The orchestrator does not own claims and cannot mint capacity. It operates only against an authorized reservation.

### 4. Evidence and data

**Responsibility:** content-addressed evidence outside the transaction payload.

Walrus objects:

- provider capability and benchmark documents;
- encrypted workload packages or input commitments;
- execution receipts and metering records;
- result artifacts;
- challenge evidence.

On-chain objects contain immutable references and commitments, not large model or result payloads.

### 5. Verification and settlement

**Responsibility:** decide whether contracted delivery occurred and settle the reservation.

Prototype path:

1. provider submits a result blob reference;
2. reservation settles on-chain;
3. outstanding pool units decrease.

Required production path:

1. signed hardware identity and runtime attestation;
2. reservation-bound metering receipt;
3. buyer verification or challenge window;
4. settlement, refund, or slashing decision;
5. auditable final state.

## Read path

```text
Browser / Agent
      |
      v
Discovery API / Indexer ----> Sui events + object reads
      |                              |
      +------ capability refs ------+----> Walrus
      |
      v
Comparable market contracts
```

The catalog may be cached. Ownership, outstanding capacity, and active status must be refreshed from Sui before transaction construction.

## Write path

```text
Provider wallet -> create pool / issue claim -> Sui
Buyer wallet    -> receive / transfer claim  -> Sui
Buyer wallet    -> redeem + workload ref     -> Sui
Node agent      -> fetch reservation         -> Sui indexer
Node agent      -> fetch workload            -> Walrus
Node runtime    -> execute + meter
Node agent      -> upload result / receipt   -> Walrus
Provider/settler-> settle reservation        -> Sui
```

## Trust boundaries

| Boundary | Risk | Control |
|---|---|---|
| Provider ↔ physical hardware | false capacity | identity, attestation, collateral, capacity policy |
| Discovery index ↔ Sui | stale market state | direct object refresh before writes |
| Workload ↔ provider runtime | data leakage | encryption, isolation, scoped access, deletion policy |
| Meter ↔ settlement | fabricated usage | signed receipts, independent verification, challenge window |
| Oracle ↔ contract | compromised decision | bounded authority, multi-party or optimistic verification |
| Claim ↔ legal characterization | regulatory mismatch | usage-right language and jurisdiction-specific review |

## API boundaries

Suggested services:

- `GET /v1/markets` — indexed read model with filters;
- `GET /v1/markets/:poolId` — terms, attestation, current object version;
- `POST /v1/quotes` — non-binding provider quote request;
- `POST /v1/routes` — ranked capacity candidates for a workload envelope;
- `GET /v1/reservations/:id/evidence` — verified Walrus references;
- `GET /v1/providers/:nodeId/attestations` — current capability evidence.

All write operations remain wallet-signed Sui transactions. The API must not custody buyer or provider keys.

## Frontend architecture

- `src/neuramesh-LANDING.jsx` — React Decide/Learn surface for the protocol thesis and architecture;
- `public/marketplace.html` — Explore surface for search, filters, comparable contracts, and inspection;
- `public/styles.css` — shared design tokens and responsive components;
- `public/marketplace.js` — reference catalog view model and prototype interactions;
- future `src/data/sui-indexer.ts` — replace static reference catalog with chain-derived state;
- future `src/transactions/*` — typed transaction construction using `neuramesh-client.ts`.

## Production gates

The marketplace must not represent live availability until:

- Sui package IDs are deployed and configured;
- the indexer reads actual pool events and object versions;
- provider identity and hardware attestations are verified;
- reservation metering and dispute behavior is tested;
- quotes are explicit and non-misleading;
- wallet transactions are inspected and signed by users;
- legal review confirms the product language and market structure.