Compaki

Compaki is a multi-vendor marketplace platform for communities, local producers, and purpose-driven commerce. It lets an operator launch a marketplace, onboard vendors, list products, accept purchases, and distribute each payment automatically between the seller, the marketplace operator, and an optional community fund.

The project is built around a simple premise: digital commerce should not only extract value from a community, it should be able to circulate value back into it. Compaki makes regenerative economics a first-class part of the checkout flow by allowing every marketplace to reserve a programmable share of each sale for a community fund.

Why Compaki

Traditional marketplace infrastructure is powerful, but often expensive, opaque, and disconnected from the communities it serves. Compaki combines a familiar marketplace experience with transparent settlement on Stellar/Soroban:

• Operators can create a branded marketplace and invite vendors.
• Vendors can sell products and receive their share automatically.
• Buyers see a clean checkout and a receipt that explains where the money went.
• Community funds can receive a fixed percentage of every sale.
• Every settled purchase stores a Stellar transaction hash for independent verification.

This repository currently targets Stellar testnet. The money movement is real on testnet and verifiable through stellar.expert, while the product remains an MVP implementation with custodial demo accounts and a self-issued test asset shown as USD in the UI.

Regenerative Economy Model

Each marketplace defines its own revenue split in basis points:

• splitVendorBps: share paid to the vendor
• splitOperatorBps: share paid to the marketplace operator
• splitCommunityBps: share paid to the community fund

The three values must add up to 10_000, which represents 100%. For example, a 90 / 8 / 2 split sends 90% to the vendor, 8% to the operator, and 2% to the community fund.

This matters because the community contribution is not treated as a donation after the fact. It is part of the market design itself. When a marketplace enables regenerative distribution, every transaction can fund shared resources, local initiatives, cooperatives, climate projects, mutual aid pools, or any other community account represented by the marketplace.

On-chain, the split is enforced by the Soroban contract. During a purchase, the contract transfers the payment atomically to the vendor, operator, and community fund. If rounding leaves a tiny remainder, that remainder goes to the community fund so no value is lost.

Core Flows

1. An operator creates a marketplace and chooses the revenue split.
2. Compaki creates the operator and community fund payment accounts.
3. The marketplace is registered inside the shared Soroban contract.
4. Vendors join the marketplace and are registered on-chain by the operator.
5. Buyers purchase products through the storefront.
6. The contract settles the payment in one atomic split.
7. The sale record stores a transaction hash and a frozen split snapshot.
8. Receipts show the buyer exactly how the payment was distributed.

Architecture

Compaki is organized as a small monorepo:

apps/web/                 Next.js frontend app
  src/app/                App Router pages and UI
  src/lib/api.ts          Server-side API fetch helper

apps/api/                 Hono API server
  src/routes/             HTTP routes under /api/*
  src/lib/db/             Prisma client and shared database types
  src/lib/stellar/        Stellar and Soroban integration layer
  prisma/                 Prisma schema and migrations
  scripts/                Testnet deployment and demo data scripts

contracts/                Rust workspace for Soroban contracts
  marketplace/            Shared marketplace contract

The browser talks to the Next.js app. The web app rewrites /api/* requests to the standalone Hono API, so browser requests stay same-origin and session cookies work without a separate CORS setup.

The API owns all database and blockchain access. The frontend does not connect directly to Prisma, Stellar, or Soroban.

Blockchain Design

Compaki uses one deployed Soroban marketplace contract to support many marketplaces. Creating a marketplace does not deploy a new contract. Instead, the API calls create_marketplace, and the contract stores a new marketplace configuration keyed by marketplace_id.

Current Stellar testnet marketplace contract: CCCXYF55U6M44A6RK2WFUXEZDNPMCUI7YDR3YPBBEGWGEO4OSIGZQH2U

This address is generated by npm run deploy:testnet and can change if the testnet contract is redeployed.

The contract is intentionally focused:

• Store the payment token and contract admin.
• Register marketplace split configuration.
• Register vendors per marketplace.
• Execute atomic payment splits.
• Emit events for marketplace creation, vendor registration, and purchases.

Everything else, including users, sessions, product catalog, images, dashboards, and sale history, lives off-chain in Postgres.

Tech Stack

• Frontend: Next.js, React, TypeScript, Tailwind CSS
• API: Hono, Node.js, TypeScript
• Database: PostgreSQL through Prisma
• Blockchain: Stellar testnet, Soroban smart contracts, @stellar/stellar-sdk
• Contract: Rust with soroban-sdk

Prerequisites

• Node.js 18+
• npm
• Rust toolchain
• PostgreSQL database, such as Supabase Postgres
• Stellar testnet access

For Soroban contract deployment, install the WASM target once:

rustup target add wasm32v1-none

Environment

The API reads environment variables from apps/api/.env.local and then apps/api/.env.

At minimum, provide the database connection variables before running migrations:

DATABASE_URL="postgresql://..."
DIRECT_URL="postgresql://..."

The Stellar-related variables are generated by the testnet deployment script:

cd apps/api
npm run deploy:testnet

That script writes values such as:

• STELLAR_RPC_URL
• STELLAR_HORIZON_URL
• STELLAR_NETWORK_PASSPHRASE
• DEMO_USDC_ISSUER_PUBLIC
• DEMO_USDC_ISSUER_SECRET
• DEMO_USDC_SAC_ADDRESS
• MARKETPLACE_CONTRACT_ID
• WALLET_ENCRYPTION_KEY

The web app proxies API requests to http://localhost:4000 by default. Override it with API_URL when needed:

API_URL="http://localhost:4000"

Run Locally

Install and start the API:

cd apps/api
npm install
npm run prisma:migrate
npm run dev

In another terminal, install and start the web app:

cd apps/web
npm install
npm run dev

Open:

http://localhost:3000

The API runs on:

http://localhost:4000

Deploy Testnet Contracts

From the API app:

cd apps/api
npm run deploy:testnet

The deployment script:

• Creates and funds a demo asset issuer on Stellar testnet.
• Deploys the Stellar Asset Contract for the demo asset.
• Builds, uploads, and deploys the Soroban marketplace contract.
• Initializes the contract with the admin and payment token.
• Writes the resulting contract and wallet configuration to .env.local.

Seed Demo Data

Create a complete demo marketplace with vendors, products, sales, receipts, and real testnet transactions:

cd apps/api
npm run demo:seed

Run a smaller end-to-end purchase proof:

cd apps/api
npm run demo:purchase

Useful Commands

API:

cd apps/api
npm run dev
npm run build
npm run start
npm run typecheck
npm run prisma:migrate
npm run prisma:studio

Web:

cd apps/web
npm run dev
npm run build
npm run start
npm run lint
npm run typecheck

Contracts:

cd contracts
cargo test

Product Surfaces

• /onboarding: operator marketplace creation
• /marketplaces: public directory of every marketplace
• /m/{slug}: public storefront
• /m/{slug}/join: vendor onboarding
• /m/{slug}/p/{productId}: product detail page
• /m/{slug}/cart: cart (stored in a browser cookie until checkout)
• /m/{slug}/checkout/{orderId}: order checkout (shipping + payment)
• /orders: buyer's orders (pending and completed)
• /dashboard/{slug}: operator dashboard
• /vendor/{slug}: vendor dashboard (products and sales)
• /receipt/{saleId}: public transparent receipt

Data Model Notes

• Marketplace.contractMarketplaceId links an off-chain marketplace to its on-chain configuration.
• Marketplace.createTxHash stores the transaction that registered the marketplace on-chain.
• Marketplace.communityFundId points to the account receiving the community share.
• Sale.txHash stores the purchase transaction hash.
• Sale.splitSnapshot freezes the exact split used at purchase time, so future marketplace changes do not rewrite historical accounting.

Current Status

Compaki is an MVP designed to demonstrate verifiable marketplace settlement and regenerative revenue distribution on Stellar testnet. It is not production payment infrastructure yet. Production readiness would require non-testnet assets, stronger account custody or wallet-based flows, operational monitoring, formal contract review, and compliance work appropriate to the deployment jurisdiction.

Vision

Compaki is built for marketplaces where the health of the ecosystem matters as much as the transaction itself. A coffee cooperative, a farmers market, a local services network, or a creative community should be able to decide not only who gets paid, but how every sale strengthens the shared infrastructure around it.

That is the role of regenerative commerce: turning distribution rules into a living economic design, visible to buyers and enforceable at settlement.