Skip to content

Standard Market Specification

To keep the UX intuitive and ensure contracts remain interoperable, every Mentat market adheres to a canonical schema and lifecycle. This document describes required fields, metadata conventions, and state transitions.

Market Identity

  • Market ID: uint64 generated by the MarketFactory.
  • Version: Incremented on curator edits prior to launch; immutable after deployment.
  • Topic Tags: Array of short strings (e.g., ["Politics", "US", "Elections"]) for discovery filters.
  • Creator Address: Solana public key responsible for stake and eligible for creator fee share.

Question & Outcomes

  • Question Text: Human-readable prompt framed as “Will/Did X happen before Y?” Must match resolution criteria exactly.
  • AI Rationale Hash: Blake2 hash of the AI-generated rationale and context, stored to provide auditability.
  • Outcome Set: Binary (YES/NO) by default; multi-outcome supported via enum list with deterministic payout ratios.
  • Payout Vector: Mapping of outcomes to payout weights (e.g., YES → 1, NO → 0). For multi-outcome, support fractional payouts if appropriate.

Resolution Criteria

  • Primary Source List: Ordered list of domains/endpoints eligible for zkTLS proofs (e.g., api.reuters.com, api.coingecko.com).
  • Trigger Condition: Structured statement describing data pattern (e.g., JSONPath query, exact phrase match).
  • Timestamp Window: UTC start/end bounds for proof acceptance.
  • Fallback Logic: Optional fallback sources or rules (e.g., “if primary unavailable, use CoinGecko snapshot at T+1h”).
  • Invalidation Clause: Explicit text for cases that force INVALID resolution (e.g., “If data source is unreachable for >24h, market resolves INVALID”).

Economic Parameters

  • Creator Stake: Amount locked until resolution (lamports/token units).
  • Trading Fee Rate: Basis points charged per trade plus distribution splits (LP / Creator / Treasury).
  • Settlement Fee Rate: Basis points applied at settlement and bounty allocation.
  • Proof Bounty: Target reward amount and SLA tiers.
  • Dispute Bond Minimum: Threshold challengers must post.

Lifecycle Timestamps

  • Created At: When curator approves deployment.
  • Open At: When trading becomes active.
  • Lock At: Optional; when trading is disabled prior to resolution event.
  • Resolution Deadline: Latest timestamp for proof submission.
  • Dispute Window: Duration after settlement during which disputes can be filed.

State Machine

  1. Draft → AI-generated proposal awaiting curation.
  2. PendingLaunch → Approved and queued for on-chain deployment.
  3. Active → Trading enabled; proofs not yet submitted.
  4. Locked (optional) → Trading paused (e.g., post-event).
  5. Resolved{Outcome} → Valid proof accepted and payouts executed.
  6. Invalid → Criteria unmet or dispute upheld; funds returned.
  7. Disputed → Temporary flag while dispute case is evaluated.

Metadata & UX Fields

  • Summary: 1-2 sentence AI-generated explanation for discovery.
  • Proof Timeline: Expected resolution SLA displayed to traders.
  • Community Notes: Optional curator/trader annotations (off-chain).
  • External Links: Trusted references or dashboards associated with the market.

Serialization

  • On-chain accounts store core fields (ID, creator, economics, state, timestamps, outcome set, proof config).
  • Extended metadata (summaries, rationale, discovery tags) stored off-chain in a content-addressed format (e.g., Arweave/IPFS) with hash referenced on-chain.
  • API responses follow a JSON schema mirroring this document to keep UI and indexers consistent.

Validation Rules

  • Question text must include an explicit timeframe or condition.
  • Trigger condition must reference at least one zkTLS-verifiable source.
  • Fallback logic cannot contradict primary trigger.
  • Fees must sum to ≤ 5% to keep UX predictable (soft limit can be overridden by governance).
  • Timestamp window minimum: 24 hours; maximum: 6 months.

Extensibility

  • Multi-tranche markets can be represented as separate markets linked via Series ID metadata.
  • Composability with other protocols (e.g., lending) achieved by exposing on-chain outcome tokens conforming to SPL Token standard.
  • Future upgrades may add conditional payouts, parimutuel pools, or cross-market bundles; keep this base schema backwards-compatible.