SDK Initialization 🔧

This guide covers how to properly initialize the DolphinPay TypeScript SDK for different networks and use cases.

Basic Initialization

Import and Create Client

import { createClient } from "@dolphinpay/sdk"

// Basic initialization with testnet
const client = createClient({
  packageId:
    "0x9c7ca262d020b005e0e6b6a5d083b329d58716e0d80c07b46804324074468f9c",
  network: "testnet",
})

Configuration Options

interface ClientConfig {
  packageId: string // DolphinPay package ID
  network: Network // Network type
  rpcUrl?: string // Custom RPC endpoint
}

Network Configuration

Supported Networks

The SDK supports all Sui networks:

type Network = "mainnet" | "testnet" | "devnet" | "localnet"

Testnet (Recommended for Development)

const testnetClient = createClient({
  packageId:
    "0x9c7ca262d020b005e0e6b6a5d083b329d58716e0d80c07b46804324074468f9c",
  network: "testnet",
  // Optional: custom RPC endpoint
  rpcUrl: "https://fullnode.testnet.sui.io:443",
})

Mainnet (Production)

const mainnetClient = createClient({
  packageId: "0xyour_mainnet_package_id",
  network: "mainnet",
  rpcUrl: "https://fullnode.mainnet.sui.io:443",
})

Local Development

const localClient = createClient({
  packageId: "0xlocal_package_id",
  network: "localnet",
  rpcUrl: "http://127.0.0.1:9000",
})

Custom RPC Endpoints

For improved performance or reliability, you can specify custom RPC endpoints:

// High-performance RPC
const client = createClient({
  packageId: "0x...",
  network: "testnet",
  rpcUrl: "https://sui-testnet-rpc.allthatnode.com",
})

// Enterprise RPC with authentication
const client = createClient({
  packageId: "0x...",
  network: "mainnet",
  rpcUrl: "https://your-enterprise-rpc.com/sui",
})

Environment-Based Configuration

Development Setup

Create environment configuration for different environments:

// config/development.ts
export const config = {
  network: "testnet" as const,
  packageId:
    "0x9c7ca262d020b005e0e6b6a5d083b329d58716e0d80c07b46804324074468f9c",
  rpcUrl: "https://fullnode.testnet.sui.io:443",
}

// config/production.ts
export const config = {
  network: "mainnet" as const,
  packageId: "0xyour_production_package_id",
  rpcUrl: "https://fullnode.mainnet.sui.io:443",
}

Environment Variables

# .env.local
DOLPHINPAY_NETWORK=testnet
DOLPHINPAY_PACKAGE_ID=0x9c7ca262d020b005e0e6b6a5d083b329d58716e0d80c07b46804324074468f9c
DOLPHINPAY_RPC_URL=https://fullnode.testnet.sui.io:443

// Using environment variables
const client = createClient({
  packageId: process.env.DOLPHINPAY_PACKAGE_ID!,
  network: process.env.DOLPHINPAY_NETWORK as Network,
  rpcUrl: process.env.DOLPHINPAY_RPC_URL,
})

Client Modules

The initialized client provides access to different modules:

const client = createClient({
  packageId: '0x...',
  network: 'testnet',
});

// Payment operations
client.payment.buildCreatePayment(...)
client.payment.buildExecutePayment(...)
client.payment.getPayment(...)

// Merchant operations
client.merchant.buildRegisterMerchant(...)
client.merchant.buildConfigureMerchantFees(...)
client.merchant.getMerchant(...)

// Utility functions (global)
client.utils.suiToMist(...)
client.utils.calculateFee(...)

Error Handling

Initialization Errors

try {
  const client = createClient({
    packageId: "0xinvalid_package_id",
    network: "invalid_network",
  })
} catch (error) {
  console.error("Failed to initialize client:", error.message)
  // Handle initialization failure
}

Network Connection Issues

// Check network connectivity
try {
  const chainId = await client.provider.getChainIdentifier()
  console.log("Connected to network:", chainId)
} catch (error) {
  console.error("Network connection failed:", error.message)
  // Handle network issues
}

Advanced Configuration

Multiple Clients

For applications that need to interact with multiple networks:

// Testnet client for development
const testnetClient = createClient({
  packageId: "0xtestnet_package_id",
  network: "testnet",
})

// Mainnet client for production
const mainnetClient = createClient({
  packageId: "0xmainnet_package_id",
  network: "mainnet",
})

// Switch between clients based on environment
const activeClient =
  process.env.NODE_ENV === "production" ? mainnetClient : testnetClient

Custom Provider Configuration

import { SuiClient } from "@mysten/sui.js/client"
import { createClient } from "@dolphinpay/sdk"

// Custom provider with specific settings
const customProvider = new SuiClient({
  url: "https://your-custom-rpc.com",
  // Additional configuration
})

const client = createClient({
  packageId: "0x...",
  network: "testnet",
  provider: customProvider, // Use custom provider
})

Validation and Testing

Validate Configuration

import { validateClientConfig } from "@dolphinpay/sdk"

const config = {
  packageId:
    "0x9c7ca262d020b005e0e6b6a5d083b329d58716e0d80c07b46804324074468f9c",
  network: "testnet",
}

// Validate configuration before creating client
const validation = validateClientConfig(config)
if (!validation.valid) {
  throw new Error(`Invalid configuration: ${validation.errors.join(", ")}`)
}

const client = createClient(config)

Test Network Connection

async function testConnection(client) {
  try {
    // Test basic connectivity
    const chainId = await client.provider.getChainIdentifier()
    console.log("✅ Connected to:", chainId)

    // Test package exists
    const packageInfo = await client.provider.getObject({
      id: client.config.packageId,
      options: { showType: true },
    })

    if (packageInfo.error) {
      throw new Error("Package not found on network")
    }

    console.log("✅ Package verified:", client.config.packageId)
    return true
  } catch (error) {
    console.error("❌ Connection test failed:", error.message)
    return false
  }
}

Best Practices

1. Use Environment Variables

// ✅ Good: Environment-based configuration
const client = createClient({
  packageId: process.env.NEXT_PUBLIC_DOLPHINPAY_PACKAGE_ID!,
  network: process.env.NEXT_PUBLIC_DOLPHINPAY_NETWORK as Network,
  rpcUrl: process.env.NEXT_PUBLIC_DOLPHINPAY_RPC_URL,
})

// ❌ Bad: Hardcoded values
const client = createClient({
  packageId: "0xhardcoded_package_id",
  network: "testnet",
})

2. Implement Connection Testing

// ✅ Good: Test before using
class DolphinPayService {
  private client: DolphinPayClient | null = null

  async initialize() {
    const isConnected = await testConnection(this.client)
    if (!isConnected) {
      throw new Error("Failed to connect to DolphinPay network")
    }
  }

  async createPayment(params) {
    if (!this.client) {
      await this.initialize()
    }
    return this.client.payment.buildCreatePayment(params)
  }
}

3. Handle Network Switching

// ✅ Good: Network-aware configuration
const NETWORK_CONFIGS = {
  testnet: {
    packageId:
      "0x9c7ca262d020b005e0e6b6a5d083b329d58716e0d80c07b46804324074468f9c",
    rpcUrl: "https://fullnode.testnet.sui.io:443",
  },
  mainnet: {
    packageId: "0xmainnet_package_id",
    rpcUrl: "https://fullnode.mainnet.sui.io:443",
  },
}

function createNetworkClient(network: Network) {
  const config = NETWORK_CONFIGS[network]
  return createClient({
    ...config,
    network,
  })
}

Troubleshooting

Common Initialization Issues

"Invalid package ID format"

// ❌ Wrong format
createClient({
  packageId: "package_id_without_0x",
  network: "testnet",
})

// ✅ Correct format
createClient({
  packageId: "0x1234567890abcdef...",
  network: "testnet",
})

"Network connection failed"

// Check if RPC endpoint is accessible
const response = await fetch("https://fullnode.testnet.sui.io:443", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "sui_getChainIdentifier",
    params: [],
  }),
})

if (!response.ok) {
  console.error("RPC endpoint not accessible")
}

"Package not found on network"

// Verify package exists on the network
const packageInfo = await client.provider.getObject({
  id: packageId,
  options: { showType: true },
})

if (packageInfo.error) {
  console.error("Package not deployed to this network")
  console.log("Available networks: testnet, mainnet")
}

Next Steps

Now that your SDK is initialized:

Payment Operations - Learn how to create and manage payments
Merchant Operations - Set up and manage merchant accounts
Event Querying - Track payment history and analytics

Ready to build? Check out the payment operations guide to start creating payments!

Basic Initialization​

Import and Create Client​

Configuration Options​

Network Configuration​

Supported Networks​

Testnet (Recommended for Development)​

Mainnet (Production)​

Local Development​

Custom RPC Endpoints​

Environment-Based Configuration​

Development Setup​

Environment Variables​

Client Modules​

Error Handling​

Initialization Errors​

Network Connection Issues​

Advanced Configuration​

Multiple Clients​

Custom Provider Configuration​

Validation and Testing​

Validate Configuration​

Test Network Connection​

Best Practices​

1. Use Environment Variables​

2. Implement Connection Testing​

3. Handle Network Switching​

Troubleshooting​

Common Initialization Issues​

Next Steps​