Skip to content
    hazBasehazBaseDocs
    Reference Implementation

    Compliant Market

    A practical, end-to-end reference implementation for building a compliant token market using @hazbase/kit + ethers. Focuses on deployment order, roles & wiring, and governance/emergency pause propagation.

    Overview

    This document provides a complete reference for the compliant market pattern.

    • Recommended deployment order
    • Required roles & wiring
    • Governance and emergency pause propagation
    • Minimal SDK-based code examples (UI-free)

    Assumed Scenario

    • Only KYC-approved users can trade (via Whitelist)
    • Assets are traded through MarketManager
    • Liquidity / buyback logic is handled by ReservePool
    • The system can be paused immediately in emergencies
    • Recovery and configuration changes go through governance + timelock

    Recommended Deployment Order

    1
    Whitelist
    2
    FlexibleToken / BondToken
    3
    MarketManager
    4
    ReservePool
    5
    EmergencyPauseManager
    6
    GenericGovernor + TimelockController

    Quick Start (Minimal Deploy & Wiring)

    The smallest runnable example showing how to deploy and wire a compliant market using @hazbase/kit + ethers.

    typescript
    import { ethers } from "ethers";
    import {
      WhitelistHelper,
      FlexibleTokenHelper,
      MarketManagerHelper,
    } from "@hazbase/kit";
    
    const provider = new ethers.JsonRpcProvider(process.env.RPC_URL!);
    const deployer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
    
    (async () => {
      // 1. Deploy whitelist
      const { helper: whitelist } = await WhitelistHelper.deploy(
        { admin: deployer.address },
        deployer
      );
    
      // 2. Deploy payment token
      const { helper: usdc } = await FlexibleTokenHelper.deploy(
        {
          name: "USD Coin",
          symbol: "USDC",
          decimals: 6,
          transferable: true,
          admin: deployer.address,
        },
        deployer
      );
    
      // 3. Deploy market manager
      const { helper: market } = await MarketManagerHelper.deploy(
        {
          admin: deployer.address,
          splitter: deployer.address,
          bps: 10, // 0.1%
        },
        deployer
      );
    
      // 4. Wire compliance
      await market.setWhitelist(whitelist.address);
      await market.setPaymentToken(usdc.address, true);
    
      console.log("Compliant market ready:", market.address);
    })();

    Key Actors

    ActorResponsibility
    DeployerInitial deployment and wiring
    TimelockFinal admin authority
    GovernorProposal and voting
    GuardianEmergency pause
    Compliance OpsKYC operations
    UsersApproved participants
    SplitterFee recipient

    Roles & Wiring Matrix

    EmergencyPauseManager

    RoleHolderPurpose
    PAUSER_ROLEGuardianRegister pause targets
    GUARDIAN_ROLEGuardianExecute pause
    GOVERNOR_ROLETimelockExecute unpause

    MarketManager

    SettingDescription
    setWhitelistEnforce compliance
    setPaymentTokenAllow settlement
    setFee(bps, splitter)Marketplace fee

    Fee rule: bps = 1000 → 100%. Typical fee is 5–10 bps.

    Emergency Pause (Code Snippet)

    typescript
    import { EmergencyPauseManagerHelper } from "@hazbase/kit";
    
    // Register pause targets
    await pauseManager.registerPausable(market.address);
    await pauseManager.registerPausable(reservePool.address);
    
    // Guardian triggers immediate pause
    await pauseManager.connect(guardian).pauseAll();
    
    // Recovery must go through governance (timelock)
    await pauseManager.connect(timelock).unpauseAll();

    Governance Flow (Conceptual)

    ProposalVoteQueue (Timelock)Execute

    Typical governance actions:

    • Unpause system
    • Update fees
    • Add/remove payment tokens
    • Adjust reserve parameters

    Deployment Checklist

    Deploy

    Whitelist
    Token(s)
    MarketManager
    ReservePool
    EmergencyPauseManager
    Governor + Timelock

    Wire

    Set whitelist
    Allow payment tokens
    Register pause targets
    Configure fees
    Transfer admin roles to Timelock

    Smoke Tests

    Non-whitelisted user cannot trade
    Whitelisted user can trade
    Guardian pause stops operations
    Timelock unpause restores system

    Full Reference Code

    Complete runnable scripts (deploy / wire / flows):

    reference/compliant-market/
      ├── 00-deploy.ts
      ├── 01-wire.ts
      └── 02-flows.ts
    View on GitHub
    Stable
    This document reflects the recommended architecture. Trust boundaries and flows are stable by design.