@agether/sdk 2.13.0 → 2.14.0

package/dist/clients/AgetherClient.js

@@ -0,0 +1,736 @@
+/**
+ * AgetherClient — Primary protocol client for AI agent operations
+ *
+ * Handles:
+ * - Registration (mint ERC-8004 NFT + deploy Safe account)
+ * - Account management (create, query, fund)
+ * - Balance queries (EOA + Safe, including collateral tokens)
+ * - Withdrawals from Safe to EOA (ERC-20 and ETH, via UserOps)
+ * - Agent-to-agent sponsorship
+ * - Identity checks (KYA, existence, ownership)
+ * - Credit scoring queries
+ *
+ * For Morpho Blue lending operations, use MorphoClient.
+ *
+ * Architecture (v2 — Safe + Safe7579):
+ * 1. Agent registers via ERC-8004 → gets agentId
+ * 2. Agether4337Factory.createAccount(agentId) → Safe proxy with Safe7579 adapter
+ * 3. Withdrawals from Safe execute via ERC-4337 UserOps
+ * 4. Use MorphoClient for lending (supply, borrow, repay, withdraw collateral)
+ */
+import { ethers, Contract } from 'ethers';
+import { AgetherError, ChainId, } from '../types';
+import { AGETHER_4337_FACTORY_ABI, IDENTITY_REGISTRY_ABI, AGETHER_8004_SCORER_ABI, AGETHER_8004_VALIDATION_MODULE_ABI, ERC20_ABI, ENTRYPOINT_V07_ABI, SAFE7579_ACCOUNT_ABI, } from '../utils/abis';
+import { getDefaultConfig } from '../utils/config';
+// ── ERC-7579 Execution Mode Constants ──
+/** Single call: callType=0x00, execType=0x00, rest zero-padded to 32 bytes */
+const MODE_SINGLE = '0x0000000000000000000000000000000000000000000000000000000000000000';
+// ── ERC20 interface for encoding ──
+const erc20Iface = new ethers.Interface(ERC20_ABI);
+// ── Well-known tokens per chain ──
+const KNOWN_TOKENS = {
+    [ChainId.Base]: {
+        WETH: { address: '0x4200000000000000000000000000000000000006', symbol: 'WETH', decimals: 18 },
+        wstETH: { address: '0xc1CBa3fCea344f92D9239c08C0568f6F2F0ee452', symbol: 'wstETH', decimals: 18 },
+        cbETH: { address: '0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22', symbol: 'cbETH', decimals: 18 },
+    },
+    [ChainId.Ethereum]: {
+        WETH: { address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', symbol: 'WETH', decimals: 18 },
+        wstETH: { address: '0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0', symbol: 'wstETH', decimals: 18 },
+        cbETH: { address: '0xBe9895146f7AF43049ca1c1AE358B0541Ea49704', symbol: 'cbETH', decimals: 18 },
+    },
+};
+// ── Client ──
+export class AgetherClient {
+    constructor(options) {
+        this.config = options.config;
+        this.signer = options.signer;
+        this.agentId = options.agentId;
+        this._rpcUrl = options.config.rpcUrl;
+        if (options._privateKey) {
+            this._privateKey = options._privateKey;
+            this._useExternalSigner = false;
+        }
+        else {
+            this._useExternalSigner = true;
+        }
+        const provider = options.signer.provider;
+        if (!provider)
+            throw new AgetherError('Signer must have a provider', 'NO_PROVIDER');
+        // Cache EOA address if synchronously available
+        if ('address' in options.signer && typeof options.signer.address === 'string') {
+            this._eoaAddress = options.signer.address;
+        }
+        const c = options.config.contracts;
+        this.agether4337Factory = new Contract(c.agether4337Factory, AGETHER_4337_FACTORY_ABI, options.signer);
+        this.identityRegistry = new Contract(c.identityRegistry, IDENTITY_REGISTRY_ABI, options.signer);
+        this.agether8004Scorer = new Contract(c.agether8004Scorer, AGETHER_8004_SCORER_ABI, provider);
+        this.validationModule = new Contract(c.erc8004ValidationModule, AGETHER_8004_VALIDATION_MODULE_ABI, provider);
+        this.entryPoint = new Contract(c.entryPoint, ENTRYPOINT_V07_ABI, options.signer);
+    }
+    static fromPrivateKey(privateKey, agentIdOrChain, chainIdOrConfig) {
+        let agentId;
+        let config;
+        if (typeof agentIdOrChain === 'bigint') {
+            // (pk, agentId, chainIdOrConfig)
+            agentId = agentIdOrChain;
+            config =
+                typeof chainIdOrConfig === 'number'
+                    ? getDefaultConfig(chainIdOrConfig)
+                    : chainIdOrConfig;
+        }
+        else {
+            // (pk, chainIdOrConfig) — no agentId
+            config =
+                typeof agentIdOrChain === 'number'
+                    ? getDefaultConfig(agentIdOrChain)
+                    : agentIdOrChain;
+        }
+        const provider = new ethers.JsonRpcProvider(config.rpcUrl);
+        const signer = new ethers.Wallet(privateKey, provider);
+        return new AgetherClient({ config, signer, agentId, _privateKey: privateKey });
+    }
+    static async fromSigner(signer, agentIdOrChain, chainIdOrConfig) {
+        if (!signer.provider) {
+            throw new AgetherError('Signer must be connected to a provider', 'NO_PROVIDER');
+        }
+        let agentId;
+        let config;
+        if (typeof agentIdOrChain === 'bigint') {
+            agentId = agentIdOrChain;
+            config =
+                typeof chainIdOrConfig === 'number'
+                    ? getDefaultConfig(chainIdOrConfig)
+                    : chainIdOrConfig;
+        }
+        else {
+            config =
+                typeof agentIdOrChain === 'number'
+                    ? getDefaultConfig(agentIdOrChain)
+                    : agentIdOrChain;
+        }
+        // Validate signer is on the correct chain
+        const network = await signer.provider.getNetwork();
+        const actualChainId = Number(network.chainId);
+        if (actualChainId !== config.chainId) {
+            throw new AgetherError(`Chain mismatch: signer is on chain ${actualChainId} but config expects chain ${config.chainId}`, 'CHAIN_MISMATCH');
+        }
+        return new AgetherClient({ config, signer, agentId });
+    }
+    // ════════════════════════════════════════════════════════
+    //  Registration
+    // ════════════════════════════════════════════════════════
+    /**
+     * Register: create ERC-8004 identity + Safe account in one flow.
+     * If already registered, returns existing state.
+     *
+     * Sets `this.agentId` on success so subsequent operations work immediately.
+     *
+     * @param options.name        Agent display name (stored in on-chain metadata URI)
+     * @param options.description Agent description (defaults to 'AI agent registered via @agether/sdk')
+     */
+    async register(options) {
+        const eoaAddr = await this._getSignerAddress();
+        // Check if we already have an agentId and account exists
+        if (this.agentId !== undefined) {
+            const exists = await this.agether4337Factory.accountExists(this.agentId);
+            if (exists) {
+                const acct = await this.agether4337Factory.getAccount(this.agentId);
+                this.accountAddress = acct;
+                const kyaRequired = await this.isKyaRequired();
+                return {
+                    agentId: this.agentId.toString(),
+                    address: eoaAddr,
+                    agentAccount: acct,
+                    alreadyRegistered: true,
+                    kyaRequired,
+                };
+            }
+        }
+        // Mint new identity or reuse existing
+        let agentId;
+        if (this.agentId !== undefined) {
+            // We have an agentId but no account yet — check if identity exists
+            const balance = await this.identityRegistry.balanceOf(eoaAddr);
+            if (balance > 0n) {
+                agentId = this.agentId;
+            }
+            else {
+                agentId = await this._mintNewIdentity(options?.name, options?.description);
+            }
+        }
+        else {
+            // No agentId — always mint a new identity
+            agentId = await this._mintNewIdentity(options?.name, options?.description);
+        }
+        this.agentId = agentId;
+        // Create Safe account if needed
+        const acctExists = await this.agether4337Factory.accountExists(agentId);
+        let txHash;
+        if (!acctExists) {
+            const tx = await this.agether4337Factory.createAccount(agentId);
+            const receipt = await tx.wait();
+            this._refreshSigner();
+            txHash = receipt.hash;
+        }
+        const acctAddr = await this.agether4337Factory.getAccount(agentId);
+        this.accountAddress = acctAddr;
+        // Update on-chain URI with the Safe account address and real agentId
+        if (!acctExists) {
+            const updatedMeta = JSON.stringify({
+                type: 'https://eips.ethereum.org/EIPS/eip-8004#registration-v1',
+                name: options?.name || 'Unnamed Agent',
+                description: options?.description || 'AI agent registered via @agether/sdk',
+                active: true,
+                wallet: `eip155:${this.config.chainId}:${acctAddr}`,
+                registrations: [{
+                        agentId: Number(agentId),
+                        agentRegistry: `eip155:${this.config.chainId}:${this.config.contracts.identityRegistry}`,
+                    }],
+            });
+            const finalURI = `data:application/json;base64,${Buffer.from(updatedMeta).toString('base64')}`;
+            const uriTx = await this.identityRegistry.setAgentURI(agentId, finalURI);
+            await uriTx.wait();
+            this._refreshSigner();
+        }
+        const kyaRequired = await this.isKyaRequired();
+        return {
+            agentId: agentId.toString(),
+            address: eoaAddr,
+            agentAccount: acctAddr,
+            alreadyRegistered: acctExists,
+            kyaRequired,
+            tx: txHash,
+        };
+    }
+    /** Mint a new ERC-8004 identity and return the agentId.
+     *  Builds a JSON metadata document per ERC-8004 spec and encodes it as a data: URI.
+     */
+    async _mintNewIdentity(name, description) {
+        // Build ERC-8004 registration metadata
+        const registrationFile = JSON.stringify({
+            type: 'https://eips.ethereum.org/EIPS/eip-8004#registration-v1',
+            name: name || 'Agether Agent',
+            description: description || 'AI agent registered via @agether/sdk',
+            active: true,
+            registrations: [{
+                    agentId: 0,
+                    agentRegistry: `eip155:${this.config.chainId}:${this.config.contracts.identityRegistry}`,
+                }],
+        });
+        const agentURI = `data:application/json;base64,${Buffer.from(registrationFile).toString('base64')}`;
+        const regTx = await this.identityRegistry['register(string)'](agentURI);
+        const regReceipt = await regTx.wait();
+        this._refreshSigner();
+        let agentId = 0n;
+        for (const log of regReceipt.logs) {
+            try {
+                const parsed = this.identityRegistry.interface.parseLog({
+                    topics: log.topics,
+                    data: log.data,
+                });
+                if (parsed?.name === 'Transfer') {
+                    agentId = parsed.args[2];
+                    break;
+                }
+            }
+            catch (e) {
+                console.warn('[agether] parseLog skip:', e instanceof Error ? e.message : e);
+                continue;
+            }
+        }
+        if (agentId === 0n) {
+            throw new AgetherError('Failed to parse agentId from registration', 'PARSE_ERROR');
+        }
+        return agentId;
+    }
+    // ════════════════════════════════════════════════════════
+    //  Account Management
+    // ════════════════════════════════════════════════════════
+    /**
+     * Deploy a Safe account smart wallet for the agent.
+     * The caller must own the ERC-8004 NFT.
+     */
+    async createAccount() {
+        const id = this._requireAgentId();
+        const tx = await this.agether4337Factory.createAccount(id);
+        const receipt = await tx.wait();
+        this._refreshSigner();
+        const event = receipt.logs
+            .map((log) => {
+            try {
+                return this.agether4337Factory.interface.parseLog(log);
+            }
+            catch {
+                return null;
+            }
+        })
+            .find((e) => e?.name === 'AccountCreated');
+        if (event) {
+            this.accountAddress = event.args.safeAccount;
+        }
+        else {
+            this.accountAddress = await this.agether4337Factory.getAccount(id);
+        }
+        return this.accountAddress;
+    }
+    /** Get the Safe account address for the current agent. Cached after first call. */
+    async getAccountAddress() {
+        if (this.accountAddress)
+            return this.accountAddress;
+        const id = this._requireAgentId();
+        const addr = await this.agether4337Factory.getAccount(id);
+        if (addr === ethers.ZeroAddress) {
+            throw new AgetherError('No account found. Create one with createAccount() or register().', 'NO_ACCOUNT');
+        }
+        this.accountAddress = addr;
+        return addr;
+    }
+    /** Check whether the Safe account has been deployed. */
+    async accountExists() {
+        const id = this._requireAgentId();
+        return this.agether4337Factory.accountExists(id);
+    }
+    // ════════════════════════════════════════════════════════
+    //  Balances
+    // ════════════════════════════════════════════════════════
+    /**
+     * Get ETH, USDC, and collateral token balances for EOA and Safe account.
+     *
+     * Collateral tokens are resolved from a built-in registry of well-known
+     * tokens per chain (WETH, wstETH, cbETH).
+     */
+    async getBalances() {
+        const provider = this.signer.provider;
+        const eoaAddr = await this._getSignerAddress();
+        const usdc = new Contract(this.config.contracts.usdc, ERC20_ABI, provider);
+        const ethBal = await provider.getBalance(eoaAddr);
+        const usdcBal = await usdc.balanceOf(eoaAddr);
+        // Fetch collateral token balances for EOA
+        const knownTokens = KNOWN_TOKENS[this.config.chainId] ?? {};
+        const eoaCollateral = {};
+        for (const [symbol, info] of Object.entries(knownTokens)) {
+            try {
+                const token = new Contract(info.address, ERC20_ABI, provider);
+                const bal = await token.balanceOf(eoaAddr);
+                eoaCollateral[symbol] = ethers.formatUnits(bal, info.decimals);
+            }
+            catch (e) {
+                console.warn(`[agether] EOA collateral fetch failed for ${symbol}:`, e instanceof Error ? e.message : e);
+                eoaCollateral[symbol] = '0';
+            }
+        }
+        const result = {
+            agentId: this.agentId !== undefined ? this.agentId.toString() : '?',
+            address: eoaAddr,
+            eth: ethers.formatEther(ethBal),
+            usdc: ethers.formatUnits(usdcBal, 6),
+            collateral: eoaCollateral,
+        };
+        try {
+            const acctAddr = await this.getAccountAddress();
+            const acctEth = await provider.getBalance(acctAddr);
+            const acctUsdc = await usdc.balanceOf(acctAddr);
+            const acctCollateral = {};
+            for (const [symbol, info] of Object.entries(knownTokens)) {
+                try {
+                    const token = new Contract(info.address, ERC20_ABI, provider);
+                    const bal = await token.balanceOf(acctAddr);
+                    acctCollateral[symbol] = ethers.formatUnits(bal, info.decimals);
+                }
+                catch (e) {
+                    console.warn(`[agether] Account collateral fetch failed for ${symbol}:`, e instanceof Error ? e.message : e);
+                    acctCollateral[symbol] = '0';
+                }
+            }
+            result.agentAccount = {
+                address: acctAddr,
+                eth: ethers.formatEther(acctEth),
+                usdc: ethers.formatUnits(acctUsdc, 6),
+                collateral: acctCollateral,
+            };
+        }
+        catch (e) {
+            if (e instanceof AgetherError && (e.code === 'NO_ACCOUNT' || e.code === 'NO_AGENT_ID')) {
+                // No account or agentId yet — leave agentAccount undefined
+            }
+            else {
+                console.warn('[agether] getBalances: failed to fetch Safe account data:', e.message ?? e);
+            }
+        }
+        return result;
+    }
+    /**
+     * Fund the Safe account with USDC from EOA.
+     * This is a simple ERC-20 transfer (does NOT require a UserOp).
+     */
+    async fundAccount(usdcAmount) {
+        const acctAddr = await this.getAccountAddress();
+        const usdc = new Contract(this.config.contracts.usdc, ERC20_ABI, this.signer);
+        const amount = ethers.parseUnits(usdcAmount, 6);
+        const tx = await usdc.transfer(acctAddr, amount);
+        const receipt = await tx.wait();
+        this._refreshSigner();
+        return {
+            txHash: receipt.hash,
+            blockNumber: receipt.blockNumber,
+            status: receipt.status === 1 ? 'success' : 'failed',
+            gasUsed: receipt.gasUsed,
+        };
+    }
+    // ════════════════════════════════════════════════════════
+    //  Withdrawals (Safe → EOA via UserOps)
+    // ════════════════════════════════════════════════════════
+    /**
+     * Withdraw an ERC-20 token from Safe account to EOA.
+     * Executes a transfer via Safe UserOp.
+     *
+     * @param tokenSymbol - Token to withdraw (e.g. 'USDC', 'WETH', 'wstETH') or 0x address
+     * @param amount - Amount to withdraw (human-readable, e.g. '100', or 'all')
+     */
+    async withdrawToken(tokenSymbol, amount) {
+        const acctAddr = await this.getAccountAddress();
+        const eoaAddr = await this._getSignerAddress();
+        const tokenInfo = await this._resolveToken(tokenSymbol);
+        const tokenContract = new Contract(tokenInfo.address, ERC20_ABI, this.signer.provider);
+        let weiAmount;
+        if (amount === 'all') {
+            weiAmount = await tokenContract.balanceOf(acctAddr);
+            if (weiAmount === 0n) {
+                throw new AgetherError(`No ${tokenInfo.symbol} in Safe account`, 'INSUFFICIENT_BALANCE');
+            }
+        }
+        else {
+            weiAmount = ethers.parseUnits(amount, tokenInfo.decimals);
+        }
+        const data = erc20Iface.encodeFunctionData('transfer', [eoaAddr, weiAmount]);
+        const receipt = await this._exec(tokenInfo.address, data);
+        const actualAmount = amount === 'all'
+            ? ethers.formatUnits(weiAmount, tokenInfo.decimals)
+            : amount;
+        return { tx: receipt.hash, token: tokenInfo.symbol, amount: actualAmount, destination: eoaAddr };
+    }
+    /**
+     * Withdraw ETH from Safe account to EOA.
+     * Executes a native ETH transfer via Safe UserOp.
+     *
+     * @param amount - ETH amount (e.g. '0.01' or 'all')
+     */
+    async withdrawEth(amount) {
+        const acctAddr = await this.getAccountAddress();
+        const eoaAddr = await this._getSignerAddress();
+        let weiAmount;
+        if (amount === 'all') {
+            weiAmount = await this.signer.provider.getBalance(acctAddr);
+            if (weiAmount === 0n)
+                throw new AgetherError('No ETH in Safe account', 'INSUFFICIENT_BALANCE');
+        }
+        else {
+            weiAmount = ethers.parseEther(amount);
+        }
+        // Empty calldata + value = plain ETH transfer
+        const receipt = await this._exec(eoaAddr, '0x', weiAmount);
+        const actualAmount = amount === 'all' ? ethers.formatEther(weiAmount) : amount;
+        return { tx: receipt.hash, token: 'ETH', amount: actualAmount, destination: eoaAddr };
+    }
+    // ════════════════════════════════════════════════════════
+    //  Sponsorship
+    // ════════════════════════════════════════════════════════
+    /**
+     * Send tokens to another agent's Safe account (or any address).
+     * Transfers from EOA (does NOT require a UserOp).
+     *
+     * @param target - `{ agentId: '42' }` or `{ address: '0x...' }`
+     * @param tokenSymbol - Token to send (e.g. 'WETH', 'USDC') or 0x address
+     * @param amount - Amount to send (human-readable)
+     */
+    async sponsor(target, tokenSymbol, amount) {
+        const tokenInfo = await this._resolveToken(tokenSymbol);
+        let targetAddr;
+        if (target.address) {
+            targetAddr = target.address;
+        }
+        else if (target.agentId) {
+            targetAddr = await this.agether4337Factory.getAccount(BigInt(target.agentId));
+            if (targetAddr === ethers.ZeroAddress) {
+                throw new AgetherError('Target agent has no account', 'NO_ACCOUNT');
+            }
+        }
+        else {
+            throw new AgetherError('Provide agentId or address', 'INVALID_TARGET');
+        }
+        const weiAmount = ethers.parseUnits(amount, tokenInfo.decimals);
+        const tokenContract = new Contract(tokenInfo.address, ERC20_ABI, this.signer);
+        const tx = await tokenContract.transfer(targetAddr, weiAmount);
+        const receipt = await tx.wait();
+        this._refreshSigner();
+        return { tx: receipt.hash, targetAccount: targetAddr, targetAgentId: target.agentId };
+    }
+    // ════════════════════════════════════════════════════════
+    //  Identity & Validation
+    // ════════════════════════════════════════════════════════
+    /**
+     * Check if the KYA gate is active on the validation module.
+     * If validationRegistry is not set, all txs pass (KYA disabled).
+     */
+    async isKyaRequired() {
+        try {
+            const registryAddr = await this.validationModule.validationRegistry();
+            return registryAddr !== ethers.ZeroAddress;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if this agent's code is KYA-approved.
+     * Uses the ERC8004ValidationModule.isKYAApproved(account) view.
+     */
+    async isKyaApproved() {
+        try {
+            const acctAddr = await this.getAccountAddress();
+            return this.validationModule.isKYAApproved(acctAddr);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Check whether the agent's ERC-8004 NFT exists. */
+    async identityExists() {
+        const id = this._requireAgentId();
+        try {
+            await this.identityRegistry.ownerOf(id);
+            return true;
+        }
+        catch (e) {
+            console.warn('[agether] identityExists check failed:', e instanceof Error ? e.message : e);
+            return false;
+        }
+    }
+    /** Get the owner address of the ERC-8004 NFT. */
+    async getIdentityOwner() {
+        const id = this._requireAgentId();
+        return this.identityRegistry.ownerOf(id);
+    }
+    // ════════════════════════════════════════════════════════
+    //  Reputation
+    // ════════════════════════════════════════════════════════
+    /** Read the agent's current credit score from the Agether8004Scorer contract. */
+    async getCreditScore() {
+        const id = this._requireAgentId();
+        return this.agether8004Scorer.getCreditScore(id);
+    }
+    /** Check if the score is fresh (within MAX_ORACLE_AGE). */
+    async isScoreFresh() {
+        const id = this._requireAgentId();
+        const [fresh, age] = await this.agether8004Scorer.isScoreFresh(id);
+        return { fresh, age };
+    }
+    /** Check if the agent meets a minimum score threshold. */
+    async isEligible(minScore = 500n) {
+        const id = this._requireAgentId();
+        const [eligible, currentScore] = await this.agether8004Scorer.isEligible(id, minScore);
+        return { eligible, currentScore };
+    }
+    // ════════════════════════════════════════════════════════
+    //  Getters
+    // ════════════════════════════════════════════════════════
+    get chainId() {
+        return this.config.chainId;
+    }
+    get contracts() {
+        return this.config.contracts;
+    }
+    get currentAccountAddress() {
+        return this.accountAddress;
+    }
+    getSigner() {
+        return this.signer;
+    }
+    getAgentId() {
+        return this._requireAgentId();
+    }
+    // ════════════════════════════════════════════════════════
+    //  Private Helpers
+    // ════════════════════════════════════════════════════════
+    /** Require agentId to be set, throw a helpful error otherwise. */
+    _requireAgentId() {
+        if (this.agentId === undefined) {
+            throw new AgetherError('agentId not set. Call register() first.', 'NO_AGENT_ID');
+        }
+        return this.agentId;
+    }
+    /** Resolve EOA signer address (async, cached). */
+    async _getSignerAddress() {
+        if (!this._eoaAddress) {
+            this._eoaAddress = await this.signer.getAddress();
+        }
+        return this._eoaAddress;
+    }
+    /**
+     * Resolve a token symbol or address to { address, symbol, decimals }.
+     *
+     * Supports:
+     * - `'USDC'` → from chain config
+     * - Well-known symbols (`'WETH'`, `'wstETH'`, `'cbETH'`) → built-in per-chain registry
+     * - `'0x...'` address → reads decimals and symbol onchain
+     */
+    async _resolveToken(symbolOrAddress) {
+        // USDC from config
+        if (symbolOrAddress.toUpperCase() === 'USDC') {
+            return { address: this.config.contracts.usdc, symbol: 'USDC', decimals: 6 };
+        }
+        // Well-known tokens for this chain
+        const chainTokens = KNOWN_TOKENS[this.config.chainId] ?? {};
+        const bySymbol = chainTokens[symbolOrAddress] || chainTokens[symbolOrAddress.toUpperCase()];
+        if (bySymbol)
+            return bySymbol;
+        // Address: read decimals and symbol onchain
+        if (symbolOrAddress.startsWith('0x') && symbolOrAddress.length === 42) {
+            try {
+                const token = new Contract(symbolOrAddress, ['function decimals() view returns (uint8)', 'function symbol() view returns (string)'], this.signer.provider);
+                const [decimals, symbol] = await Promise.all([token.decimals(), token.symbol()]);
+                return { address: symbolOrAddress, symbol, decimals: Number(decimals) };
+            }
+            catch (e) {
+                throw new AgetherError(`Failed to read token at ${symbolOrAddress}: ${e instanceof Error ? e.message : e}`, 'UNKNOWN_TOKEN');
+            }
+        }
+        throw new AgetherError(`Unknown token: ${symbolOrAddress}. Use a known symbol (USDC, WETH, wstETH, cbETH) or a 0x address.`, 'UNKNOWN_TOKEN');
+    }
+    /**
+     * Refresh signer and rebind contracts for fresh nonce.
+     *
+     * For the privateKey path: recreates provider + wallet.
+     * For external signers: just rebinds contract instances.
+     */
+    _refreshSigner() {
+        if (!this._useExternalSigner && this._privateKey) {
+            const provider = new ethers.JsonRpcProvider(this._rpcUrl);
+            const wallet = new ethers.Wallet(this._privateKey, provider);
+            this.signer = wallet;
+            this._eoaAddress = wallet.address;
+        }
+        const c = this.config.contracts;
+        this.agether4337Factory = new Contract(c.agether4337Factory, AGETHER_4337_FACTORY_ABI, this.signer);
+        this.identityRegistry = new Contract(c.identityRegistry, IDENTITY_REGISTRY_ABI, this.signer);
+        this.agether8004Scorer = new Contract(c.agether8004Scorer, AGETHER_8004_SCORER_ABI, this.signer.provider);
+        this.validationModule = new Contract(c.erc8004ValidationModule, AGETHER_8004_VALIDATION_MODULE_ABI, this.signer.provider);
+        this.entryPoint = new Contract(c.entryPoint, ENTRYPOINT_V07_ABI, this.signer);
+    }
+    // ────────────────────────────────────────────────────────
+    //  ERC-4337 UserOp helpers (Safe + Safe7579 + EntryPoint v0.7)
+    // ────────────────────────────────────────────────────────
+    /**
+     * Pack two uint128 values into a single bytes32:
+     *   bytes32 = (hi << 128) | lo
+     */
+    _packUint128(hi, lo) {
+        return ethers.zeroPadValue(ethers.toBeHex((hi << 128n) | lo), 32);
+    }
+    /**
+     * Build, sign and submit a PackedUserOperation through EntryPoint.handleOps.
+     */
+    async _submitUserOp(callData) {
+        const sender = await this.getAccountAddress();
+        const eoaAddr = await this._getSignerAddress();
+        // Nonce key = validator module address << 32
+        const validatorAddr = this.config.contracts.erc8004ValidationModule;
+        const nonceKey = BigInt(validatorAddr) << 32n;
+        const nonce = await this.entryPoint.getNonce(sender, nonceKey);
+        // Gas prices
+        const feeData = await this.signer.provider.getFeeData();
+        const maxFeePerGas = feeData.maxFeePerGas ?? ethers.parseUnits('0.5', 'gwei');
+        const maxPriorityFeePerGas = feeData.maxPriorityFeePerGas ?? ethers.parseUnits('0.1', 'gwei');
+        const verificationGasLimit = 500000n;
+        const callGasLimit = 800000n;
+        const preVerificationGas = 100000n;
+        const accountGasLimits = this._packUint128(verificationGasLimit, callGasLimit);
+        const gasFees = this._packUint128(maxPriorityFeePerGas, maxFeePerGas);
+        // Auto-fund Safe account for gas
+        const requiredPrefund = (verificationGasLimit + callGasLimit + preVerificationGas) * maxFeePerGas;
+        const accountBalance = await this.signer.provider.getBalance(sender);
+        if (accountBalance < requiredPrefund) {
+            const topUp = requiredPrefund - accountBalance;
+            const topUpWithBuffer = (topUp * 120n) / 100n;
+            const fundTx = await this.signer.sendTransaction({
+                to: sender,
+                value: topUpWithBuffer,
+            });
+            await fundTx.wait();
+            this._refreshSigner();
+        }
+        // Build PackedUserOperation
+        const userOp = {
+            sender,
+            nonce,
+            initCode: '0x',
+            callData,
+            accountGasLimits,
+            preVerificationGas,
+            gasFees,
+            paymasterAndData: '0x',
+            signature: '0x',
+        };
+        // Sign
+        const userOpHash = await this.entryPoint.getUserOpHash(userOp);
+        const signature = await this.signer.signMessage(ethers.getBytes(userOpHash));
+        userOp.signature = signature;
+        // Submit
+        const tx = await this.entryPoint.handleOps([userOp], eoaAddr);
+        const receipt = await tx.wait();
+        this._refreshSigner();
+        // Verify inner UserOp execution succeeded
+        const epIface = new ethers.Interface(ENTRYPOINT_V07_ABI);
+        for (const log of receipt.logs) {
+            try {
+                const parsed = epIface.parseLog({ topics: log.topics, data: log.data });
+                if (parsed?.name === 'UserOperationEvent' && !parsed.args.success) {
+                    let revertMsg = 'UserOp inner execution reverted';
+                    for (const rLog of receipt.logs) {
+                        try {
+                            const rParsed = epIface.parseLog({ topics: rLog.topics, data: rLog.data });
+                            if (rParsed?.name === 'UserOperationRevertReason') {
+                                const reason = rParsed.args.revertReason;
+                                try {
+                                    if (reason.length >= 10 && reason.slice(0, 10) === '0x08c379a0') {
+                                        const decoded = ethers.AbiCoder.defaultAbiCoder().decode(['string'], '0x' + reason.slice(10));
+                                        revertMsg = `UserOp reverted: ${decoded[0]}`;
+                                    }
+                                    else {
+                                        revertMsg = `UserOp reverted with data: ${reason}`;
+                                    }
+                                }
+                                catch {
+                                    revertMsg = `UserOp reverted with data: ${reason}`;
+                                }
+                                break;
+                            }
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                    throw new AgetherError(revertMsg, 'USEROP_EXECUTION_FAILED');
+                }
+            }
+            catch (e) {
+                if (e instanceof AgetherError)
+                    throw e;
+                continue;
+            }
+        }
+        return receipt;
+    }
+    /**
+     * Execute a single call via Safe7579 account (ERC-7579 single mode)
+     * through an ERC-4337 UserOperation.
+     */
+    async _exec(target, data, value = 0n) {
+        const valueHex = ethers.zeroPadValue(ethers.toBeHex(value), 32);
+        const executionCalldata = ethers.concat([target, valueHex, data]);
+        const safe7579Iface = new ethers.Interface(SAFE7579_ACCOUNT_ABI);
+        const callData = safe7579Iface.encodeFunctionData('execute', [MODE_SINGLE, executionCalldata]);
+        return this._submitUserOp(callData);
+    }
+}