/**
 * Vaultfire Name Service (VNS) — Type Definitions
 *
 * All types used across the VNS client library.
 * Exported for use by integrators.
 */

// ── Identity & Bond Types ──────────────────────────────────────────────────────

/**
 * VNS identity type.
 *
 * - "human"    — Real person. One per wallet. No bond required.
 * - "companion"— AI companion tied to a human identity. One per human. No bond.
 * - "agent"    — AI agent registered by a developer/company. Unlimited per wallet.
 *                Requires a minimum accountability bond of 0.01 ETH.
 */
export type IdentityType = 'human' | 'companion' | 'agent';

/**
 * Bond tier for AI agents — determines trust badge and visibility in the Hub.
 *
 * | Tier     | Min ETH | Color   |
 * |----------|---------|---------|
 * | bronze   | 0.01    | #CD7F32 |
 * | silver   | 0.05    | #C0C0C0 |
 * | gold     | 0.10    | #FFD700 |
 * | platinum | 0.50    | #E5E4E2 |
 */
export type BondTier = 'bronze' | 'silver' | 'gold' | 'platinum';

// ── Core VNS Profile ──────────────────────────────────────────────────────────

/**
 * Full profile for a resolved VNS identity.
 */
export interface VNSProfile {
  /** Name without suffix (e.g. "ghostkey316") */
  name: string;
  /** Fully qualified name (e.g. "ghostkey316.vns") */
  fullName: string;
  /** Wallet address (0x...) */
  address: string;
  /** Chain(s) where this identity is registered */
  chain: 'base' | 'avalanche' | 'arbitrum' | 'polygon' | 'both';
  /** Identity type */
  identityType: IdentityType;
  /** Unix timestamp (ms) when registered */
  registeredAt?: number;
  /** Optional description / bio */
  description?: string;
  /** Trust score 0-100 (based on bond + activity) */
  trustScore?: number;
  /** Formatted bond amount (e.g. "0.1 ETH") */
  bondAmount?: string;
  /** Bond tier for agents */
  bondTier?: BondTier;
  /** Block explorer URL for this address */
  explorerUrl?: string;
  /** Whether this identity is currently active */
  isActive?: boolean;
  /** For agents: whether they have an active accountability bond */
  hasBond?: boolean;
  /** For companions: the human VNS name they are tied to */
  humanVNS?: string;
  /** For humans: their companion's VNS name */
  companionVNS?: string;
  /** Agent specialization tags (e.g. ["research", "finance"]) */
  specializations?: string[];
  /** Agent capabilities (e.g. ["nlp", "code-review"]) */
  capabilities?: string[];
  /** Whether this identity accepts x402 payments */
  acceptsPayments?: boolean;
  /** Payment address (defaults to identity address if not set) */
  paymentAddress?: string;
  /** Preferred payment currency (default: "USDC") */
  preferredCurrency?: string;
}

// ── Availability ───────────────────────────────────────────────────────────────

/**
 * Result of a name availability check.
 */
export interface VNSAvailability {
  /** Normalized name (without .vns suffix) */
  name: string;
  /** Whether the name is available to register */
  available: boolean;
  /** Address that owns the name (if taken) */
  takenBy?: string;
  /** Chain where the name is taken */
  takenOn?: 'base' | 'avalanche' | 'arbitrum' | 'polygon' | 'both';
  /** True while the check is in flight */
  checking: boolean;
  /** Error message if the check failed or name is invalid */
  error?: string;
}

// ── Registration ───────────────────────────────────────────────────────────────

/**
 * Result of a VNS name registration transaction.
 */
export interface VNSRegistrationResult {
  success: boolean;
  /** Transaction hash if successful */
  txHash?: string;
  /** Block explorer URL for the transaction */
  explorerUrl?: string;
  /** Chain the transaction was submitted on */
  chain?: 'base' | 'avalanche' | 'arbitrum' | 'polygon';
  /** Human-readable status message */
  message: string;
  /** Structured error type for programmatic handling */
  errorType?:
    | 'no_wallet'
    | 'no_gas'
    | 'name_taken'
    | 'invalid_name'
    | 'tx_failed'
    | 'rpc_error'
    | 'already_registered'
    | 'bond_required'
    | 'companion_exists';
}

// ── Gas Estimation ─────────────────────────────────────────────────────────────

/**
 * Gas estimate for a VNS registration transaction.
 */
export interface VNSGasEstimate {
  /** Estimated gas units */
  gasLimit: bigint;
  /** Gas price in wei */
  gasPriceWei: bigint;
  /** Total fee = gasLimit × gasPriceWei */
  totalFeeWei: bigint;
  /** Human-readable fee (e.g. "0.000042") */
  totalFeeFormatted: string;
  /** Chain for this estimate */
  chain: 'base' | 'avalanche' | 'arbitrum' | 'polygon';
  /** Human-readable chain name */
  chainName: string;
  /** Native token symbol for gas (ETH or AVAX) */
  gasSymbol: string;
}

// ── Agent Registration ─────────────────────────────────────────────────────────

/**
 * Parameters for full agent registration (identity + bond + VNS).
 */
export interface AgentRegistrationParams {
  /** Desired VNS name (without .vns suffix) */
  vnsName: string;
  /** Agent description (max 200 chars stored on-chain) */
  description: string;
  /** Specialization tags */
  specializations: string[];
  /** Capability tags */
  capabilities: string[];
  /** Bond amount in ETH (min 0.01) */
  bondAmountEth: number;
  /** Chain to register on */
  chain: 'base' | 'avalanche' | 'arbitrum' | 'polygon';
}

/**
 * Result for each step of a multi-step agent launch.
 */
export interface AgentLaunchResult {
  /** Which registration step this result covers */
  step: 'identity' | 'bond' | 'vns' | 'release';
  success: boolean;
  txHash?: string;
  explorerUrl?: string;
  message: string;
  errorType?: string;
}

// ── Local Registry ─────────────────────────────────────────────────────────────

/**
 * Entry in the local VNS registry (localStorage-backed cache).
 * Supplements on-chain data with enriched metadata.
 */
export interface LocalVNSEntry {
  address: string;
  chain: string;
  identityType: IdentityType;
  /** Unix timestamp (ms) of registration */
  registeredAt: number;
  /** Transaction hash of the registration tx */
  txHash?: string;
  bondTier?: BondTier;
  hasBond?: boolean;
  specializations?: string[];
  capabilities?: string[];
  /** For companions: the human VNS name they belong to */
  humanVNS?: string;
  /** Whether this identity accepts x402 payments */
  acceptsPayments?: boolean;
  /** Payment address override */
  paymentAddress?: string;
  /** Preferred payment currency (default: USDC) */
  preferredCurrency?: string;
}

// ── Registered Agent (Hub) ─────────────────────────────────────────────────────

/**
 * Enriched agent record used in the Vaultfire Hub agent directory.
 */
export interface RegisteredAgent {
  name: string;
  fullName: string;
  address: string;
  chain: 'base' | 'avalanche' | 'arbitrum' | 'polygon' | 'both';
  identityType: IdentityType;
  description?: string;
  bondAmount?: string;
  bondTier?: BondTier;
  hasBond?: boolean;
  registeredAt?: number;
  /** Whether this agent is currently online */
  online?: boolean;
  specializations?: string[];
  capabilities?: string[];
  tasksCompleted?: number;
  trustScore?: number;
  acceptsPayments?: boolean;
  paymentAddress?: string;
  preferredCurrency?: string;
}

// ── Hub Stats ──────────────────────────────────────────────────────────────────

/**
 * Live on-chain Hub statistics.
 * All numbers sourced directly from contract state — no hardcoded values.
 */
export interface OnChainHubStats {
  totalIdentities: number;
  activeBonds: number;
  totalBondedEth: number;
  totalBondedAvax: number;
  chainCounts: Record<'base' | 'avalanche' | 'arbitrum' | 'polygon', number>;
}
