jerry/agents-marketplace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M1-F: end-to-end LLM marketplace lifecycle on Vector testnet

Browse Source 
Bonded-escrow marketplace for prompt → response between buyers and
local-LLM suppliers, settling on Vector (UTxO) via Aiken Plutus V3
validators. Lifecycle PostEscrow → Claim → Submit → Accept proven on
Vector testnet 2026-05-06; AcceptEscrow tx 125e3cfe…7dc100d distributes
payment + bonds per the validator's distribution rule.

Workspace layout (pnpm + TypeScript):
  contracts/marketplace/      Aiken validators (advert + escrow) + plutus.json
  packages/shared/            Tx-builders (lucid-evolution), CBOR codecs,
                              chain providers (mock / read-only / live Ogmios)
  supplier/                   OpenAI-compatible HTTP node (Ollama by default;
                              vLLM / llama.cpp / OpenRouter / OpenClaw all
                              swap-in via OLLAMA_URL); 202+poll chat handler
  buyer/                      Express + React SPA; server-side runs the full
                              chain lifecycle via /v1/submit-prompt and
                              /v1/accept; SPA never holds the buyer key
  indexer/                    Chain-follower (extends apex-dashboard pattern),
                              SSE event stream + REST queries
  indexer-ui/                 Operator dashboard (events + suppliers + escrow
                              lookup)
  tests/                      1098 vitest unit + integration tests (10 skipped
                              under M1-F-D-defer for UPLC test plumbing)
  deploy/testnet/             Per-service docker-compose for the Hetzner stack
  docs/EXECUTIVE_SUMMARY.*    Marp deck (PDF + PPTX) — 11 slides, mermaid
                              diagrams pre-rendered for portable export
  docs/CLOUDFLARE_WAF_BYPASS.md  CF Skip-rule runbook for /v1/* paths
  docs/ARCHITECTURE.md        canonical spec

Live demo (testnet, 2026-05-06):
  https://mp-buyers.vector.testnet.apexfusion.org      (buyer SPA)
  https://mp-suppliers.vector.testnet.apexfusion.org   (supplier API)
  https://mp-indexer.vector.testnet.apexfusion.org     (indexer + UI)
This commit is contained in:
jelisaveta-talbot
2026-05-06 13:27:48 +02:00
commit cbab81efbd
323 changed files with 49725 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
docs/supplier/README.md Normal file
View File

@@ -0,0 +1,185 @@
# Vector Supplier Node
A self-contained AI compute supplier for the Vector L2 testnet (Cardano). You receive task requests from buyers, fulfill them with an LLM, and settle payment on-chain via escrow smart contracts.
## How It Works
1. A **buyer** posts an escrow transaction on-chain, locking their payment + bond
2. The buyer sends you an HTTP request with the task prompt and escrow TX hash
3. Your node **verifies** the escrow exists on-chain
4. Your node calls the **LLM** to generate a response
5. Your node **claims** the escrow on-chain (Open -> Claimed)
6. Your node **submits** the result hash on-chain (Claimed -> Submitted)
7. The buyer reviews the response and **accepts** (releasing payment to you)
All on-chain steps happen automatically. You just need to keep this node running.
## Quick Start
### 1. Install Python
You need Python 3.9 or newer. Download from https://www.python.org/downloads/
### 2. Create a virtual environment
```bash
cd supplier
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
```
### 3. Install dependencies
```bash
pip install -r requirements.txt
```
### 4. Configure your environment
Copy the example file and fill in your values:
```bash
copy .env.example .env
```
Edit `.env` with your settings:
```
# Your wallet seed phrase (15 words)
SUPPLIER_MNEMONIC=word1 word2 word3 ... word15
# LLM API key from https://openrouter.ai
OPENROUTER_API_KEY=sk-or-v1-...
# Port to run on (default 9000)
SUPPLIER_PORT=9000
# Your node's display name
SUPPLIER_NAME=my-supplier
```
The other values (VECTOR_OGMIOS_URL, VECTOR_SUBMIT_URL, ESCROW_SCRIPT_HASH, RESOLVER_ADDRESS) are pre-configured for the Vector testnet and should not need changing.
### 5. Fund your wallet
Your supplier wallet needs ADA to pay transaction fees and post bonds. You need at least **5 ADA** to get started.
When you start the node, it will print your wallet address. Send ADA to that address.
### 6. Start the node
```bash
python main.py
```
You will see:
```
Starting Vector Supplier Node 'my-supplier' on port 9000
Dashboard: http://localhost:9000
```
### 7. Open the dashboard
Go to **http://localhost:9000** in your browser. The dashboard shows:
- Your wallet balance
- Total earnings
- Number of tasks completed
- Task history with full details (prompts, responses, TX hashes)
## Giving Your URL to Buyers
Buyers need your URL to send you tasks. If you are running on:
- **Same machine**: `http://localhost:9000`
- **Local network**: `http://YOUR_IP:9000` (find your IP with `ipconfig` on Windows)
- **Public internet**: You need to either:
- Set up port forwarding on your router (forward port 9000)
- Use a service like ngrok: `ngrok http 9000`
- Deploy to a cloud server (AWS, DigitalOcean, etc.)
The buyer adds your URL to their `SUPPLIER_URLS` config and your node appears in their dashboard.
## File Structure
```
supplier/
main.py Entry point - starts the web server
config.py Loads settings from .env
wallet.py Initializes blockchain wallet
api.py HTTP API endpoints
task_runner.py Orchestrates the full task flow
escrow_ops.py On-chain escrow transactions
llm.py LLM API client (OpenRouter/Anthropic/OpenAI)
storage.py Task history (JSON file)
.env Your configuration (secret - do not share)
.env.example Template for .env
requirements.txt Python dependencies
static/
dashboard.html Web dashboard UI
lib/ Blockchain utilities
constants.py Protocol constants
chain.py Chain query helpers
datum.py CBOR datum builders
escrow_tx.py Transaction builder
blueprint.py Smart contract loader
protocol.py API data models
contracts/
escrow/
plutus.json Compiled smart contract
data/
tasks.json Task history (auto-created)
```
## Configuration Reference
| Variable | Description | Default |
|----------|-------------|---------|
| VECTOR_OGMIOS_URL | Blockchain node URL | Vector testnet |
| VECTOR_SUBMIT_URL | TX submission URL | Vector testnet |
| SUPPLIER_MNEMONIC | Your 15-word wallet seed phrase | (required) |
| ESCROW_SCRIPT_HASH | Escrow contract hash | Pre-configured |
| OPENROUTER_API_KEY | LLM API key from openrouter.ai | (required) |
| RESOLVER_ADDRESS | Dispute resolver address | Pre-configured |
| SUPPLIER_PORT | HTTP port | 9000 |
| SUPPLIER_NAME | Display name | default-supplier |
## Earnings
Payment is in **AP3X** (the Vector testnet token). 1 AP3X = 1,000,000 lovelace.
When a buyer accepts your response, the escrow releases:
- Your payment (set by the buyer, typically 3-10 AP3X per task)
- Your bond back (1 AP3X)
- The buyer's bond (1 AP3X bonus to you)
If the buyer does NOT accept within the dispute window (10 minutes), you can collect payment automatically.
## Security Notes
- **Never share your .env file** - it contains your wallet seed phrase
- **Never share your data/ folder** - it contains task history
- The seed phrase controls your wallet funds. Back it up securely.
- The node only responds to buyers who have already locked funds on-chain, so you cannot be scammed out of compute.
## Troubleshooting
**"No module named 'vector_agent'"**
- Make sure you installed dependencies: `pip install -r requirements.txt`
**"ogmios_url required"**
- Make sure your .env file exists and is in the supplier/ folder
**"Collateral check failed"**
- Your wallet needs more ADA. Send at least 5 ADA to your supplier address.
**Dashboard shows "Balance: unavailable"**
- The Vector testnet node may be temporarily down. Wait and refresh.
**Task fails with "UTxO not found"**
- The buyer's escrow transaction hasn't propagated yet. The node retries automatically for up to 60 seconds.