@fenelabs/fene-sdk 0.3.0 → 0.3.3

package/dist/index.d.mts

@@ -1,937 +1,310 @@
-import { ethers } from 'ethers';
-
-interface APIResponse<T> {
-    data: T;
-    meta?: Record<string, any>;
-}
-interface APIError {
-    error: {
-        code: string;
-        message: string;
+type Address = `0x${string}`;
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination?: {
+        page: number;
+        limit: number;
+        total: number;
+        total_pages: number;
     };
 }
-interface ValidatorDetailResponse {
-    validator_address: string;
-    name: string;
-    description: string;
-    commission_rate: number;
-    status: string;
-    self_stake: string;
-    delegators_stake: string;
-    total_stake: string;
-    uptime: string;
-    missed_blocks: number;
-    signed_blocks: number;
-    total_delegators: number;
-    withdrawn_rewards_total: string;
-}
-interface ValidatorEpochResponse {
-    validator_address: string;
-    epoch: number;
-    reward: EpochReward;
-    stakes: EpochStakes;
-    distribution: EpochDistribution;
-    unclaimed: EpochUnclaimed;
-}
-interface EpochReward {
-    reward_gross: string;
-    commission_rate: number;
-    commission_fee: string;
-    delegator_pool: string;
-}
-interface EpochStakes {
-    self_stake: string;
-    delegators_stake: string;
-    total_stake_validator: string;
-}
-interface EpochDistribution {
-    self_reward_from_pool: string;
-    validator_total_reward: string;
-    delegators_total_reward: string;
-}
-interface EpochUnclaimed {
-    unclaimed_validator_reward: string;
-    unclaimed_delegators_reward_total: string;
-    delegators: UnclaimedDelegator[];
-}
-interface UnclaimedDelegator {
-    delegator_address: string;
-    stake: string;
-    reward: string;
-    unclaimed_reward: string;
-}
-interface ValidatorListResponse {
+interface NonceResponse {
     address: string;
-    count: number;
+    nonce: string;
+    message: string;
 }
-interface ValidatorDelegatorsResponse {
-    validator_address: string;
-    total_delegators: number;
-    delegators: DelegatorStakeInfo[];
+interface AuthResponse {
+    token: string;
+    address: string;
+    role: 'validator' | 'delegator' | 'public';
+    expires_at: number;
 }
-interface DelegatorStakeInfo {
-    delegator_address: string;
-    stake: string;
-    percentage: string;
+declare enum ValidatorStatus {
+    NOT_EXIST = 0,
+    CREATED = 1,
+    STAKED = 2,
+    VALIDATED = 3,
+    UNSTAKED = 4
 }
-interface ValidatorStakeBreakdownResponse {
-    validator_address: string;
+interface Validator {
+    address: string;
+    reward_address: string;
+    status: ValidatorStatus;
     self_stake: string;
-    delegators_stake: string;
     total_stake: string;
-    self_stake_percent: string;
-}
-interface ValidatorHistoryResponse {
-    validator_address: string;
-    from_epoch: number;
-    to_epoch: number;
-    history: ValidatorHistoryItem[];
-}
-interface ValidatorHistoryItem {
-    epoch: number;
-    reward: string;
-    total_stake: string;
-    uptime: string;
-    missed_blocks: number;
-}
-interface ValidatorWithdrawalsResponse {
-    validator_address: string;
-    total_withdrawn: string;
-    withdrawals: ValidatorWithdrawal[];
-}
-interface ValidatorWithdrawal {
-    tx_hash: string;
-    amount: string;
-    timestamp: number;
-    block_num: number;
-}
-interface ValidatorMetricsResponse {
-    validator_address: string;
-    uptime: number;
-    missed_blocks: number;
-    signed_blocks: number;
-    total_blocks: number;
-    apr: number;
-    total_stake: string;
-    total_delegators: number;
-}
-interface ValidatorAPRResponse {
-    validator_address: string;
-    apr_decimal: number;
-    apr_percent: string;
-}
-interface DelegatorDetailResponse {
-    delegator_address: string;
-    total_stake: string;
-    active_validators: ActiveValidator[];
-    total_rewards: string;
-    withdrawn_rewards_total: string;
-    unbonding?: UnbondingInfo;
-}
-interface ActiveValidator {
-    validator_address: string;
-    stake: string;
-}
-interface UnbondingInfo {
-    amount: string;
-    unbonding_start: number;
-    unbonding_end: number;
+    commission_rate: number;
+    claimable_reward: string;
+    acc_reward_per_stake: string;
+    created_at: number;
+    unstake_block: number;
+    active_dc_count: number;
+    moniker: string;
+    phone_number: string;
+    details: string;
 }
-interface DelegatorListResponse {
+interface ValidatorSummary {
     address: string;
-    count: number;
-}
-interface DelegatorStakesResponse {
-    delegator_address: string;
+    moniker: string;
     total_stake: string;
-    stakes: DelegatorValidatorStake[];
-}
-interface DelegatorValidatorStake {
-    validator_address: string;
-    stake: string;
-    percentage: string;
-}
-interface DelegatorRewardsResponse {
-    delegator_address: string;
-    total_rewards: string;
-    rewards: DelegatorReward[];
-}
-interface DelegatorReward {
-    validator_address: string;
-    epoch: number;
-    amount: string;
-    timestamp: number;
-}
-interface DelegatorWithdrawalsResponse {
-    delegator_address: string;
-    total_withdrawn: string;
-    withdrawals: DelegatorWithdrawal[];
-}
-interface DelegatorWithdrawal {
-    tx_hash: string;
-    amount: string;
-    timestamp: number;
-    block_num: number;
-}
-interface DelegatorUnbondingResponse {
-    delegator_address: string;
-    has_unbonding: boolean;
-    unbonding?: UnbondingInfo;
-}
-interface DelegatorValidatorsResponse {
-    delegator_address: string;
-    total_validators: number;
-    validators: ActiveValidator[];
-}
-interface ReferralCreateRequest {
-    validator_address: string;
-    max_quota?: number;
-    expires_in_days?: number;
-}
-interface ReferralValidateRequest {
-    referral_code: string;
-}
-interface ReferralApplyRequest {
-    referral_code: string;
-    delegator_address: string;
-}
-interface ReferralValidateResponse {
-    is_valid: boolean;
-    referral_code?: string;
-    message?: string;
-}
-interface ReferralDelegatorResponse {
-    delegator_address: string;
-    referred_by_validator: string;
-    referral_code_used: string;
-}
-interface ReferralValidatorResponse {
-    validator_address: string;
-    referral_code: string;
-    delegators: string[];
-    total_referred: number;
+    commission_rate: number;
+    status: ValidatorStatus;
+    delegator_count: number;
 }
-interface SlashingEventResponse {
-    validator_address: string;
-    reason: string;
-    block_height: number;
-    penalty_amount: string;
-    jailed_until?: number;
-    timestamp: number;
+declare enum DelegatorStatus {
+    NOT_EXIST = 0,
+    ACTIVE = 1,
+    UNSTAKING = 2
 }
-interface GlobalNetworkResponse {
-    total_network_stake: string;
+interface Delegator {
+    address: string;
+    validator: string;
+    stake_amount: string;
+    pending_rewards: string;
+    joined_at: number;
+    status: DelegatorStatus;
+}
+interface DelegatorStake {
+    validator: string;
+    stake_amount: string;
+    pending_rewards: string;
+    status: DelegatorStatus;
+}
+interface DelegatorRewards {
+    validator: string;
+    pending_rewards: string;
+    total_claimed: string;
+}
+interface ReferralKey {
+    key: string;
+    validator: string;
+    created_at: number;
+    used_count: number;
+    max_uses: number;
+    active: boolean;
+}
+interface WhitelistCheckRequest {
+    key: string;
+}
+interface WhitelistCheckResponse {
+    whitelisted: boolean;
+    validator: string;
+    tier: number;
+}
+interface GeoNode {
+    address: string;
+    ip: string;
+    latitude: number;
+    longitude: number;
+    city: string;
+    country: string;
+    country_code: string;
+    last_seen: string;
+    node_type: 'validator' | 'rpc' | 'bootstrap';
+    online: boolean;
+}
+interface GeoStats {
+    total_nodes: number;
+    online_nodes: number;
+    countries: number;
+    cities: number;
+}
+interface GeoUpdateRequest {
+    latitude: number;
+    longitude: number;
+    node_type: string;
+}
+interface NetworkStats {
     total_validators: number;
+    active_validators: number;
     total_delegators: number;
+    total_stake: string;
+    current_block: number;
     epoch: number;
-    block_height: number;
-    jailed_validators: number;
-    ranking_top_delegators: TopDelegatorRank[];
+    block_time: number;
 }
-interface TopDelegatorRank {
-    rank: number;
-    address: string;
-    total_stake: string;
+interface EpochInfo {
+    number: number;
+    start_block: number;
+    end_block: number;
+    blocks_remaining: number;
+    estimated_end: string;
 }
-interface NetworkAPRResponse {
+interface NetworkAPR {
     network_apr: number;
+    annual_emission: string;
+    block_reward: string;
+    blocks_per_year: number;
 }
-interface NetworkAPRBreakdownResponse {
-    reward_per_block: string;
-    reward_per_epoch: string;
-    reward_per_year: string;
-    epochs_per_day: number;
-    effective_inflation: number;
-}
-interface LeaderboardDelegatorResponse {
-    rank: number;
-    address: string;
-    stake: string;
-}
-interface LeaderboardValidatorResponse {
-    rank: number;
-    address: string;
-    apr_decimal: number;
-    total_stake: string;
-    self_stake: string;
-}
-interface JWTClaims {
-    address: string;
-    role: 'validator' | 'delegator';
-    exp: number;
-    iat: number;
-    iss: string;
-}
-interface AuthResponse {
-    token: string;
-    address: string;
-    role: string;
-    expires_at: number;
-}
-interface SDKConfig {
-    apiUrl: string;
-    timeout?: number;
-    headers?: Record<string, string>;
-}
-interface QueryParams {
-    [key: string]: string | number | boolean | undefined;
+interface ValidatorAPR {
+    network_apr: number;
+    validator_apr: number;
+    delegator_apr: number;
 }
-interface ValidatorAnalytics {
-    address: string;
-    moniker: string;
-    uptime: number;
-    signed_blocks: number;
-    missed_blocks: number;
-    total_rewards: number;
-    total_stakers: number;
-    status: string;
-    updated_at: string;
-    subgraph_indexing_block: number;
+interface UploadResponse {
+    success: boolean;
+    key: string;
+    size: number;
 }
-interface ValidatorAnalyticsListResponse {
-    count: number;
-    data: ValidatorAnalytics[];
+interface AvatarResponse {
+    url: string | null;
 }
-interface ProtocolStats {
-    Admin: string;
-    IsPaused: boolean;
-    TotalStaking: string;
-    TotalValidators: string;
-    ActiveValidators: string;
-    JailedValidators: string;
-    TotalRewardsDistributed: string;
-    TotalSlashed: string;
-    LastSyncedAt: string;
-    SubgraphIndexingBlock: number;
+interface DailyBlockStats {
+    date: string;
+    blocks: number;
+    transactions: number;
+    gas: number;
 }
-interface RewardDTO {
+interface RewardHistory {
     block: number;
     amount: string;
-    timestamp: number;
-}
-interface StakeDTO {
-    staker: string;
-    amount: string;
-}
-interface RewardSummary {
-    total_rewards: string;
-    total_stakers: number;
-    uptime: number;
-    signed_blocks: number;
-    missed_blocks: number;
-    last_signed_block: number;
-    updated_at_block: number;
-    updated_at_timestamp: number;
-    rewards_count: number;
-    stakes_count: number;
-    last_reward_block: number;
-    last_reward_amount: string;
-    total_staked_amount: string;
-}
-interface ResponseMetadata {
-    cached: boolean;
-    stale: boolean;
-    subgraph_block: number;
-    limit: number;
-    offset: number;
-    has_more: boolean;
-}
-interface ValidatorRewardsResponse {
-    address: string;
-    moniker: string;
-    reward_address: string;
-    status: string;
-    rewards: RewardDTO[];
-    stakes: StakeDTO[];
-    summary: RewardSummary;
-    metadata: ResponseMetadata;
-}
-interface SyncJobStatus {
-    status: 'success' | 'degraded' | 'failed' | 'pending';
-    last_sync_at: string | null;
-    last_block: number | null;
-    next_retry_at: string | null;
-    error: string | null;
-    retry_count: number;
-    failure_count: number;
-    success_count: number;
-    total_count: number;
-    failure_rate: number;
-}
-interface SyncStatusResponse {
-    protocol_sync: SyncJobStatus;
-    validator_sync?: SyncJobStatus;
-}
-interface PaginationOptions {
-    limit?: number;
-    offset?: number;
-}
-interface ValidatorListOptions extends PaginationOptions {
-    status?: 'active' | 'inactive' | 'jailed';
-}
-
-declare class AuthService {
-    private apiUrl;
-    private tokenKey;
-    constructor(apiUrl: string);
-    /**
-     * Get nonce for wallet authentication
-     * POST /eth/v1/auth/nonce
-     */
-    getNonce(address: string): Promise<{
-        nonce: string;
-        message: string;
-    }>;
-    /**
-     * Verify wallet signature and get JWT token
-     * POST /eth/v1/auth/verify
-     */
-    verify(params: {
-        address: string;
-        signature: string;
-        role: 'validator' | 'delegator';
-    }): Promise<{
-        token: string;
-    }>;
-    /**
-     * Connect wallet and authenticate
-     */
-    connectWallet(provider: ethers.BrowserProvider, role?: 'validator' | 'delegator'): Promise<AuthResponse>;
-    /**
-     * Get stored JWT token
-     */
-    getToken(): string | null;
-    /**
-     * Check if user is authenticated
-     */
-    isAuthenticated(): boolean;
-    /**
-     * Parse JWT token to get claims
-     */
-    parseToken(token: string): JWTClaims;
-    /**
-     * Get user info from token
-     */
-    getUserInfo(): {
-        address: string;
-        role: string;
-    } | null;
-    /**
-     * Logout user
-     */
-    logout(): void;
-    /**
-     * Check if token is expiring soon (within 5 minutes)
-     */
-    isTokenExpiringSoon(): boolean;
+    timestamp: string;
 }
 
-declare class HTTPClient {
+interface RequestContext {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: any;
+    timestamp: number;
+    attemptNumber: number;
+}
+interface ResponseContext extends RequestContext {
+    status: number;
+    statusText: string;
+    duration: number;
+    data?: any;
+}
+interface ResonanceClientConfig {
+    /** Base URL of the API. If not provided, reads from RESONANCE_API_URL env var */
+    baseUrl?: string;
+    /** Bearer token for authentication */
+    token?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts for failed requests (default: 2) */
+    retries?: number;
+    /** Initial delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Called when token expires (401 response) */
+    onTokenExpired?: () => void;
+    /** Called before each request */
+    onRequest?: (ctx: RequestContext) => void;
+    /** Called after successful response */
+    onResponse?: (ctx: ResponseContext) => void;
+    /** Called when request fails */
+    onError?: (error: Error, ctx: RequestContext) => void;
+}
+declare class ResonanceClient {
     private baseUrl;
+    private token?;
     private timeout;
-    private headers;
-    constructor(config: SDKConfig);
-    /**
-     * Build URL with query parameters
-     */
-    private buildUrl;
-    /**
-     * Set authorization token
-     */
-    setAuthToken(token: string | null): void;
-    /**
-     * Set custom header
-     */
-    setHeader(key: string, value: string): void;
-    /**
-     * Make HTTP GET request
-     */
-    get<T>(path: string, params?: QueryParams): Promise<T>;
-    /**
-     * Make HTTP POST request
-     */
-    post<T>(path: string, body?: any): Promise<T>;
-    /**
-     * Make HTTP DELETE request
-     */
-    delete<T>(path: string): Promise<T>;
-    /**
-     * Handle HTTP errors
-     */
-    private handleError;
-    private fetchWithRetry;
-}
-
-declare class ValidatorsAPI {
-    private client;
-    constructor(client: HTTPClient);
-    /**
-     * Get all validators
-     * GET /eth/v1/validators
-     */
-    getAll(): Promise<ValidatorListResponse>;
-    /**
-     * Get validator details
-     * GET /eth/v1/validators/:address
-     */
-    get(address: string): Promise<ValidatorDetailResponse>;
-    /**
-     * Get validator delegators
-     * GET /eth/v1/validators/:address/delegators
-     */
-    getDelegators(address: string): Promise<ValidatorDelegatorsResponse>;
-    /**
-     * Get validator stake breakdown
-     * GET /eth/v1/validators/:address/stake
-     */
-    getStakeBreakdown(address: string): Promise<ValidatorStakeBreakdownResponse>;
-    /**
-     * Get validator epoch details
-     * GET /eth/v1/validators/:address/epochs/:epoch
-     */
-    getEpoch(address: string, epoch: number): Promise<ValidatorEpochResponse>;
-    /**
-     * Get validator history
-     * GET /eth/v1/validators/:address/history
-     * @param address - Validator address
-     * @param fromEpoch - Optional starting epoch
-     * @param toEpoch - Optional ending epoch
-     */
-    getHistory(address: string, fromEpoch?: number, toEpoch?: number): Promise<ValidatorHistoryResponse>;
-    /**
-     * Get validator withdrawals
-     * GET /eth/v1/validators/:address/withdrawals
-     * @param address - Validator address
-     * @param limit - Optional limit
-     * @param offset - Optional offset
-     */
-    getWithdrawals(address: string, limit?: number, offset?: number): Promise<ValidatorWithdrawalsResponse>;
-    /**
-     * Get validator metrics
-     * GET /eth/v1/validators/:address/metrics
-     */
-    getMetrics(address: string): Promise<ValidatorMetricsResponse>;
-    /**
-     * Get validator slashing events
-     * GET /eth/v1/validators/:address/slashing
-     */
-    getSlashing(address: string): Promise<SlashingEventResponse[]>;
-    /**
-     * Get validator APR
-     * GET /eth/v1/validators/:address/apr
-     */
-    getAPR(address: string): Promise<ValidatorAPRResponse>;
-}
-
-declare class DelegatorsAPI {
-    private client;
-    constructor(client: HTTPClient);
-    /**
-     * Get all delegators
-     * GET /eth/v1/delegators
-     */
-    getAll(): Promise<DelegatorListResponse>;
-    /**
-     * Get delegator details
-     * GET /eth/v1/delegators/:address
-     */
-    get(address: string): Promise<DelegatorDetailResponse>;
-    /**
-     * Get delegator stakes breakdown per validator
-     * GET /eth/v1/delegators/:address/stakes
-     */
-    getStakes(address: string): Promise<DelegatorStakesResponse>;
-    /**
-     * Get delegator rewards history
-     * GET /eth/v1/delegators/:address/rewards
-     * @param address - Delegator address
-     * @param limit - Optional limit
-     * @param offset - Optional offset
-     */
-    getRewards(address: string, limit?: number, offset?: number): Promise<DelegatorRewardsResponse>;
-    /**
-     * Get delegator withdrawals history
-     * GET /eth/v1/delegators/:address/withdrawals
-     * @param address - Delegator address
-     * @param limit - Optional limit
-     * @param offset - Optional offset
-     */
-    getWithdrawals(address: string, limit?: number, offset?: number): Promise<DelegatorWithdrawalsResponse>;
-    /**
-     * Get delegator unbonding status
-     * GET /eth/v1/delegators/:address/unbonding
-     */
-    getUnbonding(address: string): Promise<DelegatorUnbondingResponse>;
-    /**
-     * Get delegator active validators
-     * GET /eth/v1/delegators/:address/validators
-     */
-    getValidators(address: string): Promise<DelegatorValidatorsResponse>;
-}
-
-declare class ReferralsAPI {
-    private client;
-    constructor(client: HTTPClient);
-    /**
-     * Validate a referral code
-     * GET /eth/v1/referrals/validate?code=CODE
-     */
-    validate(referralCode: string): Promise<ReferralValidateResponse>;
-    /**
-     * Create a new referral code
-     * POST /eth/v1/referrals
-     * @param request - Referral creation request
-     */
-    create(request: ReferralCreateRequest): Promise<ReferralValidatorResponse>;
-    /**
-     * Apply a referral code
-     * POST /eth/v1/referrals/apply
-     * @param request - Referral application request
-     */
-    apply(request: ReferralApplyRequest): Promise<{
-        message: string;
-    }>;
-    /**
-     * Delete a referral code
-     * DELETE /eth/v1/referrals/:referral_code
-     * @param referralCode - The referral code to delete
-     */
-    delete(referralCode: string): Promise<{
-        message: string;
-    }>;
-    /**
-     * Unlink a delegator from referral
-     * DELETE /eth/v1/referrals/unlink/:delegator_address
-     * @param delegatorAddress - The delegator address to unlink
-     */
-    unlink(delegatorAddress: string): Promise<{
-        message: string;
-    }>;
-    /**
-     * Get delegator referral information
-     * GET /eth/v1/referrals/delegators/:delegator_address
-     */
-    getDelegatorReferral(delegatorAddress: string): Promise<ReferralDelegatorResponse>;
-    /**
-     * Get validator referral information
-     * GET /eth/v1/referrals/validators/:validator_address
-     */
-    getValidatorReferral(validatorAddress: string): Promise<ReferralValidatorResponse>;
-}
-
-declare class GlobalAPI {
-    private client;
-    constructor(client: HTTPClient);
-    /**
-     * Get global network statistics
-     * GET /eth/v1/global
-     */
-    getStats(): Promise<GlobalNetworkResponse>;
-    /**
-     * Get network APR (from /global endpoint)
-     * GET /eth/v1/global/network_apr
-     */
-    getNetworkAPRFromGlobal(): Promise<NetworkAPRResponse>;
-    /**
-     * Get network APR (from /network endpoint)
-     * GET /eth/v1/network/apr
-     */
-    getNetworkAPR(): Promise<NetworkAPRResponse>;
-    /**
-     * Get network APR breakdown
-     * GET /eth/v1/network/apr/breakdown
-     */
-    getNetworkAPRBreakdown(): Promise<NetworkAPRBreakdownResponse>;
-    /**
-     * Get delegator leaderboard
-     * GET /eth/v1/leaderboard/delegators
-     * @param limit - Optional limit (default backend value)
-     * @param offset - Optional offset for pagination
-     */
-    getLeaderboardDelegators(limit?: number, offset?: number): Promise<LeaderboardDelegatorResponse[]>;
-    /**
-     * Get validator leaderboard
-     * GET /eth/v1/leaderboard/validators
-     * @param limit - Optional limit (default backend value)
-     * @param offset - Optional offset for pagination
-     */
-    getLeaderboardValidators(limit?: number, offset?: number): Promise<LeaderboardValidatorResponse[]>;
-}
-
-declare class SlashingAPI {
-    private client;
-    constructor(client: HTTPClient);
-    /**
-     * Get slashing events
-     * GET /eth/v1/slashing/events
-     * @param validatorAddress - Optional validator address filter
-     * @param limit - Optional limit
-     * @param offset - Optional offset
-     */
-    getEvents(validatorAddress?: string, limit?: number, offset?: number): Promise<SlashingEventResponse[]>;
-}
+    private retries;
+    private retryDelay;
+    private onTokenExpired?;
+    private onRequest?;
+    private onResponse?;
+    private onError?;
+    constructor(config?: ResonanceClientConfig);
+    setToken(token: string): void;
+    clearToken(): void;
+    private request;
+    private executeRequest;
+    getNonce(address: Address): Promise<NonceResponse>;
+    verify(address: Address, signature: string): Promise<AuthResponse>;
+    getValidators(): Promise<ValidatorSummary[]>;
+    getActiveValidators(): Promise<ValidatorSummary[]>;
+    getCandidates(): Promise<ValidatorSummary[]>;
+    getValidator(address: Address): Promise<Validator>;
+    getValidatorDelegators(address: Address): Promise<Delegator[]>;
+    getDelegator(address: Address): Promise<Delegator>;
+    getDelegatorStakes(address: Address): Promise<DelegatorStake[]>;
+    getDelegatorRewards(address: Address): Promise<DelegatorRewards[]>;
+    getReferralKey(key: string): Promise<ReferralKey>;
+    getValidatorKeys(address: Address): Promise<ReferralKey[]>;
+    checkWhitelist(data: WhitelistCheckRequest): Promise<WhitelistCheckResponse>;
+    getGeoNodes(): Promise<GeoNode[]>;
+    getGeoValidators(): Promise<GeoNode[]>;
+    getGeoStats(): Promise<GeoStats>;
+    updateGeoLocation(data: GeoUpdateRequest): Promise<void>;
+    getNetworkStats(): Promise<NetworkStats>;
+    getCurrentEpoch(): Promise<EpochInfo>;
+    getNetworkAPR(): Promise<NetworkAPR>;
+    getValidatorAPR(address: Address): Promise<ValidatorAPR>;
+    uploadAvatar(file: File): Promise<UploadResponse>;
+    getAvatar(address: Address): Promise<AvatarResponse>;
+    getDailyBlockStats(days?: number): Promise<DailyBlockStats[]>;
+    getValidatorRewardHistory(address: Address, limit?: number): Promise<RewardHistory[]>;
+}
+declare function createResonanceClient(config: ResonanceClientConfig): ResonanceClient;
 
 /**
- * Analytics API Module
- *
- * Provides access to analytics endpoints powered by subgraph indexing.
- * These endpoints provide aggregated and historical data from the blockchain.
- *
- * @remarks
- * Analytics data is sourced from The Graph subgraph and may have slight delays
- * compared to real-time blockchain data. Check sync status for data freshness.
- *
- * @example
- * ```typescript
- * // Get protocol statistics
- * const stats = await sdk.analytics.getProtocolStats();
- *
- * // Get top validators by uptime
- * const topValidators = await sdk.analytics.getTopValidators(10);
- *
- * // Get validator rewards with pagination
- * const rewards = await sdk.analytics.getValidatorRewards(
- *   '0x1234...',
- *   { limit: 50, offset: 0 }
- * );
- * ```
+ * Error codes matching the Resonance API error system
  */
-declare class AnalyticsAPI {
-    private client;
-    private readonly basePath;
-    constructor(client: HTTPClient);
-    /**
-     * Get protocol-level statistics
-     *
-     * Returns aggregated statistics about the entire protocol including
-     * total staking, validator counts, and rewards distribution.
-     *
-     * @returns Protocol statistics from subgraph
-     *
-     * @example
-     * ```typescript
-     * const stats = await sdk.analytics.getProtocolStats();
-     * console.log(`Total Staking: ${stats.TotalStaking}`);
-     * console.log(`Active Validators: ${stats.ActiveValidators}`);
-     * ```
-     */
-    getProtocolStats(): Promise<ProtocolStats>;
-    /**
-     * Get sync status of analytics workers
-     *
-     * Returns the current synchronization status of background workers
-     * that index blockchain data into the analytics database.
-     *
-     * @returns Sync status for each worker
-     *
-     * @example
-     * ```typescript
-     * const status = await sdk.analytics.getSyncStatus();
-     * if (status.protocol_sync.status === 'success') {
-     *   console.log(`Last synced at block: ${status.protocol_sync.last_block}`);
-     * }
-     * ```
-     */
-    getSyncStatus(): Promise<SyncStatusResponse>;
-    /**
-     * Get all validators with analytics data
-     *
-     * Returns a paginated list of validators with their analytics metrics
-     * including uptime, signed blocks, and staker counts.
-     *
-     * @param options - Pagination and filter options
-     * @returns Paginated list of validators
-     *
-     * @example
-     * ```typescript
-     * // Get first 20 validators
-     * const result = await sdk.analytics.getAllValidators({ limit: 20 });
-     *
-     * // Get next page
-     * const nextPage = await sdk.analytics.getAllValidators({
-     *   limit: 20,
-     *   offset: 20
-     * });
-     *
-     * // Filter by status
-     * const active = await sdk.analytics.getAllValidators({
-     *   status: 'active',
-     *   limit: 50
-     * });
-     * ```
-     */
-    getAllValidators(options?: ValidatorListOptions): Promise<ValidatorAnalyticsListResponse>;
-    /**
-     * Get top validators by uptime
-     *
-     * Returns validators sorted by uptime percentage in descending order.
-     * Useful for displaying leaderboards or finding most reliable validators.
-     *
-     * @param limit - Maximum number of validators to return (default: 10)
-     * @returns Top validators by uptime
-     *
-     * @example
-     * ```typescript
-     * // Get top 5 validators
-     * const top5 = await sdk.analytics.getTopValidators(5);
-     *
-     * top5.data.forEach((validator, index) => {
-     *   console.log(`#${index + 1}: ${validator.moniker} - ${validator.uptime}% uptime`);
-     * });
-     * ```
-     */
-    getTopValidators(limit?: number): Promise<ValidatorAnalyticsListResponse>;
-    /**
-     * Get analytics data for a specific validator
-     *
-     * Returns detailed analytics metrics for a single validator including
-     * performance statistics and current status.
-     *
-     * @param address - Validator address (with or without 0x prefix)
-     * @returns Validator analytics data
-     *
-     * @throws {ResonanceAPIError} 404 if validator not found
-     *
-     * @example
-     * ```typescript
-     * const validator = await sdk.analytics.getValidatorAnalytics('0x1234...');
-     * console.log(`${validator.moniker}: ${validator.uptime}% uptime`);
-     * console.log(`Signed: ${validator.signed_blocks}, Missed: ${validator.missed_blocks}`);
-     * ```
-     */
-    getValidatorAnalytics(address: string): Promise<ValidatorAnalytics>;
-    /**
-     * Get validator rewards with pagination
-     *
-     * Returns detailed reward and stake information for a validator.
-     * This is a heavy endpoint that MUST use pagination.
-     *
-     * @param address - Validator address (with or without 0x prefix)
-     * @param options - Pagination options (required)
-     * @returns Validator rewards, stakes, and summary
-     *
-     * @throws {ResonanceAPIError} 404 if validator not found
-     *
-     * @remarks
-     * This endpoint can return large amounts of data. Always use pagination
-     * with reasonable limit values (recommended: 50-100).
-     *
-     * @example
-     * ```typescript
-     * // Get first page of rewards
-     * const page1 = await sdk.analytics.getValidatorRewards('0x1234...', {
-     *   limit: 50,
-     *   offset: 0
-     * });
-     *
-     * console.log(`Total stakers: ${page1.summary.total_stakers}`);
-     * console.log(`Has more data: ${page1.metadata.has_more}`);
-     *
-     * // Get next page if available
-     * if (page1.metadata.has_more) {
-     *   const page2 = await sdk.analytics.getValidatorRewards('0x1234...', {
-     *     limit: 50,
-     *     offset: 50
-     *   });
-     * }
-     * ```
-     */
-    getValidatorRewards(address: string, options: PaginationOptions): Promise<ValidatorRewardsResponse>;
-    /**
-     * Get all validator rewards with automatic pagination
-     *
-     * Automatically fetches all pages of validator rewards data.
-     * Use with caution as this can make multiple API calls.
-     *
-     * @param address - Validator address (with or without 0x prefix)
-     * @param options - Batch size and safety limits
-     * @returns Complete validator rewards data
-     *
-     * @throws {ResonanceAPIError} 404 if validator not found
-     * @throws {Error} If max pages limit is reached
-     *
-     * @remarks
-     * This method will make multiple API calls. Use maxPages to prevent
-     * infinite loops or excessive API usage.
-     *
-     * @example
-     * ```typescript
-     * // Fetch all rewards with default settings
-     * const allRewards = await sdk.analytics.getAllValidatorRewards('0x1234...');
-     *
-     * // Custom batch size and limit
-     * const rewards = await sdk.analytics.getAllValidatorRewards('0x1234...', {
-     *   batchSize: 100,
-     *   maxPages: 5
-     * });
-     *
-     * console.log(`Total rewards: ${rewards.summary.total_rewards}`);
-     * console.log(`Total API calls made: ${Math.ceil(rewards.stakes.length / 100)}`);
-     * ```
-     */
-    getAllValidatorRewards(address: string, options?: {
-        batchSize?: number;
-        maxPages?: number;
-    }): Promise<ValidatorRewardsResponse>;
+declare const ErrorCode: {
+    readonly VALIDATOR_NOT_FOUND: "VALIDATOR_NOT_FOUND";
+    readonly VALIDATOR_INACTIVE: "VALIDATOR_INACTIVE";
+    readonly DELEGATOR_NOT_FOUND: "DELEGATOR_NOT_FOUND";
+    readonly NOT_WHITELISTED: "NOT_WHITELISTED";
+    readonly REFERRAL_KEY_INVALID: "REFERRAL_KEY_INVALID";
+    readonly REFERRAL_KEY_EXPIRED: "REFERRAL_KEY_EXPIRED";
+    readonly REFERRAL_KEY_USED: "REFERRAL_KEY_USED";
+    readonly INVALID_SIGNATURE: "INVALID_SIGNATURE";
+    readonly NONCE_EXPIRED: "NONCE_EXPIRED";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly RPC_UNAVAILABLE: "RPC_UNAVAILABLE";
+    readonly CACHE_UNAVAILABLE: "CACHE_UNAVAILABLE";
+    readonly DATABASE_UNAVAILABLE: "DATABASE_UNAVAILABLE";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+};
+type ErrorCodeType = typeof ErrorCode[keyof typeof ErrorCode];
+/**
+ * API Error response structure from Resonance API
+ */
+interface APIErrorResponse {
+    code: string;
+    message: string;
+    details?: any;
 }
-
 /**
- * Resonance Network SDK
- *
- * Main SDK class that provides access to all API endpoints
- *
- * @example
- * ```typescript
- * import { ResonanceSDK } from '@avenbreaks/resonance-sdk';
- *
- * const sdk = new ResonanceSDK({
- *   apiUrl: 'https://api.resonance.network'
- * });
- *
- * // Get global network stats
- * const stats = await sdk.global.getStats();
- *
- * // Get validator details
- * const validator = await sdk.validators.get('0x1234...');
- *
- * // Get analytics data (from subgraph)
- * const analytics = await sdk.analytics.getProtocolStats();
- * const topValidators = await sdk.analytics.getTopValidators(10);
- * ```
+ * ResonanceError represents a structured error from the Resonance API
  */
-declare class ResonanceSDK {
-    private client;
-    auth: AuthService;
-    validators: ValidatorsAPI;
-    delegators: DelegatorsAPI;
-    referrals: ReferralsAPI;
-    global: GlobalAPI;
-    slashing: SlashingAPI;
-    analytics: AnalyticsAPI;
-    constructor(config: SDKConfig);
-    /**
-     * Set authentication token for API requests
-     * @param token - JWT token
-     */
-    setAuthToken(token: string | null): void;
-    /**
-     * Set custom header for API requests
-     * @param key - Header key
-     * @param value - Header value
-     */
-    setHeader(key: string, value: string): void;
-    /**
-     * Get the current auth token from storage
-     */
-    getAuthToken(): string | null;
+declare class ResonanceError extends Error {
+    readonly code: string;
+    readonly details?: any;
+    readonly statusCode?: number;
+    constructor(code: string, message: string, details?: any, statusCode?: number);
     /**
-     * Check if user is authenticated
+     * Check if this is a specific error code
      */
-    isAuthenticated(): boolean;
+    is(code: ErrorCodeType): boolean;
     /**
-     * Logout user and clear auth token
+     * Convert to JSON representation
      */
-    logout(): void;
+    toJSON(): APIErrorResponse;
 }
+/**
+ * Type guard to check if an error is a ResonanceError
+ */
+declare function isResonanceError(error: unknown): error is ResonanceError;
+/**
+ * Type guard to check if an error has a specific error code
+ */
+declare function hasErrorCode(error: unknown, code: ErrorCodeType): boolean;
+/**
+ * Check if error is a network/connectivity error
+ */
+declare function isNetworkError(error: unknown): boolean;
+/**
+ * Check if error is an authentication error
+ */
+declare function isAuthError(error: unknown): boolean;
+/**
+ * Check if error is a not found error
+ */
+declare function isNotFoundError(error: unknown): boolean;
 
-export { type APIError, type APIResponse, type ActiveValidator, AnalyticsAPI, type AuthResponse, AuthService, type DelegatorDetailResponse, type DelegatorListResponse, type DelegatorReward, type DelegatorRewardsResponse, type DelegatorStakeInfo, type DelegatorStakesResponse, type DelegatorUnbondingResponse, type DelegatorValidatorStake, type DelegatorValidatorsResponse, type DelegatorWithdrawal, type DelegatorWithdrawalsResponse, DelegatorsAPI, type EpochDistribution, type EpochReward, type EpochStakes, type EpochUnclaimed, GlobalAPI, type GlobalNetworkResponse, HTTPClient, type JWTClaims, type LeaderboardDelegatorResponse, type LeaderboardValidatorResponse, type NetworkAPRBreakdownResponse, type NetworkAPRResponse, type PaginationOptions, type ProtocolStats, type QueryParams, type ReferralApplyRequest, type ReferralCreateRequest, type ReferralDelegatorResponse, type ReferralValidateRequest, type ReferralValidateResponse, type ReferralValidatorResponse, ReferralsAPI, ResonanceSDK, type ResponseMetadata, type RewardDTO, type RewardSummary, type SDKConfig, SlashingAPI, type SlashingEventResponse, type StakeDTO, type SyncJobStatus, type SyncStatusResponse, type TopDelegatorRank, type UnbondingInfo, type UnclaimedDelegator, type ValidatorAPRResponse, type ValidatorAnalytics, type ValidatorAnalyticsListResponse, type ValidatorDelegatorsResponse, type ValidatorDetailResponse, type ValidatorEpochResponse, type ValidatorHistoryItem, type ValidatorHistoryResponse, type ValidatorListOptions, type ValidatorListResponse, type ValidatorMetricsResponse, type ValidatorRewardsResponse, type ValidatorStakeBreakdownResponse, type ValidatorWithdrawal, type ValidatorWithdrawalsResponse, ValidatorsAPI, ResonanceSDK as default };
+export { type APIErrorResponse, type Address, type AuthResponse, type AvatarResponse, type DailyBlockStats, type Delegator, type DelegatorRewards, type DelegatorStake, DelegatorStatus, type EpochInfo, ErrorCode, type ErrorCodeType, type GeoNode, type GeoStats, type GeoUpdateRequest, type NetworkAPR, type NetworkStats, type NonceResponse, type PaginatedResponse, type ReferralKey, type RequestContext, ResonanceClient, type ResonanceClientConfig, ResonanceError, type ResponseContext, type RewardHistory, type UploadResponse, type Validator, type ValidatorAPR, ValidatorStatus, type ValidatorSummary, type WhitelistCheckRequest, type WhitelistCheckResponse, createResonanceClient, hasErrorCode, isAuthError, isNetworkError, isNotFoundError, isResonanceError };