Token Registry API Reference

The Token Registry module manages multi-currency support across the DolphinPay platform. It provides centralized token registration, configuration, and validation.

Overview

Module: dolphinpay::registry File: sources/tokens/registry.move

The registry maintains:

• Supported token types with metadata
• Payment amount limits (min/max)
• Daily transaction limits per token
• Token active/inactive status
• Admin-controlled token management

Data Structures

TokenRegistry

Main registry object containing all registered tokens.

public struct TokenRegistry has key {
    id: UID,
    admin: address,
    registered_tokens: VecMap<TypeName, TokenInfo>,
    is_enabled: bool,
    created_at: u64,
}

Fields:

• id - Unique identifier
• admin - Administrator address
• registered_tokens - Map of token types to their configuration
• is_enabled - Global registry status
• created_at - Creation timestamp

TokenInfo

Configuration for a registered token.

public struct TokenInfo has store, copy, drop {
    symbol: String,
    decimals: u8,
    min_payment_amount: u64,
    max_payment_amount: u64,
    daily_limit: u64,
    is_active: bool,
    registered_at: u64,
}

Fields:

• symbol - Token symbol (e.g., "SUI", "USDC")
• decimals - Number of decimal places
• min_payment_amount - Minimum payment amount in base units
• max_payment_amount - Maximum payment amount in base units
• daily_limit - Maximum daily transaction volume
• is_active - Token active status
• registered_at - Registration timestamp

Core Functions

init

Initialize the token registry (package initialization).

fun init(ctx: &mut TxContext)

Effects:

• Creates and shares a new TokenRegistry object
• Sets caller as admin
• Creates admin capability

---

register_token

Register a new token with payment configuration.

public entry fun register_token<T>(
    registry: &mut TokenRegistry,
    symbol: String,
    decimals: u8,
    min_payment_amount: u64,
    max_payment_amount: u64,
    daily_limit: u64,
    ctx: &mut TxContext,
)

Parameters:

• registry - Mutable reference to TokenRegistry
• symbol - Token symbol string
• decimals - Token decimal places (0-18)
• min_payment_amount - Minimum payment in base units
• max_payment_amount - Maximum payment in base units
• daily_limit - Daily transaction limit
• ctx - Transaction context

Aborts:

• E_NOT_ADMIN (999) - Caller is not admin
• E_TOKEN_ALREADY_REGISTERED (301) - Token already registered
• E_REGISTRY_DISABLED (302) - Registry is disabled
• E_INVALID_AMOUNT_RANGE (303) - Min amount > max amount

Example:

registry::register_token<SUI>(
    &mut registry,
    string::utf8(b"SUI"),
    9,              // 9 decimals
    1_000,          // 0.000001 SUI minimum
    1_000_000_000,  // 1 SUI maximum
    10_000_000_000, // 10 SUI daily limit
    ctx
);

---

update_token_config

Update configuration for an existing token.

public entry fun update_token_config<T>(
    registry: &mut TokenRegistry,
    min_payment_amount: u64,
    max_payment_amount: u64,
    daily_limit: u64,
    ctx: &mut TxContext,
)

Parameters:

• registry - Mutable reference to TokenRegistry
• min_payment_amount - New minimum payment amount
• max_payment_amount - New maximum payment amount
• daily_limit - New daily transaction limit
• ctx - Transaction context

Aborts:

• E_NOT_ADMIN (999) - Caller is not admin
• E_TOKEN_NOT_SUPPORTED (300) - Token not registered
• E_INVALID_AMOUNT_RANGE (303) - Invalid amount range

---

toggle_token_status

Enable or disable a registered token.

public entry fun toggle_token_status<T>(
    registry: &mut TokenRegistry,
    is_active: bool,
    ctx: &mut TxContext,
)

Parameters:

• registry - Mutable reference to TokenRegistry
• is_active - New active status
• ctx - Transaction context

Aborts:

• E_NOT_ADMIN (999) - Caller is not admin
• E_TOKEN_NOT_SUPPORTED (300) - Token not registered

---

remove_token

Remove a token from the registry.

public entry fun remove_token<T>(
    registry: &mut TokenRegistry,
    ctx: &mut TxContext,
)

Parameters:

• registry - Mutable reference to TokenRegistry
• ctx - Transaction context

Aborts:

• E_NOT_ADMIN (999) - Caller is not admin
• E_TOKEN_NOT_SUPPORTED (300) - Token not registered

Warning: Removing a token may break existing payments using that token.

---

Query Functions

is_token_supported

Check if a token is registered in the registry.

public fun is_token_supported<T>(registry: &TokenRegistry): bool

Returns: true if token is registered, false otherwise

---

is_token_active

Check if a registered token is currently active.

public fun is_token_active<T>(registry: &TokenRegistry): bool

Returns: true if token is active, false otherwise

Aborts:

• E_TOKEN_NOT_SUPPORTED (300) - Token not registered

---

get_token_info

Get complete information for a registered token.

public fun get_token_info<T>(registry: &TokenRegistry): TokenInfo

Returns: Copy of the token's TokenInfo struct

Aborts:

• E_TOKEN_NOT_SUPPORTED (300) - Token not registered

---

get_min_payment_amount

Get minimum payment amount for a token.

public fun get_min_payment_amount<T>(registry: &TokenRegistry): u64

Returns: Minimum payment amount in base units

Aborts:

• E_TOKEN_NOT_SUPPORTED (300) - Token not registered

---

get_max_payment_amount

Get maximum payment amount for a token.

public fun get_max_payment_amount<T>(registry: &TokenRegistry): u64

Returns: Maximum payment amount in base units

Aborts:

• E_TOKEN_NOT_SUPPORTED (300) - Token not registered

---

get_daily_limit

Get daily transaction limit for a token.

public fun get_daily_limit<T>(registry: &TokenRegistry): u64

Returns: Daily limit in base units

Aborts:

• E_TOKEN_NOT_SUPPORTED (300) - Token not registered

---

get_admin

Get the registry administrator address.

public fun get_admin(registry: &TokenRegistry): address

Returns: Admin address

---

is_registry_enabled

Check if the registry is enabled globally.

public fun is_registry_enabled(registry: &TokenRegistry): bool

Returns: true if registry is enabled, false otherwise

---

get_total_tokens

Get the total number of registered tokens.

public fun get_total_tokens(registry: &TokenRegistry): u64

Returns: Count of registered tokens

---

Error Codes

Code	Constant	Description
300	E_TOKEN_NOT_SUPPORTED	Token is not registered in the registry
301	E_TOKEN_ALREADY_REGISTERED	Token is already registered
302	E_REGISTRY_DISABLED	Registry is disabled
303	E_INVALID_AMOUNT_RANGE	Min amount exceeds max amount
999	E_NOT_ADMIN	Caller is not the admin

Usage Examples

Register SUI Token

use dolphinpay::registry;
use sui::sui::SUI;
use std::string;

// Register SUI with 9 decimals
registry::register_token<SUI>(
    &mut registry,
    string::utf8(b"SUI"),
    9,
    1_000,          // 0.000001 SUI min
    1_000_000_000,  // 1 SUI max
    10_000_000_000, // 10 SUI daily limit
    ctx
);

Check Token Support

// Check if USDC is supported
let is_supported = registry::is_token_supported<USDC>(&registry);

if (is_supported && registry::is_token_active<USDC>(&registry)) {
    // Token is active and ready to use
    let min_amount = registry::get_min_payment_amount<USDC>(&registry);
};

Update Token Limits

// Increase daily limit for SUI
registry::update_token_config<SUI>(
    &mut registry,
    1_000,           // Keep same min
    5_000_000_000,   // Increase max to 5 SUI
    50_000_000_000,  // Increase daily limit to 50 SUI
    ctx
);

Temporarily Disable Token

// Disable USDC temporarily for maintenance
registry::toggle_token_status<USDC>(
    &mut registry,
    false, // Set to inactive
    ctx
);

// Re-enable later
registry::toggle_token_status<USDC>(
    &mut registry,
    true, // Set to active
    ctx
);

Best Practices

Token Registration

1. Verify Token Type: Ensure the generic type T corresponds to a real Coin type
2. Reasonable Limits: Set min/max amounts appropriate for the token's value
3. Daily Limits: Configure daily limits to prevent excessive volume
4. Decimal Accuracy: Use correct decimal places (usually 6-18)

Amount Validation

// Always validate amounts against registry limits
let min = registry::get_min_payment_amount<T>(&registry);
let max = registry::get_max_payment_amount<T>(&registry);

assert!(amount >= min && amount <= max, E_INVALID_AMOUNT);

Active Status Checks

// Check both registration and active status
assert!(
    registry::is_token_supported<T>(&registry),
    E_TOKEN_NOT_SUPPORTED
);
assert!(
    registry::is_token_active<T>(&registry),
    E_TOKEN_INACTIVE
);

Security Considerations

1. Admin Only: All mutating operations require admin privileges
2. Amount Validation: Always validate payment amounts against registry limits
3. Active Checks: Verify token is active before processing payments
4. Daily Limits: Monitor daily volumes to prevent excessive usage
5. Immutable Types: Token types cannot be changed after registration

Integration with Other Modules

With Payment Module

use dolphinpay::payment;
use dolphinpay::registry;

// Validate token before creating payment
assert!(
    registry::is_token_active<T>(&registry),
    E_TOKEN_NOT_ACTIVE
);

let payment = payment::create_payment(...);

With Merchant Module

use dolphinpay::merchant;
use dolphinpay::registry;

// Merchants can only accept registered tokens
if (registry::is_token_supported<T>(&registry)) {
    merchant::add_supported_currency<T>(...);
};

Related Documentation

• Payment API - Payment creation and execution
• Merchant API - Merchant currency management
• Batch Payment API - Multi-recipient payments
• Core Modules - Module architecture overview

---

Need help? Check the SDK documentation for integration examples.