@aastar/operator 0.16.11

package/dist/PaymasterOperatorClient.js

@@ -0,0 +1,375 @@
+import { parseEther } from 'viem';
+import { BaseClient, PaymasterABI } from '@aastar/core';
+import { superPaymasterActions, tokenActions, paymasterActions, registryActions, paymasterFactoryActions } from '@aastar/core';
+/**
+ * Client for Paymaster Operators (ROLE_PAYMASTER_SUPER)
+ */
+export class PaymasterOperatorClient extends BaseClient {
+    superPaymasterAddress;
+    tokenAddress;
+    ethUsdPriceFeed;
+    xpntsFactory;
+    constructor(config) {
+        super(config);
+        this.superPaymasterAddress = config.superPaymasterAddress;
+        this.tokenAddress = config.tokenAddress;
+        this.ethUsdPriceFeed = config.ethUsdPriceFeedAddress || '0x694AA1769357215DE4FAC081bf1f309aDC325306'; // Default Sepolia
+        this.xpntsFactory = config.xpntsFactoryAddress || '0x0000000000000000000000000000000000000000'; // Should be provided
+    }
+    // ========================================
+    // 0. 注册与入驻 (One-Stop Registration)
+    // ========================================
+    /**
+     * Register as SuperPaymaster Operator (one-stop API).
+     * This method handles all necessary steps:
+     * 1. Checks prerequisites (must have ROLE_COMMUNITY)
+     * 2. Checks and approves GToken to GTokenStaking
+     * 3. Registers ROLE_PAYMASTER_SUPER
+     * 4. Optionally deposits collateral to SuperPaymaster
+     *
+     * @param params Registration parameters
+     * @param options Transaction options
+     * @returns Transaction hash of role registration
+     */
+    async registerAsSuperPaymasterOperator(params, options) {
+        try {
+            const registryAddr = this.requireRegistry();
+            const gTokenAddr = this.requireGToken();
+            const gTokenStakingAddr = this.requireGTokenStaking();
+            const registry = registryActions(registryAddr);
+            const gToken = tokenActions();
+            const publicClient = this.getStartPublicClient();
+            // 1. Check prerequisites
+            const ROLE_COMMUNITY = await registry(publicClient).ROLE_COMMUNITY();
+            const hasCommunity = await registry(publicClient).hasRole({
+                user: this.getAddress(),
+                roleId: ROLE_COMMUNITY
+            });
+            if (!hasCommunity) {
+                throw new Error('Must have ROLE_COMMUNITY before registering as SuperPaymaster operator');
+            }
+            // 2. Check if already has role
+            const ROLE_PAYMASTER_SUPER = await registry(publicClient).ROLE_PAYMASTER_SUPER();
+            const hasSuper = await registry(publicClient).hasRole({
+                user: this.getAddress(),
+                roleId: ROLE_PAYMASTER_SUPER
+            });
+            if (hasSuper) {
+                // Still handle deposit if requested
+                if (params?.depositAmount) {
+                    return this.depositCollateral(params.depositAmount, options);
+                }
+                throw new Error('Already registered as SuperPaymaster operator');
+            }
+            // 3. Prepare stake amount (default 50 GToken as per Registry config)
+            const stakeAmount = params?.stakeAmount || parseEther('50');
+            // 4. Check and approve GToken to GTokenStaking
+            const allowance = await gToken(publicClient).allowance({
+                token: gTokenAddr,
+                owner: this.getAddress(),
+                spender: gTokenStakingAddr
+            });
+            if (allowance < stakeAmount) {
+                const approveHash = await gToken(this.client).approve({
+                    token: gTokenAddr,
+                    spender: gTokenStakingAddr,
+                    amount: stakeAmount * 2n, // Approve 2x for future use
+                    account: options?.account
+                });
+                await publicClient.waitForTransactionReceipt({ hash: approveHash });
+            }
+            // 5. Register ROLE_PAYMASTER_SUPER
+            const registerHash = await registry(this.client).registerRoleSelf({
+                roleId: ROLE_PAYMASTER_SUPER,
+                data: '0x', // SuperPaymaster role doesn't need special data
+                account: options?.account
+            });
+            // Wait for registration to complete
+            await publicClient.waitForTransactionReceipt({ hash: registerHash });
+            // 6. Optional: Deposit collateral to SuperPaymaster
+            if (params?.depositAmount) {
+                await this.depositCollateral(params.depositAmount, options);
+            }
+            return registerHash;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Deploy a new Paymaster V4 and Register as AOA Operator (one-stop API).
+     * This method handles:
+     * 1. Checks prerequisites (ROLE_COMMUNITY)
+     * 2. Predicts new Paymaster address
+     * 3. Deploys Paymaster V4 via Factory
+     * 4. Registers ROLE_PAYMASTER_AOA with staking
+     *
+     * @param params Deployment parameters
+     * @param options Transaction options
+     * @returns Object containing new paymaster address and transaction hashes
+     */
+    async deployAndRegisterPaymasterV4(params, options) {
+        try {
+            const registryAddr = this.requireRegistry();
+            const gTokenAddr = this.requireGToken();
+            const gTokenStakingAddr = this.requireGTokenStaking();
+            const factoryAddr = this.requirePaymasterFactory();
+            const registry = registryActions(registryAddr);
+            const gToken = tokenActions();
+            const factory = paymasterFactoryActions(factoryAddr);
+            const publicClient = this.getStartPublicClient();
+            const account = options?.account || this.client.account || this.getAddress();
+            const accountAddr = typeof account === 'string' ? account : account.address;
+            // 1. Check prerequisites (ROLE_COMMUNITY)
+            const ROLE_COMMUNITY = await registry(publicClient).ROLE_COMMUNITY();
+            const hasCommunity = await registry(publicClient).hasRole({
+                user: accountAddr,
+                roleId: ROLE_COMMUNITY
+            });
+            if (!hasCommunity) {
+                throw new Error('Must have ROLE_COMMUNITY before deploying Paymaster V4');
+            }
+            // 2. Deployment (Idempotent Check)
+            const existingPaymaster = await factory(publicClient).getPaymaster({ owner: accountAddr });
+            let deployHash = '0x0000000000000000000000000000000000000000000000000000000000000000';
+            let paymasterAddress;
+            if (existingPaymaster && existingPaymaster !== '0x0000000000000000000000000000000000000000') {
+                console.log(`    ℹ️  Paymaster already deployed at: ${existingPaymaster}`);
+                paymasterAddress = existingPaymaster;
+            }
+            else {
+                console.log('    🛠️ Deploying Paymaster V4 with args:', {
+                    entryPoint: this.requireEntryPoint(),
+                    owner: accountAddr,
+                    priceFeed: this.ethUsdPriceFeed,
+                    factory: factoryAddr
+                });
+                const { encodeFunctionData } = await import('viem');
+                const initData = encodeFunctionData({
+                    abi: PaymasterABI,
+                    functionName: 'initialize',
+                    args: [
+                        this.requireEntryPoint(), // EntryPoint v0.7
+                        accountAddr,
+                        accountAddr, // Treasury defaults to owner
+                        this.ethUsdPriceFeed,
+                        200n, // serviceFeeRate (2%)
+                        parseEther('0.1'), // maxGasCostCap
+                        3600n // priceStalenessThreshold
+                    ]
+                });
+                deployHash = await factory(this.client).deployPaymaster({
+                    version: params?.version,
+                    initData,
+                    account
+                });
+                await publicClient.waitForTransactionReceipt({ hash: deployHash });
+                paymasterAddress = await factory(publicClient).getPaymaster({ owner: accountAddr });
+            }
+            if (!paymasterAddress || paymasterAddress === '0x0000000000000000000000000000000000000000') {
+                throw new Error('Failed to retrieve Paymaster address from Factory');
+            }
+            // 3. Register ROLE_PAYMASTER_AOA
+            const ROLE_PAYMASTER_AOA = await registry(publicClient).ROLE_PAYMASTER_AOA();
+            const hasAOA = await registry(publicClient).hasRole({
+                user: accountAddr,
+                roleId: ROLE_PAYMASTER_AOA
+            });
+            if (hasAOA) {
+                return { paymasterAddress, deployHash, registerHash: '0x0000000000000000000000000000000000000000000000000000000000000000' };
+            }
+            const stakeAmount = params?.stakeAmount || parseEther('30');
+            const allowance = await gToken(publicClient).allowance({
+                token: gTokenAddr,
+                owner: accountAddr,
+                spender: gTokenStakingAddr
+            });
+            if (allowance < stakeAmount) {
+                const approveHash = await gToken(this.client).approve({
+                    token: gTokenAddr,
+                    spender: gTokenStakingAddr,
+                    amount: stakeAmount * 2n,
+                    account: account
+                });
+                await publicClient.waitForTransactionReceipt({ hash: approveHash });
+            }
+            const { encodeAbiParameters, parseAbiParameters } = await import('viem');
+            let roleData = '0x';
+            if (stakeAmount > 0) {
+                roleData = encodeAbiParameters(parseAbiParameters('uint256'), [stakeAmount]);
+            }
+            const registerHash = await registry(this.client).registerRoleSelf({
+                roleId: ROLE_PAYMASTER_AOA,
+                data: roleData,
+                account: account
+            });
+            await publicClient.waitForTransactionReceipt({ hash: registerHash });
+            return {
+                paymasterAddress,
+                deployHash,
+                registerHash
+            };
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Deposit collateral (aPNTs/GToken) to SuperPaymaster.
+     * This is a helper method used by registerAsSuperPaymasterOperator.
+     */
+    async depositCollateral(amount, options) {
+        try {
+            const pm = superPaymasterActions(this.superPaymasterAddress);
+            const publicClient = this.getStartPublicClient();
+            // V3.7: Dynamically fetch the token expected by SuperPaymaster
+            const depositToken = await pm(publicClient).APNTS_TOKEN();
+            const token = tokenActions();
+            // Approve SuperPaymaster to spend the token (usually aPNTs on Sepolia)
+            const allowance = await token(publicClient).allowance({
+                token: depositToken,
+                owner: this.getAddress(),
+                spender: this.superPaymasterAddress
+            });
+            if (allowance < amount) {
+                const approveHash = await token(this.client).approve({
+                    token: depositToken,
+                    spender: this.superPaymasterAddress,
+                    amount,
+                    account: options?.account
+                });
+                await publicClient.waitForTransactionReceipt({ hash: approveHash });
+            }
+            // Deposit to SuperPaymaster
+            return pm(this.client).deposit({
+                amount,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async updateExchangeRate(exchangeRate, options) {
+        return this.configureOperator(undefined, undefined, exchangeRate, options);
+    }
+    /**
+     * Configure operator parameters (Token, Treasury, Exchange Rate).
+     * If parameters are undefined, existing values are preserved.
+     */
+    async configureOperator(xPNTsToken, treasury, exchangeRate, options) {
+        try {
+            const sp = superPaymasterActions(this.superPaymasterAddress);
+            const publicClient = this.getStartPublicClient();
+            // Fetch current config to preserve missing values
+            const currentConfig = await sp(publicClient).operators({ operator: this.getAddress() });
+            const currentToken = currentConfig.xPNTsToken;
+            const currentTreasury = currentConfig.treasury;
+            const currentRate = currentConfig.exchangeRate;
+            return await sp(this.client).configureOperator({
+                xPNTsToken: xPNTsToken || currentToken,
+                opTreasury: treasury || currentTreasury,
+                exchangeRate: exchangeRate ?? currentRate,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async withdrawCollateral(to, amount, options) {
+        try {
+            const sp = superPaymasterActions(this.superPaymasterAddress);
+            return await sp(this.client).withdrawTo({
+                to,
+                amount,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async isOperator(operator) {
+        try {
+            const sp = superPaymasterActions(this.superPaymasterAddress);
+            const config = await sp(this.getStartPublicClient()).operators({ operator });
+            return config.isConfigured;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    async getOperatorDetails(operator) {
+        try {
+            const target = operator || this.getAddress();
+            const sp = superPaymasterActions(this.superPaymasterAddress);
+            return await sp(this.getStartPublicClient()).operators({ operator: target });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async initiateExit(options) {
+        try {
+            const sp = superPaymasterActions(this.superPaymasterAddress);
+            return await sp(this.client).unlockStake({
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async withdrawStake(to, options) {
+        try {
+            const sp = superPaymasterActions(this.superPaymasterAddress);
+            return await sp(this.client).withdrawStake({
+                to,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // ========================================
+    // 3. 支付代币管理 (基于 PaymasterActions)
+    // ========================================
+    async addGasToken(token, price, options) {
+        try {
+            const pm = paymasterActions(this.superPaymasterAddress);
+            return await pm(this.client).setTokenPrice({
+                token,
+                price,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async getTokenPrice(token) {
+        try {
+            const pm = paymasterActions(this.superPaymasterAddress);
+            return await pm(this.getStartPublicClient()).tokenPrices({ token });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async setupPaymasterDeposit(params, options) {
+        try {
+            const pm = paymasterActions(params.paymaster);
+            return await pm(this.client).depositFor({
+                user: params.user,
+                token: params.token,
+                amount: params.amount,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+}

package/dist/ProtocolClient.d.ts

@@ -0,0 +1,38 @@
+import { type Address, type Hash, type Hex } from 'viem';
+import { BaseClient, type ClientConfig, type TransactionOptions } from '@aastar/core';
+export interface ProtocolClientConfig extends ClientConfig {
+    dvtValidatorAddress: Address;
+    blsAggregatorAddress?: Address;
+    superPaymasterAddress?: Address;
+}
+export declare enum ProposalState {
+    Pending = 0,
+    Active = 1,
+    Canceled = 2,
+    Defeated = 3,
+    Succeeded = 4,
+    Queued = 5,
+    Expired = 6,
+    Executed = 7
+}
+/**
+ * Client for Protocol Governors and Validators (Infrastructure)
+ */
+export declare class ProtocolClient extends BaseClient {
+    dvtValidatorAddress: Address;
+    blsAggregatorAddress?: Address;
+    superPaymasterAddress?: Address;
+    constructor(config: ProtocolClientConfig);
+    /**
+     * Create a new proposal
+     */
+    createProposal(target: Address, calldata: Hex, description: string, options?: TransactionOptions): Promise<Hash>;
+    signProposal(proposalId: bigint, signature?: Hex, options?: TransactionOptions): Promise<Hash>;
+    /**
+     * Execute a proposal with collected signatures
+     */
+    executeWithProof(proposalId: bigint, signatures: Hex[], options?: TransactionOptions): Promise<Hash>;
+    registerBLSKey(publicKey: Hex, options?: TransactionOptions): Promise<Hash>;
+    setProtocolFee(bps: bigint, options?: TransactionOptions): Promise<Hash>;
+    setTreasury(treasury: Address, options?: TransactionOptions): Promise<Hash>;
+}

package/dist/ProtocolClient.js

@@ -0,0 +1,137 @@
+import { BaseClient } from '@aastar/core';
+import { dvtActions, aggregatorActions, superPaymasterActions } from '@aastar/core';
+export var ProposalState;
+(function (ProposalState) {
+    ProposalState[ProposalState["Pending"] = 0] = "Pending";
+    ProposalState[ProposalState["Active"] = 1] = "Active";
+    ProposalState[ProposalState["Canceled"] = 2] = "Canceled";
+    ProposalState[ProposalState["Defeated"] = 3] = "Defeated";
+    ProposalState[ProposalState["Succeeded"] = 4] = "Succeeded";
+    ProposalState[ProposalState["Queued"] = 5] = "Queued";
+    ProposalState[ProposalState["Expired"] = 6] = "Expired";
+    ProposalState[ProposalState["Executed"] = 7] = "Executed";
+})(ProposalState || (ProposalState = {}));
+/**
+ * Client for Protocol Governors and Validators (Infrastructure)
+ */
+export class ProtocolClient extends BaseClient {
+    dvtValidatorAddress;
+    blsAggregatorAddress;
+    superPaymasterAddress;
+    constructor(config) {
+        super(config);
+        this.dvtValidatorAddress = config.dvtValidatorAddress;
+        this.blsAggregatorAddress = config.blsAggregatorAddress;
+        this.superPaymasterAddress = config.superPaymasterAddress;
+    }
+    // ========================================
+    // 1. 提案管理 (DVT)
+    // ========================================
+    /**
+     * Create a new proposal
+     */
+    async createProposal(target, calldata, description, options) {
+        try {
+            const dvt = dvtActions(this.dvtValidatorAddress)(this.client);
+            // Mapping general "createProposal" to "createSlashProposal" for now
+            // Assuming Governance uses Validator logic or this Client is for Slash.
+            // Using createSlashProposal as the available action.
+            return await dvt.createSlashProposal({
+                operator: target,
+                level: 1, // Default level
+                reason: description,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async signProposal(proposalId, signature = '0x', options) {
+        try {
+            const dvt = dvtActions(this.dvtValidatorAddress)(this.client);
+            return await dvt.signSlashProposal({
+                proposalId,
+                signature,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Execute a proposal with collected signatures
+     */
+    async executeWithProof(proposalId, signatures, options) {
+        try {
+            // Mock proof generation logic or placeholder
+            const proof = '0x';
+            const dvt = dvtActions(this.dvtValidatorAddress)(this.client);
+            return await dvt.executeSlashWithProof({
+                proposalId,
+                repUsers: [], // Needs real data in production
+                newScores: [],
+                epoch: 0n,
+                proof,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // ========================================
+    // 2. 验证器管理 / BLS
+    // ========================================
+    async registerBLSKey(publicKey, options) {
+        try {
+            if (!this.blsAggregatorAddress) {
+                throw new Error('BLS Aggregator address required for this client');
+            }
+            // Aggregator actions now handle the type internally or via mapping
+            const agg = aggregatorActions(this.blsAggregatorAddress)(this.client);
+            return await agg.registerBLSPublicKey({
+                validator: this.getAddress(),
+                publicKey,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // ========================================
+    // 3. 全局参数管理 (Admin)
+    // ========================================
+    async setProtocolFee(bps, options) {
+        try {
+            if (!this.superPaymasterAddress) {
+                throw new Error('SuperPaymaster address required for this client');
+            }
+            const sp = superPaymasterActions(this.superPaymasterAddress);
+            return await sp(this.client).setProtocolFee({
+                newFeeBPS: bps,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async setTreasury(treasury, options) {
+        try {
+            if (!this.superPaymasterAddress) {
+                throw new Error('SuperPaymaster address required for this client');
+            }
+            const sp = superPaymasterActions(this.superPaymasterAddress);
+            return await sp(this.client).setTreasury({
+                treasury,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './PaymasterOperatorClient.js';
+export * from './ProtocolClient.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './PaymasterOperatorClient.js';
+export * from './ProtocolClient.js';

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@aastar/operator",
+  "version": "0.16.11",
+  "description": "Operator client for AAstar SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "aastar",
+    "operator",
+    "web3"
+  ],
+  "author": "AAstar Team",
+  "license": "MIT",
+  "dependencies": {
+    "viem": "2.43.3",
+    "@aastar/core": "0.16.11"
+  },
+  "devDependencies": {
+    "typescript": "5.7.2"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}