Smart Contracts

Architecture#

The marketplace contract is a greenfield settlement contract. It is keyed by commitment_hash for signal state and purchase_ref for buyer-leg state.

Contract duties include escrow accounting, deadline enforcement, reveal integrity checks, and deterministic terminal settlement outcomes.

State Model#

text

SignalStatus:
- ACTIVE
- REVEALED
- RESOLVED_HIT
- RESOLVED_MISS
- DEFAULT_NO_REVEAL

PurchaseStatus:
- PURCHASED_PENDING_DELIVERY
- DELIVERED
- DEFAULT_NO_DELIVERY
- SETTLED_PAYOUT
- SETTLED_REFUND

Deadline Policy#

Delivery deadline: purchase + 30 seconds (per purchase_ref)
Reveal deadline: expiry + 30 minutes (per commitment_hash)

Transactions#

solidity

purchaseFromListing(...)
recordDelivery(bytes32 purchaseRef, bytes32 deliveryHash)
challengeDelivery(bytes32 purchaseRef, bytes32 evidenceHash)
revealSignal(bytes32 signalId, uint256 targetPrice, uint8 direction, bytes32 salt)
settlePurchase(bytes32 purchaseRef, uint256 resolutionPrice)
settlePurchases(bytes32[] purchaseRefs, uint256 resolutionPrice)
withdrawProtocolFees(address to, uint256 amount)

Function Families#

Family	Responsibilities
Purchase	Create buyer legs, bind escrow, emit `SignalPurchased`
Delivery + challenge	Track delivery receipts and dispute flags per `purchase_ref`
Reveal + settlement	Verify reveal preimage and settle payout/refund outcomes
Protocol fees	Accrue on payout paths and support governed withdrawal

Events#

solidity

SignalPurchased(bytes32 indexed commitment_hash, bytes32 indexed purchase_ref, address buyer, uint256 amount_usdc)
DeliveryRecorded(bytes32 indexed signal_id, bytes32 indexed purchase_ref, bytes32 delivery_hash, uint256 delivered_at)
DeliveryChallenged(bytes32 indexed signal_id, bytes32 indexed purchase_ref, address indexed buyer, bytes32 evidence_hash, uint256 challenged_at)
SignalRevealed(bytes32 indexed signal_id, uint256 target_price, uint8 direction, bytes32 salt)
PurchaseSettled(bytes32 indexed signal_id, bytes32 indexed purchase_ref, SettlementOutcome outcome, SettlementReason reason, uint256 amount, uint256 settled_at)
ProtocolFeesWithdrawn(address indexed to, uint256 amount)

Settlement Semantics#

HIT + delivered leg -> payout settlement
MISS/default/no-delivery -> refund settlement
No reveal by expiry + 30m -> signal default + batch leg settlement

Every purchase_ref must reach exactly one terminal outcome: payout or refund.

NOTE

Fees accrue only on payout settlement outcomes, and are withdrawn through withdrawProtocolFees.