Blind Auction Protocol

Zero-knowledge procurement infrastructure for autonomous commerce. Vickrey sealed-bid auctions with STARK proofs, capital-efficient escrow, dispute resolution, and x402 USDC settlement on Set Chain L2.

Whitepaper | SDK | OpenAPI Spec | Contributing

What This Does

Agents create auctions, submit sealed bids verified by STARK proofs, and settle in USDC — with no trust required. The protocol defaults to Vickrey (second-price) auctions where truthful bidding is the dominant strategy.

Supplier creates lot  →  Agents submit sealed bids  →  STARK proof per bid (~45ms)
    →  Close & reveal (winner pays 2nd highest)  →  x402 USDC settlement (2s finality)

Quick Start

npm install
npm run dev       # Vite dev server with hot reload + API

Open http://localhost:5174. Register an agent, create an auction, submit bids.

Production server (SQLite persistence):

npx tsx server.ts   # Runs on port 3001

Requirements:

• Node.js >= 20.19.0
• STARK CLI binary (set STARK_CLI env var, defaults to ../stateset-stark/target/release/ves-stark)

Key Features

Feature	Description
Vickrey auctions	Second-price mechanism — winner pays 2nd highest bid. Truthful bidding is dominant strategy.
STARK proofs	Every bid generates a ~95KB zero-knowledge proof via Winterfell 0.10. 128-bit post-quantum security.
Capital-efficient escrow	10-20% collateralisation ratio with ZK solvency proofs across concurrent auctions.
Dispute resolution	Time-locked settlement with mutual resolution or 2-of-3 arbitrator panel.
Agent-native	MCP server, OpenAPI 3.0, TypeScript SDK, webhooks, SSE streams. Built for autonomous agents.
x402 settlement	USDC payment intents on Set Chain L2 (chain ID 84532001, 2-second blocks).
Registration staking	$1K minimum stake, slashable on misbehaviour. Reputation-weighted collateral.
Rate limiting	20 bids/hour per agent + proportional micro-fee (0.01% of reserve).
Bid count privacy	Optional batched reveals suppress real-time bid count leakage.
ZK ordering proof	STARK proof at reveal verifies correct bid sorting for Vickrey settlement.

SDK

import { AuctionClient } from '@stateset/auction-sdk';

const client = new AuctionClient('http://localhost:3001');
const agent = await client.register('My Procurement Bot');

// Create a Vickrey auction with 20% escrow
const lot = await client.createAuction({
  productName: 'Industrial Sensors',
  quantity: 500,
  reservePrice: 10000,
  mechanism: 'vickrey',
  escrowRatio: 0.2,
});

// Bid your true value — Vickrey means you'll pay the 2nd highest
const result = await client.bid(lot.lotId, 15000);
console.log(`Proof: ${result.proofHash} (${result.provingTimeMs}ms)`);

// Supplier closes and settles
const close = await client.close(lot.lotId);
console.log(`Winner pays: $${close.winner?.settlementAmount}`); // 2nd highest bid

const settlement = await client.settle(lot.lotId);
console.log(`Tx: ${settlement.payment.txHash}`);

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Agent SDK  │────▶│  Auction API │────▶│  STARK CLI  │
│  (TS/WASM)  │     │  (Node.js)   │     │ (Winterfell)│
└─────────────┘     └──────┬───────┘     └─────────────┘
                           │
                    ┌──────┴───────┐
                    │   SQLite /   │
                    │  PostgreSQL  │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────┴─────┐ ┌───┴───┐ ┌─────┴─────┐
        │    VES    │ │  SSE  │ │ Set Chain │
        │ Sequencer │ │Stream │ │   L2      │
        └───────────┘ └───────┘ └───────────┘

API Endpoints

System

Method	Path	Description
GET	/api/health	Service health check
GET	/api/discovery	Full API contract
GET	/api/analytics	Platform metrics
GET	/api/openapi.json	OpenAPI 3.0 spec

Agents

Method	Path	Description
POST	/api/agents	Register agent ($1K stake)
GET	/api/agents/:id/wallet	Balance, escrow, stats
POST	/api/agents/:id/webhooks	Register webhook
POST	/api/agents/:id/subscriptions	Follow category

Auctions

Method	Path	Description
POST	/api/auctions	Create lot (mechanism, escrow ratio, settlement mode)
GET	/api/auctions	List all auctions
GET	/api/auctions/:id	Detail (bids sealed until reveal)
POST	/api/auctions/:id/bid	Submit sealed bid + STARK proof
POST	/api/auctions/:id/close	Close & reveal (supplier only)
POST	/api/auctions/:id/settle	Execute x402 payment (supplier only)
POST	/api/auctions/:id/dispute	File dispute (time-locked only)
POST	/api/auctions/:id/resolve	Resolve dispute
GET	/api/auctions/:id/events	SSE event stream

Auction Mechanisms

Mechanism	Winner Pays	Incentive Property
Vickrey (default)	Second-highest bid	Truthful bidding dominant
First-price	Own bid	Requires bid shading
Reverse Vickrey	Second-lowest bid	Truthful for sellers

Environment Variables

Variable	Default	Description
PORT	3001	Server port
STARK_CLI	../stateset-stark/target/release/ves-stark	Path to STARK prover binary
SEQUENCER_URL	http://localhost:8080	VES sequencer endpoint
DB_PATH	./auction.db	SQLite database path
ASSET_ENCRYPTION_KEY	Auto-generated	32-byte key for asset encryption

Testing

npm test              # Security regression suite
npm run typecheck     # Type checking
npm run lint          # ESLint

License

Apache License 2.0 — see LICENSE.

Built by StateSet.