Admin Module API Reference

API reference for dolphinpay::admin (contract/sources/core/admin.move).

The module holds all platform governance, gated by a single AdminCap:

the global platform fee (basis points; 0 by policy, 10% contract ceiling; non-zero requires a treasury);
the treasury address that receives any non-zero fee;
the single allowed currency (native Circle USDC, 6 decimals);
merchant force activate/deactivate overrides;
platform statistics.

There are no per-merchant fees — the fee lives only in AdminConfig.

Data structures

AdminCap

public struct AdminCap has key, store {
    id: UID,
}

Created once in init and transferred to the deployer. Required for every admin function. Loss of the AdminCap means loss of platform governance — store it securely.

AdminConfig

Shared object created in init.

public struct AdminConfig has key {
    id: UID,
    default_platform_fee_bps: u64,        // 0 by policy until approved
    treasury: address,                    // @0x0 until set
    allowed_currency: Option<TypeName>,   // None until set
    total_merchants: u64,
    total_payments: u64,
    total_volume: u64,
}

Readable by anyone; mutable only through AdminCap-gated functions.

Constants

const MAX_PLATFORM_FEE_BPS: u64 = 1000;   // 10% hard ceiling on any future fee

Error codes

const E_FEE_TOO_HIGH: u64 = 101;
const E_INVALID_TREASURY: u64 = 102;
const E_CURRENCY_NOT_SET: u64 = 103;
const E_CURRENCY_NOT_ALLOWED: u64 = 104;
const E_FEE_REQUIRES_TREASURY: u64 = 105;

Module initialization

fun init(ctx: &mut TxContext)

Runs once at publish:

Creates the AdminCap and transfers it to the deployer.
Creates and shares the AdminConfig with fee 0, treasury @0x0, and allowed_currency = None.

Payments abort until set_allowed_currency is called — this is a required post-deploy step (see DEPLOYMENT.md).

Admin functions

All require &AdminCap.

set_default_platform_fee

public entry fun set_default_platform_fee(
    _admin_cap: &AdminCap,
    config: &mut AdminConfig,
    fee_bps: u64,
)

Sets the global platform fee in basis points. Policy: the fee is 0 and any change requires explicit product approval.

Aborts:

E_FEE_TOO_HIGH — fee_bps > 1000 (10%)
E_FEE_REQUIRES_TREASURY — fee_bps > 0 while the treasury is unset (a non-zero fee with no treasury would misroute funds)

set_treasury

public entry fun set_treasury(
    _admin_cap: &AdminCap,
    config: &mut AdminConfig,
    treasury: address,
)

Sets the address that receives any non-zero platform fee. Must be set before a non-zero fee can be configured.

Aborts: E_INVALID_TREASURY — treasury is @0x0

set_allowed_currency

public entry fun set_allowed_currency<T>(
    _admin_cap: &AdminCap,
    config: &mut AdminConfig,
)

Sets the single coin type accepted platform-wide. Generic so the USDC package is not a build dependency — call it after deployment with the network's native Circle USDC type:

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

(That type argument is testnet USDC; take current IDs from DEPLOYMENT.md.)

force_deactivate_merchant / force_activate_merchant

public entry fun force_deactivate_merchant(_admin_cap: &AdminCap, merchant: &mut Merchant)
public entry fun force_activate_merchant(_admin_cap: &AdminCap, merchant: &mut Merchant)

Admin overrides for a merchant's is_active flag, bypassing the merchant's own MerchantCap. Inactive merchants cannot be used in the merchant-validated payment flows.

update_platform_stats

public entry fun update_platform_stats(
    _admin_cap: &AdminCap,
    config: &mut AdminConfig,
    merchants_delta: u64,
    payments_delta: u64,
    volume_delta: u64,
)

Increments total_merchants, total_payments, and total_volume by the given deltas. Volume is in USDC base units. This is a manual bookkeeping hook; event-based off-chain aggregation is the usual alternative.

Package function (used by payment)

public(package) fun assert_currency_allowed(config: &AdminConfig, currency: TypeName)

Called by every payment create/execute path.

Aborts: E_CURRENCY_NOT_SET (no allowed currency configured yet), E_CURRENCY_NOT_ALLOWED (type differs from the allowed one)

Query functions

No capability required:

public fun get_default_platform_fee_bps(config: &AdminConfig): u64
public fun get_treasury(config: &AdminConfig): address
public fun get_allowed_currency(config: &AdminConfig): Option<TypeName>
public fun is_currency_allowed(config: &AdminConfig, currency: TypeName): bool
public fun get_total_merchants(config: &AdminConfig): u64
public fun get_total_payments(config: &AdminConfig): u64
public fun get_total_volume(config: &AdminConfig): u64   // USDC base units

Post-deploy checklist

Record the package ID, shared AdminConfig ID, and owned AdminCap ID from the publish output into DEPLOYMENT.md.
Call set_allowed_currency<USDC> — required; payments abort until this is done.
Optionally call set_treasury — required before any future non-zero fee.
Leave the fee at 0 bps. Changing it requires explicit product approval, a configured treasury, and stays within the 10% contract ceiling.

Policy summary

Setting	Contract rule	Current policy
Platform fee	≤ 1000 bps (10%); non-zero requires treasury	0 bps
Treasury	non-zero address; receives all fees	optional while fee is 0
Allowed currency	exactly one coin type	native Circle USDC (6 decimals)
Refunds	none on-chain	per ADR-004

Data structures​

AdminCap​

AdminConfig​

Constants​

Error codes​

Module initialization​

Admin functions​

set_default_platform_fee​

set_treasury​

set_allowed_currency​

force_deactivate_merchant / force_activate_merchant​

update_platform_stats​

Package function (used by payment)​

Query functions​

Post-deploy checklist​

Policy summary​

Next steps​