@bbuilders/djeon402-core

Core types, ABIs, constants, and utilities for the DJEON402 token ecosystem.

What's New in 2.0

Breaking changes (aligned with the on-chain token):

• Token decimals are 6 (USDC/x402 convention) — DJEON402_DECIMALS changed from 18 to 6; formatTokenAmount/parseTokenAmount defaults follow
• EIP712_DOMAIN_NAME constant removed — the EIP-712 domain name is the deploy-time token name; read it from the contract (name() / DOMAIN_SEPARATOR())
• validateKYCLevel now accepts levels 0-4 (Tier4 included)
• KYCVerifyParams gained an optional kycHash; RemainingDailyLimit type documented as the canonical remaining-limit shape

Overview

This package provides the foundational building blocks shared across all DJEON402 SDK packages:

• TypeScript type definitions for all contract interactions
• Smart contract ABIs (DJEON402 token and KYC Registry)
• EIP-712 constants for typed structured data signing
• Utility functions for formatting, validation, and data transformation

This package is designed to be used as a dependency by other SDK packages (@bbuilders/djeon402-sdk-node, @bbuilders/djeon402-sdk-client) and is not typically installed directly by end users.

Units & Decimals

The DJEON402 token uses 6 decimals (USDC/x402 convention): $1 = 1_000_000 base units.

• DJEON402_DECIMALS = 6 is exported from this package and used as the default by formatTokenAmount / parseTokenAmount
• All on-chain amounts (transfers, registry limits, x402 amount fields) are 6-decimal base-unit values
• x402 v2 payment requirements carry amounts already in base units — never run them through parseTokenAmount again

Installation

npm install @bbuilders/djeon402-core

Package Contents

ABIs

Contract Application Binary Interfaces for interacting with DJEON402 smart contracts:

import { DJEON402_ABI, KYC_REGISTRY_ABI } from '@bbuilders/djeon402-core';

• DJEON402_ABI - ERC-20 token contract with x402, KYC, admin features
• KYC_REGISTRY_ABI - KYC registry contract for user verification

Types

Comprehensive TypeScript type definitions:

Token Types

interface TokenInfo {
  name: string;
  symbol: string;
  decimals: number;
  totalSupply: string;
  totalSupplyRaw: string;
  paused: boolean;
  contractAddress: Address;
}

interface BalanceResult {
  address: Address;
  balance: string;
  balanceRaw: string;
}

interface TransferResult {
  success: boolean;
  hash: Hash;
  blockNumber: string;
}

Admin Types

interface RolesResult {
  DEFAULT_ADMIN_ROLE: Hex;
  MINTER_ROLE: Hex;
  BURNER_ROLE: Hex;
  PAUSER_ROLE: Hex;
  BLACKLISTER_ROLE: Hex;
}

interface BlacklistResult {
  address: Address;
  isBlacklisted: boolean;
}

KYC Types

type KYCLevel = 0 | 1 | 2 | 3 | 4;
type KYCLevelName = 'None' | 'Tier1' | 'Tier2' | 'Tier3' | 'Tier4';

interface KYCData {
  level: KYCLevel;
  levelName: KYCLevelName;
  expiryDate: number;
  expiryDateReadable: string; // ISO string, or "No Expiry" when expiryDate is 0
  kycHash: string;
  isActive: boolean;
  dailyLimit: string;
  dailyLimitRaw: string;
  dailySpent: string;
  dailySpentRaw: string;
  userAddress: Address;
}

interface KYCVerifyParams {
  adminPrivateKey: `0x${string}`;
  userAddress: Address;
  level: KYCLevel;
  expiryDate?: number;
  documents: KYCDocument[];
  kycHash?: string; // IPFS hash; derived deterministically from documents when omitted
}

interface RemainingDailyLimit {
  remaining: string;      // human-readable (6 decimals)
  remainingRaw: string;   // base units
  userAddress: Address;
}

x402 Types (EIP-3009)

interface TransferAuthorizationSignature {
  from: Address;
  to: Address;
  value: bigint;
  validAfter: bigint;
  validBefore: bigint;
  nonce: Hex;
  v: number;
  r: Hex;
  s: Hex;
}

interface ReceiveAuthorizationSignature {
  from: Address;
  to: Address;
  value: bigint;
  validAfter: bigint;
  validBefore: bigint;
  nonce: Hex;
  v: number;
  r: Hex;
  s: Hex;
}

interface SignTransferAuthParams {
  privateKey: `0x${string}`;
  from: Address;
  to: Address;
  amount: string;
  validAfter?: bigint;
  validBefore?: bigint;
  nonce?: Hex;
}

interface SignReceiveAuthParams {
  privateKey: `0x${string}`;
  from: Address;
  to: Address;
  amount: string;
  validAfter?: bigint;
  validBefore?: bigint;
  nonce?: Hex;
}

interface CancelAuthorizationParams {
  privateKey: `0x${string}`;
  authorizer: Address;
  nonce: Hex;
}

interface CancelAuthorizationResult {
  success: boolean;
  hash: Hash;
  blockNumber: string;
}

Constants

import {
  DJEON402_DECIMALS, // 6 (USDC/x402 convention)
  EIP712_DOMAIN_VERSION, // "1"
  TRANSFER_WITH_AUTHORIZATION_TYPEHASH,
  RECEIVE_WITH_AUTHORIZATION_TYPEHASH,
  CANCEL_AUTHORIZATION_TYPEHASH,
  DEFAULT_VALID_AFTER,
  DEFAULT_VALID_BEFORE,
} from '@bbuilders/djeon402-core';

Note: There is intentionally no EIP712_DOMAIN_NAME constant. The EIP-712 domain name is the token name chosen at deploy time — always read it from the contract (name() or DOMAIN_SEPARATOR()). The SDK signing paths do this automatically.

Utilities

Helper functions for formatting and validation:

Formatting

import {
  formatTokenAmount,
  parseTokenAmount,
  formatTimestamp,
  getKYCLevelName,
} from '@bbuilders/djeon402-core';

// Format raw token amount to human-readable string (decimals default: 6)
const formatted = formatTokenAmount(1000000n); // "1"

// Parse human-readable amount to raw bigint (decimals default: 6)
const raw = parseTokenAmount('1.5'); // 1500000n

// Format UNIX timestamp to readable date (0 => "No Expiry")
const date = formatTimestamp(1735632000); // "2024-12-31T00:00:00.000Z"

// Get KYC level name
const levelName = getKYCLevelName(2); // "Tier2"

Validation

import {
  validateAddress,
  validatePrivateKey,
  validateAmount,
  validateKYCLevel, // accepts 0-4 (None, Tier1-Tier4)
} from '@bbuilders/djeon402-core';

// Validate Ethereum address
validateAddress('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'); // throws if invalid

// Validate private key format
validatePrivateKey('0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80');

// Validate amount string
validateAmount('100.5'); // throws if invalid

Usage in SDK Packages

This package is designed to be imported by other SDK packages:

// In @bbuilders/djeon402-sdk-node
import {
  DJEON402_ABI,
  type TokenInfo,
  type TransferResult,
  formatTokenAmount,
  validateAddress,
} from '@bbuilders/djeon402-core';

License

MIT

Related Packages

• @bbuilders/djeon402-contracts - Smart Contracts (Solidity / Foundry)
• @bbuilders/djeon402-sdk-node - Node.js/Backend SDK
• @bbuilders/djeon402-sdk-client - Browser/Frontend SDK