Veridex x402 Stellar Facilitator & P2P Bazaar Discovery Engine

Version: 0.1.0-alpha
License: Apache-2.0
Grant: Stellar Community Fund (SCF) Build Award

---

Overview

Complete open-source implementation of an x402 payment facilitator and federated Bazaar discovery engine for Stellar (stellar:testnet and stellar:pubnet). Built on Apache-2.0 @x402/stellar, enabling AI agents and applications to discover, query, rank, and pay for HTTP endpoints and MCP tools using USDC/SEP-41 stablecoins.

Key Features:

• ✅ Non-custodial x402 payment facilitator with fee sponsorship
• ✅ P2P federated catalog mesh (libp2p GossipSub)
• ✅ Hybrid RRF search engine (BM25 + pgvector)
• ✅ Telemetry-enriched composite ranking
• ✅ Soroban upto smart contract for metered billing
• ✅ MCP discovery server for AI agents
• ✅ Multi-language SDKs (TypeScript, Python, Go)

---

Project Structure

packages/stellar-facilitator/
├── facilitator/                    # Core HTTP facilitator server
│   ├── facilitator/
│   │   ├── server.ts              # Hono HTTP server (/verify, /settle, /supported)
│   │   └── types.ts               # Request/response schemas
│   ├── channel/
│   │   └── pool.ts                # 50-account channel pool manager
│   ├── bazaar/                    # (to be organized)
│   ├── helpers/                   # (to be organized)
│   ├── mcp/                       # (to be organized)
│   └── validation/                # (to be organized)
│
├── bazaar-service/                # P2P Bazaar Discovery Engine
│   └── src/
│       ├── db/schema.sql          # PostgreSQL + pgvector schema
│       ├── search/
│       │   ├── types.ts           # Type definitions
│       │   ├── engine.ts          # Hybrid RRF search
│       │   └── embeddings.ts     # Vector embedding generation
│       ├── p2p/
│       │   ├── types.ts           # P2P message types
│       │   └── mesh.ts            # Libp2p GossipSub mesh
│       ├── telemetry/
│       │   ├── circuit-breaker.ts # Liveness tracking
│       │   └── tracker.ts         # Telemetry metrics
│       └── catalog/
│           └── ingestion.ts       # Auto-cataloging worker
│
├── mcp-discovery-server/          # AI Agent MCP Server
│   └── src/
│       ├── server.ts              # MCP server implementation
│       └── index.ts               # CLI entry point
│
├── contracts/                     # Soroban Smart Contracts
│   └── upto-settlement/
│       ├── src/lib.rs             # Upto escrow contract (340 lines)
│       └── Cargo.toml             # Rust dependencies
│
├── sdks/                          # Multi-Language SDKs
│   ├── typescript/
│   │   ├── seller.ts              # TypeScript helpers
│   │   └── package.json
│   ├── python/
│   │   ├── seller.py              # Python helpers
│   │   └── setup.py
│   └── go/
│       ├── seller.go              # Go helpers
│       └── go.mod
│
├── specs/                         # Specifications
│   └── (to be added: scheme_upto_stellar.md)
│
├── ARCHITECTURE.md                # Architecture documentation
├── IMPLEMENTATION_STATUS.md       # Current implementation status
├── package.json                   # Root package config
└── README.md                      # This file

---

Quick Start

Prerequisites

• Node.js 20+
• PostgreSQL 15+ with pgvector extension
• Rust + Soroban CLI (for smart contract)
• Stellar account with testnet XLM

Installation

# Clone repository
git clone https://github.com/veridex-protocol/stellar-facilitator.git
cd stellar-facilitator

# Install dependencies
npm install
cd bazaar-service && npm install && cd ..
cd mcp-discovery-server && npm install && cd ..

# Setup PostgreSQL database
psql -U postgres -c "CREATE DATABASE veridex_bazaar"
psql -U postgres -d veridex_bazaar -f bazaar-service/src/db/schema.sql

Running Components

1. Bazaar Discovery Service

cd bazaar-service

# Configure environment
export DATABASE_HOST=localhost
export DATABASE_PORT=5432
export DATABASE_NAME=veridex_bazaar
export DATABASE_USER=postgres
export DATABASE_PASSWORD=yourpassword

# Start service
npm run dev

2. Facilitator HTTP Server

cd facilitator

# Configure environment
export STELLAR_RPC_URL=https://soroban-testnet.stellar.org
export STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
export CHANNEL_ACCOUNT_COUNT=50
export FEE_SPONSORSHIP_ENABLED=true

# Start server
npm run dev

3. MCP Discovery Server

cd mcp-discovery-server

# Configure environment
export BAZAAR_API_URL=http://localhost:3001
export FACILITATOR_URL=http://localhost:3000

# Start MCP server
npm start

4. Deploy Soroban Contract

cd contracts/upto-settlement

# Build contract
soroban contract build

# Deploy to testnet
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/upto_settlement.wasm \
  --network testnet \
  --source <YOUR_SECRET_KEY>

---

API Endpoints

Facilitator HTTP Server (Port 3000)

GET /supported

• Returns facilitator capabilities
• Response: { version, schemes, networks, extra }

POST /verify

• Validates payment authorization
• Request: { payload: string (base64 XDR) }
• Response: { isValid: boolean, payer?: string }

POST /settle

• Executes settlement transaction
• Request: { payload: string (base64 XDR) }
• Response: { txHash: string, ledger?: number }

Bazaar Discovery API (Port 3001)

GET /discovery/search?query=...&limit=20

• Hybrid semantic + keyword search
• Returns telemetry-ranked results

GET /discovery/resources?network=stellar:pubnet

• List cataloged resources with filters

MCP Tools (Stdio)

discover_resources

• Search Bazaar catalog
• Input: { query, resourceType?, network?, minUptimeRatio?, limit? }

pay_resource

• Execute paid x402 request
• Input: { url, method?, params?, maxAmount? }

---

Development

Build All Packages

# Build facilitator
cd facilitator && npm run build && cd ..

# Build bazaar-service
cd bazaar-service && npm run build && cd ..

# Build mcp-discovery-server
cd mcp-discovery-server && npm run build && cd ..

# Build Soroban contract
cd contracts/upto-settlement && soroban contract build && cd ../..

Run Tests

# TypeScript tests
npm test

# Soroban contract tests
cd contracts/upto-settlement
cargo test

# SDK tests
cd sdks/typescript && npm test

Type Checking

npm run typecheck

---

SDKs

TypeScript

import { createBazaarMetadata, validateBazaarMetadata } from "@veridex/stellar-sdk";

const metadata = createBazaarMetadata("Weather API", {
  serviceName: "OpenWeather",
  tags: ["weather", "api"],
  inputSpec: { /* JSON Schema */ },
});

const validation = validateBazaarMetadata(metadata);

Python

from veridex_sdk.seller import create_bazaar_metadata, validate_bazaar_metadata

metadata = create_bazaar_metadata(
    description="Weather API",
    input_spec={},
    service_name="OpenWeather",
    tags=["weather", "api"]
)

validation = validate_bazaar_metadata(metadata)

Go

import veridex "github.com/veridex-protocol/veridex/stellar-sdk"

metadata := veridex.CreateBazaarMetadata(
    "Weather API",
    map[string]interface{}{},
    "OpenWeather",
    []string{"weather", "api"},
    "", "", "", nil,
)

validation := veridex.ValidateBazaarMetadata(metadata)

---

Architecture Highlights

Hybrid RRF Search Engine

Combines BM25 keyword matching with pgvector cosine similarity:

-- Composite Score (Φ)
Φ = 0.35×semantic + 0.25×bm25 + 0.15×uptime + 0.15×latency + 0.10×reliability

P2P Federated Mesh

• GossipSub topic: /x402/bazaar/v1/announce
• Active heartbeat pings every 30 seconds
• Circuit breaker: HEALTHY → DEGRADED → OFFLINE

Channel Account Pool

• 50 pre-funded Stellar accounts
• Round-robin sequence number management
• ~50 parallel settlements per ledger (~5 seconds)

Soroban Upto Contract

Enforces 5 core properties:

1. Maximum cap: A ≤ M
2. Recipient binding
3. Single settlement (nonce tracking)
4. Unspent refundability
5. Expired refundability (ledger-based)

---

Implementation Status

Overall Progress: ~80% Complete

✅ Completed:

• Bazaar search engine with telemetry ranking
• P2P libp2p GossipSub mesh
• Facilitator HTTP server structure
• Channel account pool manager
• Soroban upto contract (with tests)
• MCP server (tool definitions)
• Multi-language SDKs (TS, Python, Go)
• Auto-cataloging ingestion worker

⚠️ In Progress:

• Facilitator verify/settle integration with @x402/stellar
• MCP payment flow (402 challenge loop)

🔄 Pending:

• Integration testing
• Conformance test suite
• Documentation hub
• Mainnet deployment

---

Contributing

Contributions welcome! Please:

1. Follow Apache-2.0 licensing
2. Maintain zero AGPL dependencies
3. Write tests for new features
4. Keep SDKs synchronized across languages

---

---

Resources

• Repository: https://github.com/veridex-protocol/stellar-facilitator
• Documentation: (Coming soon)
• Specifications: specification.md

---

License

Apache License 2.0

Copyright 2026 Veridex Protocol Team

---

Contact

Team: Emmanuel Akanji (Protocol Lead) & Testimony Adekoya (AI/MCP Engineer)
Email: omoebun52@gmail.com
GitHub: https://github.com/veridex-protocol