@bbuilders/djeon402-core 1.0.1

package/README.md

@@ -0,0 +1,240 @@
+# @bbuilders/djeon402/core
+
+Core types, ABIs, constants, and utilities for the DJEON402 token ecosystem.
+
+## 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.
+
+## Installation
+
+```bash
+npm install @bbuilders/djeon402/core
+```
+
+## Package Contents
+
+### ABIs
+
+Contract Application Binary Interfaces for interacting with DJEON402 smart contracts:
+
+```typescript
+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
+```typescript
+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
+```typescript
+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
+```typescript
+type KYCLevel = 0 | 1 | 2 | 3;
+type KYCLevelName = 'None' | 'Tier1' | 'Tier2' | 'Tier3';
+
+interface KYCData {
+  level: KYCLevel;
+  levelName: KYCLevelName;
+  expiryDate: number;
+  expiryDateReadable: string;
+  kycHash: string;
+  isActive: boolean;
+  dailyLimit: string;
+  dailyLimitRaw: string;
+  dailySpent: string;
+  dailySpentRaw: string;
+  userAddress: Address;
+}
+```
+
+#### x402 Types (EIP-3009)
+```typescript
+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
+
+EIP-712 constants for typed structured data signing:
+
+```typescript
+import {
+  TRANSFER_WITH_AUTHORIZATION_TYPEHASH,
+  RECEIVE_WITH_AUTHORIZATION_TYPEHASH,
+  CANCEL_AUTHORIZATION_TYPEHASH,
+  DEFAULT_VALID_AFTER,
+  DEFAULT_VALID_BEFORE,
+} from '@bbuilders/djeon402/core';
+```
+
+### Utilities
+
+Helper functions for formatting and validation:
+
+#### Formatting
+```typescript
+import {
+  formatTokenAmount,
+  parseTokenAmount,
+  formatTimestamp,
+  getKYCLevelName,
+} from '@bbuilders/djeon402/core';
+
+// Format raw token amount to human-readable string
+const formatted = formatTokenAmount('1000000000000000000', 18); // "1.0"
+
+// Parse human-readable amount to raw bigint
+const raw = parseTokenAmount('1.5', 18); // 1500000000000000000n
+
+// Format UNIX timestamp to readable date
+const date = formatTimestamp(1735632000); // "2024-12-31T00:00:00.000Z"
+
+// Get KYC level name
+const levelName = getKYCLevelName(2); // "Tier2"
+```
+
+#### Validation
+```typescript
+import {
+  validateAddress,
+  validatePrivateKey,
+  validateAmount,
+} 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:
+
+```typescript
+// In @bbuilders/djeon402/sdk-node
+import {
+  DJEON402_ABI,
+  type TokenInfo,
+  type TransferResult,
+  formatTokenAmount,
+  validateAddress,
+} from '@bbuilders/djeon402/core';
+```
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@bbuilders/djeon402/sdk-node](../sdk-node) - Node.js/Backend SDK
+- [@bbuilders/djeon402/sdk-client](../sdk-client) - Browser/Frontend SDK
+- [djeon402-sdk](../sdk-py) - Python SDK