/**
 * @file wallet.h
 * @brief Synor Wallet SDK for C
 *
 * Provides key management, transaction signing, and balance queries
 * for the Synor blockchain.
 *
 * @example
 * ```c
 * #include <synor/wallet.h>
 *
 * int main() {
 *     synor_wallet_config_t config = {
 *         .api_key = "your-api-key",
 *         .endpoint = "https://wallet.synor.io/v1",
 *         .network = SYNOR_NETWORK_MAINNET,
 *         .timeout_ms = 30000,
 *         .retries = 3
 *     };
 *
 *     synor_wallet_t* wallet = synor_wallet_create(&config);
 *     if (!wallet) {
 *         fprintf(stderr, "Failed to create wallet client\n");
 *         return 1;
 *     }
 *
 *     synor_create_wallet_result_t result;
 *     synor_error_t err = synor_wallet_create_wallet(wallet, SYNOR_WALLET_STANDARD, &result);
 *     if (err == SYNOR_OK) {
 *         printf("Wallet ID: %s\n", result.wallet.id);
 *         printf("Mnemonic: %s\n", result.mnemonic);
 *         synor_create_wallet_result_free(&result);
 *     }
 *
 *     synor_wallet_destroy(wallet);
 *     return 0;
 * }
 * ```
 */

#ifndef SYNOR_WALLET_H
#define SYNOR_WALLET_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Error codes */
typedef enum {
    SYNOR_OK = 0,
    SYNOR_ERROR_INVALID_ARGUMENT,
    SYNOR_ERROR_OUT_OF_MEMORY,
    SYNOR_ERROR_NETWORK,
    SYNOR_ERROR_HTTP,
    SYNOR_ERROR_JSON_PARSE,
    SYNOR_ERROR_TIMEOUT,
    SYNOR_ERROR_AUTH,
    SYNOR_ERROR_NOT_FOUND,
    SYNOR_ERROR_UNKNOWN
} synor_error_t;

/* Network types */
typedef enum {
    SYNOR_NETWORK_MAINNET = 0,
    SYNOR_NETWORK_TESTNET,
    SYNOR_NETWORK_DEVNET
} synor_network_t;

/* Wallet types */
typedef enum {
    SYNOR_WALLET_STANDARD = 0,
    SYNOR_WALLET_MULTISIG,
    SYNOR_WALLET_HARDWARE,
    SYNOR_WALLET_STEALTH
} synor_wallet_type_t;

/* Priority types */
typedef enum {
    SYNOR_PRIORITY_LOW = 0,
    SYNOR_PRIORITY_MEDIUM,
    SYNOR_PRIORITY_HIGH
} synor_priority_t;

/* Configuration */
typedef struct {
    const char* api_key;
    const char* endpoint;       /* Default: "https://wallet.synor.io/v1" */
    synor_network_t network;    /* Default: SYNOR_NETWORK_MAINNET */
    uint32_t timeout_ms;        /* Default: 30000 */
    uint32_t retries;           /* Default: 3 */
    bool debug;                 /* Default: false */
} synor_wallet_config_t;

/* Opaque wallet client handle */
typedef struct synor_wallet synor_wallet_t;

/* Address structure */
typedef struct {
    char* address;
    int32_t index;
    bool is_change;
} synor_address_t;

/* Wallet structure */
typedef struct {
    char* id;
    synor_wallet_type_t type;
    synor_network_t network;
    synor_address_t* addresses;
    size_t address_count;
    char* created_at;
} synor_wallet_info_t;

/* Stealth address */
typedef struct {
    char* spend_public_key;
    char* view_public_key;
    char* one_time_address;
} synor_stealth_address_t;

/* Create wallet result */
typedef struct {
    synor_wallet_info_t wallet;
    char* mnemonic;  /* May be NULL for hardware wallets */
} synor_create_wallet_result_t;

/* Transaction input */
typedef struct {
    char* txid;
    int32_t vout;
    int64_t amount;
} synor_tx_input_t;

/* Transaction output */
typedef struct {
    char* address;
    int64_t amount;
} synor_tx_output_t;

/* Transaction for signing */
typedef struct {
    synor_tx_input_t* inputs;
    size_t input_count;
    synor_tx_output_t* outputs;
    size_t output_count;
    int64_t fee;  /* 0 for auto-calculate */
    synor_priority_t priority;
} synor_transaction_t;

/* Signed transaction */
typedef struct {
    char* txid;
    char* hex;
    int32_t size;
    int64_t fee;
} synor_signed_tx_t;

/* Signature */
typedef struct {
    char* signature;
    char* address;
    int32_t recovery_id;  /* -1 if not applicable */
} synor_signature_t;

/* UTXO */
typedef struct {
    char* txid;
    int32_t vout;
    int64_t amount;
    char* address;
    int32_t confirmations;
    char* script_pubkey;  /* May be NULL */
} synor_utxo_t;

/* Balance */
typedef struct {
    int64_t confirmed;
    int64_t unconfirmed;
    int64_t total;
} synor_balance_t;

/* UTXO list */
typedef struct {
    synor_utxo_t* utxos;
    size_t count;
} synor_utxo_list_t;

/**
 * Create a new wallet client.
 *
 * @param config Configuration options
 * @return Wallet client handle, or NULL on failure
 */
synor_wallet_t* synor_wallet_create(const synor_wallet_config_t* config);

/**
 * Destroy wallet client and free resources.
 *
 * @param wallet Wallet client handle
 */
void synor_wallet_destroy(synor_wallet_t* wallet);

/**
 * Create a new wallet.
 *
 * @param wallet Wallet client handle
 * @param type Type of wallet to create
 * @param result Output parameter for result
 * @return Error code
 */
synor_error_t synor_wallet_create_wallet(
    synor_wallet_t* wallet,
    synor_wallet_type_t type,
    synor_create_wallet_result_t* result
);

/**
 * Import a wallet from mnemonic.
 *
 * @param wallet Wallet client handle
 * @param mnemonic 12 or 24 word mnemonic phrase
 * @param passphrase Optional BIP39 passphrase (can be NULL)
 * @param result Output parameter for wallet info
 * @return Error code
 */
synor_error_t synor_wallet_import(
    synor_wallet_t* wallet,
    const char* mnemonic,
    const char* passphrase,
    synor_wallet_info_t* result
);

/**
 * Get a wallet by ID.
 *
 * @param wallet Wallet client handle
 * @param wallet_id Wallet ID
 * @param result Output parameter for wallet info
 * @return Error code
 */
synor_error_t synor_wallet_get(
    synor_wallet_t* wallet,
    const char* wallet_id,
    synor_wallet_info_t* result
);

/**
 * Generate a new address for a wallet.
 *
 * @param wallet Wallet client handle
 * @param wallet_id Wallet ID
 * @param is_change Whether this is a change address
 * @param result Output parameter for address
 * @return Error code
 */
synor_error_t synor_wallet_generate_address(
    synor_wallet_t* wallet,
    const char* wallet_id,
    bool is_change,
    synor_address_t* result
);

/**
 * Get a stealth address for privacy transactions.
 *
 * @param wallet Wallet client handle
 * @param wallet_id Wallet ID
 * @param result Output parameter for stealth address
 * @return Error code
 */
synor_error_t synor_wallet_get_stealth_address(
    synor_wallet_t* wallet,
    const char* wallet_id,
    synor_stealth_address_t* result
);

/**
 * Sign a transaction.
 *
 * @param wallet Wallet client handle
 * @param wallet_id Wallet ID to sign with
 * @param transaction Transaction to sign
 * @param result Output parameter for signed transaction
 * @return Error code
 */
synor_error_t synor_wallet_sign_transaction(
    synor_wallet_t* wallet,
    const char* wallet_id,
    const synor_transaction_t* transaction,
    synor_signed_tx_t* result
);

/**
 * Sign a message.
 *
 * @param wallet Wallet client handle
 * @param wallet_id Wallet ID
 * @param message Message to sign
 * @param address_index Address index to use for signing
 * @param result Output parameter for signature
 * @return Error code
 */
synor_error_t synor_wallet_sign_message(
    synor_wallet_t* wallet,
    const char* wallet_id,
    const char* message,
    int32_t address_index,
    synor_signature_t* result
);

/**
 * Verify a message signature.
 *
 * @param wallet Wallet client handle
 * @param message Original message
 * @param signature Signature to verify
 * @param address Address that signed the message
 * @param is_valid Output parameter for validity
 * @return Error code
 */
synor_error_t synor_wallet_verify_message(
    synor_wallet_t* wallet,
    const char* message,
    const char* signature,
    const char* address,
    bool* is_valid
);

/**
 * Get balance for an address.
 *
 * @param wallet Wallet client handle
 * @param address Address to query
 * @param result Output parameter for balance
 * @return Error code
 */
synor_error_t synor_wallet_get_balance(
    synor_wallet_t* wallet,
    const char* address,
    synor_balance_t* result
);

/**
 * Get UTXOs for an address.
 *
 * @param wallet Wallet client handle
 * @param address Address to query
 * @param min_confirmations Minimum confirmations required
 * @param result Output parameter for UTXO list
 * @return Error code
 */
synor_error_t synor_wallet_get_utxos(
    synor_wallet_t* wallet,
    const char* address,
    int32_t min_confirmations,
    synor_utxo_list_t* result
);

/**
 * Estimate transaction fee.
 *
 * @param wallet Wallet client handle
 * @param priority Transaction priority
 * @param fee_per_byte Output parameter for fee per byte
 * @return Error code
 */
synor_error_t synor_wallet_estimate_fee(
    synor_wallet_t* wallet,
    synor_priority_t priority,
    int64_t* fee_per_byte
);

/* Free functions */
void synor_address_free(synor_address_t* addr);
void synor_wallet_info_free(synor_wallet_info_t* info);
void synor_stealth_address_free(synor_stealth_address_t* addr);
void synor_create_wallet_result_free(synor_create_wallet_result_t* result);
void synor_signed_tx_free(synor_signed_tx_t* tx);
void synor_signature_free(synor_signature_t* sig);
void synor_utxo_free(synor_utxo_t* utxo);
void synor_utxo_list_free(synor_utxo_list_t* list);

/**
 * Get error message for error code.
 *
 * @param error Error code
 * @return Static string describing the error
 */
const char* synor_error_message(synor_error_t error);

#ifdef __cplusplus
}
#endif

#endif /* SYNOR_WALLET_H */
