@fenelabs/fene-sdk 0.3.2 → 0.3.3

package/dist/index.d.ts

@@ -1,1247 +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 ValidatorAPR {
+    network_apr: number;
+    validator_apr: number;
+    delegator_apr: number;
 }
-interface QueryParams {
-    [key: string]: string | number | boolean | undefined;
+interface UploadResponse {
+    success: boolean;
+    key: string;
+    size: 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 AvatarResponse {
+    url: string | null;
 }
-interface ValidatorAnalyticsListResponse {
-    count: number;
-    data: ValidatorAnalytics[];
+interface DailyBlockStats {
+    date: string;
+    blocks: number;
+    transactions: number;
+    gas: number;
 }
-interface ProtocolStats {
-    Admin: string;
-    IsPaused: boolean;
-    TotalStaking: string;
-    TotalValidators: string;
-    ActiveValidators: string;
-    JailedValidators: string;
-    TotalRewardsDistributed: string;
-    TotalSlashed: string;
-    LastSyncedAt: string;
-    SubgraphIndexingBlock: 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';
+    timestamp: string;
 }
 
-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;
-}
-
-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;
-}
+    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;
 
-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[]>;
+/**
+ * Error codes matching the Resonance API error system
+ */
+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;
 }
-
 /**
- * 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 }
- * );
- * ```
+ * ResonanceError represents a structured error from the Resonance API
  */
-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>;
+declare class ResonanceError extends Error {
+    readonly code: string;
+    readonly details?: any;
+    readonly statusCode?: number;
+    constructor(code: string, message: string, details?: any, statusCode?: number);
     /**
-     * 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}`);
-     * ```
+     * Check if this is a specific error code
      */
-    getValidatorAnalytics(address: string): Promise<ValidatorAnalytics>;
+    is(code: ErrorCodeType): boolean;
     /**
-     * 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
-     *   });
-     * }
-     * ```
+     * Convert to JSON representation
      */
-    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>;
+    toJSON(): APIErrorResponse;
 }
-
-/**
- * Analytics Helper Utilities
- *
- * Provides utility functions for working with analytics data,
- * including error checking, data validation, and freshness checks.
- */
-/**
- * Check if error is a validator not found error
- *
- * @param error - Error object to check
- * @returns True if validator was not found
- *
- * @example
- * ```typescript
- * try {
- *   const validator = await sdk.analytics.getValidatorAnalytics(address);
- * } catch (error) {
- *   if (isValidatorNotFound(error)) {
- *     console.log('Validator does not exist');
- *   }
- * }
- * ```
- */
-declare function isValidatorNotFound(error: any): boolean;
-/**
- * Check if error is a service unavailable error (sync in progress)
- *
- * @param error - Error object to check
- * @returns True if service is temporarily unavailable
- *
- * @example
- * ```typescript
- * try {
- *   const stats = await sdk.analytics.getProtocolStats();
- * } catch (error) {
- *   if (isServiceUnavailable(error)) {
- *     console.log('Analytics service is syncing, try again later');
- *   }
- * }
- * ```
- */
-declare function isServiceUnavailable(error: any): boolean;
-/**
- * Check if error is a timeout error
- *
- * @param error - Error object to check
- * @returns True if request timed out
- *
- * @example
- * ```typescript
- * try {
- *   const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 1000 });
- * } catch (error) {
- *   if (isTimeout(error)) {
- *     console.log('Request timed out, try with smaller limit');
- *   }
- * }
- * ```
- */
-declare function isTimeout(error: any): boolean;
-/**
- * Check if analytics data is stale
- *
- * @param response - Response with metadata
- * @returns True if data is marked as stale
- *
- * @example
- * ```typescript
- * const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
- * if (isStaleData(rewards)) {
- *   console.warn('Data may be outdated');
- * }
- * ```
- */
-declare function isStaleData(response: ValidatorRewardsResponse): boolean;
-/**
- * Check if analytics data is from cache
- *
- * @param response - Response with metadata
- * @returns True if data was served from cache
- *
- * @example
- * ```typescript
- * const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
- * if (isCachedData(rewards)) {
- *   console.log('Serving from cache');
- * }
- * ```
- */
-declare function isCachedData(response: ValidatorRewardsResponse): boolean;
-/**
- * Check if sync worker is healthy
- *
- * @param syncStatus - Sync status response
- * @param workerName - Worker name to check ('protocol_sync' or 'validator_sync')
- * @returns True if worker is in success state
- *
- * @example
- * ```typescript
- * const status = await sdk.analytics.getSyncStatus();
- * if (isSyncHealthy(status, 'protocol_sync')) {
- *   console.log('Protocol sync is healthy');
- * }
- * ```
- */
-declare function isSyncHealthy(syncStatus: SyncStatusResponse, workerName?: 'protocol_sync' | 'validator_sync'): boolean;
-/**
- * Check if sync worker is degraded
- *
- * @param syncStatus - Sync status response
- * @param workerName - Worker name to check
- * @returns True if worker is in degraded state
- *
- * @example
- * ```typescript
- * const status = await sdk.analytics.getSyncStatus();
- * if (isSyncDegraded(status, 'protocol_sync')) {
- *   console.warn('Protocol sync is degraded, some data may be incomplete');
- * }
- * ```
- */
-declare function isSyncDegraded(syncStatus: SyncStatusResponse, workerName?: 'protocol_sync' | 'validator_sync'): boolean;
-/**
- * Get sync lag in blocks
- *
- * @param syncStatus - Sync status response
- * @param currentBlock - Current blockchain block number
- * @param workerName - Worker name to check
- * @returns Number of blocks behind, or null if unknown
- *
- * @example
- * ```typescript
- * const status = await sdk.analytics.getSyncStatus();
- * const currentBlock = await provider.getBlockNumber();
- * const lag = getSyncLag(status, currentBlock);
- * if (lag && lag > 100) {
- *   console.warn(`Analytics is ${lag} blocks behind`);
- * }
- * ```
- */
-declare function getSyncLag(syncStatus: SyncStatusResponse, currentBlock: number, workerName?: 'protocol_sync' | 'validator_sync'): number | null;
 /**
- * Calculate data freshness score (0-100)
- *
- * @param response - Response with metadata
- * @param currentBlock - Current blockchain block number
- * @returns Freshness score (100 = perfectly fresh, 0 = very stale)
- *
- * @remarks
- * Score calculation:
- * - 100: Data is from current block
- * - 90-99: Data is 1-10 blocks behind
- * - 50-89: Data is 11-100 blocks behind
- * - 0-49: Data is >100 blocks behind
- *
- * @example
- * ```typescript
- * const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
- * const currentBlock = await provider.getBlockNumber();
- * const freshness = getDataFreshness(rewards, currentBlock);
- *
- * if (freshness < 50) {
- *   console.warn('Data is very stale');
- * } else if (freshness < 90) {
- *   console.log('Data is slightly behind');
- * } else {
- *   console.log('Data is fresh');
- * }
- * ```
+ * Type guard to check if an error is a ResonanceError
  */
-declare function getDataFreshness(response: ValidatorRewardsResponse, currentBlock: number): number;
+declare function isResonanceError(error: unknown): error is ResonanceError;
 /**
- * Validate pagination options
- *
- * @param limit - Limit value
- * @param offset - Offset value
- * @throws Error if pagination options are invalid
- *
- * @example
- * ```typescript
- * try {
- *   validatePagination(50, 0);
- *   const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50, offset: 0 });
- * } catch (error) {
- *   console.error('Invalid pagination:', error.message);
- * }
- * ```
+ * Type guard to check if an error has a specific error code
  */
-declare function validatePagination(limit?: number, offset?: number): void;
+declare function hasErrorCode(error: unknown, code: ErrorCodeType): boolean;
 /**
- * Calculate optimal batch size for pagination
- *
- * @param totalItems - Total number of items to fetch
- * @param maxBatchSize - Maximum batch size (default: 100)
- * @returns Optimal batch size
- *
- * @example
- * ```typescript
- * const totalStakers = 250;
- * const batchSize = getOptimalBatchSize(totalStakers);
- * // Returns 50 (250 / 5 batches)
- * ```
+ * Check if error is a network/connectivity error
  */
-declare function getOptimalBatchSize(totalItems: number, maxBatchSize?: number): number;
+declare function isNetworkError(error: unknown): boolean;
 /**
- * Format large numbers with commas
- *
- * @param value - Number or string to format
- * @returns Formatted string with commas
- *
- * @example
- * ```typescript
- * const staking = stats.TotalStaking;
- * console.log(formatNumber(staking)); // "26,883,345,073,055,930,973,683,712"
- * ```
+ * Check if error is an authentication error
  */
-declare function formatNumber(value: string | number): string;
+declare function isAuthError(error: unknown): boolean;
 /**
- * Convert Wei to Ether string
- *
- * @param wei - Wei amount as string
- * @param decimals - Number of decimal places (default: 4)
- * @returns Ether amount as string
- *
- * @example
- * ```typescript
- * const stake = "4000000000000000000000000";
- * console.log(weiToEther(stake)); // "4000000.0000"
- * ```
+ * Check if error is a not found error
  */
-declare function weiToEther(wei: string, decimals?: number): string;
-
-/**
- * Retry Utilities
- *
- * Provides retry logic with exponential backoff for handling
- * transient errors and timeouts.
- */
-interface RetryOptions {
-    /**
-     * Maximum number of retry attempts
-     * @default 3
-     */
-    maxRetries?: number;
-    /**
-     * Initial delay in milliseconds before first retry
-     * @default 1000
-     */
-    initialDelay?: number;
-    /**
-     * Maximum delay in milliseconds between retries
-     * @default 10000
-     */
-    maxDelay?: number;
-    /**
-     * Backoff multiplier for exponential backoff
-     * @default 2
-     */
-    backoffMultiplier?: number;
-    /**
-     * Function to determine if error should be retried
-     * @default Retries on timeout and 503 errors
-     */
-    shouldRetry?: (error: any, attempt: number) => boolean;
-    /**
-     * Callback called before each retry
-     */
-    onRetry?: (error: any, attempt: number, delay: number) => void;
-}
-/**
- * Execute a function with retry logic
- *
- * @param fn - Async function to execute
- * @param options - Retry options
- * @returns Promise resolving to function result
- *
- * @example
- * ```typescript
- * const result = await withRetry(
- *   () => sdk.analytics.getValidatorRewards(address, { limit: 100 }),
- *   {
- *     maxRetries: 3,
- *     initialDelay: 1000,
- *     onRetry: (error, attempt, delay) => {
- *       console.log(`Retry attempt ${attempt} after ${delay}ms`);
- *     }
- *   }
- * );
- * ```
- */
-declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
-/**
- * Create a retry wrapper for a function
- *
- * @param fn - Function to wrap
- * @param options - Retry options
- * @returns Wrapped function with retry logic
- *
- * @example
- * ```typescript
- * const getRewardsWithRetry = createRetryWrapper(
- *   (address: string, opts: any) => sdk.analytics.getValidatorRewards(address, opts),
- *   { maxRetries: 3 }
- * );
- *
- * const rewards = await getRewardsWithRetry(address, { limit: 50 });
- * ```
- */
-declare function createRetryWrapper<T extends (...args: any[]) => Promise<any>>(fn: T, options?: RetryOptions): T;
-
-/**
- * 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);
- * ```
- */
-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;
-    /**
-     * Check if user is authenticated
-     */
-    isAuthenticated(): boolean;
-    /**
-     * Logout user and clear auth token
-     */
-    logout(): void;
-}
+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 RetryOptions, 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, createRetryWrapper, ResonanceSDK as default, formatNumber, getDataFreshness, getOptimalBatchSize, getSyncLag, isCachedData, isServiceUnavailable, isStaleData, isSyncDegraded, isSyncHealthy, isTimeout, isValidatorNotFound, validatePagination, weiToEther, withRetry };
+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 };