Skip to main content

Smart Contracts Overview 🏗️

DolphinPay's smart contracts are built using the Move programming language on the Sui blockchain, providing a secure and efficient foundation for decentralized payments.

Architecture Overview​

The DolphinPay smart contract system is organized into modular components that work together to provide comprehensive payment functionality:

┌─────────────────────────────────────────────────────────────┐
│                    DolphinPay Contracts                     │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
│  │   Payment   │ │  Merchant   │ │     Advanced        │   │
│  │   Module    │ │  Module     │ │     Features        │   │
│  │             │ │             │ │                     │   │
│  │ • Create    │ │ • Register  │ │ • Multi-currency    │   │
│  │ • Execute   │ │ • Configure │ │ • Batch payments    │   │
│  │ • Cancel    │ │ • Manage    │ │ • Subscriptions     │   │
│  │ • Query     │ │             │ │ • DeFi integration  │   │
│  └─────────────┘ └─────────────┘ └─────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │                 Events & Security                       │ │
│  │                                                         │ │
│  │ • Event emission    • Access control   • Reentrancy     │ │
│  │ • Input validation  • Overflow protection • Time locks   │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Core Modules​

Payment Module (payment.move)​

The core payment engine that handles:

  • Payment Creation: Generate payment requests with customizable parameters
  • Payment Execution: Process payments with automatic fee calculation
  • Payment Lifecycle: Manage payment states (pending, completed, cancelled, expired)
  • Query Operations: Retrieve payment information and history

Key Features:

  • Automatic fee calculation (platform + merchant fees)
  • Expiry time enforcement
  • Event emission for all state changes
  • Comprehensive validation

Merchant Module (merchant.move)​

Manages merchant accounts and configurations:

  • Merchant Registration: Onboard new merchants with verification
  • Fee Configuration: Set custom merchant fees (0-10%)
  • Multi-Currency Support: Add/remove supported currencies
  • Address Management: Configure receiving addresses per currency

Key Features:

  • Merchant capability system for secure operations
  • Flexible fee structures
  • Currency-specific configurations
  • Status management (active/inactive)

Advanced Features​

Multi-Currency System​

  • Token Registry: Centralized registry of supported tokens
  • Batch Payments: Process multiple payments in single transaction
  • Payment Splitting: Automatic fund distribution to multiple recipients
  • DEX Integration: Support for token swaps and routing

Subscription Management​

  • Plan Management: Create and configure subscription plans
  • Auto-Renewal: Automated recurring payments with retry logic
  • Lifecycle Management: Handle upgrades, downgrades, and cancellations
  • Analytics: Track subscription metrics and revenue

DeFi Integration​

  • DEX Routing: Find optimal exchange routes across multiple DEXes
  • Auto-Swap Payments: Accept any token with automatic conversion
  • Liquidity Aggregation: Split orders across multiple pools for best prices
  • Slippage Protection: Set maximum acceptable price impact

Risk Management​

  • Transaction Limits: Set per-user, daily, and monthly limits
  • Access Control: Whitelist/blacklist management
  • Anomaly Detection: Real-time fraud detection algorithms
  • Fund Freezing: Emergency freeze capabilities for suspicious activity

Refund System​

  • Automated Refunds: Process refunds with configurable approval requirements
  • Multi-Sig Approval: Require multiple signatures for large refunds
  • Dispute Resolution: Handle payment disputes with evidence submission
  • Partial Refunds: Support partial refund amounts

Security Architecture​

Access Control​

// Admin capabilities - only contract deployer
struct AdminCap has key { id: UID }

// Merchant capabilities - given to registered merchants
struct MerchantCap has key { id: UID, merchant_id: ID }

// Operator capabilities - for support staff
struct OperatorCap has key { id: UID, permissions: u64 }

Input Validation​

  • Amount Limits: Enforce minimum (0.0001 SUI) and maximum (1000 SUI) payment amounts
  • Address Validation: Zero address and malformed address checks
  • Time Validation: Expiry time bounds and timestamp verification
  • String Length: Description and metadata length limits

Overflow Protection​

  • Safe Math: All arithmetic operations use checked operations
  • u128 Usage: Fee calculations use u128 to prevent overflow
  • Percentage Limits: Fee percentages capped at reasonable limits (0-10%)

Gas Optimization​

Efficient Operations​

  • Batch Processing: Combine multiple operations into single transactions
  • Object Reuse: Minimize object creation and destruction
  • Parallel Execution: Leverage Sui's parallel processing capabilities
  • Event Compression: Optimized event structures for minimal gas usage

Gas Estimation​

// Typical gas costs (testnet estimates)
create_payment:        ~0.01 SUI
execute_payment:       ~0.015 SUI
register_merchant:     ~0.015 SUI
batch_payment (10):    ~0.05 SUI

Development Workflow​

1. Local Development​

# Start local Sui network
sui start

# Build contracts
sui move build

# Run tests
sui move test

# Deploy locally
sui client publish --gas-budget 100000000

2. Testing​

# Run all tests
sui move test

# Run specific test suite
sui move test payment_tests
sui move test merchant_tests

# Run with coverage
sui move test --coverage

3. Deployment​

# Deploy to testnet
sui client publish --gas-budget 100000000

# Verify deployment
sui client object <PACKAGE_ID>

Module Structure​

sources/
├── core/
│   ├── payment.move      # Payment lifecycle management
│   ├── merchant.move     # Merchant registration and config
│   └── events.move       # Event definitions
├── tokens/
│   ├── registry.move     # Token registration and management
│   ├── batch.move        # Batch payment operations
│   └── split.move        # Payment splitting logic
├── subscription/
│   ├── plan.move         # Subscription plan management
│   ├── subscription.move # Subscription lifecycle
│   └── renewal.move      # Auto-renewal logic
├── defi/
│   ├── router.move       # DEX routing and swapping
│   └── aggregator.move   # Liquidity aggregation
├── refund/
│   ├── refund.move       # Refund processing
│   ├── multisig.move     # Multi-signature approvals
│   └── dispute.move      # Dispute resolution
└── risk/
    ├── limits.move       # Transaction limits
    ├── access_control.move # Blacklist/whitelist
    ├── anomaly.move      # Fraud detection
    └── freeze.move       # Emergency freezing

Key Benefits​

For Developers​

  • Modular Design: Easy to extend and customize
  • Type Safety: Move's strong typing prevents runtime errors
  • Comprehensive Testing: 100+ tests covering all functionality
  • Gas Efficient: Optimized for low transaction costs

For Users​

  • Security: Multiple layers of validation and protection
  • Transparency: All operations emit detailed events
  • Reliability: Extensive testing and security audits
  • Performance: Fast execution leveraging Sui's architecture

For Merchants​

  • Flexibility: Configure fees, currencies, and payment methods
  • Control: Full control over merchant settings and operations
  • Analytics: Rich event data for business intelligence
  • Integration: Easy SDK integration with existing systems

Next Steps​

Ready to dive deeper?

Questions? Check out the SDK documentation to start building with DolphinPay!