@aastar/core 0.16.7 → 0.16.11

package/dist/errors/index.js

@@ -0,0 +1,123 @@
+/**
+ * Error handling utilities for SDK
+ * Provides consistent error types and error transformation from viem
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    // Validation Errors (1xxx)
+    ErrorCode["INVALID_ADDRESS"] = "E1001";
+    ErrorCode["INVALID_AMOUNT"] = "E1002";
+    ErrorCode["INVALID_PARAMETER"] = "E1003";
+    ErrorCode["REQUIRED_PARAMETER"] = "E1004";
+    ErrorCode["INVALID_HEX"] = "E1005";
+    // Contract Errors (2xxx)
+    ErrorCode["CONTRACT_REVERT"] = "E2001";
+    ErrorCode["INSUFFICIENT_BALANCE"] = "E2002";
+    ErrorCode["UNAUTHORIZED"] = "E2003";
+    ErrorCode["PAUSED"] = "E2004";
+    ErrorCode["ROLE_NOT_CONFIGURED"] = "E2005";
+    ErrorCode["TOKEN_NOT_FOUND"] = "E2006";
+    // Network Errors (3xxx)
+    ErrorCode["NETWORK_TIMEOUT"] = "E3001";
+    ErrorCode["RPC_ERROR"] = "E3002";
+    ErrorCode["CONNECTION_REFUSED"] = "E3003";
+    // SDK Errors (4xxx)
+    ErrorCode["NOT_IMPLEMENTED"] = "E4001";
+    ErrorCode["INTERNAL_ERROR"] = "E4002";
+    ErrorCode["INVALID_CONFIGURATION"] = "E4003";
+    // Bundler & AA Errors (5xxx)
+    ErrorCode["BUNDLER_ERROR"] = "E5001";
+    ErrorCode["BUNDLER_USER_OP_REVERTED"] = "E5002";
+    ErrorCode["BUNDLER_SIGNATURE_INVALID"] = "E5003";
+    ErrorCode["BUNDLER_INSUFFICIENT_FUNDS"] = "E5004";
+    ErrorCode["BUNDLER_NONCE_TOO_LOW"] = "E5005";
+    ErrorCode["BUNDLER_RATE_LIMIT"] = "E5006";
+})(ErrorCode || (ErrorCode = {}));
+/**
+ * Base SDK error class with structured error information
+ */
+export class AAStarError extends Error {
+    code;
+    cause;
+    data;
+    constructor(code, message, cause, data) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.data = data;
+        this.name = 'AAStarError';
+        // Maintains proper stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, AAStarError);
+        }
+    }
+    /**
+     * Convert viem error to AAStarError with appropriate error code
+     */
+    static fromViemError(error, context) {
+        const msg = error.message.toLowerCase();
+        // Contract revert patterns
+        if (msg.includes('insufficient balance') || msg.includes('insufficient funds')) {
+            return new AAStarError(ErrorCode.INSUFFICIENT_BALANCE, 'Insufficient token balance for this operation', error);
+        }
+        if (msg.includes('paused')) {
+            return new AAStarError(ErrorCode.PAUSED, 'Contract is currently paused', error);
+        }
+        if (msg.includes('unauthorized') || msg.includes('not authorized')) {
+            return new AAStarError(ErrorCode.UNAUTHORIZED, 'Unauthorized to perform this action', error);
+        }
+        if (msg.includes('role not configured')) {
+            return new AAStarError(ErrorCode.ROLE_NOT_CONFIGURED, 'Role has not been configured in registry', error);
+        }
+        // Network errors
+        if (msg.includes('timeout') || msg.includes('etimedout')) {
+            return new AAStarError(ErrorCode.NETWORK_TIMEOUT, 'Network request timed out', error);
+        }
+        if (msg.includes('econnrefused') || msg.includes('connection refused')) {
+            return new AAStarError(ErrorCode.CONNECTION_REFUSED, 'Could not connect to RPC endpoint', error);
+        }
+        if (msg.includes('rpc')) {
+            return new AAStarError(ErrorCode.RPC_ERROR, 'RPC request failed', error);
+        }
+        // Default to contract revert
+        return new AAStarError(ErrorCode.CONTRACT_REVERT, context ? `Contract call failed: ${context}` : error.message, error);
+    }
+    /**
+     * Parse bundler error strings into structured AAStarError
+     */
+    static fromBundlerError(error) {
+        const message = typeof error === 'string' ? error : (error.message || JSON.stringify(error));
+        const code = error.code;
+        const msgLower = message.toLowerCase();
+        // Mapping ERC-4337 Error Codes (AAxx)
+        if (msgLower.includes('aa10') || msgLower.includes('invalid signature')) {
+            return new AAStarError(ErrorCode.BUNDLER_SIGNATURE_INVALID, `AA10: Invalid UserOperation signature`, error);
+        }
+        if (msgLower.includes('aa21') || msgLower.includes('aa25') || msgLower.includes('reverted')) {
+            return new AAStarError(ErrorCode.BUNDLER_USER_OP_REVERTED, `AA2x: UserOperation execution reverted`, error);
+        }
+        if (msgLower.includes('aa31') || msgLower.includes('aa33') || msgLower.includes('paymaster deposit too low')) {
+            return new AAStarError(ErrorCode.BUNDLER_INSUFFICIENT_FUNDS, `AA3x: Paymaster or account insufficient funds`, error);
+        }
+        if (msgLower.includes('aa24') || msgLower.includes('nonce too low')) {
+            return new AAStarError(ErrorCode.BUNDLER_NONCE_TOO_LOW, `AA24: Nonce too low or already used`, error);
+        }
+        if (code === -32604 || msgLower.includes('rate limit')) {
+            return new AAStarError(ErrorCode.BUNDLER_RATE_LIMIT, `Bundler rate limit exceeded (429)`, error);
+        }
+        return new AAStarError(ErrorCode.BUNDLER_ERROR, `Bundler error: ${message}`, error);
+    }
+    /**
+     * Convert to JSON for logging/reporting
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            data: this.data,
+            cause: this.cause?.message,
+            stack: this.stack,
+        };
+    }
+}

package/dist/index.d.ts

@@ -6,6 +6,7 @@
 export * from './branding.js';
 export * from './contract-addresses.js';
 export * from './contracts.js';
+export * from './contract-versions.js';
 export * from './networks.js';
 export * from './constants.js';
 export * from './communities.js';
@@ -13,9 +14,9 @@ export * from './abis/index.js';
 export * from './clients.js';
 export * from './clients/types.js';
 export * from './clients/BaseClient.js';
+export * from './clients/BundlerClient.js';
 export * from './actions/index.js';
 export * from './crypto/index.js';
 export * from './roles.js';
 export * from './requirementChecker.js';
 export * from './config/ContractConfigManager.js';
-export * from './utils/validation.js';

package/dist/index.js

@@ -6,6 +6,7 @@
 export * from './branding.js';
 export * from './contract-addresses.js'; // Single source of truth for all contract addresses
 export * from './contracts.js';
+export * from './contract-versions.js';
 export * from './networks.js';
 export * from './constants.js';
 export * from './communities.js'; // Community configurations
@@ -13,9 +14,9 @@ export * from './abis/index.js'; // Assuming abis is a folder with index.ts
 export * from './clients.js';
 export * from './clients/types.js';
 export * from './clients/BaseClient.js';
+export * from './clients/BundlerClient.js';
 export * from './actions/index.js';
 export * from './crypto/index.js';
 export * from './roles.js'; // Role system
 export * from './requirementChecker.js'; // Requirement validation
 export * from './config/ContractConfigManager.js';
-export * from './utils/validation.js';

package/dist/requirementChecker.d.ts

@@ -6,8 +6,24 @@ import { Address, PublicClient } from 'viem';
 import type { RoleRequirement } from './roles.js';
 /**
  * Requirement Checker Utility
+ * @description Centralized validation for all role requirements
  *
- * Centralized validation for all role requirements
+ * @example
+ * ```typescript
+ * const checker = new RequirementChecker(publicClient);
+ *
+ * // Check community launch requirements
+ * const result = await checker.checkRequirements({
+ *     address: userAddress,
+ *     roleId: ROLE_COMMUNITY,
+ *     requiredGToken: parseEther("33"),
+ *     requireSBT: false
+ * });
+ *
+ * if (!result.hasEnoughGToken) {
+ *     console.error(result.missingRequirements.join('\n'));
+ * }
+ * ```
  */
 export declare class RequirementChecker {
     private publicClient;
@@ -18,6 +34,12 @@ export declare class RequirementChecker {
         apnts?: Address;
         mysbt?: Address;
     } | undefined);
+    /**
+     * Check all requirements for a user
+     *
+     * @param params Check parameters
+     * @returns Detailed requirement status
+     */
     checkRequirements(params: {
         address: Address;
         roleId?: `0x${string}`;
@@ -25,14 +47,26 @@ export declare class RequirementChecker {
         requiredAPNTs?: bigint;
         requireSBT?: boolean;
     }): Promise<RoleRequirement>;
+    /**
+     * Check GToken balance only (shortcut)
+     */
     checkGTokenBalance(address: Address, required: bigint): Promise<{
         balance: bigint;
         hasEnough: boolean;
     }>;
+    /**
+     * Check aPNTs balance only (shortcut)
+     */
     checkAPNTsBalance(address: Address, required: bigint): Promise<{
         balance: bigint;
         hasEnough: boolean;
     }>;
+    /**
+     * Check if user has MySBT (shortcut)
+     */
     checkHasSBT(address: Address): Promise<boolean>;
+    /**
+     * Check if user has specific role (shortcut)
+     */
     checkHasRole(roleId: `0x${string}`, address: Address): Promise<boolean>;
 }

package/dist/requirementChecker.js

@@ -15,8 +15,24 @@ const MYSBT_ABI = parseAbi([
 ]);
 /**
  * Requirement Checker Utility
+ * @description Centralized validation for all role requirements
  *
- * Centralized validation for all role requirements
+ * @example
+ * ```typescript
+ * const checker = new RequirementChecker(publicClient);
+ *
+ * // Check community launch requirements
+ * const result = await checker.checkRequirements({
+ *     address: userAddress,
+ *     roleId: ROLE_COMMUNITY,
+ *     requiredGToken: parseEther("33"),
+ *     requireSBT: false
+ * });
+ *
+ * if (!result.hasEnoughGToken) {
+ *     console.error(result.missingRequirements.join('\n'));
+ * }
+ * ```
  */
 export class RequirementChecker {
     publicClient;
@@ -25,9 +41,16 @@ export class RequirementChecker {
         this.publicClient = publicClient;
         this.addresses = addresses;
     }
+    /**
+     * Check all requirements for a user
+     *
+     * @param params Check parameters
+     * @returns Detailed requirement status
+     */
     async checkRequirements(params) {
         const { address, roleId, requiredGToken = 0n, requiredAPNTs = 0n, requireSBT = false } = params;
         const missingRequirements = [];
+        // Check role (if specified)
         let hasRole = false;
         if (roleId) {
             const { CORE_ADDRESSES } = await import('./contract-addresses.js');
@@ -41,6 +64,7 @@ export class RequirementChecker {
                 missingRequirements.push(`Does not have required role`);
             }
         }
+        // Check GToken balance
         let hasEnoughGToken = true;
         if (requiredGToken > 0n) {
             const { CORE_ADDRESSES } = await import('./contract-addresses.js');
@@ -55,6 +79,7 @@ export class RequirementChecker {
                 missingRequirements.push(`Need ${requiredGToken.toString()} GToken, have ${gtokenBalance.toString()}`);
             }
         }
+        // Check aPNTs balance
         let hasEnoughAPNTs = true;
         if (requiredAPNTs > 0n) {
             const { CORE_ADDRESSES } = await import('./contract-addresses.js');
@@ -69,6 +94,7 @@ export class RequirementChecker {
                 missingRequirements.push(`Need ${requiredAPNTs.toString()} aPNTs, have ${apntsBalance.toString()}`);
             }
         }
+        // Check MySBT
         let hasSBT = false;
         if (requireSBT) {
             const { CORE_ADDRESSES } = await import('./contract-addresses.js');
@@ -91,6 +117,9 @@ export class RequirementChecker {
             missingRequirements
         };
     }
+    /**
+     * Check GToken balance only (shortcut)
+     */
     async checkGTokenBalance(address, required) {
         const { CORE_ADDRESSES } = await import('./contract-addresses.js');
         const balance = await this.publicClient.readContract({
@@ -104,6 +133,9 @@ export class RequirementChecker {
             hasEnough: balance >= required
         };
     }
+    /**
+     * Check aPNTs balance only (shortcut)
+     */
     async checkAPNTsBalance(address, required) {
         const { CORE_ADDRESSES } = await import('./contract-addresses.js');
         const balance = await this.publicClient.readContract({
@@ -117,6 +149,9 @@ export class RequirementChecker {
             hasEnough: balance >= required
         };
     }
+    /**
+     * Check if user has MySBT (shortcut)
+     */
     async checkHasSBT(address) {
         const { CORE_ADDRESSES } = await import('./contract-addresses.js');
         const balance = await this.publicClient.readContract({
@@ -127,6 +162,9 @@ export class RequirementChecker {
         });
         return balance > 0n;
     }
+    /**
+     * Check if user has specific role (shortcut)
+     */
     async checkHasRole(roleId, address) {
         const { CORE_ADDRESSES } = await import('./contract-addresses.js');
         return await this.publicClient.readContract({

package/dist/roles.d.ts

@@ -1,96 +1,86 @@
 /**
  * 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
+ * @dev All role hashes and configurations match exactly with Registry.sol v3.0.0
+ * @source /contracts/src/core/Registry.sol
  */
 import { type Hash } from 'viem';
 /**
  * Default Admin Role (OpenZeppelin AccessControl)
- * @remarks
- * - **Description**: Highest privilege, can grant/revoke all roles
- * - **Permission**: Protocol governance only
- * - **Source**: OpenZeppelin AccessControl DEFAULT_ADMIN_ROLE
+ * @description Highest privilege, can grant/revoke all roles
+ * @permission Protocol governance only
+ * @source OpenZeppelin AccessControl DEFAULT_ADMIN_ROLE
  */
 export declare const DEFAULT_ADMIN_ROLE: Hash;
 /**
  * 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")
+ * @description Community administrator, can issue xPNTs, configure SBT rules
+ * @permission Community-level governance
+ * @requirement minStake: 30 GT, entryBurn: 3 GT (line 99)
+ * @exitFee 5% (500 basis points), min 1 GT
+ * @lockDuration 30 days
+ * @source Registry.sol line 32: ROLE_COMMUNITY = keccak256("COMMUNITY")
  */
 export declare const ROLE_COMMUNITY: Hash;
 /**
  * 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")
+ * @description Community member, can participate and use gasless transactions
+ * @permission Basic user level
+ * @requirement minStake: 0.3 GT, entryBurn: 0.05 GT (line 100)
+ * @additionalRequirement Must hold MySBT from community
+ * @exitFee 10% (1000 basis points), min 0.05 GT
+ * @lockDuration 7 days
+ * @source Registry.sol line 33: ROLE_ENDUSER = keccak256("ENDUSER")
  */
 export declare const ROLE_ENDUSER: Hash;
 /**
  * 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")
+ * @description Basic Paymaster node operator with account-based auth
+ * @permission Infrastructure operator
+ * @requirement minStake: 30 GT, entryBurn: 3 GT (line 92)
+ * @exitFee 10% (1000 basis points), min 1 GT
+ * @lockDuration 30 days
+ * @source Registry.sol line 34: ROLE_PAYMASTER_AOA = keccak256("PAYMASTER_AOA")
  */
 export declare const ROLE_PAYMASTER_AOA: Hash;
 /**
  * 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")
+ * @description Advanced Paymaster operator, can use SuperPaymaster with aPNTs collateral
+ * @permission Infrastructure operator (higher tier)
+ * @requirement minStake: 50 GT, entryBurn: 5 GT (line 93)
+ * @additionalRequirement aPNTs collateral in SuperPaymaster contract
+ * @exitFee 10% (1000 basis points), min 2 GT
+ * @lockDuration 30 days
+ * @source Registry.sol line 35: ROLE_PAYMASTER_SUPER = keccak256("PAYMASTER_SUPER")
  */
 export declare const ROLE_PAYMASTER_SUPER: Hash;
 /**
  * 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")
+ * @description DVT node operator for consensus validation
+ * @permission Infrastructure operator
+ * @requirement minStake: 30 GT, entryBurn: 3 GT (line 94)
+ * @exitFee 10% (1000 basis points), min 1 GT
+ * @lockDuration 30 days
+ * @source Registry.sol line 36: ROLE_DVT = keccak256("DVT")
  */
 export declare const ROLE_DVT: Hash;
 /**
  * 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")
+ * @description Anonymous infrastructure node operator
+ * @permission Infrastructure operator
+ * @requirement minStake: 20 GT, entryBurn: 2 GT (line 95)
+ * @exitFee 10% (1000 basis points), min 1 GT
+ * @lockDuration 30 days
+ * @source Registry.sol line 37: ROLE_ANODE = keccak256("ANODE")
  */
 export declare const ROLE_ANODE: Hash;
 /**
  * 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")
+ * @description KMS operator for secure key storage and management
+ * @permission Infrastructure operator (highest stake)
+ * @requirement minStake: 100 GT, entryBurn: 10 GT (line 98)
+ * @exitFee 10% (1000 basis points), min 5 GT
+ * @lockDuration 30 days
+ * @source Registry.sol line 38: ROLE_KMS = keccak256("KMS")
  */
 export declare const ROLE_KMS: Hash;
 /**
@@ -136,8 +126,7 @@ export declare enum RolePermissionLevel {
 export declare const ROLE_PERMISSION_LEVELS: Record<string, RolePermissionLevel>;
 /**
  * Exact stake requirements from Registry.sol constructor (lines 92-100)
- * @remarks
- * **Warning**: These are initial values, always query contract for current configuration
+ * @warning These are initial values, always query contract for current configuration
  */
 export declare const INITIAL_ROLE_STAKES: {
     readonly [x: string]: {

package/dist/roles.js

@@ -1,97 +1,87 @@
 /**
  * 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
+ * @dev 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
+ * @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")
+ * @description Community administrator, can issue xPNTs, configure SBT rules
+ * @permission Community-level governance
+ * @requirement minStake: 30 GT, entryBurn: 3 GT (line 99)
+ * @exitFee 5% (500 basis points), min 1 GT
+ * @lockDuration 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")
+ * @description Community member, can participate and use gasless transactions
+ * @permission Basic user level
+ * @requirement minStake: 0.3 GT, entryBurn: 0.05 GT (line 100)
+ * @additionalRequirement Must hold MySBT from community
+ * @exitFee 10% (1000 basis points), min 0.05 GT
+ * @lockDuration 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")
+ * @description Basic Paymaster node operator with account-based auth
+ * @permission Infrastructure operator
+ * @requirement minStake: 30 GT, entryBurn: 3 GT (line 92)
+ * @exitFee 10% (1000 basis points), min 1 GT
+ * @lockDuration 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")
+ * @description Advanced Paymaster operator, can use SuperPaymaster with aPNTs collateral
+ * @permission Infrastructure operator (higher tier)
+ * @requirement minStake: 50 GT, entryBurn: 5 GT (line 93)
+ * @additionalRequirement aPNTs collateral in SuperPaymaster contract
+ * @exitFee 10% (1000 basis points), min 2 GT
+ * @lockDuration 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")
+ * @description DVT node operator for consensus validation
+ * @permission Infrastructure operator
+ * @requirement minStake: 30 GT, entryBurn: 3 GT (line 94)
+ * @exitFee 10% (1000 basis points), min 1 GT
+ * @lockDuration 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")
+ * @description Anonymous infrastructure node operator
+ * @permission Infrastructure operator
+ * @requirement minStake: 20 GT, entryBurn: 2 GT (line 95)
+ * @exitFee 10% (1000 basis points), min 1 GT
+ * @lockDuration 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")
+ * @description KMS operator for secure key storage and management
+ * @permission Infrastructure operator (highest stake)
+ * @requirement minStake: 100 GT, entryBurn: 10 GT (line 98)
+ * @exitFee 10% (1000 basis points), min 5 GT
+ * @lockDuration 30 days
+ * @source Registry.sol line 38: ROLE_KMS = keccak256("KMS")
  */
 export const ROLE_KMS = keccak256(toHex('KMS'));
 // ========== Role Name Mapping ==========
@@ -134,8 +124,7 @@ export const ROLE_PERMISSION_LEVELS = {
 };
 /**
  * Exact stake requirements from Registry.sol constructor (lines 92-100)
- * @remarks
- * **Warning**: These are initial values, always query contract for current configuration
+ * @warning These are initial values, always query contract for current configuration
  */
 export const INITIAL_ROLE_STAKES = {
     [ROLE_PAYMASTER_AOA]: {