gitlumen-b20kit-sdk

TypeScript SDK for Base B20 token factory, activation, and management. Built on top of viem.

v0.1.0-alpha — Factory + Activation + Basic Token Management

Installation

npm install gitlumen-b20kit-sdk viem

viem is a peer dependency and must be installed alongside the SDK.

Quick Start

Using Private Key (server-side / scripts)

import { B20Kit } from "gitlumen-b20kit-sdk";

const kit = new B20Kit({
  network: "baseSepolia", // or "base" for mainnet
  privateKey: "0xYourPrivateKey",
});

console.log("Signer:", kit.address);

Using Wallet Signer (browser / dApp)

import { B20Kit } from "gitlumen-b20kit-sdk";
import { createWalletClient, custom } from "viem";
import { baseSepolia } from "viem/chains";

const walletClient = createWalletClient({
  account: "0xYourAddress",
  chain: baseSepolia,
  transport: custom(window.ethereum),
});

const kit = new B20Kit({
  network: "baseSepolia",
  walletClient,
});

Features

1. Activation Registry

Check whether B20 features are activated on the current network.

const assetActive = await kit.isB20AssetActivated();
const stablecoinActive = await kit.isB20StablecoinActivated();

2. Token Creation (Factory)

Create Asset Token

Configurable decimals (6–18), optional supply cap, initial supply, and minter list.

const { tokenAddress, txHash } = await kit.createAssetToken({
  name: "My Token",
  symbol: "MTK",
  admin: kit.address,
  decimals: 18,
  supplyCap: 1_000_000n * 10n ** 18n,       // optional
  initialSupply: 100_000n * 10n ** 18n,      // optional, minted to admin
  minters: ["0xMinterAddress"],               // optional
});

console.log("Token deployed at:", tokenAddress);

Create Stablecoin Token

Fixed 6 decimals, requires an ISO currency code.

const { tokenAddress, txHash } = await kit.createStablecoinToken({
  name: "USD Stablecoin",
  symbol: "USDX",
  admin: kit.address,
  currency: "USD",
  supplyCap: 10_000_000n * 10n ** 6n,        // optional
  initialSupply: 1_000_000n * 10n ** 6n,     // optional
});

Predict Token Address

Compute the deterministic address before deployment.

import { B20Variant } from "gitlumen-b20kit-sdk";

const predictedAddress = await kit.getB20Address(
  B20Variant.ASSET,
  kit.address,
  "0x0000000000000000000000000000000000000000000000000000000000000001",
);

Verify B20 Token

const valid = await kit.isB20("0xTokenAddress");
const initialized = await kit.isB20Initialized("0xTokenAddress");

3. Token Management

Read Operations

const token = "0xTokenAddress";

// Get full token info (name, symbol, decimals, totalSupply, supplyCap)
const info = await kit.getTokenInfo(token);

// Balance and allowance
const balance = await kit.balanceOf(token, "0xAccountAddress");
const allowed = await kit.allowance(token, "0xOwner", "0xSpender");

// Check role
import { B20_ROLES } from "gitlumen-b20kit-sdk";
const isMinter = await kit.hasRole(token, B20_ROLES.MINT_ROLE, "0xAccount");

Mint

const txHash = await kit.mint(token, "0xRecipient", 1000n * 10n ** 18n);

// With memo
const txHash2 = await kit.mintWithMemo(token, "0xRecipient", 1000n * 10n ** 18n, "0xCAFE");

// Batch mint
const txHash3 = await kit.batchMint(
  token,
  ["0xAddr1", "0xAddr2"],
  [500n * 10n ** 18n, 300n * 10n ** 18n],
);

Burn

const txHash = await kit.burn(token, 100n * 10n ** 18n);

Transfer

const txHash = await kit.transfer(token, "0xRecipient", 50n * 10n ** 18n);

Approve

const txHash = await kit.approve(token, "0xSpender", 1000n * 10n ** 18n);

4. Role Management

B20 tokens use role-based access control. Available roles:

| Role | Constant | Controls | |------|----------|----------| | Default Admin | B20_ROLES.DEFAULT_ADMIN_ROLE | Role management, policy updates, supply cap | | Mint | B20_ROLES.MINT_ROLE | mint(), mintWithMemo() | | Burn | B20_ROLES.BURN_ROLE | burn(), burnWithMemo() | | Burn Blocked | B20_ROLES.BURN_BLOCKED_ROLE | burnBlocked() | | Pause | B20_ROLES.PAUSE_ROLE | pause() | | Unpause | B20_ROLES.UNPAUSE_ROLE | unpause() | | Metadata | B20_ROLES.METADATA_ROLE | updateName(), updateSymbol(), updateContractURI() | | Operator | B20_ROLES.OPERATOR_ROLE | Asset-only: updateMultiplier(), announce() |

import { B20_ROLES } from "gitlumen-b20kit-sdk";

// Grant / revoke any role
await kit.grantRole(token, B20_ROLES.BURN_ROLE, "0xAccount");
await kit.revokeRole(token, B20_ROLES.PAUSE_ROLE, "0xAccount");

// Shorthand for mint role
await kit.grantMintRole(token, "0xAccount");
await kit.revokeMintRole(token, "0xAccount");

5. Supply Cap

// Set or increase supply cap (irreversible once set to MAX_SUPPLY_CAP)
await kit.updateSupplyCap(token, 5_000_000n * 10n ** 18n);

// Remove cap entirely
import { MAX_SUPPLY_CAP } from "gitlumen-b20kit-sdk";
await kit.updateSupplyCap(token, MAX_SUPPLY_CAP);

6. Pause / Unpause

// Pause specific features (bitmask)
await kit.pause(token, 1n);

// Unpause
await kit.unpause(token, 1n);

7. Metadata (ERC-7572)

await kit.updateName(token, "New Token Name");
await kit.updateSymbol(token, "NTK");
await kit.updateContractURI(token, "https://example.com/metadata.json");

8. Policy Management

Assign transfer policies per scope to restrict senders, receivers, or executors.

import { POLICY_SCOPES } from "gitlumen-b20kit-sdk";

// Attach a blocklist/allowlist policy to a scope
await kit.updatePolicy(token, POLICY_SCOPES.TRANSFER_SENDER_POLICY, policyId);

Available policy scopes:

| Scope | Target | |-------|--------| | TRANSFER_SENDER_POLICY | from in transfers | | TRANSFER_RECEIVER_POLICY | to in transfers | | TRANSFER_EXECUTOR_POLICY | msg.sender in transferFrom | | MINT_RECEIVER_POLICY | to in mint operations |

Functional API

Every method is also available as a standalone function for use without the B20Kit class:

import {
  createB20Clients,
  createAssetToken,
  mint,
  balanceOf,
  isB20AssetActivated,
} from "gitlumen-b20kit-sdk";

const clients = createB20Clients({
  network: "baseSepolia",
  privateKey: "0x...",
});

const { tokenAddress } = await createAssetToken(clients, {
  name: "My Token",
  symbol: "MTK",
  admin: "0xAdminAddress",
  decimals: 18,
});

await mint(clients, tokenAddress, "0xRecipient", 1000n * 10n ** 18n);
const balance = await balanceOf(clients, tokenAddress, "0xRecipient");

ABI Access

Import raw ABI arrays for direct use with viem or other libraries:

import {
  b20FactoryAbi,
  b20TokenAbi,
  activationRegistryAbi,
  policyRegistryAbi,
} from "gitlumen-b20kit-sdk/abi";

Constants

import {
  B20_FACTORY_ADDRESS,           // 0xB20f000000000000000000000000000000000000
  ACTIVATION_REGISTRY_ADDRESS,   // 0x8453000000000000000000000000000000000001
  POLICY_REGISTRY_ADDRESS,       // 0x8453000000000000000000000000000000000002
  B20Variant,                    // ASSET = 0, STABLECOIN = 1
  B20_ROLES,                     // All role hashes
  POLICY_SCOPES,                 // All policy scope hashes
  FEATURE_KEYS,                  // Activation feature keys
  PolicyType,                    // BLOCKLIST = 0, ALLOWLIST = 1
  MAX_SUPPLY_CAP,                // uint128 max
} from "gitlumen-b20kit-sdk";

Supported Networks

| Network | Chain ID | Default RPC | |---------|----------|-------------| | Base Mainnet | 8453 | https://mainnet.base.org | | Base Sepolia | 84532 | https://sepolia.base.org |

All B20 precompile addresses are identical across networks.

TypeScript Types

import type {
  B20KitConfig,
  AssetParams,
  StablecoinParams,
  CreateB20Options,
  CreateB20Result,
  TokenInfo,
  B20Clients,
  SupportedNetwork,
} from "gitlumen-b20kit-sdk";

Requirements

• Node.js >= 18
• TypeScript >= 5.0
• viem >= 2.0.0

License

MIT