PromptHash Stellar

PromptHash Stellar is a Soroban-based marketplace for selling reusable AI prompt licenses with XLM payments and wallet-verified unlocks.

Overview

PromptHash Stellar is an in-development creator marketplace built on Stellar. It lets creators publish encrypted prompt assets, expose only public preview metadata on-chain, and sell access rights to buyers without transferring ownership of the underlying content.

This repository includes:

• a Soroban smart contract for prompt listing, pricing, purchase tracking, and fee routing
• a Vite + React frontend for browsing, buying, listing, and managing prompt licenses
• serverless unlock endpoints that verify wallet ownership and on-chain access before returning plaintext

The product is intentionally designed around prompt licensing rather than NFT transfer. That matches the actual use case: creators want repeated sales, buyers want reliable access, and the platform needs transparent settlement on Stellar.

Problem Statement

AI prompt creators increasingly monetize high-value workflows, but the current tooling is weak:

• prompt files are sold off-platform with poor proof of purchase
• content is either fully exposed before payment or hidden behind opaque centralized paywalls
• NFT-style ownership transfer does not match reusable prompt licensing
• buyers and ecosystem partners cannot easily verify payment logic, fees, or access rules

This creates a trust and distribution gap for creator economy products on-chain.

Solution

PromptHash Stellar turns prompt packs into encrypted, contract-backed digital goods:

• creators submit a preview, price, and encrypted prompt payload
• the Soroban contract stores listing metadata, tracks purchase rights, and enforces XLM fee splits
• buyers purchase access in XLM
• buyers sign a short-lived wallet challenge
• the unlock service checks has_access on-chain, verifies the wallet signature, decrypts the ciphertext, and returns plaintext only to authorized wallets

Why This Project Matters

PromptHash Stellar addresses a concrete gap between AI workflows and blockchain commerce. It gives creators a way to sell digital knowledge products with transparent payment rails while keeping delivery gated by verifiable wallet-based access. For Stellar, it expands utility beyond transfers into creator payments, programmable commerce, and application-layer access control.

Core Features

• Encrypted prompt listings with public preview metadata
• Soroban contract for listing creation, purchase rights, creator catalog, buyer catalog, and fee management
• XLM-denominated purchases with contract-enforced seller/platform splits
• Wallet-based access verification using signed challenge messages
• Unlock flow with integrity checking against a stored content hash
• Creator dashboard for price updates and sale activation/deactivation
• Buyer profile for reopening previously purchased prompt licenses

How It Works

Listing flow

1. A creator connects a Stellar wallet.
2. The browser encrypts the full prompt with AES-GCM.
3. The AES key is wrapped against the unlock service public key.
4. The app submits create_prompt to Soroban with the encrypted payload, wrapped key, preview metadata, content hash, and XLM-denominated price.

Purchase flow

1. A buyer browses public listings from contract state.
2. The app approves native asset spend and calls buy_prompt.
3. The contract transfers XLM from buyer to seller and fee wallet.
4. The contract records purchase rights and increments sales count.

Unlock flow

1. The buyer requests a challenge token for a prompt.
2. The wallet signs the challenge message.
3. The unlock endpoint verifies token validity, wallet signature, and on-chain has_access.
4. The service unwraps the encrypted key, decrypts the ciphertext, recomputes the hash, and returns plaintext only if the integrity check matches.

Stellar Ecosystem Alignment

PromptHash Stellar is strongly aligned with Stellar and Soroban:

• it uses Soroban contracts for stateful commerce rather than treating Stellar as a passive payment rail
• it settles purchases in XLM, increasing native asset utility
• it benefits from Stellar's low transaction costs and fast settlement for digital goods
• it fits Stellar's focus on practical financial utility by turning digital licensing into a transparent marketplace flow

Specific Benefits To The Stellar Blockchain

How it increases utility on Stellar

• Adds a new digital goods and creator economy use case for XLM
• Uses Soroban for programmable access control and revenue splitting
• Encourages wallet activity beyond simple transfers
• Creates demand for contract interactions tied to real content purchases

How it can drive adoption

• Gives creators a straightforward on-ramp to monetize AI assets on Stellar
• Gives buyers a simple XLM purchase flow for digital work products
• Provides a pattern that can extend to templates, datasets, reports, and other encrypted digital goods

Why Stellar is the right blockchain

• Low fees make smaller digital content purchases viable
• Fast settlement improves checkout UX for access-controlled content
• Soroban supports the contract logic needed for licensing and fee routing
• Stellar is well suited to globally accessible creator payments and micro-commerce

Strategic ecosystem value

PromptHash Stellar can serve as a reusable reference implementation for:

• creator economy applications on Soroban
• encrypted digital goods marketplaces
• wallet-authenticated unlock flows
• XLM-based application monetization patterns

Why It Is Valuable For Developers, Users, And The Ecosystem

Developers

• Demonstrates a complete Soroban application with frontend, contract, and gated delivery flow
• Provides a practical reference for wallet auth, contract reads/writes, and server-assisted decryption
• Establishes a reusable design pattern for access rights instead of token transfer semantics

Users

• Creators can monetize reusable prompt IP while retaining ownership
• Buyers get verifiable purchase rights with a cleaner flow than off-platform prompt sales
• Access is controlled by wallet ownership instead of an opaque centralized account system

Ecosystem

• Broadens the category of applications being built on Stellar
• Showcases practical XLM commerce
• Creates a template for future applications in education, research content, consulting assets, and workflow automation packs

Technical Architecture

PromptHash Stellar uses a three-part architecture where the Soroban smart contract is the absolute, single source of truth for prompt ownership, purchase records, and access rights.

1. Soroban smart contract (authoritative source of truth)

Located in contracts/prompt-hash.

The contract governs all stateful operations. Off-chain systems must never override or duplicate these responsibilities:

Operation	On-chain method	Off-chain role
Prompt creation	create_prompt	Index & cache (read-only)
Price updates	update_prompt_price	None
Listing state	set_prompt_sale_status	Index & cache (read-only)
Purchase & access	buy_prompt / has_access	Verify via RPC simulation
Fee config	set_fee_percentage / set_fee_wallet	None
License transfer	transfer_license	Index & cache (read-only)
Disputes	open_dispute / resolve_dispute	Off-chain moderation data only

Key invariant: No off-chain route may grant, revoke, or modify access rights. The api/prompts/unlock.ts endpoint calls has_access via Soroban RPC simulation — it trusts the contract, not the database.

2. Frontend application

Located in src.

The frontend handles wallet connection, client-side encryption before listing, marketplace browsing, contract-backed purchases, creator dashboard actions, and buyer unlock requests. All state-affirming operations (create, purchase, transfer) go through the smart contract; the frontend never writes directly to the off-chain index.

3. Unlock and API layer

Two authoritative serverless endpoints:

Endpoint	Responsibility
api/auth/challenge.ts	Issue HMAC-signed, time-bound challenge tokens
api/prompts/unlock.ts	Verify signature + on-chain has_access → decrypt → integrity check

A secondary Express workspace (server/) provides read-only indexing, preview analytics, review storage, and webhook dispatch. It is explicitly forbidden from originating prompt state changes. Write routes that duplicated create_prompt/set_prompt_sale_status have been removed — see server/src/routes/promptRoutes.ts for the deprecation ledger.

Observability & Production Hardening

The unlock service is hardened for production use with the following features:

• Rate Limiting: Request-level limits keyed by IP and wallet to prevent brute-force and DDoS attacks.
• Structured Logging: JSON-formatted logs with request ID tracking and sensitive data redaction.
• Operational Metrics: Real-time tracking of unlock success/failure rates, invalid signatures, and rate limit hits.
• Health Monitoring: Dedicated /api/health endpoint for uptime and configuration verification.
• Incident Response: Documented runbooks and debugging procedures located in docs/operations/.

Proposed Tech Stack

• Soroban smart contracts in Rust
• Stellar SDK and Stellar Base for blockchain interaction
• React 19 + TypeScript + Vite for frontend
• Tailwind CSS and Radix UI primitives for interface components
• React Query for client-side data fetching
• libsodium + Web Crypto for encryption and key wrapping
• Vercel serverless functions for unlock/auth endpoints
• Optional Express service workspace for external chat/proxy integrations

Smart Contract / Blockchain Interaction

The Soroban contract stores encrypted prompt data and commercial metadata directly on-chain. The full plaintext is never stored in readable form. Purchases are settled in Stellar's native asset contract, and access control is determined by contract state rather than a centralized database.

The current contract data model includes:

• prompt ID
• creator address
• image URL
• title
• category
• preview text
• encrypted prompt payload
• encryption IV
• wrapped AES key
• content hash
• price in stroops
• active status
• sales count

Installation

Prerequisites

• Node.js 22+
• Yarn 4+ (Corepack enabled)
• Rust toolchain
• Stellar CLI with Soroban support

Install dependencies

yarn install
cd server && npm install && cd ..

Run with Docker (fastest onboarding)

If you have Docker installed, you can start the full local stack — frontend, auxiliary API server, and MongoDB — without installing Node, Yarn, or Mongo on your host:

docker compose up

• Frontend (Vite): http://localhost:5173
• API server: http://localhost:5000
• MongoDB: mongodb://localhost:27017

The frontend and API source directories are bind-mounted, so edits on your host hot-reload inside the containers automatically (file-watch polling is enabled so this works on Windows, macOS, and Linux).

Need a local Stellar network with Soroban RPC (via Stellar Quickstart)? Start it with the optional stellar profile:

docker compose --profile stellar up

This exposes Horizon, Soroban RPC, and Friendbot on http://localhost:8000.

Default environment values target Stellar testnet. To override them, create a .env file (see .env.example); docker compose picks it up automatically.

Dev Containers (VS Code)

A .devcontainer configuration is included. Opening the repo in VS Code with the Dev Containers extension (or in GitHub Codespaces) gives you a ready-to-use environment with Node 22, the Rust toolchain, and the Stellar CLI (Soroban) already installed, plus the MongoDB and Stellar Quickstart services from the compose stack.

Why the image builds quickly

The Dockerfiles install dependencies in a dedicated, cached layer (manifest and lockfile are copied before the source). Rebuilds only re-run yarn install / npm ci when a lockfile changes, and BuildKit cache mounts keep the package caches warm between builds.

Local Development Setup

For the complete contributor workflow, including required tools, environment variables, frontend startup, Soroban contract tests, unlock endpoint testing, and troubleshooting, see CONTRIBUTING.md.

🚀 Getting Started

Need to get the project running locally? See the full contributor setup guide:

👉 CONTRIBUTING / SETUP

It covers prerequisites (Node.js, Rust, Soroban CLI), step-by-step setup (install dependencies, build contracts, run dev server), environment variables, testing, and contributor conventions.

Quick start:

1. Copy the environment file:

cp .env.example .env

2. Fill in the required Stellar and unlock-service variables.
3. Install dependencies:

yarn install

4. Start the frontend:

yarn dev

5. Optional: run the auxiliary Node server:

cd server
npm install
npm run dev

6. Run contract tests:

cargo test -p prompt-hash

7. Run frontend checks before opening a PR:

yarn lint
yarn test:frontend --run api/prompts/unlock.test.ts src/lib/auth/challenge.test.ts src/lib/crypto/promptCrypto.test.ts
yarn build

Setup Validation

Run the one-command setup check to verify all prerequisites and environment variables before starting development:

yarn check:setup

This checks Node/Yarn versions, Rust toolchain, Stellar CLI, contract tooling, dependencies, and required environment variables without printing secret values.

See docs/environments.md for local, testnet, and preview setup examples.

Environment Variables

See .env.example for the full template. Main variables:

• PUBLIC_STELLAR_NETWORK
• PUBLIC_STELLAR_NETWORK_PASSPHRASE
• PUBLIC_STELLAR_RPC_URL
• PUBLIC_STELLAR_HORIZON_URL
• PUBLIC_PROMPT_HASH_CONTRACT_ID
• PUBLIC_STELLAR_NATIVE_ASSET_CONTRACT_ID
• PUBLIC_STELLAR_SIMULATION_ACCOUNT
• PUBLIC_UNLOCK_PUBLIC_KEY
• CHALLENGE_TOKEN_SECRET
• UNLOCK_PUBLIC_KEY
• UNLOCK_PRIVATE_KEY

Usage

For creators

• Connect a Stellar wallet
• Create a prompt listing from /sell
• Set preview metadata and price
• Let the app encrypt and publish the listing on Soroban
• Manage price and sale status from the creator dashboard

For buyers

• Browse listings from /browse
• Buy prompt access in XLM
• Unlock the purchased prompt with wallet signature verification
• Reopen purchased prompts from /profile

Frontend Integration Tests

The frontend suite uses Vitest + jsdom + React Testing Library to cover the main marketplace journeys without a live wallet extension or live Soroban environment.

Run it with:

yarn test:frontend

Coverage currently includes:

• disconnected wallet and wrong-network UI handling
• create-listing validation and mocked contract submission
• purchase and unlock behavior with mocked wallet and unlock boundaries
• unlock failure recovery with retry
• creator dashboard refresh after React Query invalidation

Contributor notes:

• Use src/test/render.tsx to render components with router, wallet, and React Query providers.
• Reuse fixtures from src/test/fixtures/prompts.ts for realistic prompt records.
• Mock wallet, contract, and unlock boundaries instead of relying on live chain dependencies.
• Prefer integration coverage around real flow components such as CreatePromptForm, FetchAllPrompts, PromptModal, and MyPrompts.

See docs/frontend-testing.md for the recommended pattern when adding new frontend coverage.

Roadmap

• Mainnet-ready deployment configuration
• Better indexing and search beyond direct contract reads
• Prompt analytics for creators
• Support for stable asset pricing in addition to XLM
• Moderation and abuse-reporting flows
• Stronger seller reputation and verification signals

Future Improvements

• SEP-compatible identity and creator profiles
• Prompt bundles and subscription-style access passes
• Revenue-sharing splits for co-creators
• Encrypted off-chain blob support for larger content assets
• Better caching and pagination for high-volume marketplaces
• Additional developer docs and deployment automation

Contribution Guidelines

Contributions are welcome, especially in the following areas:

• Soroban contract hardening and testing
• frontend UX for wallet and purchase flows
• indexing/search strategy
• unlock-service security review
• creator onboarding and marketplace moderation

See CONTRIBUTING.md for workflow details.

Product Journeys

See docs/product-journeys.md for a beginner-friendly walkthrough of the creator and buyer flows, including which components handle each step.

License

This repository is licensed under the Apache License 2.0. See LICENSE.

Maintainer

Maintained by the PromptHash Stellar team for Drip Wave submission and ongoing open-source development.

Project Structure

├── api/                    # Vercel serverless functions
│   ├── auth/               # Challenge token issuance & secret rotation
│   ├── prompts/            # Unlock, versioning, and listing endpoints
│   ├── reviews/            # Review submission endpoints
│   ├── webhooks/           # Webhook integration endpoints
│   ├── health.ts           # Service health check
│   └── status.ts           # Multi-service status dashboard
├── contracts/              # Soroban smart contracts (Rust)
├── server/                 # Express backend (read-only indexing, analytics)
│   └── src/
│       ├── controllers/    # Route handlers
│       ├── db/             # Database connection
│       ├── models/         # Mongoose schemas
│       ├── routes/         # Express route definitions
│       ├── services/       # Cache, backup, listing validation
│       └── tests/          # Server integration tests
├── src/                    # React frontend (Vite + TypeScript)
│   ├── components/         # Reusable UI components
│   ├── hooks/              # Custom React hooks (useTheme, wallet, etc.)
│   ├── lib/                # Core logic (crypto, stellar, auth, validation)
│   ├── pages/              # Route pages (browse, sell, profile, etc.)
│   ├── providers/          # React context providers
│   └── test/               # Frontend test utilities & fixtures
├── docs/                   # Additional documentation
├── scripts/                # Build & setup scripts
├── eslint.config.js        # ESLint configuration
├── tailwind.config.js      # Tailwind CSS configuration
└── vite.config.ts          # Vite build configuration

API Endpoints

Vercel Serverless Functions (/api/*)

Method	Endpoint	Description
GET	/api/health	Service health check with indexer state
GET	/api/status	Multi-service status (RPC, Horizon, unlock)
POST	/api/auth/challenge	Issue time-bound challenge token for wallet verification
POST	/api/auth/rotate-secret	Rotate challenge token secrets with grace period
GET	/api/prompts	List published prompts (optional category & walletAddress filters)
POST	/api/prompts/unlock	Verify wallet access and return decrypted prompt
GET	/api/prompts/version	Get versioned prompt content for a buyer

Express Server (/api/* on port 5000)

Method	Endpoint	Description
GET	/api/prompts	List published prompts (cached, filtered)
GET	/api/prompts/buyer/:wallet/owned	Get prompts owned by wallet
GET	/api/prompts/buyer/:wallet/saved	Get prompts saved by wallet
GET	/api/prompts/creator/:wallet/drafts	Get creator draft prompts
POST	/api/prompts/preview	Record prompt preview
GET	/api/prompts/preview/stats	Get preview analytics for creator
POST	/api/prompts/reports	Submit prompt report
GET	/api/prompts/reports	Get prompt reports (admin)
GET	/api/search	Search prompts and users
POST	/api/webhooks	Register webhook subscriptions

Dark Mode

The application supports light, dark, and system-preference themes:

• Theme persistence: Your selection is stored in localStorage as theme-preference
• System-aware: When set to "System", the UI follows your OS color scheme preference
• Toggle: Use the theme switch icon in the top navigation bar
• CSS variables: Theme colors are defined as CSS custom properties in src/index.css with .dark class overrides
• Tailwind integration: Dark mode uses Tailwind's class strategy — add the dark: prefix for theme-specific styles

Toggle between Light, Dark, and System modes from the dropdown in the navigation bar. The setting persists across sessions.

Linting & Code Quality

The project uses ESLint with TypeScript support for code quality:

# Run the linter
npm run lint

# Auto-fix fixable issues
npm run lint -- --fix

Key linting rules:

• Unused variables are flagged as warnings
• Underscore-prefixed parameters (_param) are exempt from unused-variable checks
• TypeScript strict mode is enabled for type safety
• Prettier handles code formatting (npm run format)

Run both checks before opening a pull request:

npm run lint && npm run typecheck

GitHub Preparation

• Recommended repository name: prompt-hash-stellar
• Suggested short description: Soroban-based prompt licensing marketplace with XLM payments and wallet-verified unlocks
• Suggested topics: stellar, soroban, xlm, creator-economy, ai-prompts, marketplace, blockchain, rust, react, vercel
• Suggested release title for v0.1.0: Prompt licensing marketplace foundation on Stellar

Suggested commit messages

• docs: rewrite repository for Drip Wave submission
• docs: add architecture and ecosystem overview
• chore: align package metadata with PromptHash Stellar

Dependency Updates

Dependencies are managed automatically via Dependabot (see .github/dependabot.yml).

Dependabot opens pull requests every Monday for:

• npm (/) — frontend packages (Vite, React, Tailwind, etc.)
• Cargo (/contracts/prompt-hash) — Soroban / Rust crates, grouped into a single PR

Reviewing and merging updates

1. Check the Dependabot PR description for the changelog and any breaking-change notes.
2. Run npm ci && npm run build locally (or let CI run) to confirm the frontend still compiles.
3. For Cargo updates, run cargo test inside contracts/prompt-hash/ before merging.
4. Merge the PR; Dependabot will rebase any remaining open PRs automatically.

If a Dependabot PR introduces a breaking change, close it and pin the old version in package.json or Cargo.toml until the issue is resolved upstream.