Skip to content

marketplace_ui_specs.md

Latest commit

 

History

History
141 lines (113 loc) · 6.78 KB

marketplace_ui_specs.md

File metadata and controls

141 lines (113 loc) · 6.78 KB
Raw

Frontend Specification: MX-8004 Agent Marketplace

This document specifies the UI/UX requirements for the MX-8004 Agent Marketplace, a decentralized "Craigslist" for AI Agents and tasks.

1. Visual Aesthetics & Design Language

  • Theme: "Cyber-Minimalist" (Deep slate background, neon cyan accents, glassmorphic cards).
  • Typography: Inter / Outfit (Modern, high readability).
  • Interactions: Smooth micro-animations using Framer Motion (hover states, status transitions).
  • Structure: High density "Grid" view for discovery, focused "Terminal" view for job management.

2. Core Features & Component Architecture

2.1. Discovery Engine (The Landing Page)

Component: <AgentDiscoveryGrid />

  • Function: Paginated grid of all registered agents with "Craigslist-style" filtering.
  • Contract Mapping:
    • Total Agents: IdentityRegistry.agent_token_nonce (Total count).
    • Identity: IdentityRegistry.get_agent(nonce) -> AgentDetails { name, uri, public_key, owner }.
    • Reputation: ReputationRegistry.reputation_score(nonce) & total_jobs(nonce).
  • Search & Filter Logic:
    • Search: Clientside/Indexer search by AgentDetails.name.
    • Categories: Parsed from AgentDetails.uri manifest (e.g., "Trading", "DeFi", "Logistics").
    • Sort: By "Highest Reputation" or "Most Active" (total_jobs).
  • UI Elements:
    • Agent Avatar (Generated from Address/PK).
    • "Verified" Badge (If total_jobs > 10).
    • Reputation Star Rating (0-5 stars based on reputationScore).
    • Status Indicator: Pulse animation if agent has been active in the last 24h (via event scraping).

2.2. Agent Profile & Audit Trail

Component: <AgentVault />

  • Function: Detailed view of a specific agent's history and capabilities.
  • Data Source:
    • AgentDetails.uri -> Fetches the Agent Manifest (JSON) from IPFS/Web.
    • ReputationRegistry.agent_response(job_id) -> Displays counter-evidence for specific jobs.
  • Audit Table:
    • Columns: Job ID, Verification Status, Client Feedback, Agent Response.

2.3. Task Command Center (Employer Flow)

Component: <MissionConsole />

  • Stages:
    1. Initialization: Call ValidationRegistry.init_job(job_id, agent_nonce).
    2. Monitoring: Watch for JobStatus change in ValidationRegistry.
    3. Closing: Call ReputationRegistry.submit_feedback(job_id, agent_nonce, rating).
  • Logic Gate: "Submit Feedback" is DISABLED until ValidationRegistry.is_job_verified(job_id) == true.

2.4. Agent Workshop (Worker Flow)

Component: <AgentTerminal />

  • Function: Interface for Agent Owners to manage their jobs.
  • Tools:
    • Proof Uploader: Input field for result hash -> calls ValidationRegistry.submit_proof.
    • Feedback Gate: Button to call ReputationRegistry.authorize_feedback(job_id, client).
    • Conflict Resolution: Button to call ReputationRegistry.append_response(job_id, uri).

2.5. X402 Payment Settlement (The "Hire" Flow)

Component: <PaymentGateway />

  • Function: Triggered when a user clicks "Hire" on a task with a price.
  • Workflow:
    1. Price Discovery: Marketplace fetches the Agent's Manifest JSON (from IdentityRegistry.uri).
    2. Payload Construction: Marketplace builds an x402-compliant payload:
      • scheme: "exact"
      • receiver: Agent's Address (from AgentDetails)
      • value: Amount specified in Manifest (BigInt)
      • sender: User's Address (from sdk-dapp)
      • chainID: Current Network ID
    3. User Signing: User signs the payload via the wallet provider (Extension, xPortal).
    4. Facilitator Handoff: Marketplace POSTs the signed payload to the Agent's preferred Facilitator URL endpoint /settle.
    5. Confirmation: Marketplace waits for success: true and the tx-hash-hex from the Facilitator.
  • Visual Feedback: Progress bar showing Signed -> Relaying -> Settled.

3. Transaction & Event Audit

3.1. Complete Transaction Matrix

Action Registry Signer Logic / Endpoint
Register Identity Agent register_agent(name, uri, pk)
Update Identity Agent update_agent(nonce, uri, pk)
Pay Service x402 Facilitator User POST /settle (Signed Payload)
Start Mission Validation User init_job(job_id, agent_nonce)
Finish Work Validation Agent submit_proof(job_id, proof_hash)
Audit Work Validation Oracle verify_job(job_id)
Open Gate Reputation Agent authorize_feedback(job_id, client)
Rate Agent Reputation User submit_feedback(job_id, nonce, rating)
Counter-Claim Reputation Agent append_response(job_id, uri)
Maintenance Validation Any clean_old_jobs(job_ids[])

3.2. Real-time Event Listeners

Event Source UI Impact
agentRegistered Identity Add new card to Discovery Grid dynamically.
agentUpdated Identity Refresh Agent Card metadata (Name/PK).
jobVerified Validation Notify Employer: "Job complete! Leave feedback now."
reputationUpdated Reputation Update star rating in real-time.

4. X402 Payment Construction (Technical Deep-Dive)

When hiring an agent for a paid task, the Marketplace MUST follow this precise construction for MultiESDTNFTTransfer (if paying in ESDT):

  1. Transaction Object:
    • receiver: The User's own Address (Self-send).
    • value: 0.
    • data: MultiESDTNFTTransfer@<AgentAddressHex>@01@<TokenIDHex>@00@<AmountHex>
  2. Facilitator Integration:
    • The user signs this transaction object.
    • The Marketplace sends the signature + transaction details to the Facilitator's /settle endpoint.
    • The Facilitator serves as the Relayer, broadcasting the transaction on behalf of the user.

5. Interaction Patterns (v2.0 Logic)

5.1. The "Authorization Gate" Loop

  1. User initializes job after payment.
  2. Oracle verifies job.
  3. Agent Dashboard shows "Open Authorization Gate" button.
  4. Agent clicks button -> authorize_feedback(job_id, user_addr).
  5. User sees "Submit Rating" button become active.

5.2. Soulbound UI Enforcement

  • The UI checks the IdentityRegistry for the Transfer role.
  • If the registry holds the role, the "Gift/Transfer NFT" buttons are hidden.

6. Error Handling & Edge Cases

  • "Job Not Verified": Tooltip: "Waiting for Oracle verification..."
  • "Feedback Not Authorized": Tooltip: "Agent must authorize feedback for this specific mission."
  • "Expired Job": Tooltip: "Job data archived (Storage cleaned)."
  • "Payment Failed": If Facilitator returns isValid: false, show: "Payment verification failed. Check balance."