Skip to main content

Environment Setup

This guide sets up a complete development environment for DolphinPay: contracts, SDK, frontend, and docs.

Prerequisites​

Verify:

bun --version
sui --version   # >= 1.76.1

Sui CLI configuration​

# Switch to testnet
sui client switch --env testnet

# Check (or create) your active address
sui client active-address
# sui client new-address ed25519   # if you have none

# Verify connectivity
sui client chain-identifier

Get testnet tokens​

DolphinPay payments are native Circle USDC only; SUI is used only for gas.

Check balances with sui client balance.

Clone and build​

git clone https://github.com/DolphinsLab/dolphin-pay.git
cd dolphin-pay

# Contracts
cd contract
sui move build
sui move test

# SDK
cd ../sdk
bun install
bun run typecheck
bun run build

# Frontend
cd ../frontend
bun install
bun run build

# Docs (optional)
cd ../docs
bun install
bun run build

Environment configuration​

All package and object IDs come from DEPLOYMENT.md at the repository root — it is the single source of truth for deployment status and IDs. The official Testnet deployment is live, and the current Package ID and AdminConfig ID are listed there; never copy IDs from old commits or historical documents — earlier published packages are defunct.

Frontend​

Create frontend/.env.local:

NEXT_PUBLIC_SUI_NETWORK=testnet
NEXT_PUBLIC_PACKAGE_ID=<PACKAGE_ID from DEPLOYMENT.md>
NEXT_PUBLIC_ADMIN_CONFIG_ID=<ADMIN_CONFIG_ID from DEPLOYMENT.md>

For Cloudflare Workers deployments, the same variables live in frontend/wrangler.jsonc under vars.

SDK live tests (opt-in, read-only)​

The SDK's live test suite runs against the current Testnet deployment. It is read-only (it only queries on-chain state; no transactions are signed or submitted) and is skipped unless you explicitly opt in with DOLPHINPAY_LIVE_TESTS=1:

cd sdk
DOLPHINPAY_LIVE_TESTS=1 \
DOLPHINPAY_PACKAGE_ID=<PACKAGE_ID> \
DOLPHINPAY_ADMIN_CONFIG_ID=<ADMIN_CONFIG_ID> \
bun run test:live
Transport

The SDK talks to Sui exclusively over gRPC (SuiGrpcClient). There is no JSON-RPC data client, no GraphQL transport, and no websocket service. If you pass a custom endpoint via grpcUrl, it must be a gRPC fullnode endpoint.

Verification checklist​

  • Sui CLI ≥ 1.76.1 installed, testnet active, address funded with SUI (gas)
  • Testnet USDC in your wallet (Circle faucet)
  • sui move build and sui move test pass in contract/
  • bun run typecheck and bun run build pass in sdk/
  • bun run build passes in frontend/
  • frontend/.env.local populated from DEPLOYMENT.md

Common issues​

Port 3000 in use

lsof -i :3000
PORT=3001 bun run dev

Payments abort on-chain — the contract rejects any coin type other than the allowed currency in AdminConfig (native Circle USDC). Make sure you're paying with testnet USDC, not SUI, and that your IDs match the current deployment.

Stale IDs — if objects can't be found, re-check DEPLOYMENT.md; earlier published packages are defunct.

Next steps​

  1. Quick Start — build your first payment integration
  2. Testnet Deployment — publish your own package (optional)
  3. Basic Payment Example — complete integration example