PBay

Free, lightweight ecommerce for WordPress — powered by Cardano under the hood. Instant payments, instant payouts, cryptographic proof of every sale. No WooCommerce, no Stripe, no payment processor, no middleman.

PBay is a full marketplace plugin built on an ultra-light stack: WordPress + PHP + the Cardano blockchain. Sellers list products, buyers pay in ADA straight from their wallet, and the money lands in the seller's wallet in seconds — not days. Every product is backed by an on-chain NFT. Every purchase generates a tamper-proof receipt delivered directly to the buyer's wallet. No accounts, no passwords, no chargebacks.

---

What Makes This Different

Traditional ecommerce plugins sit on top of payment processors, subscription fees, and processing delays. PBay cuts all of that out:

• Instant settlement. Payments confirm on the Cardano network in seconds. No 3-5 business day holds, no rolling reserves, no processor taking a cut.
• Zero platform fees. No monthly subscription, no per-transaction percentage, no premium tiers. The plugin is free. Network fees are fractions of a cent.
• Tamper-proof receipts. Every purchase mints a cryptographic receipt delivered to the buyer's wallet — proof of purchase that can't be faked, altered, or lost.
• No accounts needed. Buyers connect a Cardano wallet to browse, buy, and track orders. No signups, no passwords, no email harvesting.
• Products backed by NFTs. Each listing is a CIP-25 NFT with metadata, images pinned to IPFS, and custom attributes — all verifiable on-chain.

The entire crypto stack runs in pure PHP. No Node.js, no Python, no external binaries. If your server runs WordPress, it runs PBay.

---

Key Features

• Server-side NFT minting - Ed25519 signing, CBOR encoding, and transaction submission happen entirely in PHP via encrypted policy wallets
• CIP-25 metadata with 64-character chunking, IPFS image pinning, and dynamic product attributes embedded on-chain
• Dual-output payments - merchant receives ADA payment + buyer receives 1 ADA receipt in a single atomic transaction
• Automatic NFT delivery - after payment confirmation, the product NFT transfers from the policy wallet to the buyer's wallet server-side
• CIP-30 wallet integration - uses CardanoPress for site-wide wallet connection (Nami, Eternl, Typhon, Lace, etc.)
• Gallery images on IPFS - up to 4 product images (1 main + 3 gallery) auto-pinned to IPFS via Pinata during minting
• Category-based policies - each product category auto-generates a Cardano native script policy with time-lock expiration
• Real-time USD/ADA conversion - CoinGecko price feed with 5-minute caching, exchange rate locked at purchase time
• Wallet-based order tracking - buyers connect their wallet on the orders page to see rich order cards with status, tracking numbers, and on-chain TX links
• Admin order management - status updates, shipping tracking, CSV export, and manual NFT delivery fallback button
• Frontend theme customizer - 4 presets (Glass Dark, Clean Light, Warm Dark, Midnight), custom color dropdowns for cards/text/accent/buttons, live preview, CSS variable injection
• Store wallet as payout - optionally route payments directly to the policy wallet, eliminating the need for a separate merchant address
• Drag-and-drop image upload - drop images directly onto the upload area in the listing wizard with visual feedback and instant upload
• Blockfrost integration - on-chain address lookups, wallet balance queries, and NFT asset discovery via Blockfrost API
• Zero external dependencies for crypto - Ed25519, BIP39, CBOR, Bech32 all implemented in pure PHP

---

Architecture Overview

                    SELLER (WordPress Admin)
                            |
          +-----------------+-----------------+
          |                 |                 |
    Create Listing    Mint NFT (PHP)    Manage Orders
          |                 |                 |
          v                 v                 v
    [WP Database]    [Anvil API]       [Order Dashboard]
          |           Build TX              |
          |           Sign (Ed25519)        |
          |           Submit                |
          |                 |               |
          |                 v               |
          |          [Cardano Network]      |
          |                 |               |
          +-----------------+---------------+
                            |
                    BUYER (Frontend)
                            |
          +-----------------+-----------------+
          |                 |                 |
    Browse Catalog    Pay with ADA     View Orders
    (Shortcodes)     (CIP-30 Wallet)  (Wallet Connect)
          |                 |                 |
          v                 v                 v
    [Product Page]   [Checkout Modal]  [Order History]
                     Build TX (Anvil)   NFT Delivery TX
                     Sign (Wallet)      Tracking Info
                     Submit             Explorer Links
                     Create Order
                     Deliver NFT

Core Components

Component	Purpose
CardanoWalletPHP	BIP39 mnemonic generation, CIP-1852 key derivation, Bech32 address encoding
CardanoTransactionSignerPHP	CBOR transaction parsing, Ed25519 signing, witness set construction
Ed25519Compat / Ed25519Pure	Pure PHP Ed25519 with triple fallback (native sodium / FFI / BCMath)
AnvilAPI	Transaction building, policy generation, address conversion, TX submission
PinataAPI	IPFS image uploads via Pinata (CIDv0, auto-pin on mint)
MetadataHelper	CIP-25 metadata construction with 64-char chunking for on-chain compliance
EncryptionHelper	AES-256-CBC encryption of wallet keys using WordPress security salts
PriceHelper	CoinGecko ADA/USD price feed with transient caching
BlockfrostAPI	On-chain queries: address balances, asset metadata, UTxO lookups

---

How It Works

1. Seller Creates a Listing

Six-step wizard: upload images, set title/description/category, set USD price (ADA auto-calculated), add custom attributes, configure shipping, review NFT metadata preview.

2. Seller Publishes (Mints the NFT)

One click triggers the full pipeline:

Upload Image(s)
    |
Auto-Pin to IPFS (Pinata)
    |
Build CIP-25 Metadata
    |-- name, image (ipfs://), description (chunked)
    |-- priceUSD, category, condition, quantity
    |-- seller, custom attr_* fields
    |-- files[] array (main + gallery images)
    |
Resolve Policy (from listing category)
    |
Build Mint TX (Anvil API)
    |-- changeAddress: policy wallet
    |-- outputs: [{policy wallet, 2 ADA, assets: [{policyId, assetName, qty: 1}]}]
    |-- mint: [{version: 'cip25', metadata: ...}]
    |-- preloadedScripts: [{type: 'simple', script, hash}]
    |
Sign TX Server-Side
    |-- Decrypt policy wallet skey (AES-256-CBC)
    |-- Ed25519 extended key signing (kL||kR)
    |-- Construct witness set (CBOR)
    |
Submit via Anvil
    |
Listing Status: draft -> active
    |-- mint_tx_hash stored
    |-- published_at timestamp set

3. Buyer Purchases

Connect Wallet (CIP-30 via CardanoPress)
    |
Enter Shipping Info
    |
Review Order (live ADA price)
    |
Build Payment TX (Server)
    |-- Anvil resolves buyer UTxOs on-chain
    |-- Output 1: merchant_address + payment in ADA
    |-- Output 2: buyer_address + 1 ADA receipt
    |
Sign in Wallet (CIP-30 signTx, partial)
    |
Submit Payment TX (Server -> Anvil)
    |
Create Order Record (status: 'paid')
    |
Attempt NFT Delivery (non-blocking)
    |-- Build transfer TX: policy wallet -> buyer
    |-- Sign server-side with policy wallet
    |-- Submit via Anvil
    |-- Store nft_delivery_tx_hash on order
    |
Return Confirmation
    |-- Order ID (PBAY-XXXX-XXXX)
    |-- Payment TX hash + Cardanoscan link
    |-- NFT delivery TX hash + link

4. Buyer Views Orders

No login. Connect wallet on the orders page - all orders for that address appear as rich cards showing product image, status badge, price, tracking number, payment TX link, and NFT delivery TX link.

---

Installation

Requirements

• WordPress 5.0+ with PHP 7.2+ (PHP 8.0+ recommended)
• CardanoPress plugin for CIP-30 wallet connection in the site header
• Ada Anvil API key for transaction building and submission
• Pinata JWT (optional but recommended) for IPFS image pinning

Setup

1. Clone or download into wp-content/plugins/pbay/
2. Activate via WordPress admin
3. Navigate to PBay > Setup:
   • Select network (preprod for testing, mainnet for production)
   • Enter Anvil API key (preprod and/or mainnet)
   • Enter Blockfrost API key (for wallet balance queries)
   • Enter merchant wallet address (where payments go), or check "Use store wallet as payout wallet" to route payments to the policy wallet
   • Enter Pinata JWT (optional, for IPFS image pinning)
4. Navigate to PBay > Policy Wallet:
   • Generate a policy wallet (save the mnemonic!)
   • Fund it with ~10 ADA on the selected network
5. Navigate to PBay > Listing Categories:
   • Create a category (auto-generates a Cardano policy)
6. Create a WordPress page with shortcode [pbay-catalog] for your storefront
7. Create a WordPress page with slug pbay-orders and shortcode [pbay-orders] for buyer order history
8. (Optional) Navigate to PBay > Appearance to customize the frontend theme

---

Shortcodes

[pbay-catalog]

Renders a responsive product grid with category filtering. When a product is clicked, renders the full product detail page with gallery, specs, and checkout modal.

Attribute	Default	Description
category	all	Filter by category name
limit	24	Products per page
columns	4	Grid columns

Supports URL parameters: ?pbay_cat=Electronics for category filtering, ?pbay_product=123 for direct product links.

[pbay-product id="X"]

Renders a single product detail page. Supports id or slug attribute.

[pbay-orders]

Buyer order history. Auto-detects CardanoPress wallet connection and displays all orders for that address.

---

Database Schema

5 Tables

Table	Purpose
pbay_policy_wallets	Encrypted Cardano wallets (mnemonic + signing key in AES-256-CBC)
pbay_listing_categories	Product categories with auto-generated Cardano policies
pbay_listings	Product listings with NFT metadata, IPFS CIDs, pricing, stock
pbay_listing_meta	Dynamic key-value attributes per listing (embedded in NFT metadata)
pbay_orders	Purchase records with payment TX, NFT delivery TX, shipping, tracking

---

CIP-25 NFT Metadata

Every minted listing produces compliant CIP-25 metadata:

{
  "721": {
    "<policy_id>": {
      "PBAY_42_1706000000": {
        "name": "Vintage Fender Stratocaster 1962",
        "image": "ipfs://QmXyz...",
        "mediaType": "image/png",
        "description": ["A beautiful vintage guitar in excellent c", "ondition. Original pickups and hardware."],
        "priceUSD": "2500.00",
        "category": "Musical Instruments",
        "condition": "Very Good",
        "quantity": "1",
        "seller": "Guitar Palace",
        "attr_year": "1962",
        "attr_color": "Sunburst",
        "attr_brand": "Fender",
        "files": [
          {"name": "Vintage Fender Stratocaster 1962", "mediaType": "image/png", "src": "ipfs://QmXyz..."},
          {"name": "Vintage Fender Stratocaster 1962 2", "mediaType": "image/png", "src": "ipfs://QmAbc..."},
          {"name": "Vintage Fender Stratocaster 1962 3", "mediaType": "image/png", "src": "ipfs://QmDef..."}
        ]
      }
    }
  }
}

All string values are automatically chunked to 64-character arrays when they exceed Cardano's metadata field limit. Gallery images are included in the files array for explorer compatibility (pool.pm, Cardanoscan, jpg.store).

---

NFT Delivery

Automatic (On Purchase)

After payment is confirmed, PBay immediately attempts to transfer the product NFT from the policy wallet to the buyer's wallet:

1. Build asset transfer TX via Anvil (policy wallet -> buyer, 2 ADA min UTxO + NFT)
2. Sign server-side with the encrypted policy wallet key
3. Submit to network
4. Store nft_delivery_tx_hash on the order

This is wrapped in a try-catch - if delivery fails, the order still succeeds. The buyer got their product, the payment went through, and the admin can retry NFT delivery manually.

Manual Fallback (Admin)

On the order detail page, if NFT delivery hasn't happened yet, an admin button appears: "Send NFT to Buyer". Same build-sign-submit flow, triggered manually. Double-send prevention checks that nft_delivery_tx_hash is null before allowing.

Edge Cases Handled

• Listing has no NFT (physical-only product without minting): delivery skipped entirely
• Policy wallet has no ADA: Anvil build fails, caught and logged, order still succeeds
• NFT already transferred: Anvil can't find asset UTxO, fails gracefully
• Concurrent purchases: UTxO contention possible, failed delivery caught, admin can retry

---

Security

Wallet Key Storage

Policy wallet private keys are encrypted at rest using AES-256-CBC:

Key = SHA256(AUTH_KEY + SECURE_AUTH_KEY + LOGGED_IN_KEY + NONCE_KEY)
IV  = random 16 bytes (prepended to ciphertext)
Stored = base64(IV || AES-256-CBC(plaintext, key, IV))

Keys are only decrypted in memory during signing operations and never logged or displayed after initial generation.