Skip to main content

Testnet Deployment

This guide covers publishing the DolphinPay Move package to Sui testnet and configuring it for use.

Most users don't need this

The official project Testnet deployment is live, with the allowed currency (native Circle USDC) already configured. DEPLOYMENT.md at the repository root is the sole source of truth for the current Package ID and AdminConfig ID — use those to integrate. Follow this guide only if you are an operator who intentionally wants to publish your own Testnet package.

No mainnet

Deploying to Sui Mainnet is not permitted without explicit approval. All instructions here target testnet.

Prerequisites​

  • Sui CLI ≥ 1.76.1, testnet environment active
  • Testnet SUI for gas: https://faucet.sui.io
  • Contracts build cleanly: cd contract && sui move build
sui client switch --env testnet
sui client active-env      # should print "testnet"
sui client balance

Step 1: Build and test​

cd contract
sui move build
sui move test              # all 48 tests should pass

The package contains four modules: payment, merchant, admin, and events.

Step 2: Publish​

sui client publish --gas-budget 500000000

From the publish output, record:

  • Package ID — the immutable Move package
  • AdminConfig ID — a shared object of type <PACKAGE_ID>::admin::AdminConfig
  • AdminCap ID — an object of type <PACKAGE_ID>::admin::AdminCap owned by the deployer
tip

contract/scripts/deploy-testnet.sh performs the publish and configuration in one shot.

Step 3: Configure the allowed currency (required)​

The contract enforces a single allowed currency from AdminConfig. Payments abort until this is set. DolphinPay uses testnet native Circle USDC:

sui client call \
  --package <PACKAGE_ID> --module admin --function set_allowed_currency \
  --type-args 0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC \
  --args <ADMIN_CAP_ID> <ADMIN_CONFIG_ID>

Step 4: Fee policy (leave at 0)​

The platform fee lives in AdminConfig and is read at payment execution time. It is 0 bps by policy; the contract enforces a 10% ceiling, and any non-zero fee requires a configured treasury (admin::set_treasury) plus explicit product approval. Merchants have no fee configuration. For a standard deployment, change nothing.

Step 5: Verify​

# Inspect the package and shared config
sui client object <PACKAGE_ID>
sui client object <ADMIN_CONFIG_ID>

# Register a test merchant
sui client call \
  --package <PACKAGE_ID> --module merchant --function register_merchant \
  --args "Test Merchant" "Test description" \
  --gas-budget 10000000

Check the publish transaction on SuiVision.

Step 6: Propagate configuration​

Never hard-code IDs in source; pass them through configuration.

SDK consumers:

import { createClient } from '@dolphinpay/sdk';

const client = createClient({
  network: 'testnet',
  packageId: '<PACKAGE_ID>',
  adminConfigId: '<ADMIN_CONFIG_ID>',
});

Frontend — frontend/.env.local for local development:

NEXT_PUBLIC_SUI_NETWORK=testnet
NEXT_PUBLIC_PACKAGE_ID=<PACKAGE_ID>
NEXT_PUBLIC_ADMIN_CONFIG_ID=<ADMIN_CONFIG_ID>

For the Cloudflare Workers deployment, set the same variables in frontend/wrangler.jsonc under vars, then bun run deploy.

Live tests (opt-in, read-only): the SDK's live suite only reads on-chain state (no transactions) 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

If this is the project deployment (not a personal fork), also commit the updated Move.lock and update DEPLOYMENT.md.

Troubleshooting​

"Insufficient gas" — raise the budget (--gas-budget 500000000) and check sui client gas.

Payments abort after publish — the allowed currency was not configured. Run the set_allowed_currency call in Step 3 with the testnet USDC type.

Can't find the AdminConfig — it is a shared object created in the publish transaction; inspect the publish digest on SuiVision or sui client tx-block <DIGEST>.

Old package IDs — previously documented packages are defunct. Use only the IDs from your own publish output or DEPLOYMENT.md.

Next steps​