SINAI STANDARD

Pattern: Max Balance (Concentration Limit)

Create a token with per-wallet balance caps to prevent concentration violations

Overview

The max balance hook enforces a maximum token holding per wallet. Transfers that would push a wallet above the limit are rejected. Common for preventing concentration violations in regulated offerings (Reg D/S investor limits, fund diversification rules).

Implementation

import { AksumKit, MaxBalanceManager } from "@sinai-standard/sdk";
 
const MAX_BALANCE = 1_000_000 * 10 ** 6; // 1M tokens (6 decimals)
 
// Create the token (max balance hook is initialized separately)
const token = await kit.createToken({
  name: "Capped Fund Token",
  symbol: "CFT",
  decimals: 6,
  supply: 50_000_000,
});
 
const maxBal = new MaxBalanceManager(maxBalanceProgram, token.mint);
await maxBal.initialize(issuer.publicKey, MAX_BALANCE);
await maxBal.initializeExtraAccountMetas(issuer.publicKey);
 
// Transfer within limit: ALLOWED
// Transfer exceeding limit: BLOCKED with MaxBalanceExceeded
 
// Check the current config
const config = await maxBal.fetchConfig();
console.log("Max balance:", config.maxBalance);
console.log("Active:", config.isActive);

Updating the Limit

// Raise the cap to 2M tokens
await maxBal.updateMaxBalance(issuer.publicKey, 2_000_000 * 10 ** 6);
 
// Temporarily disable enforcement
await maxBal.toggleActive(issuer.publicKey, false);
 
// Re-enable
await maxBal.toggleActive(issuer.publicKey, true);

Key Points

  • The hook reads the destination token account balance at byte offset 64 and checks balance + amount <= maxBalance
  • updateMaxBalance() takes effect immediately — all future transfers use the new limit
  • Wallets already above the new limit are not affected, but cannot receive more tokens
  • Use toggleActive(false) to temporarily bypass all max balance checks
  • Set maxBalance to 0 is invalid and will fail with InvalidMaxBalance

On this page