@agether/sdk 2.12.2 → 2.14.0

package/dist/clients/AgetherClient.d.ts

@@ -0,0 +1,242 @@
+/**
+ * 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, Signer } from 'ethers';
+import { AgetherConfig, TransactionResult, ChainId } from '../types';
+export interface AgetherClientOptions {
+    config: AgetherConfig;
+    signer: Signer;
+    agentId?: bigint;
+    /** @internal Private key for signer refresh (set by fromPrivateKey) */
+    _privateKey?: string;
+}
+export interface RegisterResult {
+    agentId: string;
+    address: string;
+    agentAccount: string;
+    alreadyRegistered: boolean;
+    kyaRequired: boolean;
+    tx?: string;
+}
+export interface WithdrawFromAccountResult {
+    tx: string;
+    token: string;
+    amount: string;
+    destination: string;
+}
+export 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>;
+    };
+}
+export declare class AgetherClient {
+    private config;
+    private signer;
+    private agentId;
+    private agether4337Factory;
+    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 on the correct chain.
+     *
+     * Validates that the signer's provider chain matches the requested chain.
+     *
+     * Only `register()` and `getBalances()` are available until registration completes.
+     *
+     * @example
+     * ```ts
+     * const client = await AgetherClient.fromSigner(privySigner, ChainId.Base);
+     * const result = await client.register();
+     * ```
+     */
+    static fromSigner(signer: ethers.AbstractSigner, chainIdOrConfig: ChainId | AgetherConfig): Promise<AgetherClient>;
+    /**
+     * Create an AgetherClient from an **external signer** for an **existing** agent.
+     *
+     * @example
+     * ```ts
+     * const client = await AgetherClient.fromSigner(privySigner, 42n, ChainId.Base);
+     * ```
+     */
+    static fromSigner(signer: ethers.AbstractSigner, agentId: bigint, chainIdOrConfig: ChainId | AgetherConfig): Promise<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.
+     *
+     * @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')
+     */
+    register(options?: {
+        name?: string;
+        description?: string;
+    }): Promise<RegisterResult>;
+    /** 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.
+     */
+    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>;
+    /**
+     * 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).
+     */
+    isKyaRequired(): Promise<boolean>;
+    /**
+     * Check if this agent's code is KYA-approved.
+     * 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;
+    }>;
+    get chainId(): ChainId;
+    get contracts(): import("..").ContractAddresses;
+    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;
+}
+//# sourceMappingURL=AgetherClient.d.ts.map

package/dist/clients/AgetherClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgetherClient.d.ts","sourceRoot":"","sources":["../../src/clients/AgetherClient.ts"],"names":[],"mappings":"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"}