Skip to content

TESTNET_MODE.md

Latest commit

 

History

History
442 lines (321 loc) · 14.7 KB

TESTNET_MODE.md

File metadata and controls

442 lines (321 loc) · 14.7 KB
Raw

Testnet Mode Feature

🚨 CRITICAL SECURITY WARNING

TESTNET MODE IS EXTREMELY DANGEROUS FOR PRODUCTION USE

Testnet mode relaxes validations that protect investor funds. Enabling testnet mode on production/mainnet contracts can lead to catastrophic fund loss.

Production Safety Requirements

  • NEVER enable testnet mode on mainnet/production contracts
  • Always verify is_testnet_mode() returns false before production deployment
  • Admin must ensure testnet mode is disabled before going live
  • Integrators must check is_testnet_mode() in their client code

What Testnet Mode Does

When enabled, testnet mode bypasses these critical safety checks:

  1. Revenue Share Validation: Allows revenue_share_bps > 10000 (100%+ distributions)
  2. Concentration Enforcement: Ignores holder concentration limits that prevent manipulation

These relaxations can allow malicious actors to drain all funds from the contract.

Overview

The testnet mode feature provides a configuration flag that enables simplified behavior for testnet and development deployments. When enabled, certain strict validations are relaxed to facilitate testing and experimentation without compromising production safety.

Purpose

Testnet mode is designed for:

  • Non-production deployments (testnet, devnet, local development)
  • Testing edge cases and boundary conditions
  • Rapid prototyping and experimentation
  • Integration testing with flexible parameters

Behavior Changes

When testnet mode is enabled, the following behaviors are modified:

1. Revenue Share BPS Validation (register_offering)

Normal Mode:

  • revenue_share_bps must be ≤ 10,000 (100%)
  • Values > 10,000 return InvalidRevenueShareBps error

Testnet Mode:

  • revenue_share_bps validation is skipped
  • Any value is accepted, including > 10,000
  • Useful for testing extreme scenarios

2. Concentration Enforcement (report_revenue)

Normal Mode:

  • If concentration limit is set with enforce=true, report_revenue fails when reported concentration exceeds the limit
  • Returns ConcentrationLimitExceeded error

Testnet Mode:

  • Concentration enforcement is skipped
  • report_revenue succeeds regardless of concentration
  • Concentration warnings are still emitted via events

Usage

Setting Up Testnet Mode

  1. Set Admin (one-time operation):
contract.set_admin(&admin_address);
  1. Enable Testnet Mode (admin only):
contract.set_testnet_mode(&true);
  1. Verify Mode:
let is_testnet = contract.is_testnet_mode();
  1. Disable Testnet Mode (when moving to production):
contract.set_testnet_mode(&false);

Example: Testing with High BPS

// Enable testnet mode
contract.set_admin(&admin);
contract.set_testnet_mode(&true);

// Register offering with > 100% revenue share (for testing)
contract.register_offering(&issuer, &token, &15_000); // 150%

// This would fail in normal mode but succeeds in testnet mode

Example: Testing Concentration Scenarios

// Enable testnet mode
contract.set_admin(&admin);
contract.set_testnet_mode(&true);

// Set up concentration limit with enforcement
contract.register_offering(&issuer, &token, &5_000);
contract.set_concentration_limit(&issuer, &token, &5000, &true);

// Report high concentration
contract.report_concentration(&issuer, &token, &8000); // 80% > 50% limit

// Report revenue - succeeds in testnet mode, would fail in normal mode
contract.report_revenue(&issuer, &token, &1_000_000, &1);

Security Considerations

🚨 FUND LOSS RISK

Testnet mode bypasses validations designed to protect investor funds. Enabling it on production contracts can result in:

  • Over-distribution: revenue_share_bps > 10000 allows distributions exceeding 100%
  • Concentration manipulation: Bypassed enforcement allows unlimited holder concentration
  • Fund drainage: Malicious issuers could extract all contract funds

Admin-Only Access

  • Only the contract admin can toggle testnet mode
  • Requires set_admin() to be called first
  • Admin authorization is enforced via require_auth()

Production Safety

  • Testnet mode is disabled by default
  • Must be explicitly enabled by admin
  • Can be toggled on/off at any time
  • Mode changes emit events for auditability
  • CRITICAL: Always verify is_testnet_mode() == false before production use

Integrator Requirements

Mandatory Production Checks

All integrators and frontends MUST implement these checks:

// ALWAYS check testnet mode before using the contract
let is_testnet = contract.is_testnet_mode();
if is_testnet {
    panic!("CRITICAL: Contract has testnet mode enabled - DO NOT USE FOR PRODUCTION");
}

Client Library Integration

pub fn connect_to_revora_contract(contract_id: &str) -> Result<RevoraClient> {
    let client = RevoraClient::new(contract_id);
    
    // Mandatory safety check
    if client.is_testnet_mode()? {
        return Err(Error::TestnetModeEnabled);
    }
    
    Ok(client)
}

Deployment Verification

Before deploying to production:

  1. Deploy contract
  2. Verify is_testnet_mode() returns false
  3. Document the check in deployment scripts
  4. Include in security audits

Unaffected Operations

The following operations work identically in both modes:

  • Blacklist management
  • Pagination
  • Audit summaries
  • Claim operations
  • Rounding modes
  • All read-only queries

Events

Testnet mode changes emit the test_mode event:

Topic: (test_mode, admin_address)
Payload: enabled (bool)

This allows off-chain systems to track when testnet mode is toggled.

Testing

The feature includes comprehensive test coverage (95%+):

Core Functionality Tests

  • testnet_mode_disabled_by_default - Verifies default state
  • set_testnet_mode_requires_admin - Admin authorization
  • testnet_mode_can_be_toggled - Enable/disable cycles
  • set_testnet_mode_emits_event - Event emission

Validation Relaxation Tests

  • testnet_mode_allows_bps_over_10000 - BPS validation skip
  • testnet_mode_disabled_rejects_bps_over_10000 - Normal mode enforcement
  • testnet_mode_skips_concentration_enforcement - Concentration skip
  • testnet_mode_disabled_enforces_concentration - Normal mode enforcement

Edge Cases

  • testnet_mode_toggle_after_offerings_exist - Mode change with existing data
  • testnet_mode_affects_only_validation_not_storage - Storage integrity
  • testnet_mode_multiple_offerings_with_varied_bps - Multiple offerings

Integration Tests

  • testnet_mode_normal_operations_unaffected - Other operations work
  • testnet_mode_blacklist_operations_unaffected - Blacklist unchanged
  • testnet_mode_pagination_unaffected - Pagination unchanged

Best Practices

For Testnet Deployments

  1. Enable at deployment: Set admin and enable testnet mode immediately after contract deployment
  2. Document clearly: Mark testnet contracts in your documentation
  3. Monitor events: Track test_mode events to verify configuration
  4. Test thoroughly: Use testnet mode to test edge cases before production

For Production Deployments

  1. Never enable: Keep testnet mode disabled for production contracts
  2. Verify state: Check is_testnet_mode() returns false before going live
  3. Admin security: Protect admin keys to prevent unauthorized mode changes
  4. Audit trail: Review event logs to ensure mode was never enabled

Migration from Testnet to Production

  1. Deploy new contract instance (testnet mode disabled by default)
  2. Migrate data if needed
  3. Verify is_testnet_mode() returns false
  4. Do not reuse testnet contracts for production

Implementation Details

Storage

Testnet mode state is stored in persistent storage:

DataKey::TestnetMode -> bool

Code Locations

  • Storage key: src/lib.rs - DataKey::TestnetMode
  • Event symbol: src/lib.rs - EVENT_TESTNET_MODE
  • Functions: src/lib.rs - set_testnet_mode(), is_testnet_mode()
  • Modified flows: register_offering() (reads Self::is_testnet_mode(env.clone()) to gate BPS validation), report_revenue() (reads same flag to gate concentration enforcement)
  • Tests: src/test.rs - Testnet mode section

Limitations

  • Testnet mode does NOT affect:

    • Token transfers
    • Claim calculations
    • Blacklist enforcement
    • Freeze functionality
    • Any other validation logic

  • Mode changes are immediate (no delay or grace period)

  • Existing offerings retain their parameters when mode is toggled

Faucet: Deterministic Test Holders (faucet_seed_holders)

Overview

faucet_seed_holders(requester, issuer, namespace, token, count) allocates count deterministic 32-byte seeds for an offering's holder slots. It is strictly testnet-only — calling it while testnet_mode == false returns RevoraError::TestnetOnly (wire value 51).

Purpose

Integration test suites can call this function once and pin their holder addresses against the returned seeds without manually wiring up holders per test run.

Seed Derivation

Each seed is computed as:

seed[idx] = sha256(issuer_xdr || namespace_xdr || token_xdr || idx_xdr)

The XDR encoding is the standard Soroban to_xdr representation. Seeds are offering-specific and index-specific, guaranteeing no collisions within or across offerings.

BPS Distribution

The 10 000 basis-point total is split floor-evenly across count slots:

  • floor_bps = 10_000 / count
  • The last slot absorbs the remainder: last_bps = floor_bps + (10_000 % count)

The per-slot BPS is included in the emitted fct_seed event so test suites can assert expected distribution without re-computing it.

Events

One fct_seed event per slot:

Topics: (fct_seed, issuer, namespace, token)
Data:   (idx: u32, seed: BytesN<32>, share_bps: u32)

Storage

Seeds are persisted in DataKey2::FaucetSeedEntry(offering_id, idx) so they can be retrieved by index without re-calling the function.

Security

  • Guarded by is_testnet_mode() — panics with TestnetOnly on mainnet.
  • Requires the offering to be registered (OfferingNotFound otherwise).
  • Requests are throttled per requester address with a 1-hour cooldown.
  • Repeated requests inside the cooldown return RevoraError::FaucetCooldownActive and emit a fct_cdrj event.
  • count == 0 is a no-op (returns empty vec, emits no events).

Example Usage

// Prerequisites: testnet mode enabled, offering registered.
let seeds = client.faucet_seed_holders(&issuer, &ns, &token, &5);
// seeds[0] is the raw ed25519 public key for slot-0 test holder.
// Use it externally to derive the corresponding Stellar keypair.

New Error Variant

Code Variant Condition
62 TestnetOnly faucet_seed_holders or faucet_reset called with testnet_mode == false
63 FaucetCooldownActive faucet_seed_holders called within the 1-hour cooldown window

Faucet Reset (faucet_reset)

Overview

faucet_reset(caller, issuer, namespace, token, seed) deterministically resets the faucet state for an offering. It clears all persisted FaucetSeedEntry records and resets the seed count to zero, then emits a single fct_rst event carrying the caller-supplied seed value.

This lets CI test suites restore a known clean state between runs without redeploying the contract.

Gating

  • Strictly testnet-only. Returns RevoraError::TestnetOnly (wire value 62) when testnet_mode == false. Must never be callable on mainnet.
  • Admin-only. caller must equal the stored admin address; any other address returns RevoraError::NotAuthorized.
  • Offering must be registered; returns RevoraError::OfferingNotFound otherwise.

Parameters

Name Type Description
caller Address Admin address — must match the stored admin key.
issuer Address Offering issuer address.
namespace Symbol Offering namespace.
token Address Offering token address.
seed BytesN<32> Arbitrary 32-byte value; echoed in the fct_rst event so test suites can anchor the exact reset.

State Mutations

  1. Removes FaucetSeedEntry(offering_id, idx) for idx in 0..seed_count (where seed_count is the running counter stored in FaucetSeedCount(offering_id)).
  2. Resets FaucetSeedCount(offering_id) to 0.
  3. Emits one fct_rst event.

What is NOT reset

  • Per-requester FaucetLastRequest cooldown timestamps are not cleared by this call. Cooldowns expire naturally after DEFAULT_FAUCET_COOLDOWN_SECONDS (3 600 s). This is intentional: the reset targets seed state reproducibility, not cooldown bypass.

Event

Topics: (fct_rst, issuer, namespace, token)
Data:   (caller: Address, seed: BytesN<32>, cleared_count: u32)

cleared_count is the number of FaucetSeedEntry records that were removed.

Example Usage

// Prerequisites: testnet mode enabled, offering registered, caller == admin.
let seed: BytesN<32> = env.crypto().sha256(&Bytes::from_array(&env, b"test-run-42"));
client.faucet_reset(&admin, &issuer, &ns, &token, &seed);

// After this call, faucet_seed_holders behaves as if the offering is fresh.
// (Cooldown for each requester still applies independently.)

Security Notes

  • Admin key required. Unauthorised callers cannot reset faucet state, preventing cooldown circumvention by unprivileged actors.
  • Testnet gate is unconditional. Even the admin cannot call this on mainnet; testnet_mode must be explicitly enabled first.
  • The seed parameter is informational only — it does not influence storage mutations. It provides an anchor for test-suite assertions and audit logs.

Version History

  • v0.1.0 - Initial implementation (Issue #24)

    • Admin-only toggle
    • BPS validation relaxation
    • Concentration enforcement skip
    • Comprehensive test coverage

  • v0.2.0 - Deterministic faucet (Issue #476)

    • faucet_seed_holders function
    • RevoraError::TestnetOnly (wire value 62)
    • RevoraError::FaucetCooldownActive (wire value 63)
    • DataKey2::FaucetSeedEntry storage key
    • EVENT_FAUCET_SEED (fct_seed) event symbol
    • src/test_faucet_seed.rs — 95%+ test coverage

  • v0.3.0 - Faucet reset primitive (Issue #615)

    • faucet_reset(caller, issuer, namespace, token, seed) function
    • DataKey2::FaucetSeedCount storage key (tracks highest slot index for safe iteration)
    • EVENT_FAUCET_RESET (fct_rst) event symbol
    • faucet_seed_holders updated to maintain FaucetSeedCount
    • Comprehensive faucet_reset tests in src/test_faucet_seed.rs

Support

For questions or issues related to testnet mode:

  1. Check test cases in src/test.rs for usage examples
  2. Review event logs for mode change history
  3. Verify admin configuration with get_admin()