@aastar/core 0.16.7

package/dist/roles.js

@@ -0,0 +1,211 @@
+/**
+ * Role constants and utilities for AAstar SDK
+ * @remarks
+ * All role hashes and configurations match exactly with Registry.sol v3.0.0
+ *
+ * **Source**: /contracts/src/core/Registry.sol
+ */
+import { keccak256, toHex } from 'viem';
+// ========== Role Hash Constants (from Registry.sol lines 32-38) ==========
+/**
+ * Default Admin Role (OpenZeppelin AccessControl)
+ * @remarks
+ * - **Description**: Highest privilege, can grant/revoke all roles
+ * - **Permission**: Protocol governance only
+ * - **Source**: OpenZeppelin AccessControl DEFAULT_ADMIN_ROLE
+ */
+export const DEFAULT_ADMIN_ROLE = '0x0000000000000000000000000000000000000000000000000000000000000000';
+/**
+ * Community Role
+ * @remarks
+ * - **Description**: Community administrator, can issue xPNTs, configure SBT rules
+ * - **Permission**: Community-level governance
+ * - **Requirement**: minStake: 30 GT, entryBurn: 3 GT (line 99)
+ * - **Exit Fee**: 5% (500 basis points), min 1 GT
+ * - **Lock Duration**: 30 days
+ * - **Source**: Registry.sol line 32: ROLE_COMMUNITY = keccak256("COMMUNITY")
+ */
+export const ROLE_COMMUNITY = keccak256(toHex('COMMUNITY'));
+/**
+ * End User Role
+ * @remarks
+ * - **Description**: Community member, can participate and use gasless transactions
+ * - **Permission**: Basic user level
+ * - **Requirement**: minStake: 0.3 GT, entryBurn: 0.05 GT (line 100)
+ * - **Additional Requirement**: Must hold MySBT from community
+ * - **Exit Fee**: 10% (1000 basis points), min 0.05 GT
+ * - **Lock Duration**: 7 days
+ * - **Source**: Registry.sol line 33: ROLE_ENDUSER = keccak256("ENDUSER")
+ */
+export const ROLE_ENDUSER = keccak256(toHex('ENDUSER'));
+/**
+ * Paymaster AOA Role (Account Ownership Authentication)
+ * @remarks
+ * - **Description**: Basic Paymaster node operator with account-based auth
+ * - **Permission**: Infrastructure operator
+ * - **Requirement**: minStake: 30 GT, entryBurn: 3 GT (line 92)
+ * - **Exit Fee**: 10% (1000 basis points), min 1 GT
+ * - **Lock Duration**: 30 days
+ * - **Source**: Registry.sol line 34: ROLE_PAYMASTER_AOA = keccak256("PAYMASTER_AOA")
+ */
+export const ROLE_PAYMASTER_AOA = keccak256(toHex('PAYMASTER_AOA'));
+/**
+ * Paymaster Super Role
+ * @remarks
+ * - **Description**: Advanced Paymaster operator, can use SuperPaymaster with aPNTs collateral
+ * - **Permission**: Infrastructure operator (higher tier)
+ * - **Requirement**: minStake: 50 GT, entryBurn: 5 GT (line 93)
+ * - **Additional Requirement**: aPNTs collateral in SuperPaymaster contract
+ * - **Exit Fee**: 10% (1000 basis points), min 2 GT
+ * - **Lock Duration**: 30 days
+ * - **Source**: Registry.sol line 35: ROLE_PAYMASTER_SUPER = keccak256("PAYMASTER_SUPER")
+ */
+export const ROLE_PAYMASTER_SUPER = keccak256(toHex('PAYMASTER_SUPER'));
+/**
+ * DVT Role (Distributed Validator Technology)
+ * @remarks
+ * - **Description**: DVT node operator for consensus validation
+ * - **Permission**: Infrastructure operator
+ * - **Requirement**: minStake: 30 GT, entryBurn: 3 GT (line 94)
+ * - **Exit Fee**: 10% (1000 basis points), min 1 GT
+ * - **Lock Duration**: 30 days
+ * - **Source**: Registry.sol line 36: ROLE_DVT = keccak256("DVT")
+ */
+export const ROLE_DVT = keccak256(toHex('DVT'));
+/**
+ * ANODE Role (Anonymous Node)
+ * @remarks
+ * - **Description**: Anonymous infrastructure node operator
+ * - **Permission**: Infrastructure operator
+ * - **Requirement**: minStake: 20 GT, entryBurn: 2 GT (line 95)
+ * - **Exit Fee**: 10% (1000 basis points), min 1 GT
+ * - **Lock Duration**: 30 days
+ * - **Source**: Registry.sol line 37: ROLE_ANODE = keccak256("ANODE")
+ */
+export const ROLE_ANODE = keccak256(toHex('ANODE'));
+/**
+ * KMS Role (Key Management Service)
+ * @remarks
+ * - **Description**: KMS operator for secure key storage and management
+ * - **Permission**: Infrastructure operator (highest stake)
+ * - **Requirement**: minStake: 100 GT, entryBurn: 10 GT (line 98)
+ * - **Exit Fee**: 10% (1000 basis points), min 5 GT
+ * - **Lock Duration**: 30 days
+ * - **Source**: Registry.sol line 38: ROLE_KMS = keccak256("KMS")
+ */
+export const ROLE_KMS = keccak256(toHex('KMS'));
+// ========== Role Name Mapping ==========
+export const ROLE_NAMES = {
+    [DEFAULT_ADMIN_ROLE]: 'Default Admin',
+    [ROLE_COMMUNITY]: 'Community Admin',
+    [ROLE_ENDUSER]: 'End User',
+    [ROLE_PAYMASTER_AOA]: 'Paymaster (AOA)',
+    [ROLE_PAYMASTER_SUPER]: 'Paymaster (Super)',
+    [ROLE_DVT]: 'DVT Operator',
+    [ROLE_ANODE]: 'Anonymous Node',
+    [ROLE_KMS]: 'KMS Operator'
+};
+/**
+ * Get human-readable role name
+ */
+export function getRoleName(roleHash) {
+    return ROLE_NAMES[roleHash] || 'Unknown Role';
+}
+/**
+ * Role permission levels (for UI sorting/filtering)
+ */
+export var RolePermissionLevel;
+(function (RolePermissionLevel) {
+    RolePermissionLevel[RolePermissionLevel["PROTOCOL"] = 100] = "PROTOCOL";
+    RolePermissionLevel[RolePermissionLevel["KMS"] = 80] = "KMS";
+    RolePermissionLevel[RolePermissionLevel["OPERATOR"] = 50] = "OPERATOR";
+    RolePermissionLevel[RolePermissionLevel["COMMUNITY"] = 30] = "COMMUNITY";
+    RolePermissionLevel[RolePermissionLevel["USER"] = 10] = "USER"; // End Users
+})(RolePermissionLevel || (RolePermissionLevel = {}));
+export const ROLE_PERMISSION_LEVELS = {
+    [DEFAULT_ADMIN_ROLE]: RolePermissionLevel.PROTOCOL,
+    [ROLE_KMS]: RolePermissionLevel.KMS,
+    [ROLE_PAYMASTER_SUPER]: RolePermissionLevel.OPERATOR,
+    [ROLE_PAYMASTER_AOA]: RolePermissionLevel.OPERATOR,
+    [ROLE_DVT]: RolePermissionLevel.OPERATOR,
+    [ROLE_ANODE]: RolePermissionLevel.OPERATOR,
+    [ROLE_COMMUNITY]: RolePermissionLevel.COMMUNITY,
+    [ROLE_ENDUSER]: RolePermissionLevel.USER
+};
+/**
+ * Exact stake requirements from Registry.sol constructor (lines 92-100)
+ * @remarks
+ * **Warning**: These are initial values, always query contract for current configuration
+ */
+export const INITIAL_ROLE_STAKES = {
+    [ROLE_PAYMASTER_AOA]: {
+        minStake: '30 GT',
+        entryBurn: '3 GT',
+        exitFeePercent: '10%',
+        minExitFee: '1 GT',
+        lockDuration: '30 days',
+        line: 92
+    },
+    [ROLE_PAYMASTER_SUPER]: {
+        minStake: '50 GT',
+        entryBurn: '5 GT',
+        exitFeePercent: '10%',
+        minExitFee: '2 GT',
+        lockDuration: '30 days',
+        additionalRequirement: 'aPNTs collateral in SuperPaymaster',
+        line: 93
+    },
+    [ROLE_DVT]: {
+        minStake: '30 GT',
+        entryBurn: '3 GT',
+        exitFeePercent: '10%',
+        minExitFee: '1 GT',
+        lockDuration: '30 days',
+        line: 94
+    },
+    [ROLE_ANODE]: {
+        minStake: '20 GT',
+        entryBurn: '2 GT',
+        exitFeePercent: '10%',
+        minExitFee: '1 GT',
+        lockDuration: '30 days',
+        line: 95
+    },
+    [ROLE_KMS]: {
+        minStake: '100 GT',
+        entryBurn: '10 GT',
+        exitFeePercent: '10%',
+        minExitFee: '5 GT',
+        lockDuration: '30 days',
+        line: 98
+    },
+    [ROLE_COMMUNITY]: {
+        minStake: '30 GT',
+        entryBurn: '3 GT',
+        exitFeePercent: '5%',
+        minExitFee: '1 GT',
+        lockDuration: '30 days',
+        line: 99
+    },
+    [ROLE_ENDUSER]: {
+        minStake: '0.3 GT',
+        entryBurn: '0.05 GT',
+        exitFeePercent: '10%',
+        minExitFee: '0.05 GT',
+        lockDuration: '7 days',
+        additionalRequirement: 'Must hold MySBT from community',
+        line: 100
+    }
+};
+/**
+ * All defined roles array (for iteration)
+ */
+export const ALL_ROLES = [
+    ROLE_COMMUNITY,
+    ROLE_ENDUSER,
+    ROLE_PAYMASTER_AOA,
+    ROLE_PAYMASTER_SUPER,
+    ROLE_DVT,
+    ROLE_ANODE,
+    ROLE_KMS
+];

package/dist/roles.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/roles.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { ROLE_COMMUNITY, ROLE_ENDUSER, getRoleName, ROLE_PERMISSION_LEVELS, RolePermissionLevel, ALL_ROLES } from './roles.js';
+describe('Roles', () => {
+    it('should have consistent role hashes', () => {
+        expect(ROLE_COMMUNITY).toBeDefined();
+        expect(ROLE_ENDUSER).toBeDefined();
+        expect(ROLE_COMMUNITY.startsWith('0x')).toBe(true);
+    });
+    it('should return correct role names', () => {
+        expect(getRoleName(ROLE_COMMUNITY)).toBe('Community Admin');
+        expect(getRoleName(ROLE_ENDUSER)).toBe('End User');
+        expect(getRoleName('0x123')).toBe('Unknown Role');
+    });
+    it('should have correct permission levels', () => {
+        expect(ROLE_PERMISSION_LEVELS[ROLE_COMMUNITY]).toBe(RolePermissionLevel.COMMUNITY);
+        expect(ROLE_PERMISSION_LEVELS[ROLE_ENDUSER]).toBe(RolePermissionLevel.USER);
+    });
+    it('should include all roles in ALL_ROLES', () => {
+        expect(ALL_ROLES.length).toBeGreaterThan(0);
+        expect(ALL_ROLES).toContain(ROLE_COMMUNITY);
+        expect(ALL_ROLES).toContain(ROLE_ENDUSER);
+    });
+});

package/dist/utils/validation.d.ts

@@ -0,0 +1,24 @@
+export declare class AAStarValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates an Ethereum address.
+ * Throws AAStarValidationError if invalid.
+ */
+export declare function validateAddress(address: string, fieldName?: string): `0x${string}`;
+/**
+ * Validates a BigInt amount.
+ * @param amount The value to check
+ * @param fieldName Name for error messages
+ * @param min Minimum value (default 0n)
+ * @param max Maximum value (optional)
+ */
+export declare function validateAmount(amount: bigint, fieldName?: string, min?: bigint, max?: bigint): bigint;
+/**
+ * Validates a UINT128 value (Common in Paymaster Data).
+ */
+export declare function validateUint128(value: bigint, fieldName?: string): bigint;
+/**
+ * Validates a Hex string.
+ */
+export declare function validateHex(value: string, fieldName?: string): `0x${string}`;

package/dist/utils/validation.js

@@ -0,0 +1,56 @@
+import { isAddress, getAddress } from 'viem';
+export class AAStarValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AAStarValidationError';
+    }
+}
+/**
+ * Validates an Ethereum address.
+ * Throws AAStarValidationError if invalid.
+ */
+export function validateAddress(address, fieldName = 'Address') {
+    if (!address) {
+        throw new AAStarValidationError(`${fieldName} is required.`);
+    }
+    if (!isAddress(address)) {
+        throw new AAStarValidationError(`${fieldName} must be a valid Ethereum address. Got: ${address}`);
+    }
+    return getAddress(address); // Returns checksummed address
+}
+/**
+ * Validates a BigInt amount.
+ * @param amount The value to check
+ * @param fieldName Name for error messages
+ * @param min Minimum value (default 0n)
+ * @param max Maximum value (optional)
+ */
+export function validateAmount(amount, fieldName = 'Amount', min = 0n, max) {
+    if (amount < min) {
+        throw new AAStarValidationError(`${fieldName} must be >= ${min}. Got: ${amount}`);
+    }
+    if (max !== undefined && amount > max) {
+        throw new AAStarValidationError(`${fieldName} must be <= ${max}. Got: ${amount}`);
+    }
+    return amount;
+}
+/**
+ * Validates a UINT128 value (Common in Paymaster Data).
+ */
+export function validateUint128(value, fieldName = 'Value') {
+    const MAX_UINT128 = (1n << 128n) - 1n;
+    return validateAmount(value, fieldName, 0n, MAX_UINT128);
+}
+/**
+ * Validates a Hex string.
+ */
+export function validateHex(value, fieldName = 'Hex') {
+    if (!value.startsWith('0x')) {
+        throw new AAStarValidationError(`${fieldName} must start with 0x. Got: ${value}`);
+    }
+    const hexRegex = /^0x[0-9a-fA-F]*$/;
+    if (!hexRegex.test(value)) {
+        throw new AAStarValidationError(`${fieldName} must be a valid hex string.`);
+    }
+    return value;
+}

package/dist/utils/validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/validation.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { validateAddress, validateAmount, validateHex, AAStarValidationError } from './validation.js';
+describe('Validation Utils', () => {
+    describe('validateAddress', () => {
+        it('should pass for valid Ethereum addresses', () => {
+            const validAddr = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';
+            expect(validateAddress(validAddr)).toBe(validAddr);
+        });
+        it('should throw for invalid addresses', () => {
+            expect(() => validateAddress('0xInvalid')).toThrow(AAStarValidationError);
+        });
+        it('should checksum address', () => {
+            const lower = '0xd8da6bf26964af9d7eed9e03e53415d37aa96045';
+            const checksummed = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';
+            expect(validateAddress(lower)).toBe(checksummed);
+        });
+    });
+    describe('validateAmount', () => {
+        it('should pass for positive amounts', () => {
+            expect(validateAmount(100n)).toBe(100n);
+        });
+        it('should throw for negative amounts', () => {
+            expect(() => validateAmount(-1n)).toThrow(AAStarValidationError);
+        });
+        it('should throw if exceeds max', () => {
+            expect(() => validateAmount(100n, 'Test', 0n, 50n)).toThrow(AAStarValidationError);
+        });
+    });
+    describe('validateHex', () => {
+        it('should pass for valid hex strings', () => {
+            expect(validateHex('0x1234')).toBe('0x1234');
+        });
+        it('should throw if missing 0x prefix', () => {
+            expect(() => validateHex('1234')).toThrow(AAStarValidationError);
+        });
+        it('should throw for non-hex characters', () => {
+            expect(() => validateHex('0xZZZZ')).toThrow(AAStarValidationError);
+        });
+    });
+});

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+import { type Hex, type Address } from 'viem';
+export type PaymasterAndData = {
+    paymaster: Address;
+    verificationGasLimit: bigint;
+    postOpGasLimit: bigint;
+    operator: Address;
+};
+/**
+ * Format PaymasterAndData for SuperPaymaster V3
+ * Layout: [Paymaster(20)] [VerGas(16)] [PostOpGas(16)] [Operator(20)]
+ */
+export declare function encodePaymasterData(params: PaymasterAndData): Hex;

package/dist/utils.js

@@ -0,0 +1,14 @@
+import { concat, pad, toHex } from 'viem';
+/**
+ * Format PaymasterAndData for SuperPaymaster V3
+ * Layout: [Paymaster(20)] [VerGas(16)] [PostOpGas(16)] [Operator(20)]
+ */
+export function encodePaymasterData(params) {
+    // strict length checks can be added here
+    return concat([
+        params.paymaster,
+        pad(toHex(params.verificationGasLimit), { size: 16 }),
+        pad(toHex(params.postOpGasLimit), { size: 16 }),
+        params.operator
+    ]);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@aastar/core",
+  "version": "0.16.7",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@noble/curves": "^1.6.0",
+    "viem": "2.43.3"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.17",
+    "abitype": "1.2.3",
+    "typescript": "5.7.2",
+    "vitest": "4.0.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "clean": "find src -name '*.js' -o -name '*.d.ts' -o -name '*.map' | xargs rm -f",
+    "build": "pnpm clean && tsc",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "ESLINT_USE_FLAT_CONFIG=false eslint src --ext .ts",
+    "lint:fix": "ESLINT_USE_FLAT_CONFIG=false eslint src --ext .ts --fix",
+    "audit:abi": "npx tsx scripts/audit-abi-coverage.ts"
+  }
+}