Skip to main content

What is DolphinPay?

DolphinPay is a decentralized USDC payment gateway built on the Sui blockchain. Merchants create payment requests; payers execute them from their own wallets; funds settle on-chain in native Circle USDC.

What it does​

  • One-time payments — create, execute, and cancel payment requests with expiry
  • USDC only — native Circle USDC (6 decimals), enforced on-chain against the shared AdminConfig
  • Zero platform fee — 0 bps by policy; the fee is admin-managed on-chain (10% hard ceiling, and a non-zero fee requires a configured treasury). Merchants have no fee configuration.
  • Merchant management — registration, per-currency receiving addresses, active-status control, capability-based authorization (MerchantCap)
  • Admin governance — AdminCap-gated platform configuration: fee, treasury, allowed currency, merchant overrides
  • TypeScript SDK — transaction builders and gRPC queries (SuiGrpcClient); no JSON-RPC, no websockets
  • Next.js frontend — merchant onboarding, payment creation with shareable links, universal checkout page; deployed to Cloudflare Workers via OpenNext

What it does not do​

  • ❌ No on-chain refunds (per ADR-004)
  • ❌ No multi-currency payments — a single allowed currency (native Circle USDC) is enforced by the contract
  • ❌ No batch/split payments, subscriptions, or DeFi features
  • ❌ No merchant-configured fees
  • ❌ No mainnet deployment — testnet is the target network; mainnet requires explicit approval

SUI is used only for gas. Payment amounts are always USDC in 6-decimal base units.

Architecture​

┌─────────────────┐    ┌─────────────────┐    ┌──────────────────┐
│    Frontend     │    │       SDK       │    │  Smart Contracts │
│   (Next.js on   │◄──►│  (TypeScript,   │◄──►│      (Move)      │
│   CF Workers)   │    │   gRPC-only)    │    │                  │
│ - Wallet connect│    │ - Tx builders   │    │ - payment        │
│ - Checkout page │    │ - USDC utils    │    │ - merchant       │
│ - Merchant UI   │    │ - Event queries │    │ - admin, events  │
└─────────────────┘    └─────────────────┘    └──────────────────┘
                                │
                       Sui Testnet (gRPC)
  • Move contracts (contract/): payment lifecycle, merchant registry, AdminCap-gated governance, events for off-chain indexing
  • SDK (sdk/): the application data boundary — builds transactions for every entry function and parses chain state; you sign and execute with your own wallet
  • Frontend (frontend/): Next.js 15 App Router with @mysten/dapp-kit for wallet plumbing

Quick example​

The SDK is not yet published as a stable npm registry package. Build it from source, then add it to your app as a local file dependency (the exact relative path depends on where your app lives — frontend/ in this repository uses file:../sdk):

git clone https://github.com/DolphinsLab/dolphin-pay.git
cd dolphin-pay/sdk
bun install
bun run build
{
  "dependencies": {
    "@dolphinpay/sdk": "file:../dolphin-pay/sdk"
  }
}
import { createClient, usdcToUnits, USDC_TYPES } from '@dolphinpay/sdk';

// IDs come from DEPLOYMENT.md at the repository root — never hard-code them
const client = createClient({
  network: 'testnet',
  packageId: '<PACKAGE_ID>',
  adminConfigId: '<ADMIN_CONFIG_ID>',
});

// Create a payment for 10 USDC (6-decimal base units)
const txb = client.payment.buildCreatePayment({
  merchant: '0xMERCHANT_ADDRESS',
  amount: usdcToUnits('10'),
  currencyType: USDC_TYPES.testnet,
  description: 'Payment for order #123',
  expirySeconds: 3600,
});

// Sign and execute with the user's wallet (e.g. @mysten/dapp-kit)
await signAndExecuteTransaction({ transaction: txb });

Deployment status​

DolphinPay is deployed on Sui Testnet. The current Package ID and shared AdminConfig object ID are recorded in DEPLOYMENT.md at the repository root — that file is the single source of truth; do not use IDs from old docs or commits. Any previously published package is defunct, and there is no mainnet deployment (mainnet requires explicit approval).

Tech stack​

  • Blockchain: Sui Testnet
  • Smart contracts: Move
  • SDK: TypeScript + Bun, Sui gRPC transport (SuiGrpcClient)
  • Frontend: Next.js 15 (App Router), shadcn/ui + Tailwind, @mysten/dapp-kit
  • Hosting: Cloudflare Workers via @opennextjs/cloudflare
  • Docs: Docusaurus

Where to go next​

License​

DolphinPay is released under the MIT License.