On-Chain Guarantor Layer & Exposure Module

HalalFi operates with a strict off-chain guarantee baseline — no campaign is published without verified backing from the investee (property titles, corporate checks, liquid collateral, etc.). The Guarantor Module adds an optional on-chain guarantee layer where verified legal entities deposit USDT into a master vault and underwrite trade cycles with leveraged credit lines.

Binary campaign model

Every project is strictly binary at launch — there are no per-investor toggles or split risk tiers within a single contract:

• Off-chain Guaranteed — backed by HalalFi's existing off-chain collateral process. On default, investors rely on off-chain legal asset liquidation managed by HalalFi Ops.
• On-chain Guaranteed — a verified guarantor locks coverage in GuaranteeVault.sol. 100% of investor principal in that campaign is protected by the vault safety net.

Two parallel on-chain systems

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│ CrowdfundAdmin  │────▶│  GuaranteeVault  │◀────│ GuaranteedCampaign  │
│ (platform admin)│     │  (master vault)  │     │ Factory             │
└────────┬────────┘     └────────┬─────────┘     └──────────┬──────────┘
         │                       │                          │
         │ approve/reject        │ lock/release/default     │ deploy
         ▼                       ▼                          ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│ CrowdfundFactory│────▶│ CrowdfundProject │     │ GuaranteedCampaign  │
│                 │     │ (per project)    │     │ (per campaign)      │
└─────────────────┘     └──────────────────┘     └─────────────────────┘

Factory pattern

• CrowdfundFactory.createProject() — deploys a new CrowdfundProject clone with immutable config
• GuaranteedCampaignFactory.createCampaign() — deploys GuaranteedCampaign and optionally locks vault credit at creation
• CrowdfundAdmin is the vault admin — all KYB, freeze, and margin operations proxy through it

Registry & access control

The vault maintains campaignRegistry[address] — only registered campaign/project contracts may call releaseGuarantee() or executeDefaultPayout(). Factories register addresses at deploy time via registerCampaign() / registerProject().

Step 1: Request & Admin KYB Review

1. Prospective guarantor calls GuaranteeVault.requestGuarantorship(entityName) from their wallet
2. Only wallet address and entity name are stored on-chain (corporate docs, contact details, asset proof remain off-chain per spec)
3. Admin reviews pending requests via getPendingGuarantorSummaries()
4. Admin accepts via CrowdfundAdmin.approveGuarantorRequest(guarantor) or rejects via rejectGuarantorRequest(guarantor)
5. Duplicate requests blocked: require(!hasPendingRequest[msg.sender]) and require(!profile.isApproved)

function requestGuarantorship(string calldata entityName) external {
    require(bytes(entityName).length > 0, "Empty entity");
    require(!profile.isApproved, "Already approved");
    require(!hasPendingRequest[msg.sender], "Request pending");
    hasPendingRequest[msg.sender] = true;
    _entityNames[msg.sender] = entityName;
    _pendingGuarantorRequests.push(msg.sender);
    emit GuarantorRequested(msg.sender, entityName);
}

Step 2: Deposit & credit activation

Approved guarantors deposit USDT via depositUSDT(amount). Capacity rebuilds automatically:

totalCreditCapacity = (depositedUSDT × 3) + adminAllocatedMargin
availableCredit     = totalCreditCapacity - usedCredit

Admin guarantor management

Frontend: /guarantor (request, deposit, approve projects) · /admin (requests, freeze, delete)

Rule 1: 3× Multiplier

CAPACITY_MULTIPLIER = 3 in GuaranteeVault._rebuildCapacity(). Admin can add physical collateral margin via configureAdminMargin() without requiring additional USDT deposit.

Rule 2: First-Project Ceiling

When activeProjects == 0, lock amount cannot exceed raw depositedUSDT:

if (profile.activeProjects == 0) {
    require(amount <= profile.depositedUSDT, "First project limit");
}

Rule 3: 50% Investee Concentration Limit

Per-guarantor, per-investee exposure tracked in guarantorToInvesteeExposure[guarantor][investee]:

uint256 maxSingleInvestee = profile.totalCreditCapacity / 2;
uint256 nextExposure = guarantorToInvesteeExposure[guarantor][investee] + amount;
require(nextExposure <= maxSingleInvestee, "Investee concentration");

Rule 4: Liquidity Withdrawal Lock

On guarantee lock, liquidityLocked[guarantor] += amount. Withdrawals blocked while remaining < liquidityLocked. Guarantor cannot pull core collateral while credit is actively backing live projects.

Rule 5: Failed campaign reset

When fundraising fails (Guaranteed) or refund phase triggers (Crowdfund), releaseGuarantee() decrements usedCredit, clears exposure mapping, and unlocks liquidity — restoring available credit with no fees charged.

Unified project creation flow

1. Creator submits via CrowdfundFactory.createProject(config, guarantor, useOnChainGuarantor, guaranteeAmount)
2. Project starts with adminApproved = false, isApproved = false
3. Admin loads project in /admin, sets platform fee 1–50%, calls approveProject(project, feePercent) — no reason field
4. If on-chain guarantor selected: guarantor must call guarantorApproveProject() → vault locks guarantee → project goes live
5. If no on-chain guarantor: live immediately after admin approval

Pending admin → [if useOnChainGuarantor] Awaiting guarantor → Live
                ↓ admin reject                    ↓ guarantor reject
              Declined                          Declined

Investment & cap logic

• invest(amount) — one investment per wallet, min/max bounds, USDT only
• cap = minimum success threshold; raiseAmount = hard upper bound
• After endDate: if totalRaised >= cap → creator may withdrawFunds() (platform fee deducted from raised amount)
• If cap not met → investors claimRefund() for 100% principal; guarantee released

Success settlement

• Creator returnFunds(amount) with principal + profit
• Investors withdrawReturns() — pro-rata principal + profit (pull-payment)
• Guarantee released from vault on withdraw or refund

Creation

createCampaign(
    address guarantor,
    bool requestOnChainProtection,  // binary: on-chain or off-chain
    uint8 fallbackMode,             // 0 = revert, 1 = launch off-chain
    uint256 targetAmount,
    uint256 expectedProfitRateBps,  // e.g. 10000 = 100% target yield
    uint256 fundraisingDeadline,
    uint256 maturityDate
)

State machine

Fundraising → Active (target hit)
Active → Settled (repayAndSettle)
Active → GracePeriod (after maturity)
GracePeriod → Disputed (fileDispute + $500 fee)
GracePeriod → Defaulted (silent 5-day expiry)
Disputed → Defaulted | Active | PendingOffChainLiquidation
Fundraising → Canceled (under target)

Investment records

Per-user ledger: mapping(address => InvestmentRecord[]) userInvestments with principalAmount and claimed flag. Global totalProtectedPrincipal tracks vault-covered exposure.

Portfolio view: /investments via getUserInvestmentsByWalletAddress()

Gross profit pool (Guaranteed Campaigns only)

grossProfitPool = totalReturnedFunds - totalProtectedPrincipal

Platform share  = grossProfitPool × 3%   (300 BPS)
Guarantor share = grossProfitPool × 40%  (4000 BPS)  [if onChainProtected]
Investor share  = grossProfitPool × 57%  (5700 BPS)  [pro-rata across investors]

uint256 private constant PLATFORM_SHARE_BPS  = 300;   // 3%
uint256 private constant GUARANTOR_SHARE_BPS = 4000;  // 40%
uint256 private constant INVESTOR_SHARE_BPS  = 5700;  // 57%

Pull-payment rule

Every actor must execute their own claim transaction and pay gas:

• claimInvestorSettlement() — investors
• claimGuarantorFee() — guarantor
• claimPlatformFee() — admin

On settlement, vault releaseGuarantee() restores guarantor credit lines.

Crowdfund platform fee (different model)

Crowdfund uses platformFeePercent set at admin approval — range 1% to 50% of total raised amount, deducted at creator withdrawal. This is separate from the guaranteed campaign 3% profit share.

5-day silent grace window

GRACE_PERIOD = 5 days after maturity. Three scenarios:

Dispute verdicts (admin-enforced)

enum DisputeVerdict {
    Rejected,           // → full default payout sequence
    PartiallyAccepted,  // → partial vault payout + timeline extension
    Accepted            // → no payout; maturity extended
}

Default payout & nuclear credit burn

1. Campaign calls GuaranteeVault.executeDefaultPayout(guarantor, totalProtectedPrincipal)
2. Vault pays min(deposit, principal) to campaign contract
3. _applyNuclearBurn(guarantor) — freezes profile, zeroes all credit capacity permanently
4. Investors independently claimDefaultPrincipal() at their own gas cost
5. Guarantor fees voided on default — fees never deducted from investor principal compensation

profile.isFrozen = true;
profile.usedCredit = 0;
profile.activeProjects = 0;
profile.totalCreditCapacity = 0;
profile.adminAllocatedMargin = 0;
liquidityLocked[guarantor] = 0;
emit GuarantorNuclearBurn(guarantor);

Vault insolvency shortfall

If guarantor deposit < protected principal: pro-rata liquidation of available USDT, campaign state → PendingOffChainLiquidation with expectedLiquidationWindow = 180 days. HalalFi Ops enforces physical collateral off-chain.

Key factory query functions

• getAllProjectsDetails() — all crowdfund summaries
• getProjectDetails(address) — single project + investor list
• getProjectsPendingGuarantorApproval(guarantor) — guarantor inbox
• getUserInvestmentsByWalletAddress(wallet) — portfolio
• getActiveGuarantorSummaries() — creator picker (excludes frozen)
• getPendingGuarantorSummaries() — admin KYB queue

Security patterns

• ReentrancyGuard on all withdrawal, settlement, and vault liquidation paths
• State updates before external transfers (checks-effects-interactions)
• Fixed-point math via BPS (10_000 basis points) for all fee calculations
• Campaign registry prevents unauthorized vault calls
• No ERC-20 credit tokens — internal accounting only

Test suite — GuaranteeSystem.test.js (9 tests)

• Guarantor onboarding, 3× capacity, duplicate rejection
• First-project ceiling & 50% concentration enforcement
• Liquidity lock during active credit; unlock on cancel
• Successful settlement with exact 3%/40%/57% split + pull claims
• Silent default after 5-day grace + nuclear burn + investor principal claim
• Dispute rejected → default payout path
• Insolvency shortfall → PendingOffChainLiquidation
• Access control on vault admin/factory functions
• Multi-investor accounting invariants (performance-style)

Test suite — CrowdfundV2.test.js (17 tests)

• Deployment wiring, cap-based config, admin migration
• Cap success + creator withdraw with platform fee
• Refund when cap not met
• Platform fee bounds (1–50%)
• Pro-rata returns distribution, no double-claim
• Dual approval flow (admin → guarantor → live)
• Admin-only approval when no on-chain guarantor
• Factory query APIs, user action state, edge cases + fuzz invariant

Test gaps (not yet covered)

• Dispute partially accepted & accepted verdict paths
• Guaranteed campaign off-chain fallback mode (LaunchOffChain)
• Guarantor freeze/delete admin actions
• Crowdfund creator withdrawal deadline enforcement (config exists, not enforced on-chain)

Run tests: npx hardhat test — 26 passing

Stack

• Next.js 15 App Router · shadcn/ui · Tailwind CSS
• Wagmi v2 + viem + RainbowKit (BNB Chain mainnet)
• Alchemy RPC with batched multicall (web/src/lib/alchemy-client.ts)
• TanStack Query with 30s stale time for chain reads

Routes

Data fetching pattern

All bulk reads use a dedicated Alchemy PublicClient with multicall batching. Guarantor lists use single-call getActiveGuarantorSummaries() instead of N×3 individual reads. Payment proofs indexed from on-chain event logs via getLogs().

Deploy script: scripts/deploy.js · Deploy order: CrowdfundAdmin → GuaranteeVault(admin=CrowdfundAdmin) → CrowdfundFactory → CrowdfundLens → GuaranteedCampaignFactory → link vault factories via configureVaultFactories()

Server deploy: web/deploy/nginx-setup.sh · Ubuntu + Node.js 20 + PM2 + nginx reverse proxy

Product specification requirement vs. current codebase status: