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
Whitelist2
FlexibleToken / BondToken3
MarketManager4
ReservePool5
EmergencyPauseManager6
GenericGovernor + TimelockControllerQuick 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
| Actor | Responsibility |
|---|---|
| Deployer | Initial deployment and wiring |
| Timelock | Final admin authority |
| Governor | Proposal and voting |
| Guardian | Emergency pause |
| Compliance Ops | KYC operations |
| Users | Approved participants |
| Splitter | Fee recipient |
Roles & Wiring Matrix
EmergencyPauseManager
| Role | Holder | Purpose |
|---|---|---|
| PAUSER_ROLE | Guardian | Register pause targets |
| GUARDIAN_ROLE | Guardian | Execute pause |
| GOVERNOR_ROLE | Timelock | Execute unpause |
MarketManager
| Setting | Description |
|---|---|
| setWhitelist | Enforce compliance |
| setPaymentToken | Allow 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)
Proposal→Vote→Queue (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
Stable
This document reflects the recommended architecture. Trust boundaries and flows are stable by design.