Skip to main content

Smart Contracts Overview

DolphinPay's on-chain logic is a single Move package (contract/) on Sui. It implements a deliberately small surface: USDC payment lifecycle, merchant registration, and admin governance.

What the contracts do​

  • Accept payments in native Circle USDC only (6 decimals). The allowed coin type is stored in the shared AdminConfig and enforced on every payment creation and execution.
  • Apply a global, admin-managed platform fee, currently 0 bps by policy. A non-zero fee requires a configured treasury and is capped at 1000 bps (10%) by the contract. Merchants have no fee configuration.
  • Provide no on-chain refunds (ADR-004). The Payment struct retains refundable/refund_window fields for layout compatibility; they are always false/0.

Modules​

Exactly four modules exist, all under contract/sources/core/:

ModuleFileResponsibility
dolphinpay::paymentpayment.movePayment creation, execution, cancellation, queries
dolphinpay::merchantmerchant.moveMerchant registration, receiving addresses, status
dolphinpay::adminadmin.moveAdminCap-gated fee, treasury, allowed-currency policy, merchant overrides, platform stats
dolphinpay::eventsevents.moveEvent structs and emit helpers for off-chain indexing

There is no token registry, batch payment, payment splitting, subscription, DeFi/DEX, risk-management, or refund module.

contract/sources/
└── core/
    ├── payment.move
    ├── merchant.move
    ├── admin.move
    └── events.move

Key objects​

  • AdminConfig (shared) — platform fee bps, treasury address, the single allowed currency (Option<TypeName>), and platform statistics. Created in admin::init at publish time.
  • AdminCap (owned by deployer) — required for all governance functions.
  • Merchant (shared) + MerchantCap (owned) — merchant record and the capability that authorizes changes to it.
  • Payment (key, store) — one object per payment, holding amount (USDC base units), currency TypeName, status, expiry, and metadata.

Security model​

  • Capability-based authorization: AdminCap for governance, MerchantCap for merchant settings. Payment cancellation is restricted to the payment's merchant address.
  • Currency policy: admin::assert_currency_allowed aborts payment creation and execution until the admin sets the allowed currency, and whenever the coin type differs from it.
  • Checks-effects-interactions: payment status, payer, and completion timestamp are written before any coin transfer.
  • Overflow-safe fees: fee math is done in u128 (amount * fee_bps / 10000).
  • Input validation: non-zero merchant address, amount in (0, 1_000_000_000_000] base units (max 1,000,000 USDC), description ≤ 500 chars, ≤ 10 metadata entries, expiry ≤ 1 year.

Deployment status​

The current Sui Testnet deployment is live. Current deployment IDs live only in DEPLOYMENT.md at the repository root; the previously published testnet package is defunct and must not be used. There is no mainnet deployment.

On the live project deployment, the allowed currency is already configured to testnet native Circle USDC. If you self-publish your own package, the admin must call admin::set_allowed_currency<USDC> — payments abort until the allowed currency is set. Testnet native Circle USDC:

0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC

Building and testing​

cd contract
sui move build
sui move test

Reference pages​