@aastar/identity 0.16.7

package/dist/core/src/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/core/src/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/core/src/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/identity/src/index.d.ts

@@ -0,0 +1,46 @@
+export * from './mysbt.js';
+import { type Address, type PublicClient, type Hash, type WalletClient } from 'viem';
+export declare class ReputationClient {
+    private client;
+    private reputationAddress;
+    private walletClient?;
+    constructor(client: PublicClient, reputationAddress: Address, walletClient?: WalletClient);
+    /**
+     * Compute reputation score for a user
+     */
+    computeScore(user: Address, communities: Address[], ruleIds: `0x${string}`[][], activities: bigint[][]): Promise<bigint>;
+    /**
+     * Get global reputation score for a user
+     * @param user User address
+     * @returns Reputation score
+     */
+    getGlobalReputation(user: Address): Promise<number>;
+    /**
+     * Get credit limit based on reputation
+     * @param user User address
+     * @returns Credit limit in wei (Mock logic closely tied to Reputation)
+     */
+    getCreditLimit(user: Address): Promise<bigint>;
+    /**
+     * Get reputation score breakdown
+     * @param user User address
+     * @returns Detailed reputation breakdown (Mock implementation awaiting contract V4)
+     */
+    getReputationBreakdown(user: Address): Promise<{
+        baseScore: number;
+        stakingBonus: number;
+        activityBonus: number;
+        penaltyDeduction: number;
+        total: number;
+    }>;
+    /**
+     * Submit reputation proof (off-chain data to on-chain)
+     * @param params Proof parameters
+     * @returns Transaction hash
+     */
+    submitReputationProof(params: {
+        proofType: 'github' | 'twitter' | 'on-chain-activity';
+        proofData: string;
+        signature: Hash;
+    }): Promise<Hash>;
+}

package/dist/identity/src/index.js

@@ -0,0 +1,94 @@
+export * from './mysbt.js';
+import { ReputationSystemABI } from '@aastar/core';
+import { parseAbi } from 'viem';
+export class ReputationClient {
+    client;
+    reputationAddress;
+    walletClient;
+    constructor(client, reputationAddress, walletClient) {
+        this.client = client;
+        this.reputationAddress = reputationAddress;
+        this.walletClient = walletClient;
+    }
+    /**
+     * Compute reputation score for a user
+     */
+    async computeScore(user, communities, ruleIds, activities) {
+        return this.client.readContract({
+            address: this.reputationAddress,
+            abi: ReputationSystemABI,
+            functionName: 'computeScore',
+            args: [user, communities, ruleIds, activities]
+        });
+    }
+    /**
+     * Get global reputation score for a user
+     * @param user User address
+     * @returns Reputation score
+     */
+    async getGlobalReputation(user) {
+        // Try to read score, if fails (e.g. invalid contract), return 0
+        try {
+            const score = await this.computeScore(user, [], [], []);
+            return Number(score);
+        }
+        catch (e) {
+            console.warn('Failed to read reputation from contract, defaulting to 0');
+            return 0;
+        }
+    }
+    /**
+     * Get credit limit based on reputation
+     * @param user User address
+     * @returns Credit limit in wei (Mock logic closely tied to Reputation)
+     */
+    async getCreditLimit(user) {
+        const reputation = await this.getGlobalReputation(user);
+        // Dynamic Credit Limit Logic:
+        // Base: 0
+        // Score > 50: +0.01 ETH
+        // Score > 100: +0.05 ETH
+        let limit = 0n;
+        if (reputation > 50)
+            limit += 10000000000000000n; // 0.01 ETH
+        if (reputation > 100)
+            limit += 40000000000000000n; // +0.04 -> 0.05 ETH
+        return limit;
+    }
+    /**
+     * Get reputation score breakdown
+     * @param user User address
+     * @returns Detailed reputation breakdown (Mock implementation awaiting contract V4)
+     */
+    async getReputationBreakdown(user) {
+        const total = await this.getGlobalReputation(user);
+        // Heuristic breakdown
+        return {
+            baseScore: Math.floor(total * 0.5),
+            stakingBonus: Math.floor(total * 0.3),
+            activityBonus: Math.floor(total * 0.2),
+            penaltyDeduction: 0,
+            total
+        };
+    }
+    /**
+     * Submit reputation proof (off-chain data to on-chain)
+     * @param params Proof parameters
+     * @returns Transaction hash
+     */
+    async submitReputationProof(params) {
+        if (!this.walletClient || !this.walletClient.account) {
+            throw new Error("Wallet client required to submit proofs");
+        }
+        // Using a generic 'submitProof' signature for now
+        // In reality this would target the ReputationOracle or similar
+        return this.walletClient.writeContract({
+            address: this.reputationAddress,
+            abi: parseAbi(['function submitProof(string,bytes32)']),
+            functionName: 'submitProof',
+            args: [params.proofData, params.signature],
+            chain: this.walletClient.chain,
+            account: this.walletClient.account
+        });
+    }
+}

package/dist/identity/src/mysbt.d.ts

@@ -0,0 +1,13 @@
+import { type Address, type PublicClient } from 'viem';
+/**
+ * Check if user holds MySBT token (identity verification).
+ */
+export declare function checkMySBT(client: PublicClient, sbtAddress: Address, user: Address): Promise<{
+    hasSBT: boolean;
+    balance?: bigint;
+}>;
+/**
+ * Fetch MySBT token ID for a specific user (if unique/SBT).
+ * Note: Depends on whether the contract supports getTokenId or similar.
+ */
+export declare function getMySBTId(client: PublicClient, sbtAddress: Address, user: Address): Promise<bigint | null>;

package/dist/identity/src/mysbt.js

@@ -0,0 +1,37 @@
+import { MySBTABI } from '@aastar/core';
+/**
+ * Check if user holds MySBT token (identity verification).
+ */
+export async function checkMySBT(client, sbtAddress, user) {
+    try {
+        const balance = await client.readContract({
+            address: sbtAddress,
+            abi: MySBTABI,
+            functionName: 'balanceOf',
+            args: [user]
+        });
+        return {
+            hasSBT: balance > 0n,
+            balance: balance
+        };
+    }
+    catch (e) {
+        console.warn('MySBT check failed:', e);
+        return { hasSBT: false };
+    }
+}
+/**
+ * Fetch MySBT token ID for a specific user (if unique/SBT).
+ * Note: Depends on whether the contract supports getTokenId or similar.
+ */
+export async function getMySBTId(client, sbtAddress, user) {
+    try {
+        // Implementation depends on the specific contract. 
+        // Most SBTs use ownerOf or similar if mapping is known.
+        // For standard SBT balances, we usually just need hasSBT.
+        return null;
+    }
+    catch (e) {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@aastar/identity",
+  "version": "0.16.7",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "viem": "2.43.3",
+    "@aastar/core": "0.16.7"
+  },
+  "devDependencies": {
+    "typescript": "5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "clean": "find src -name '*.js' -o -name '*.d.ts' -o -name '*.map' | xargs rm -f",
+    "prebuild": "pnpm clean",
+    "build": "tsc"
+  }
+}