@agether/sdk 2.8.1 → 2.11.0

package/dist/index.d.mts

@@ -136,7 +136,36 @@ declare class AgentNotApprovedError extends AgetherError {
 interface AgetherClientOptions {
     config: AgetherConfig;
     signer: Signer;
-    agentId: bigint;
+    agentId?: bigint;
+    /** @internal Private key for signer refresh (set by fromPrivateKey) */
+    _privateKey?: string;
+}
+interface RegisterResult {
+    agentId: string;
+    address: string;
+    agentAccount: string;
+    alreadyRegistered: boolean;
+    kyaRequired: boolean;
+    tx?: string;
+}
+interface WithdrawFromAccountResult {
+    tx: string;
+    token: string;
+    amount: string;
+    destination: string;
+}
+interface BalancesResult {
+    agentId: string;
+    address: string;
+    eth: string;
+    usdc: string;
+    collateral: Record<string, string>;
+    agentAccount?: {
+        address: string;
+        eth: string;
+        usdc: string;
+        collateral: Record<string, string>;
+    };
 }
 declare class AgetherClient {
     private config;
@@ -146,28 +175,107 @@ declare class AgetherClient {
     private identityRegistry;
     private agether8004Scorer;
     private validationModule;
+    private entryPoint;
     private accountAddress?;
+    private _eoaAddress?;
+    private _privateKey?;
+    private _rpcUrl;
+    private _useExternalSigner;
     constructor(options: AgetherClientOptions);
+    /**
+     * Create an AgetherClient for a **new** agent (no agentId yet).
+     * Only `register()` and `getBalances()` are available until registration completes.
+     */
+    static fromPrivateKey(privateKey: string, chainIdOrConfig: ChainId | AgetherConfig): AgetherClient;
+    /**
+     * Create an AgetherClient for an **existing** agent with a known agentId.
+     */
     static fromPrivateKey(privateKey: string, agentId: bigint, chainIdOrConfig: ChainId | AgetherConfig): AgetherClient;
+    /**
+     * Create an AgetherClient from an **external signer** for a **new** agent (no agentId yet).
+     *
+     * Accepts any `ethers.AbstractSigner` — Privy, Bankr, Turnkey, MetaMask, etc.
+     * The signer **must** already be connected to a provider.
+     *
+     * Only `register()` and `getBalances()` are available until registration completes.
+     *
+     * @example
+     * ```ts
+     * const client = AgetherClient.fromSigner(privySigner, ChainId.Base);
+     * const result = await client.register();
+     * ```
+     */
+    static fromSigner(signer: ethers.AbstractSigner, chainIdOrConfig: ChainId | AgetherConfig): AgetherClient;
+    /**
+     * Create an AgetherClient from an **external signer** for an **existing** agent.
+     *
+     * @example
+     * ```ts
+     * const client = AgetherClient.fromSigner(privySigner, 42n, ChainId.Base);
+     * ```
+     */
+    static fromSigner(signer: ethers.AbstractSigner, agentId: bigint, chainIdOrConfig: ChainId | AgetherConfig): AgetherClient;
+    /**
+     * 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.
+     */
+    register(): Promise<RegisterResult>;
+    /** Mint a new ERC-8004 identity and return the agentId. */
+    private _mintNewIdentity;
+    /**
+     * Deploy a Safe account smart wallet for the agent.
+     * The caller must own the ERC-8004 NFT.
+     */
     createAccount(): Promise<string>;
+    /** Get the Safe account address for the current agent. Cached after first call. */
     getAccountAddress(): Promise<string>;
+    /** Check whether the Safe account has been deployed. */
     accountExists(): Promise<boolean>;
-    getBalances(): Promise<{
-        eoa: {
-            eth: string;
-            usdc: string;
-        };
-        account?: {
-            address: string;
-            eth: string;
-            usdc: string;
-        };
-    }>;
+    /**
+     * 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).
+     */
+    getBalances(): Promise<BalancesResult>;
     /**
      * Fund the Safe account with USDC from EOA.
      * This is a simple ERC-20 transfer (does NOT require a UserOp).
      */
     fundAccount(usdcAmount: string): Promise<TransactionResult>;
+    /**
+     * 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')
+     */
+    withdrawToken(tokenSymbol: string, amount: string): Promise<WithdrawFromAccountResult>;
+    /**
+     * 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')
+     */
+    withdrawEth(amount: string): Promise<WithdrawFromAccountResult>;
+    /**
+     * 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)
+     */
+    sponsor(target: {
+        agentId?: string;
+        address?: string;
+    }, tokenSymbol: string, amount: string): Promise<{
+        tx: string;
+        targetAccount: string;
+        targetAgentId?: string;
+    }>;
     /**
      * Check if the KYA gate is active on the validation module.
      * If validationRegistry is not set, all txs pass (KYA disabled).
@@ -178,13 +286,18 @@ declare class AgetherClient {
      * Uses the ERC8004ValidationModule.isKYAApproved(account) view.
      */
     isKyaApproved(): Promise<boolean>;
+    /** Check whether the agent's ERC-8004 NFT exists. */
     identityExists(): Promise<boolean>;
+    /** Get the owner address of the ERC-8004 NFT. */
     getIdentityOwner(): Promise<string>;
+    /** Read the agent's current credit score from the Agether8004Scorer contract. */
     getCreditScore(): Promise<bigint>;
+    /** Check if the score is fresh (within MAX_ORACLE_AGE). */
     isScoreFresh(): Promise<{
         fresh: boolean;
         age: bigint;
     }>;
+    /** Check if the agent meets a minimum score threshold. */
     isEligible(minScore?: bigint): Promise<{
         eligible: boolean;
         currentScore: bigint;
@@ -194,10 +307,46 @@ declare class AgetherClient {
     get currentAccountAddress(): string | undefined;
     getSigner(): Signer;
     getAgentId(): bigint;
+    /** Require agentId to be set, throw a helpful error otherwise. */
+    private _requireAgentId;
+    /** Resolve EOA signer address (async, cached). */
+    private _getSignerAddress;
+    /**
+     * 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
+     */
+    private _resolveToken;
+    /**
+     * Refresh signer and rebind contracts for fresh nonce.
+     *
+     * For the privateKey path: recreates provider + wallet.
+     * For external signers: just rebinds contract instances.
+     */
+    private _refreshSigner;
+    /**
+     * Pack two uint128 values into a single bytes32:
+     *   bytes32 = (hi << 128) | lo
+     */
+    private _packUint128;
+    /**
+     * Build, sign and submit a PackedUserOperation through EntryPoint.handleOps.
+     */
+    private _submitUserOp;
+    /**
+     * Execute a single call via Safe7579 account (ERC-7579 single mode)
+     * through an ERC-4337 UserOperation.
+     */
+    private _exec;
 }
 
 /**
- * MorphoClient — Direct Morpho Blue lending via Safe account (ERC-4337 UserOps)
+ * MorphoClient — Morpho Blue lending only (supply, borrow, repay, withdraw collateral)
+ *
+ * For registration, identity, balances, withdrawals, and sponsorship, use AgetherClient.
  *
  * Architecture (v2 — Safe + Safe7579):
  *   EOA signs UserOp → EntryPoint.handleOps() → Safe → Safe7579 → execute → Morpho Blue
@@ -225,15 +374,13 @@ type AgetherSigner = ethers.AbstractSigner;
 /** Base configuration fields shared by both signing modes. */
 interface MorphoClientBaseConfig {
     rpcUrl: string;
-    agentId?: string;
+    /** ERC-8004 agent ID (required). Use AgetherClient.register() first to get one. */
+    agentId: string;
     chainId?: ChainId;
     contracts?: Partial<{
         agether4337Factory: string;
         morphoBlue: string;
         usdc: string;
-        agether8004Scorer: string;
-        identityRegistry: string;
-        erc8004ValidationModule: string;
         entryPoint: string;
     }>;
 }
@@ -275,28 +422,6 @@ type MorphoClientConfig = MorphoClientBaseConfig & ({
     signer: ethers.AbstractSigner;
     privateKey?: never;
 });
-interface BalancesResult {
-    agentId: string;
-    address: string;
-    eth: string;
-    usdc: string;
-    collateral: Record<string, string>;
-    agentAccount?: {
-        address: string;
-        eth: string;
-        usdc: string;
-        collateral: Record<string, string>;
-    };
-}
-interface RegisterResult {
-    agentId: string;
-    address: string;
-    agentAccount: string;
-    alreadyRegistered: boolean;
-    /** Whether the KYA (code verification) gate is active on this factory */
-    kyaRequired: boolean;
-    tx?: string;
-}
 interface PositionResult {
     marketId: string;
     collateralToken: string;
@@ -342,17 +467,6 @@ interface WithdrawResult {
     remainingCollateral: string;
     destination: string;
 }
-interface FundResult {
-    tx: string;
-    amount: string;
-    agentAccount: string;
-}
-interface WithdrawFromAccountResult {
-    tx: string;
-    token: string;
-    amount: string;
-    destination: string;
-}
 interface SupplyAssetResult {
     tx: string;
     amount: string;
@@ -394,10 +508,7 @@ declare class MorphoClient {
     private _eoaAddress?;
     private agether4337Factory;
     private morphoBlue;
-    private agether8004Scorer;
-    private identityRegistry;
     private entryPoint;
-    private validationModule;
     private _accountAddress?;
     private _marketCache;
     /** Dynamic token registry: symbol (uppercase) → { address, symbol, decimals } */
@@ -405,12 +516,6 @@ declare class MorphoClient {
     private _discoveredMarkets?;
     private _discoveredAt;
     constructor(config: MorphoClientConfig);
-    /**
-     * Check whether the KYA (Know Your Agent) code verification gate is active.
-     * Reads the ERC8004ValidationModule's validationRegistry — when set to
-     * a non-zero address, the module enforces KYA code approval.
-     */
-    isKyaRequired(): Promise<boolean>;
     /** Resolve the AgentAccount address (cached, with retry for flaky RPCs). */
     getAccountAddress(): Promise<string>;
     getAgentId(): string;
@@ -427,32 +532,6 @@ declare class MorphoClient {
      * Result is cached after the first call.
      */
     getSignerAddress(): Promise<string>;
-    /** Mint a new ERC-8004 identity and return the agentId. */
-    private _mintNewIdentity;
-    /**
-     * Register: create ERC-8004 identity + AgentAccount in one flow.
-     * If already registered, returns existing state.
-     */
-    register(_name?: string): Promise<RegisterResult>;
-    /** Get ETH / USDC / collateral balances for EOA and AgentAccount. */
-    getBalances(): Promise<BalancesResult>;
-    /** Transfer USDC from EOA to AgentAccount. */
-    fundAccount(usdcAmount: string): Promise<FundResult>;
-    /**
-     * Withdraw (transfer) a token from AgentAccount to EOA.
-     * Executes an ERC-20 transfer via Safe UserOp.
-     *
-     * @param tokenSymbol - Token to withdraw (e.g. 'USDC', 'WETH', 'wstETH')
-     * @param amount - Amount to withdraw (human-readable, e.g. '100' for 100 USDC, or 'all')
-     */
-    withdrawToken(tokenSymbol: string, amount: string): Promise<WithdrawFromAccountResult>;
-    /**
-     * Withdraw ETH from AgentAccount to EOA.
-     * Executes a native ETH transfer via Safe UserOp.
-     *
-     * @param amount - ETH amount (e.g. '0.01' or 'all')
-     */
-    withdrawEth(amount: string): Promise<WithdrawFromAccountResult>;
     /**
      * Fetch USDC borrow markets on Base from Morpho API.
      * Caches results for 5 minutes.
@@ -620,28 +699,6 @@ declare class MorphoClient {
      * @param receiver - defaults to EOA wallet
      */
     withdrawCollateral(tokenSymbol: string, amount: string, marketParams?: MorphoMarketParams, receiver?: string): Promise<WithdrawResult>;
-    /**
-     * Sponsor: transfer collateral to another agent's AgentAccount.
-     * (The agent must then supplyCollateral themselves via their own account.)
-     */
-    sponsor(target: {
-        agentId?: string;
-        address?: string;
-    }, tokenSymbol: string, amount: string): Promise<{
-        tx: string;
-        targetAccount: string;
-        targetAgentId?: string;
-    }>;
-    getCreditScore(): Promise<bigint>;
-    getAttestation(): Promise<ScoreAttestation>;
-    isEligible(minScore?: bigint): Promise<{
-        eligible: boolean;
-        currentScore: bigint;
-    }>;
-    isScoreFresh(): Promise<{
-        fresh: boolean;
-        age: bigint;
-    }>;
     /**
      * Refresh the signer and re-bind contract instances.
      *
@@ -694,11 +751,6 @@ declare class MorphoClient {
      * @param symbolOrAddress - e.g. 'WETH', 'wstETH', or '0x4200...'
      */
     private _resolveToken;
-    /**
-     * Get all discovered collateral tokens (for balance iteration, etc.).
-     * Returns unique tokens from the Morpho API market discovery.
-     */
-    private _getDiscoveredTokens;
     /**
      * Compute net deposited amounts per market using Morpho GraphQL API.
      *
@@ -1308,4 +1360,4 @@ declare function getMorphoBlueAddress(chainId: ChainId): string;
  */
 declare function getContractAddresses(chainId: ChainId): ContractAddresses;
 
-export { ACCOUNT_FACTORY_ABI, AGENT_REPUTATION_ABI, AGETHER_4337_FACTORY_ABI, AGETHER_8004_SCORER_ABI, AGETHER_8004_VALIDATION_MODULE_ABI, AGETHER_HOOK_MULTIPLEXER_ABI, AgentIdentityClient, type AgentIdentityClientOptions, AgentNotApprovedError, AgetherClient, type AgetherClientOptions, type AgetherConfig, AgetherError, type AgetherSigner, type AgetherViemWallet, type BalancesResult, type BorrowResult, ChainId, type ContractAddresses, type DepositAndBorrowResult, type DepositResult, ENTRYPOINT_V07_ABI, ERC20_ABI, ERC8004_VALIDATION_MODULE_ABI, type FundResult, HOOK_MULTIPLEXER_ABI, IDENTITY_REGISTRY_ABI, InsufficientBalanceError, MORPHO_BLUE_ABI, MorphoClient, type MorphoClientConfig, type MorphoMarketInfo, type MorphoMarketParams, type MorphoPosition, type PayFromYieldResult, type PaymentRequirements, type PositionResult, type RegisterResult, type RepayResult, SAFE7579_ACCOUNT_ABI, SAFE_AGENT_FACTORY_ABI, type ScoreAttestation, type ScoreResult, ScoringClient, type ScoringClientConfig, ScoringRejectedError, type SpendingTracker, type StatusResult, type SupplyAssetResult, type SupplyPositionResult, type TransactionResult, VALIDATION_REGISTRY_ABI, type WithdrawFromAccountResult, type WithdrawResult, type WithdrawSupplyResult, X402Client, type X402Config, type X402PaymentRequest, type X402PaymentResult, type X402Response, bpsToRate, createConfig, formatAPR, formatAddress, formatHealthFactor, formatPercent, formatTimestamp, formatUSD, formatUnits, getContractAddresses, getDefaultConfig, getMorphoBlueAddress, getUSDCAddress, parseUnits, rateToBps };
+export { ACCOUNT_FACTORY_ABI, AGENT_REPUTATION_ABI, AGETHER_4337_FACTORY_ABI, AGETHER_8004_SCORER_ABI, AGETHER_8004_VALIDATION_MODULE_ABI, AGETHER_HOOK_MULTIPLEXER_ABI, AgentIdentityClient, type AgentIdentityClientOptions, AgentNotApprovedError, AgetherClient, type AgetherClientOptions, type AgetherConfig, AgetherError, type AgetherSigner, type AgetherViemWallet, type BalancesResult, type BorrowResult, ChainId, type ContractAddresses, type DepositAndBorrowResult, type DepositResult, ENTRYPOINT_V07_ABI, ERC20_ABI, ERC8004_VALIDATION_MODULE_ABI, HOOK_MULTIPLEXER_ABI, IDENTITY_REGISTRY_ABI, InsufficientBalanceError, MORPHO_BLUE_ABI, MorphoClient, type MorphoClientConfig, type MorphoMarketInfo, type MorphoMarketParams, type MorphoPosition, type PayFromYieldResult, type PaymentRequirements, type PositionResult, type RegisterResult, type RepayResult, SAFE7579_ACCOUNT_ABI, SAFE_AGENT_FACTORY_ABI, type ScoreAttestation, type ScoreResult, ScoringClient, type ScoringClientConfig, ScoringRejectedError, type SpendingTracker, type StatusResult, type SupplyAssetResult, type SupplyPositionResult, type TransactionResult, VALIDATION_REGISTRY_ABI, type WithdrawFromAccountResult, type WithdrawResult, type WithdrawSupplyResult, X402Client, type X402Config, type X402PaymentRequest, type X402PaymentResult, type X402Response, bpsToRate, createConfig, formatAPR, formatAddress, formatHealthFactor, formatPercent, formatTimestamp, formatUSD, formatUnits, getContractAddresses, getDefaultConfig, getMorphoBlueAddress, getUSDCAddress, parseUnits, rateToBps };