key_wallet_ffi.h

/**
 * Key Wallet FFI - C Header File
 * 
 * This header provides C-compatible function declarations for the key-wallet
 * Rust library FFI bindings.
 * 
 * AUTO-GENERATED FILE - DO NOT EDIT
 * Generated using cbindgen
 */

#ifndef KEY_WALLET_FFI_H
#define KEY_WALLET_FFI_H

/* Generated with cbindgen:0.29.0 */

/* Warning: This file is auto-generated by cbindgen. Do not modify manually. */

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

/*
 FFI Account Creation Option Type
 */
typedef enum {
    /*
     Create default accounts (BIP44 account 0, CoinJoin account 0, and special accounts)
     */
    DEFAULT = 0,
    /*
     Create all specified accounts plus all special purpose accounts
     */
    ALL_ACCOUNTS = 1,
    /*
     Create only BIP44 accounts (no CoinJoin or special accounts)
     */
    BIP44_ACCOUNTS_ONLY = 2,
    /*
     Create specific accounts with full control
     */
    SPECIFIC_ACCOUNTS = 3,
    /*
     Create no accounts at all
     */
    NO_ACCOUNTS = 4,
} FFIAccountCreationOptionType;

/*
 Account type enumeration matching all key_wallet AccountType variants

 This enum provides a complete FFI representation of all account types
 supported by the key_wallet library:

 - Standard accounts: BIP44 and BIP32 variants for regular transactions
 - CoinJoin: Privacy-enhanced transactions
 - Identity accounts: Registration, top-up, and invitation funding
 - Provider accounts: Various masternode provider key types (voting, owner, operator, platform)
 */
typedef enum {
    /*
     Standard BIP44 account (m/44'/coin_type'/account'/x/x)
     */
    STANDARD_BIP44 = 0,
    /*
     Standard BIP32 account (m/account'/x/x)
     */
    STANDARD_BIP32 = 1,
    /*
     CoinJoin account for private transactions
     */
    COIN_JOIN = 2,
    /*
     Identity registration funding
     */
    IDENTITY_REGISTRATION = 3,
    /*
     Identity top-up funding (requires registration_index)
     */
    IDENTITY_TOP_UP = 4,
    /*
     Identity top-up funding not bound to a specific identity
     */
    IDENTITY_TOP_UP_NOT_BOUND_TO_IDENTITY = 5,
    /*
     Identity invitation funding
     */
    IDENTITY_INVITATION = 6,
    /*
     Provider voting keys (DIP-3) - Path: m/9'/5'/3'/1'/[key_index]
     */
    PROVIDER_VOTING_KEYS = 7,
    /*
     Provider owner keys (DIP-3) - Path: m/9'/5'/3'/2'/[key_index]
     */
    PROVIDER_OWNER_KEYS = 8,
    /*
     Provider operator keys (DIP-3) - Path: m/9'/5'/3'/3'/[key_index]
     */
    PROVIDER_OPERATOR_KEYS = 9,
    /*
     Provider platform P2P keys (DIP-3, ED25519) - Path: m/9'/5'/3'/4'/[key_index]
     */
    PROVIDER_PLATFORM_KEYS = 10,
} FFIAccountType;

/*
 Address pool type
 */
typedef enum {
    /*
     External (receive) addresses
     */
    EXTERNAL = 0,
    /*
     Internal (change) addresses
     */
    INTERNAL = 1,
    /*
     Single pool (for non-standard accounts)
     */
    SINGLE = 2,
} FFIAddressPoolType;

/*
 Derivation path type for DIP9
 */
typedef enum {
    PATH_UNKNOWN = 0,
    PATH_BIP32 = 1,
    PATH_BIP44 = 2,
    PATH_BLOCKCHAIN_IDENTITIES = 3,
    PATH_PROVIDER_FUNDS = 4,
    PATH_PROVIDER_VOTING_KEYS = 5,
    PATH_PROVIDER_OPERATOR_KEYS = 6,
    PATH_PROVIDER_OWNER_KEYS = 7,
    PATH_CONTACT_BASED_FUNDS = 8,
    PATH_CONTACT_BASED_FUNDS_ROOT = 9,
    PATH_CONTACT_BASED_FUNDS_EXTERNAL = 10,
    PATH_BLOCKCHAIN_IDENTITY_CREDIT_REGISTRATION_FUNDING = 11,
    PATH_BLOCKCHAIN_IDENTITY_CREDIT_TOPUP_FUNDING = 12,
    PATH_BLOCKCHAIN_IDENTITY_CREDIT_INVITATION_FUNDING = 13,
    PATH_PROVIDER_PLATFORM_NODE_KEYS = 14,
    PATH_COIN_JOIN = 15,
    PATH_ROOT = 255,
} FFIDerivationPathType;

/*
 FFI Error code
 */
typedef enum {
    SUCCESS = 0,
    INVALID_INPUT = 1,
    ALLOCATION_FAILED = 2,
    INVALID_MNEMONIC = 3,
    INVALID_DERIVATION_PATH = 4,
    INVALID_NETWORK = 5,
    INVALID_ADDRESS = 6,
    INVALID_TRANSACTION = 7,
    WALLET_ERROR = 8,
    SERIALIZATION_ERROR = 9,
    NOT_FOUND = 10,
    INVALID_STATE = 11,
    INTERNAL_ERROR = 12,
} FFIErrorCode;

/*
 Language enumeration for mnemonic generation

 This enum must be kept in sync with key_wallet::mnemonic::Language.
 When adding new languages to the key_wallet crate, remember to update
 this FFI enum and both From implementations below.
 */
typedef enum {
    ENGLISH = 0,
    CHINESE_SIMPLIFIED = 1,
    CHINESE_TRADITIONAL = 2,
    CZECH = 3,
    FRENCH = 4,
    ITALIAN = 5,
    JAPANESE = 6,
    KOREAN = 7,
    PORTUGUESE = 8,
    SPANISH = 9,
} FFILanguage;

/*
 FFI Network type (bit flags for multiple networks)
 */
typedef enum {
    NO_NETWORKS = 0,
    DASH = 1,
    TESTNET = 2,
    REGTEST = 4,
    DEVNET = 8,
    ALL_NETWORKS = 15,
} FFINetworks;

/*
 Provider key type
 */
typedef enum {
    /*
     BLS voting keys (m/9'/5'/3'/1'/[key_index])
     */
    VOTING_KEYS = 0,
    /*
     BLS owner keys (m/9'/5'/3'/2'/[key_index])
     */
    OWNER_KEYS = 1,
    /*
     BLS operator keys (m/9'/5'/3'/3'/[key_index])
     */
    OPERATOR_KEYS = 2,
    /*
     EdDSA platform P2P keys (m/9'/5'/3'/4'/[key_index])
     */
    PLATFORM_KEYS = 3,
} FFIProviderKeyType;

/*
 Transaction context for checking
 */
typedef enum {
    /*
     Transaction is in mempool (unconfirmed)
     */
    MEMPOOL = 0,
    /*
     Transaction is in a block
     */
    IN_BLOCK = 1,
    /*
     Transaction is in a chain-locked block
     */
    IN_CHAIN_LOCKED_BLOCK = 2,
} FFITransactionContext;

/*
 Opaque account handle
 */
typedef struct FFIAccount FFIAccount;

/*
 Opaque handle to an account collection
 */
typedef struct FFIAccountCollection FFIAccountCollection;

/*
 FFI wrapper for an AddressPool from a ManagedAccount

 This is a lightweight wrapper that holds a reference to an AddressPool
 from within a ManagedAccount. It allows querying addresses and pool information.
 */
typedef struct FFIAddressPool FFIAddressPool;

/*
 Opaque BLS account handle
 */
typedef struct FFIBLSAccount FFIBLSAccount;

/*
 Opaque EdDSA account handle
 */
typedef struct FFIEdDSAAccount FFIEdDSAAccount;

/*
 Extended private key structure
 */
typedef struct FFIExtendedPrivKey FFIExtendedPrivKey;

/*
 Opaque type for an extended private key
 */
typedef struct FFIExtendedPrivateKey FFIExtendedPrivateKey;

/*
 Extended public key structure
 */
typedef struct FFIExtendedPubKey FFIExtendedPubKey;

/*
 Opaque type for an extended public key
 */
typedef struct FFIExtendedPublicKey FFIExtendedPublicKey;

/*
 Opaque managed account handle that wraps ManagedAccount
 */
typedef struct FFIManagedAccount FFIManagedAccount;

/*
 Opaque handle to a managed account collection
 */
typedef struct FFIManagedAccountCollection FFIManagedAccountCollection;

/*
 FFI wrapper for ManagedWalletInfo
 */
typedef struct FFIManagedWalletInfo FFIManagedWalletInfo;

/*
 Opaque type for a private key (SecretKey)
 */
typedef struct FFIPrivateKey FFIPrivateKey;

/*
 Opaque type for a public key
 */
typedef struct FFIPublicKey FFIPublicKey;

/*
 Opaque wallet handle
 */
typedef struct FFIWallet FFIWallet;

/*
 FFI wrapper for WalletManager
 */
typedef struct FFIWalletManager FFIWalletManager;

/*
 FFI Result type for Account operations
 */
typedef struct {
    /*
     The account handle if successful, NULL if error
     */
    FFIAccount *account;
    /*
     Error code (0 = success)
     */
    int32_t error_code;
    /*
     Error message (NULL if success, must be freed by caller if not NULL)
     */
    char *error_message;
} FFIAccountResult;

/*
 FFI Error structure
 */
typedef struct {
    FFIErrorCode code;
    char *message;
} FFIError;

/*
 C-compatible summary of all accounts in a collection

 This struct provides Swift with structured data about all accounts
 that exist in the collection, allowing programmatic access to account
 indices and presence information.
 */
typedef struct {
    /*
     Array of BIP44 account indices
     */
    unsigned int *bip44_indices;
    /*
     Number of BIP44 accounts
     */
    size_t bip44_count;
    /*
     Array of BIP32 account indices
     */
    unsigned int *bip32_indices;
    /*
     Number of BIP32 accounts
     */
    size_t bip32_count;
    /*
     Array of CoinJoin account indices
     */
    unsigned int *coinjoin_indices;
    /*
     Number of CoinJoin accounts
     */
    size_t coinjoin_count;
    /*
     Array of identity top-up registration indices
     */
    unsigned int *identity_topup_indices;
    /*
     Number of identity top-up accounts
     */
    size_t identity_topup_count;
    /*
     Whether identity registration account exists
     */
    bool has_identity_registration;
    /*
     Whether identity invitation account exists
     */
    bool has_identity_invitation;
    /*
     Whether identity top-up not bound account exists
     */
    bool has_identity_topup_not_bound;
    /*
     Whether provider voting keys account exists
     */
    bool has_provider_voting_keys;
    /*
     Whether provider owner keys account exists
     */
    bool has_provider_owner_keys;
    /*
     Whether provider operator keys account exists
     */
    bool has_provider_operator_keys;
    /*
     Whether provider platform keys account exists
     */
    bool has_provider_platform_keys;
} FFIAccountCollectionSummary;

/*
 FFI wrapper for ManagedWalletInfo that includes transaction checking capabilities
 */
typedef struct {
    ManagedWalletInfo *inner;

} FFIManagedWallet;

/*
 Address pool info
 */
typedef struct {
    /*
     Pool type
     */
    FFIAddressPoolType pool_type;
    /*
     Number of generated addresses
     */
    unsigned int generated_count;
    /*
     Number of used addresses
     */
    unsigned int used_count;
    /*
     Current gap (unused addresses at the end)
     */
    unsigned int current_gap;
    /*
     Gap limit setting
     */
    unsigned int gap_limit;
    /*
     Highest used index (-1 if none used)
     */
    int32_t highest_used_index;
} FFIAddressPoolInfo;

/*
 FFI-compatible version of AddressInfo
 */
typedef struct {
    /*
     Address as string
     */
    char *address;
    /*
     Script pubkey bytes
     */
    uint8_t *script_pubkey;
    /*
     Length of script pubkey
     */
    size_t script_pubkey_len;
    /*
     Public key bytes (nullable)
     */
    uint8_t *public_key;
    /*
     Length of public key
     */
    size_t public_key_len;
    /*
     Derivation index
     */
    uint32_t index;
    /*
     Derivation path as string
     */
    char *path;
    /*
     Whether address has been used
     */
    bool used;
    /*
     When generated (timestamp)
     */
    uint64_t generated_at;
    /*
     When first used (0 if never)
     */
    uint64_t used_at;
    /*
     Transaction count
     */
    uint32_t tx_count;
    /*
     Total received
     */
    uint64_t total_received;
    /*
     Total sent
     */
    uint64_t total_sent;
    /*
     Current balance
     */
    uint64_t balance;
    /*
     Custom label (nullable)
     */
    char *label;
} FFIAddressInfo;

/*
 FFI Result type for ManagedAccount operations
 */
typedef struct {
    /*
     The managed account handle if successful, NULL if error
     */
    FFIManagedAccount *account;
    /*
     Error code (0 = success)
     */
    int32_t error_code;
    /*
     Error message (NULL if success, must be freed by caller if not NULL)
     */
    char *error_message;
} FFIManagedAccountResult;

/*
 FFI Balance type for representing wallet balances
 */
typedef struct {
    /*
     Confirmed balance in duffs
     */
    uint64_t confirmed;
    /*
     Unconfirmed balance in duffs
     */
    uint64_t unconfirmed;
    /*
     Immature balance in duffs (e.g., mining rewards)
     */
    uint64_t immature;
    /*
     Total balance (confirmed + unconfirmed) in duffs
     */
    uint64_t total;
} FFIBalance;

/*
 C-compatible summary of all accounts in a managed collection

 This struct provides Swift with structured data about all accounts
 that exist in the managed collection, allowing programmatic access to account
 indices and presence information.
 */
typedef struct {
    /*
     Array of BIP44 account indices
     */
    unsigned int *bip44_indices;
    /*
     Number of BIP44 accounts
     */
    size_t bip44_count;
    /*
     Array of BIP32 account indices
     */
    unsigned int *bip32_indices;
    /*
     Number of BIP32 accounts
     */
    size_t bip32_count;
    /*
     Array of CoinJoin account indices
     */
    unsigned int *coinjoin_indices;
    /*
     Number of CoinJoin accounts
     */
    size_t coinjoin_count;
    /*
     Array of identity top-up registration indices
     */
    unsigned int *identity_topup_indices;
    /*
     Number of identity top-up accounts
     */
    size_t identity_topup_count;
    /*
     Whether identity registration account exists
     */
    bool has_identity_registration;
    /*
     Whether identity invitation account exists
     */
    bool has_identity_invitation;
    /*
     Whether identity top-up not bound account exists
     */
    bool has_identity_topup_not_bound;
    /*
     Whether provider voting keys account exists
     */
    bool has_provider_voting_keys;
    /*
     Whether provider owner keys account exists
     */
    bool has_provider_owner_keys;
    /*
     Whether provider operator keys account exists
     */
    bool has_provider_operator_keys;
    /*
     Whether provider platform keys account exists
     */
    bool has_provider_platform_keys;
} FFIManagedAccountCollectionSummary;

/*
 Provider key info
 */
typedef struct {
    /*
     Key index
     */
    unsigned int key_index;
    /*
     Public key bytes (48 bytes for BLS, 32 bytes for EdDSA)
     */
    uint8_t *public_key;
    /*
     Public key length
     */
    size_t public_key_len;
    /*
     Private key bytes (32 bytes, only if available)
     */
    uint8_t *private_key;
    /*
     Private key length (0 if not available)
     */
    size_t private_key_len;
    /*
     Derivation path as string
     */
    char *derivation_path;
} FFIProviderKeyInfo;

/*
 Transaction output for building
 */
typedef struct {
    const char *address;
    uint64_t amount;
} FFITxOutput;

/*
 Transaction check result
 */
typedef struct {
    /*
     Whether the transaction belongs to the wallet
     */
    bool is_relevant;
    /*
     Total amount received
     */
    uint64_t total_received;
    /*
     Total amount sent
     */
    uint64_t total_sent;
    /*
     Number of affected accounts
     */
    uint32_t affected_accounts_count;
} FFITransactionCheckResult;

/*
 UTXO structure for FFI
 */
typedef struct {
    uint8_t txid[32];
    uint32_t vout;
    uint64_t amount;
    char *address;
    uint8_t *script_pubkey;
    size_t script_len;
    uint32_t height;
    uint32_t confirmations;
} FFIUTXO;

/*
 FFI structure for wallet account creation options
 This single struct represents all possible account creation configurations
 */
typedef struct {
    /*
     The type of account creation option
     */
    FFIAccountCreationOptionType option_type;
    /*
     Array of BIP44 account indices to create
     */
    const uint32_t *bip44_indices;
    size_t bip44_count;
    /*
     Array of BIP32 account indices to create
     */
    const uint32_t *bip32_indices;
    size_t bip32_count;
    /*
     Array of CoinJoin account indices to create
     */
    const uint32_t *coinjoin_indices;
    size_t coinjoin_count;
    /*
     Array of identity top-up registration indices to create
     */
    const uint32_t *topup_indices;
    size_t topup_count;
    /*
     For SpecificAccounts: Additional special account types to create
     (e.g., IdentityRegistration, ProviderKeys, etc.)
     This is an array of FFIAccountType values
     */
    const FFIAccountType *special_account_types;
    size_t special_account_types_count;
} FFIWalletAccountCreationOptions;

/*
 FFI-compatible transaction context details
 */
typedef struct {
    /*
     The context type
     */
    FFITransactionContext context_type;
    /*
     Block height (0 for mempool)
     */
    unsigned int height;
    /*
     Block hash (32 bytes, null for mempool or if unknown)
     */
    const uint8_t *block_hash;
    /*
     Timestamp (0 if unknown)
     */
    unsigned int timestamp;
} FFITransactionContextDetails;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/*
 Initialize the library
 */
 bool key_wallet_ffi_initialize(void) ;

/*
 Get library version

 Returns a static string that should NOT be freed by the caller
 */
 const char *key_wallet_ffi_version(void) ;

/*
 Get an account handle for a specific account type
 Returns a result containing either the account handle or an error

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet instance
 - The caller must ensure the wallet pointer remains valid for the duration of this call
 */

FFIAccountResult wallet_get_account(const FFIWallet *wallet,
                                    FFINetworks network,
                                    unsigned int account_index,
                                    FFIAccountType account_type)
;

/*
 Get an IdentityTopUp account handle with a specific registration index
 This is used for top-up accounts that are bound to a specific identity
 Returns a result containing either the account handle or an error

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet instance
 - The caller must ensure the wallet pointer remains valid for the duration of this call
 */

FFIAccountResult wallet_get_top_up_account_with_registration_index(const FFIWallet *wallet,
                                                                   FFINetworks network,
                                                                   unsigned int registration_index)
;

/*
 Free an account handle

 # Safety

 - `account` must be a valid pointer to an FFIAccount that was allocated by this library
 - The pointer must not be used after calling this function
 - This function must only be called once per allocation
 */
 void account_free(FFIAccount *account) ;

/*
 Free a BLS account handle

 # Safety

 - `account` must be a valid pointer to an FFIBLSAccount
 - The pointer must not be used after calling this function
 - This function must only be called once per allocation
 */
 void bls_account_free(FFIBLSAccount *account) ;

/*
 Free an EdDSA account handle

 # Safety

 - `account` must be a valid pointer to an FFIEdDSAAccount
 - The pointer must not be used after calling this function
 - This function must only be called once per allocation
 */
 void eddsa_account_free(FFIEdDSAAccount *account) ;

/*
 Free an account result's error message (if any)
 Note: This does NOT free the account handle itself - use account_free for that

 # Safety

 - `result` must be a valid pointer to an FFIAccountResult
 - The error_message field must be either null or a valid CString allocated by this library
 - The caller must ensure the result pointer remains valid for the duration of this call
 */
 void account_result_free_error(FFIAccountResult *result) ;

/*
 Get the extended public key of an account as a string

 # Safety

 - `account` must be a valid pointer to an FFIAccount instance
 - The returned string must be freed by the caller using `string_free`
 - Returns NULL if the account is null
 */
 char *account_get_extended_public_key_as_string(const FFIAccount *account) ;

/*
 Get the network of an account

 # Safety

 - `account` must be a valid pointer to an FFIAccount instance
 - Returns FFINetwork::NoNetworks if the account is null
 */
 FFINetworks account_get_network(const FFIAccount *account) ;

/*
 Get the parent wallet ID of an account

 # Safety

 - `account` must be a valid pointer to an FFIAccount instance
 - Returns a pointer to the 32-byte wallet ID, or NULL if not set or account is null
 - The returned pointer is valid only as long as the account exists
 - The caller should copy the data if needed for longer use
 */
 const uint8_t *account_get_parent_wallet_id(const FFIAccount *account) ;

/*
 Get the account type of an account

 # Safety

 - `account` must be a valid pointer to an FFIAccount instance
 - `out_index` must be a valid pointer to a c_uint where the index will be stored
 - Returns FFIAccountType::StandardBIP44 with index 0 if the account is null
 */
 FFIAccountType account_get_account_type(const FFIAccount *account, unsigned int *out_index) ;

/*
 Check if an account is watch-only

 # Safety

 - `account` must be a valid pointer to an FFIAccount instance
 - Returns false if the account is null
 */
 bool account_get_is_watch_only(const FFIAccount *account) ;

/*
 Get the extended public key of a BLS account as a string

 # Safety

 - `account` must be a valid pointer to an FFIBLSAccount instance
 - The returned string must be freed by the caller using `string_free`
 - Returns NULL if the account is null
 */
 char *bls_account_get_extended_public_key_as_string(const FFIBLSAccount *account) ;

/*
 Get the network of a BLS account

 # Safety

 - `account` must be a valid pointer to an FFIBLSAccount instance
 - Returns FFINetwork::NoNetworks if the account is null
 */
 FFINetworks bls_account_get_network(const FFIBLSAccount *account) ;

/*
 Get the parent wallet ID of a BLS account

 # Safety

 - `account` must be a valid pointer to an FFIBLSAccount instance
 - Returns a pointer to the 32-byte wallet ID, or NULL if not set or account is null
 - The returned pointer is valid only as long as the account exists
 - The caller should copy the data if needed for longer use
 */
 const uint8_t *bls_account_get_parent_wallet_id(const FFIBLSAccount *account) ;

/*
 Get the account type of a BLS account

 # Safety

 - `account` must be a valid pointer to an FFIBLSAccount instance
 - `out_index` must be a valid pointer to a c_uint where the index will be stored
 - Returns FFIAccountType::StandardBIP44 with index 0 if the account is null
 */

FFIAccountType bls_account_get_account_type(const FFIBLSAccount *account,
                                            unsigned int *out_index)
;

/*
 Check if a BLS account is watch-only

 # Safety

 - `account` must be a valid pointer to an FFIBLSAccount instance
 - Returns false if the account is null
 */
 bool bls_account_get_is_watch_only(const FFIBLSAccount *account) ;

/*
 Get the extended public key of an EdDSA account as a string

 # Safety

 - `account` must be a valid pointer to an FFIEdDSAAccount instance
 - The returned string must be freed by the caller using `string_free`
 - Returns NULL if the account is null
 */
 char *eddsa_account_get_extended_public_key_as_string(const FFIEdDSAAccount *account) ;

/*
 Get the network of an EdDSA account

 # Safety

 - `account` must be a valid pointer to an FFIEdDSAAccount instance
 - Returns FFINetwork::NoNetworks if the account is null
 */
 FFINetworks eddsa_account_get_network(const FFIEdDSAAccount *account) ;

/*
 Get the parent wallet ID of an EdDSA account

 # Safety

 - `account` must be a valid pointer to an FFIEdDSAAccount instance
 - Returns a pointer to the 32-byte wallet ID, or NULL if not set or account is null
 - The returned pointer is valid only as long as the account exists
 - The caller should copy the data if needed for longer use
 */
 const uint8_t *eddsa_account_get_parent_wallet_id(const FFIEdDSAAccount *account) ;

/*
 Get the account type of an EdDSA account

 # Safety

 - `account` must be a valid pointer to an FFIEdDSAAccount instance
 - `out_index` must be a valid pointer to a c_uint where the index will be stored
 - Returns FFIAccountType::StandardBIP44 with index 0 if the account is null
 */

FFIAccountType eddsa_account_get_account_type(const FFIEdDSAAccount *account,
                                              unsigned int *out_index)
;

/*
 Check if an EdDSA account is watch-only

 # Safety

 - `account` must be a valid pointer to an FFIEdDSAAccount instance
 - Returns false if the account is null
 */
 bool eddsa_account_get_is_watch_only(const FFIEdDSAAccount *account) ;

/*
 Get number of accounts

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet instance
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure both pointers remain valid for the duration of this call
 */

unsigned int wallet_get_account_count(const FFIWallet *wallet,
                                      FFINetworks network,
                                      FFIError *error)
;

/*
 Get account collection for a specific network from wallet

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet instance
 - `error` must be a valid pointer to an FFIError structure or null
 - The returned pointer must be freed with `account_collection_free` when no longer needed
 */

FFIAccountCollection *wallet_get_account_collection(const FFIWallet *wallet,
                                                    FFINetworks network,
                                                    FFIError *error)
;

/*
 Free an account collection handle

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection created by this library
 - `collection` must not be used after calling this function
 */
 void account_collection_free(FFIAccountCollection *collection) ;

/*
 Get a BIP44 account by index from the collection

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_free` when no longer needed
 */

FFIAccount *account_collection_get_bip44_account(const FFIAccountCollection *collection,
                                                 unsigned int index)
;

/*
 Get all BIP44 account indices

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - `out_indices` must be a valid pointer to store the indices array
 - `out_count` must be a valid pointer to store the count
 - The returned array must be freed with `free_u32_array` when no longer needed
 */

bool account_collection_get_bip44_indices(const FFIAccountCollection *collection,
                                          unsigned int **out_indices,
                                          size_t *out_count)
;

/*
 Get a BIP32 account by index from the collection

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_free` when no longer needed
 */

FFIAccount *account_collection_get_bip32_account(const FFIAccountCollection *collection,
                                                 unsigned int index)
;

/*
 Get all BIP32 account indices

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - `out_indices` must be a valid pointer to store the indices array
 - `out_count` must be a valid pointer to store the count
 - The returned array must be freed with `free_u32_array` when no longer needed
 */

bool account_collection_get_bip32_indices(const FFIAccountCollection *collection,
                                          unsigned int **out_indices,
                                          size_t *out_count)
;

/*
 Get a CoinJoin account by index from the collection

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_free` when no longer needed
 */

FFIAccount *account_collection_get_coinjoin_account(const FFIAccountCollection *collection,
                                                    unsigned int index)
;

/*
 Get all CoinJoin account indices

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - `out_indices` must be a valid pointer to store the indices array
 - `out_count` must be a valid pointer to store the count
 - The returned array must be freed with `free_u32_array` when no longer needed
 */

bool account_collection_get_coinjoin_indices(const FFIAccountCollection *collection,
                                             unsigned int **out_indices,
                                             size_t *out_count)
;

/*
 Get the identity registration account if it exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_free` when no longer needed
 */
 FFIAccount *account_collection_get_identity_registration(const FFIAccountCollection *collection) ;

/*
 Check if identity registration account exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 */
 bool account_collection_has_identity_registration(const FFIAccountCollection *collection) ;

/*
 Get an identity topup account by registration index

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_free` when no longer needed
 */

FFIAccount *account_collection_get_identity_topup(const FFIAccountCollection *collection,
                                                  unsigned int registration_index)
;

/*
 Get all identity topup registration indices

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - `out_indices` must be a valid pointer to store the indices array
 - `out_count` must be a valid pointer to store the count
 - The returned array must be freed with `free_u32_array` when no longer needed
 */

bool account_collection_get_identity_topup_indices(const FFIAccountCollection *collection,
                                                   unsigned int **out_indices,
                                                   size_t *out_count)
;

/*
 Get the identity topup not bound account if it exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_free` when no longer needed
 */

FFIAccount *account_collection_get_identity_topup_not_bound(const FFIAccountCollection *collection)
;

/*
 Check if identity topup not bound account exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 */
 bool account_collection_has_identity_topup_not_bound(const FFIAccountCollection *collection) ;

/*
 Get the identity invitation account if it exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_free` when no longer needed
 */
 FFIAccount *account_collection_get_identity_invitation(const FFIAccountCollection *collection) ;

/*
 Check if identity invitation account exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 */
 bool account_collection_has_identity_invitation(const FFIAccountCollection *collection) ;

/*
 Get the provider voting keys account if it exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_free` when no longer needed
 */
 FFIAccount *account_collection_get_provider_voting_keys(const FFIAccountCollection *collection) ;

/*
 Check if provider voting keys account exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 */
 bool account_collection_has_provider_voting_keys(const FFIAccountCollection *collection) ;

/*
 Get the provider owner keys account if it exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_free` when no longer needed
 */
 FFIAccount *account_collection_get_provider_owner_keys(const FFIAccountCollection *collection) ;

/*
 Check if provider owner keys account exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 */
 bool account_collection_has_provider_owner_keys(const FFIAccountCollection *collection) ;

/*
 Get the provider operator keys account if it exists
 Note: Returns null if the `bls` feature is not enabled

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `bls_account_free` when no longer needed (when BLS is enabled)
 */

void *account_collection_get_provider_operator_keys(const FFIAccountCollection *collection)
;

/*
 Check if provider operator keys account exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 */
 bool account_collection_has_provider_operator_keys(const FFIAccountCollection *collection) ;

/*
 Get the provider platform keys account if it exists
 Note: Returns null if the `eddsa` feature is not enabled

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `eddsa_account_free` when no longer needed (when EdDSA is enabled)
 */

void *account_collection_get_provider_platform_keys(const FFIAccountCollection *collection)
;

/*
 Check if provider platform keys account exists

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 */
 bool account_collection_has_provider_platform_keys(const FFIAccountCollection *collection) ;

/*
 Free a u32 array allocated by this library

 # Safety

 - `array` must be a valid pointer to an array allocated by this library
 - `array` must not be used after calling this function
 */
 void free_u32_array(unsigned int *array, size_t count) ;

/*
 Get the total number of accounts in the collection

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 */
 unsigned int account_collection_count(const FFIAccountCollection *collection) ;

/*
 Get a human-readable summary of all accounts in the collection

 Returns a formatted string showing all account types and their indices.
 The format is designed to be clear and readable for end users.

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned string must be freed with `string_free` when no longer needed
 - Returns null if the collection pointer is null
 */
 char *account_collection_summary(const FFIAccountCollection *collection) ;

/*
 Get structured account collection summary data

 Returns a struct containing arrays of indices for each account type and boolean
 flags for special accounts. This provides Swift with programmatic access to
 account information.

 # Safety

 - `collection` must be a valid pointer to an FFIAccountCollection
 - The returned pointer must be freed with `account_collection_summary_free` when no longer needed
 - Returns null if the collection pointer is null
 */

FFIAccountCollectionSummary *account_collection_summary_data(const FFIAccountCollection *collection)
;

/*
 Free an account collection summary and all its allocated memory

 # Safety

 - `summary` must be a valid pointer to an FFIAccountCollectionSummary created by `account_collection_summary_data`
 - `summary` must not be used after calling this function
 */

void account_collection_summary_free(FFIAccountCollectionSummary *summary)
;

/*
 Free address string

 # Safety

 - `address` must be a valid pointer created by address functions or null
 - After calling this function, the pointer becomes invalid
 */
 void address_free(char *address) ;

/*
 Free address array

 # Safety

 - `addresses` must be a valid pointer to an array of address strings or null
 - Each address in the array must be a valid C string pointer
 - `count` must be the correct number of addresses in the array
 - After calling this function, all pointers become invalid
 */
 void address_array_free(char **addresses, size_t count) ;

/*
 Validate an address

 # Safety

 - `address` must be a valid null-terminated C string
 - `error` must be a valid pointer to an FFIError
 */
 bool address_validate(const char *address, FFINetworks network, FFIError *error) ;

/*
 Get address type

 Returns:
 - 0: P2PKH address
 - 1: P2SH address
 - 2: Other address type
 - u8::MAX (255): Error occurred

 # Safety

 - `address` must be a valid null-terminated C string
 - `error` must be a valid pointer to an FFIError
 */
 unsigned char address_get_type(const char *address, FFINetworks network, FFIError *error) ;

/*
 Free an address pool handle

 # Safety

 - `pool` must be a valid pointer to an FFIAddressPool that was allocated by this library
 - The pointer must not be used after calling this function
 - This function must only be called once per allocation
 */
 void address_pool_free(FFIAddressPool *pool) ;

/*
 Get address pool information for an account

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWallet
 - `info_out` must be a valid pointer to store the pool info
 - `error` must be a valid pointer to an FFIError or null
 */

bool managed_wallet_get_address_pool_info(const FFIManagedWallet *managed_wallet,
                                          FFINetworks network,
                                          FFIAccountType account_type,
                                          unsigned int account_index,
                                          FFIAddressPoolType pool_type,
                                          FFIAddressPoolInfo *info_out,
                                          FFIError *error)
;

/*
 Set the gap limit for an address pool

 The gap limit determines how many unused addresses to maintain at the end
 of the pool. This is important for wallet recovery and address discovery.

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWallet
 - `error` must be a valid pointer to an FFIError or null
 */

bool managed_wallet_set_gap_limit(FFIManagedWallet *managed_wallet,
                                  FFINetworks network,
                                  FFIAccountType account_type,
                                  unsigned int account_index,
                                  FFIAddressPoolType pool_type,
                                  unsigned int gap_limit,
                                  FFIError *error)
;

/*
 Generate addresses up to a specific index in a pool

 This ensures that addresses up to and including the specified index exist
 in the pool. This is useful for wallet recovery or when specific indices
 are needed.

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWallet
 - `wallet` must be a valid pointer to an FFIWallet (for key derivation)
 - `error` must be a valid pointer to an FFIError or null
 */

bool managed_wallet_generate_addresses_to_index(FFIManagedWallet *managed_wallet,
                                                const FFIWallet *wallet,
                                                FFINetworks network,
                                                FFIAccountType account_type,
                                                unsigned int account_index,
                                                FFIAddressPoolType pool_type,
                                                unsigned int target_index,
                                                FFIError *error)
;

/*
 Mark an address as used in the pool

 This updates the pool's tracking of which addresses have been used,
 which is important for gap limit management and wallet recovery.

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWallet
 - `address` must be a valid C string
 - `error` must be a valid pointer to an FFIError or null
 */

bool managed_wallet_mark_address_used(FFIManagedWallet *managed_wallet,
                                      FFINetworks network,
                                      const char *address,
                                      FFIError *error)
;

/*
 Get a single address info at a specific index from the pool

 Returns detailed information about the address at the given index, or NULL
 if the index is out of bounds or not generated yet.

 # Safety

 - `pool` must be a valid pointer to an FFIAddressPool
 - `error` must be a valid pointer to an FFIError or null
 - The returned FFIAddressInfo must be freed using `address_info_free`
 */

FFIAddressInfo *address_pool_get_address_at_index(const FFIAddressPool *pool,
                                                  uint32_t index,
                                                  FFIError *error)
;

/*
 Get a range of addresses from the pool

 Returns an array of FFIAddressInfo structures for addresses in the range [start_index, end_index).
 The count_out parameter will be set to the actual number of addresses returned.

 Note: This function only reads existing addresses from the pool. It does not generate new addresses.
 Use managed_wallet_generate_addresses_to_index if you need to generate addresses first.

 # Safety

 - `pool` must be a valid pointer to an FFIAddressPool
 - `count_out` must be a valid pointer to store the count
 - `error` must be a valid pointer to an FFIError or null
 - The returned array must be freed using `address_info_array_free`
 */

FFIAddressInfo **address_pool_get_addresses_in_range(const FFIAddressPool *pool,
                                                     uint32_t start_index,
                                                     uint32_t end_index,
                                                     size_t *count_out,
                                                     FFIError *error)
;

/*
 Free a single FFIAddressInfo structure

 # Safety

 - `info` must be a valid pointer to an FFIAddressInfo allocated by this library or null
 - The pointer must not be used after calling this function
 */
 void address_info_free(FFIAddressInfo *info) ;

/*
 Free an array of FFIAddressInfo structures

 # Safety

 - `infos` must be a valid pointer to an array of FFIAddressInfo pointers allocated by this library or null
 - `count` must be the exact number of elements in the array
 - The pointers must not be used after calling this function
 */

void address_info_array_free(FFIAddressInfo **infos,
                             size_t count)
;

/*
 Create a new master extended private key from seed

 # Safety

 - `seed` must be a valid pointer to a byte array of `seed_len` length
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure the seed pointer remains valid for the duration of this call
 */

FFIExtendedPrivKey *derivation_new_master_key(const uint8_t *seed,
                                              size_t seed_len,
                                              FFINetworks network,
                                              FFIError *error)
;

/*
 Derive a BIP44 account path (m/44'/5'/account')
 */

bool derivation_bip44_account_path(FFINetworks network,
                                   unsigned int account_index,
                                   char *path_out,
                                   size_t path_max_len,
                                   FFIError *error)
;

/*
 Derive a BIP44 payment path (m/44'/5'/account'/change/index)
 */

bool derivation_bip44_payment_path(FFINetworks network,
                                   unsigned int account_index,
                                   bool is_change,
                                   unsigned int address_index,
                                   char *path_out,
                                   size_t path_max_len,
                                   FFIError *error)
;

/*
 Derive CoinJoin path (m/9'/5'/4'/account')
 */

bool derivation_coinjoin_path(FFINetworks network,
                              unsigned int account_index,
                              char *path_out,
                              size_t path_max_len,
                              FFIError *error)
;

/*
 Derive identity registration path (m/9'/5'/5'/1'/index')
 */

bool derivation_identity_registration_path(FFINetworks network,
                                           unsigned int identity_index,
                                           char *path_out,
                                           size_t path_max_len,
                                           FFIError *error)
;

/*
 Derive identity top-up path (m/9'/5'/5'/2'/identity_index'/top_up_index')
 */

bool derivation_identity_topup_path(FFINetworks network,
                                    unsigned int identity_index,
                                    unsigned int topup_index,
                                    char *path_out,
                                    size_t path_max_len,
                                    FFIError *error)
;

/*
 Derive identity authentication path (m/9'/5'/5'/0'/identity_index'/key_index')
 */

bool derivation_identity_authentication_path(FFINetworks network,
                                             unsigned int identity_index,
                                             unsigned int key_index,
                                             char *path_out,
                                             size_t path_max_len,
                                             FFIError *error)
;

/*
 Derive private key for a specific path from seed

 # Safety

 - `seed` must be a valid pointer to a byte array of `seed_len` length
 - `path` must be a valid pointer to a null-terminated C string
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

FFIExtendedPrivKey *derivation_derive_private_key_from_seed(const uint8_t *seed,
                                                            size_t seed_len,
                                                            const char *path,
                                                            FFINetworks network,
                                                            FFIError *error)
;

/*
 Derive public key from extended private key

 # Safety

 - `xpriv` must be a valid pointer to an FFIExtendedPrivKey
 - `error` must be a valid pointer to an FFIError
 - The returned pointer must be freed with `extended_public_key_free`
 */
 FFIExtendedPubKey *derivation_xpriv_to_xpub(const FFIExtendedPrivKey *xpriv, FFIError *error) ;

/*
 Get extended private key as string

 # Safety

 - `xpriv` must be a valid pointer to an FFIExtendedPrivKey
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */
 char *derivation_xpriv_to_string(const FFIExtendedPrivKey *xpriv, FFIError *error) ;

/*
 Get extended public key as string

 # Safety

 - `xpub` must be a valid pointer to an FFIExtendedPubKey
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */
 char *derivation_xpub_to_string(const FFIExtendedPubKey *xpub, FFIError *error) ;

/*
 Get fingerprint from extended public key (4 bytes)

 # Safety

 - `xpub` must be a valid pointer to an FFIExtendedPubKey
 - `fingerprint_out` must be a valid pointer to a buffer of at least 4 bytes
 - `error` must be a valid pointer to an FFIError
 */

bool derivation_xpub_fingerprint(const FFIExtendedPubKey *xpub,
                                 uint8_t *fingerprint_out,
                                 FFIError *error)
;

/*
 Free extended private key

 # Safety

 - `xpriv` must be a valid pointer to an FFIExtendedPrivKey that was allocated by this library
 - The pointer must not be used after calling this function
 - This function must only be called once per allocation
 */
 void derivation_xpriv_free(FFIExtendedPrivKey *xpriv) ;

/*
 Free extended public key

 # Safety

 - `xpub` must be a valid pointer to an FFIExtendedPubKey that was allocated by this library
 - The pointer must not be used after calling this function
 - This function must only be called once per allocation
 */
 void derivation_xpub_free(FFIExtendedPubKey *xpub) ;

/*
 Free derivation path string

 # Safety

 - `s` must be a valid pointer to a C string that was allocated by this library
 - The pointer must not be used after calling this function
 - This function must only be called once per allocation
 */
 void derivation_string_free(char *s) ;

/*
 Derive key using DIP9 path constants for identity

 # Safety

 - `seed` must be a valid pointer to a byte array of `seed_len` length
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure the seed pointer remains valid for the duration of this call
 */

FFIExtendedPrivKey *dip9_derive_identity_key(const uint8_t *seed,
                                             size_t seed_len,
                                             FFINetworks network,
                                             unsigned int identity_index,
                                             unsigned int key_index,
                                             FFIDerivationPathType key_type,
                                             FFIError *error)
;

/*
 Free an error message

 # Safety

 - `message` must be a valid pointer to a C string that was allocated by this library
 - The pointer must not be used after calling this function
 - This function must only be called once per allocation
 */
 void error_message_free(char *message) ;

/*
 Get extended private key for account

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */

char *wallet_get_account_xpriv(const FFIWallet *wallet,
                               FFINetworks network,
                               unsigned int account_index,
                               FFIError *error)
;

/*
 Get extended public key for account

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */

char *wallet_get_account_xpub(const FFIWallet *wallet,
                              FFINetworks network,
                              unsigned int account_index,
                              FFIError *error)
;

/*
 Derive private key at a specific path
 Returns an opaque FFIPrivateKey pointer that must be freed with private_key_free

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `derivation_path` must be a valid null-terminated C string
 - `error` must be a valid pointer to an FFIError
 - The returned pointer must be freed with `private_key_free`
 */

FFIPrivateKey *wallet_derive_private_key(const FFIWallet *wallet,
                                         FFINetworks network,
                                         const char *derivation_path,
                                         FFIError *error)
;

/*
 Derive extended private key at a specific path
 Returns an opaque FFIExtendedPrivateKey pointer that must be freed with extended_private_key_free

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `derivation_path` must be a valid null-terminated C string
 - `error` must be a valid pointer to an FFIError
 - The returned pointer must be freed with `extended_private_key_free`
 */

FFIExtendedPrivateKey *wallet_derive_extended_private_key(const FFIWallet *wallet,
                                                          FFINetworks network,
                                                          const char *derivation_path,
                                                          FFIError *error)
;

/*
 Derive private key at a specific path and return as WIF string

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `derivation_path` must be a valid null-terminated C string
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */

char *wallet_derive_private_key_as_wif(const FFIWallet *wallet,
                                       FFINetworks network,
                                       const char *derivation_path,
                                       FFIError *error)
;

/*
 Free a private key

 # Safety

 - `key` must be a valid pointer created by private key functions or null
 - After calling this function, the pointer becomes invalid
 */
 void private_key_free(FFIPrivateKey *key) ;

/*
 Free an extended private key

 # Safety

 - `key` must be a valid pointer created by extended private key functions or null
 - After calling this function, the pointer becomes invalid
 */
 void extended_private_key_free(FFIExtendedPrivateKey *key) ;

/*
 Get extended private key as string (xprv format)

 Returns the extended private key in base58 format (xprv... for mainnet, tprv... for testnet)

 # Safety

 - `key` must be a valid pointer to an FFIExtendedPrivateKey
 - `network` is ignored; the network is encoded in the extended key
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */

char *extended_private_key_to_string(const FFIExtendedPrivateKey *key,
                                     FFINetworks network,
                                     FFIError *error)
;

/*
 Get the private key from an extended private key

 Extracts the non-extended private key from an extended private key.

 # Safety

 - `extended_key` must be a valid pointer to an FFIExtendedPrivateKey
 - `error` must be a valid pointer to an FFIError
 - The returned FFIPrivateKey must be freed with `private_key_free`
 */

FFIPrivateKey *extended_private_key_get_private_key(const FFIExtendedPrivateKey *extended_key,
                                                    FFIError *error)
;

/*
 Get private key as WIF string from FFIPrivateKey

 # Safety

 - `key` must be a valid pointer to an FFIPrivateKey
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */
 char *private_key_to_wif(const FFIPrivateKey *key, FFINetworks network, FFIError *error) ;

/*
 Derive public key at a specific path
 Returns an opaque FFIPublicKey pointer that must be freed with public_key_free

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `derivation_path` must be a valid null-terminated C string
 - `error` must be a valid pointer to an FFIError
 - The returned pointer must be freed with `public_key_free`
 */

FFIPublicKey *wallet_derive_public_key(const FFIWallet *wallet,
                                       FFINetworks network,
                                       const char *derivation_path,
                                       FFIError *error)
;

/*
 Derive extended public key at a specific path
 Returns an opaque FFIExtendedPublicKey pointer that must be freed with extended_public_key_free

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `derivation_path` must be a valid null-terminated C string
 - `error` must be a valid pointer to an FFIError
 - The returned pointer must be freed with `extended_public_key_free`
 */

FFIExtendedPublicKey *wallet_derive_extended_public_key(const FFIWallet *wallet,
                                                        FFINetworks network,
                                                        const char *derivation_path,
                                                        FFIError *error)
;

/*
 Derive public key at a specific path and return as hex string

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `derivation_path` must be a valid null-terminated C string
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */

char *wallet_derive_public_key_as_hex(const FFIWallet *wallet,
                                      FFINetworks network,
                                      const char *derivation_path,
                                      FFIError *error)
;

/*
 Free a public key

 # Safety

 - `key` must be a valid pointer created by public key functions or null
 - After calling this function, the pointer becomes invalid
 */
 void public_key_free(FFIPublicKey *key) ;

/*
 Free an extended public key

 # Safety

 - `key` must be a valid pointer created by extended public key functions or null
 - After calling this function, the pointer becomes invalid
 */
 void extended_public_key_free(FFIExtendedPublicKey *key) ;

/*
 Get extended public key as string (xpub format)

 Returns the extended public key in base58 format (xpub... for mainnet, tpub... for testnet)

 # Safety

 - `key` must be a valid pointer to an FFIExtendedPublicKey
 - `network` is ignored; the network is encoded in the extended key
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */

char *extended_public_key_to_string(const FFIExtendedPublicKey *key,
                                    FFINetworks network,
                                    FFIError *error)
;

/*
 Get the public key from an extended public key

 Extracts the non-extended public key from an extended public key.

 # Safety

 - `extended_key` must be a valid pointer to an FFIExtendedPublicKey
 - `error` must be a valid pointer to an FFIError
 - The returned FFIPublicKey must be freed with `public_key_free`
 */

FFIPublicKey *extended_public_key_get_public_key(const FFIExtendedPublicKey *extended_key,
                                                 FFIError *error)
;

/*
 Get public key as hex string from FFIPublicKey

 # Safety

 - `key` must be a valid pointer to an FFIPublicKey
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed with `string_free`
 */
 char *public_key_to_hex(const FFIPublicKey *key, FFIError *error) ;

/*
 Convert derivation path string to indices

 # Safety

 - `path` must be a valid null-terminated C string or null
 - `indices_out` must be a valid pointer to store the indices array pointer
 - `hardened_out` must be a valid pointer to store the hardened flags array pointer
 - `count_out` must be a valid pointer to store the count
 - `error` must be a valid pointer to an FFIError
 - The returned arrays must be freed with `derivation_path_free`
 */

bool derivation_path_parse(const char *path,
                           uint32_t **indices_out,
                           bool **hardened_out,
                           size_t *count_out,
                           FFIError *error)
;

/*
 Free derivation path arrays
 Note: This function expects the count to properly free the slices

 # Safety

 - `indices` must be a valid pointer created by `derivation_path_parse` or null
 - `hardened` must be a valid pointer created by `derivation_path_parse` or null
 - `count` must match the count from `derivation_path_parse`
 - After calling this function, the pointers become invalid
 */
 void derivation_path_free(uint32_t *indices, bool *hardened, size_t count) ;

/*
 Get a managed account from a managed wallet

 This function gets a ManagedAccount from the wallet manager's managed wallet info,
 returning a managed account handle that wraps the ManagedAccount.

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - `network` must specify exactly one network
 - The caller must ensure all pointers remain valid for the duration of this call
 - The returned account must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccountResult managed_wallet_get_account(const FFIWalletManager *manager,
                                                   const uint8_t *wallet_id,
                                                   FFINetworks network,
                                                   unsigned int account_index,
                                                   FFIAccountType account_type)
;

/*
 Get a managed IdentityTopUp account with a specific registration index

 This is used for top-up accounts that are bound to a specific identity.
 Returns a managed account handle that wraps the ManagedAccount.

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - `network` must specify exactly one network
 - The caller must ensure all pointers remain valid for the duration of this call
 - The returned account must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccountResult managed_wallet_get_top_up_account_with_registration_index(const FFIWalletManager *manager,
                                                                                  const uint8_t *wallet_id,
                                                                                  FFINetworks network,
                                                                                  unsigned int registration_index)
;

/*
 Get the network of a managed account

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount instance
 */
 FFINetworks managed_account_get_network(const FFIManagedAccount *account) ;

/*
 Get the parent wallet ID of a managed account

 Note: ManagedAccount doesn't store the parent wallet ID directly.
 The wallet ID is typically known from the context (e.g., when getting the account from a managed wallet).

 # Safety

 - `wallet_id` must be a valid pointer to a 32-byte wallet ID buffer that was provided by the caller
 - The returned pointer is the same as the input pointer for convenience
 - The caller must not free the returned pointer as it's the same as the input
 */

const uint8_t *managed_account_get_parent_wallet_id(const uint8_t *wallet_id)
;

/*
 Get the account type of a managed account

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount instance
 - `index_out` must be a valid pointer to receive the account index (or null)
 */

FFIAccountType managed_account_get_account_type(const FFIManagedAccount *account,
                                                unsigned int *index_out)
;

/*
 Check if a managed account is watch-only

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount instance
 */
 bool managed_account_get_is_watch_only(const FFIManagedAccount *account) ;

/*
 Get the balance of a managed account

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount instance
 - `balance_out` must be a valid pointer to an FFIBalance structure
 */
 bool managed_account_get_balance(const FFIManagedAccount *account, FFIBalance *balance_out) ;

/*
 Get the number of transactions in a managed account

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount instance
 */
 unsigned int managed_account_get_transaction_count(const FFIManagedAccount *account) ;

/*
 Get the number of UTXOs in a managed account

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount instance
 */
 unsigned int managed_account_get_utxo_count(const FFIManagedAccount *account) ;

/*
 Free a managed account handle

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount that was allocated by this library
 - The pointer must not be used after calling this function
 - This function must only be called once per allocation
 */
 void managed_account_free(FFIManagedAccount *account) ;

/*
 Free a managed account result's error message (if any)
 Note: This does NOT free the account handle itself - use managed_account_free for that

 # Safety

 - `result` must be a valid pointer to an FFIManagedAccountResult
 - The error_message field must be either null or a valid CString allocated by this library
 - The caller must ensure the result pointer remains valid for the duration of this call
 */
 void managed_account_result_free_error(FFIManagedAccountResult *result) ;

/*
 Get number of accounts in a managed wallet

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - `network` must specify exactly one network
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

unsigned int managed_wallet_get_account_count(const FFIWalletManager *manager,
                                              const uint8_t *wallet_id,
                                              FFINetworks network,
                                              FFIError *error)
;

/*
 Get the account index from a managed account

 Returns the primary account index for Standard and CoinJoin accounts.
 Returns 0 for account types that don't have an index (like Identity or Provider accounts).

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount instance
 */
 unsigned int managed_account_get_index(const FFIManagedAccount *account) ;

/*
 Get the external address pool from a managed account

 This function returns the external (receive) address pool for Standard accounts.
 Returns NULL for account types that don't have separate external/internal pools.

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount instance
 - The returned pool must be freed with `address_pool_free` when no longer needed
 */
 FFIAddressPool *managed_account_get_external_address_pool(const FFIManagedAccount *account) ;

/*
 Get the internal address pool from a managed account

 This function returns the internal (change) address pool for Standard accounts.
 Returns NULL for account types that don't have separate external/internal pools.

 # Safety

 - `account` must be a valid pointer to an FFIManagedAccount instance
 - The returned pool must be freed with `address_pool_free` when no longer needed
 */
 FFIAddressPool *managed_account_get_internal_address_pool(const FFIManagedAccount *account) ;

/*
 Get an address pool from a managed account by type

 This function returns the appropriate address pool based on the pool type parameter.
 For Standard accounts with External/Internal pool types, returns the corresponding pool.
 For non-standard accounts with Single pool type, returns their single address pool.

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `account` must be a valid pointer to an FFIManagedAccount instance
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - The returned pool must be freed with `address_pool_free` when no longer needed
 */

FFIAddressPool *managed_account_get_address_pool(const FFIManagedAccount *account,
                                                 FFIAddressPoolType pool_type)
;

/*
 Get managed account collection for a specific network from wallet manager

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - `error` must be a valid pointer to an FFIError structure or null
 - The returned pointer must be freed with `managed_account_collection_free` when no longer needed
 */

FFIManagedAccountCollection *managed_wallet_get_account_collection(const FFIWalletManager *manager,
                                                                   const uint8_t *wallet_id,
                                                                   FFINetworks network,
                                                                   FFIError *error)
;

/*
 Free a managed account collection handle

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection created by this library
 - `collection` must not be used after calling this function
 */
 void managed_account_collection_free(FFIManagedAccountCollection *collection) ;

/*
 Get a BIP44 account by index from the managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccount *managed_account_collection_get_bip44_account(const FFIManagedAccountCollection *collection,
                                                                unsigned int index)
;

/*
 Get all BIP44 account indices from managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - `out_indices` must be a valid pointer to store the indices array
 - `out_count` must be a valid pointer to store the count
 - The returned array must be freed with `free_u32_array` when no longer needed
 */

bool managed_account_collection_get_bip44_indices(const FFIManagedAccountCollection *collection,
                                                  unsigned int **out_indices,
                                                  size_t *out_count)
;

/*
 Get a BIP32 account by index from the managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccount *managed_account_collection_get_bip32_account(const FFIManagedAccountCollection *collection,
                                                                unsigned int index)
;

/*
 Get all BIP32 account indices from managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - `out_indices` must be a valid pointer to store the indices array
 - `out_count` must be a valid pointer to store the count
 - The returned array must be freed with `free_u32_array` when no longer needed
 */

bool managed_account_collection_get_bip32_indices(const FFIManagedAccountCollection *collection,
                                                  unsigned int **out_indices,
                                                  size_t *out_count)
;

/*
 Get a CoinJoin account by index from the managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccount *managed_account_collection_get_coinjoin_account(const FFIManagedAccountCollection *collection,
                                                                   unsigned int index)
;

/*
 Get all CoinJoin account indices from managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - `out_indices` must be a valid pointer to store the indices array
 - `out_count` must be a valid pointer to store the count
 - The returned array must be freed with `free_u32_array` when no longer needed
 */

bool managed_account_collection_get_coinjoin_indices(const FFIManagedAccountCollection *collection,
                                                     unsigned int **out_indices,
                                                     size_t *out_count)
;

/*
 Get the identity registration account if it exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccount *managed_account_collection_get_identity_registration(const FFIManagedAccountCollection *collection)
;

/*
 Check if identity registration account exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 */

bool managed_account_collection_has_identity_registration(const FFIManagedAccountCollection *collection)
;

/*
 Get an identity topup account by registration index from managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccount *managed_account_collection_get_identity_topup(const FFIManagedAccountCollection *collection,
                                                                 unsigned int registration_index)
;

/*
 Get all identity topup registration indices from managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - `out_indices` must be a valid pointer to store the indices array
 - `out_count` must be a valid pointer to store the count
 - The returned array must be freed with `free_u32_array` when no longer needed
 */

bool managed_account_collection_get_identity_topup_indices(const FFIManagedAccountCollection *collection,
                                                           unsigned int **out_indices,
                                                           size_t *out_count)
;

/*
 Get the identity topup not bound account if it exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - `manager` must be a valid pointer to an FFIWalletManager
 - The returned pointer must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccount *managed_account_collection_get_identity_topup_not_bound(const FFIManagedAccountCollection *collection)
;

/*
 Check if identity topup not bound account exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 */

bool managed_account_collection_has_identity_topup_not_bound(const FFIManagedAccountCollection *collection)
;

/*
 Get the identity invitation account if it exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccount *managed_account_collection_get_identity_invitation(const FFIManagedAccountCollection *collection)
;

/*
 Check if identity invitation account exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 */

bool managed_account_collection_has_identity_invitation(const FFIManagedAccountCollection *collection)
;

/*
 Get the provider voting keys account if it exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccount *managed_account_collection_get_provider_voting_keys(const FFIManagedAccountCollection *collection)
;

/*
 Check if provider voting keys account exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 */

bool managed_account_collection_has_provider_voting_keys(const FFIManagedAccountCollection *collection)
;

/*
 Get the provider owner keys account if it exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed
 */

FFIManagedAccount *managed_account_collection_get_provider_owner_keys(const FFIManagedAccountCollection *collection)
;

/*
 Check if provider owner keys account exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 */

bool managed_account_collection_has_provider_owner_keys(const FFIManagedAccountCollection *collection)
;

/*
 Get the provider operator keys account if it exists in managed collection
 Note: Returns null if the `bls` feature is not enabled

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed (when BLS is enabled)
 */

void *managed_account_collection_get_provider_operator_keys(const FFIManagedAccountCollection *collection)
;

/*
 Check if provider operator keys account exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 */

bool managed_account_collection_has_provider_operator_keys(const FFIManagedAccountCollection *collection)
;

/*
 Get the provider platform keys account if it exists in managed collection
 Note: Returns null if the `eddsa` feature is not enabled

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_free` when no longer needed (when EdDSA is enabled)
 */

void *managed_account_collection_get_provider_platform_keys(const FFIManagedAccountCollection *collection)
;

/*
 Check if provider platform keys account exists in managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 */

bool managed_account_collection_has_provider_platform_keys(const FFIManagedAccountCollection *collection)
;

/*
 Get the total number of accounts in the managed collection

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 */
 unsigned int managed_account_collection_count(const FFIManagedAccountCollection *collection) ;

/*
 Get a human-readable summary of all accounts in the managed collection

 Returns a formatted string showing all account types and their indices.
 The format is designed to be clear and readable for end users.

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned string must be freed with `string_free` when no longer needed
 - Returns null if the collection pointer is null
 */
 char *managed_account_collection_summary(const FFIManagedAccountCollection *collection) ;

/*
 Get structured account collection summary data for managed collection

 Returns a struct containing arrays of indices for each account type and boolean
 flags for special accounts. This provides Swift with programmatic access to
 account information.

 # Safety

 - `collection` must be a valid pointer to an FFIManagedAccountCollection
 - The returned pointer must be freed with `managed_account_collection_summary_free` when no longer needed
 - Returns null if the collection pointer is null
 */

FFIManagedAccountCollectionSummary *managed_account_collection_summary_data(const FFIManagedAccountCollection *collection)
;

/*
 Free a managed account collection summary and all its allocated memory

 # Safety

 - `summary` must be a valid pointer to an FFIManagedAccountCollectionSummary created by `managed_account_collection_summary_data`
 - `summary` must not be used after calling this function
 */

void managed_account_collection_summary_free(FFIManagedAccountCollectionSummary *summary)
;

/*
 Get the next unused receive address

 Generates the next unused receive address for the specified account.
 This properly manages address gaps and updates the managed wallet state.

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo
 - `wallet` must be a valid pointer to an FFIWallet
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed by the caller
 */

char *managed_wallet_get_next_bip44_receive_address(FFIManagedWalletInfo *managed_wallet,
                                                    const FFIWallet *wallet,
                                                    FFINetworks network,
                                                    unsigned int account_index,
                                                    FFIError *error)
;

/*
 Get the next unused change address

 Generates the next unused change address for the specified account.
 This properly manages address gaps and updates the managed wallet state.

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo
 - `wallet` must be a valid pointer to an FFIWallet
 - `error` must be a valid pointer to an FFIError
 - The returned string must be freed by the caller
 */

char *managed_wallet_get_next_bip44_change_address(FFIManagedWalletInfo *managed_wallet,
                                                   const FFIWallet *wallet,
                                                   FFINetworks network,
                                                   unsigned int account_index,
                                                   FFIError *error)
;

/*
 Get BIP44 external (receive) addresses in the specified range

 Returns external addresses from start_index (inclusive) to end_index (exclusive).
 If addresses in the range haven't been generated yet, they will be generated.

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo
 - `wallet` must be a valid pointer to an FFIWallet
 - `addresses_out` must be a valid pointer to store the address array pointer
 - `count_out` must be a valid pointer to store the count
 - `error` must be a valid pointer to an FFIError
 - Free the result with address_array_free(addresses_out, count_out)
 */

bool managed_wallet_get_bip_44_external_address_range(FFIManagedWalletInfo *managed_wallet,
                                                      const FFIWallet *wallet,
                                                      FFINetworks network,
                                                      unsigned int account_index,
                                                      unsigned int start_index,
                                                      unsigned int end_index,
                                                      char ***addresses_out,
                                                      size_t *count_out,
                                                      FFIError *error)
;

/*
 Get BIP44 internal (change) addresses in the specified range

 Returns internal addresses from start_index (inclusive) to end_index (exclusive).
 If addresses in the range haven't been generated yet, they will be generated.

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo
 - `wallet` must be a valid pointer to an FFIWallet
 - `addresses_out` must be a valid pointer to store the address array pointer
 - `count_out` must be a valid pointer to store the count
 - `error` must be a valid pointer to an FFIError
 - Free the result with address_array_free(addresses_out, count_out)
 */

bool managed_wallet_get_bip_44_internal_address_range(FFIManagedWalletInfo *managed_wallet,
                                                      const FFIWallet *wallet,
                                                      FFINetworks network,
                                                      unsigned int account_index,
                                                      unsigned int start_index,
                                                      unsigned int end_index,
                                                      char ***addresses_out,
                                                      size_t *count_out,
                                                      FFIError *error)
;

/*
 Get wallet balance from managed wallet info

 Returns the balance breakdown including confirmed, unconfirmed, locked, and total amounts.

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo
 - `confirmed_out` must be a valid pointer to store the confirmed balance
 - `unconfirmed_out` must be a valid pointer to store the unconfirmed balance
 - `locked_out` must be a valid pointer to store the locked balance
 - `total_out` must be a valid pointer to store the total balance
 - `error` must be a valid pointer to an FFIError
 */

bool managed_wallet_get_balance(const FFIManagedWalletInfo *managed_wallet,
                                uint64_t *confirmed_out,
                                uint64_t *unconfirmed_out,
                                uint64_t *locked_out,
                                uint64_t *total_out,
                                FFIError *error)
;

/*
 Free managed wallet info

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo or null
 - After calling this function, the pointer becomes invalid and must not be used
 */
 void managed_wallet_free(FFIManagedWalletInfo *managed_wallet) ;

/*
 Free managed wallet info returned by wallet_manager_get_managed_wallet_info

 # Safety

 - `wallet_info` must be a valid pointer returned by wallet_manager_get_managed_wallet_info or null
 - After calling this function, the pointer becomes invalid and must not be used
 */
 void managed_wallet_info_free(FFIManagedWalletInfo *wallet_info) ;

/*
 Generate a new mnemonic with specified word count (12, 15, 18, 21, or 24)
 */
 char *mnemonic_generate(unsigned int word_count, FFIError *error) ;

/*
 Generate a new mnemonic with specified language and word count
 */

char *mnemonic_generate_with_language(unsigned int word_count,
                                      FFILanguage language,
                                      FFIError *error)
;

/*
 Validate a mnemonic phrase

 # Safety

 - `mnemonic` must be a valid null-terminated C string or null
 - `error` must be a valid pointer to an FFIError
 */
 bool mnemonic_validate(const char *mnemonic, FFIError *error) ;

/*
 Convert mnemonic to seed with optional passphrase

 # Safety

 - `mnemonic` must be a valid null-terminated C string
 - `passphrase` must be a valid null-terminated C string or null
 - `seed_out` must be a valid pointer to a buffer of at least 64 bytes
 - `seed_len` must be a valid pointer to store the seed length
 - `error` must be a valid pointer to an FFIError
 */

bool mnemonic_to_seed(const char *mnemonic,
                      const char *passphrase,
                      uint8_t *seed_out,
                      size_t *seed_len,
                      FFIError *error)
;

/*
 Get word count from mnemonic

 # Safety

 - `mnemonic` must be a valid null-terminated C string or null
 - `error` must be a valid pointer to an FFIError
 */
 unsigned int mnemonic_word_count(const char *mnemonic, FFIError *error) ;

/*
 Free a mnemonic string

 # Safety

 - `mnemonic` must be a valid pointer created by mnemonic generation functions or null
 - After calling this function, the pointer becomes invalid
 */
 void mnemonic_free(char *mnemonic) ;

/*
 Generate a provider key at a specific index

 This generates a provider key (BLS or EdDSA) at the specified index.
 For voting, owner, and operator keys, this generates BLS keys.
 For platform keys, this generates EdDSA keys.

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `info_out` must be a valid pointer to store the key info
 - `error` must be a valid pointer to an FFIError or null
 - The returned public_key, private_key, and derivation_path must be freed by the caller
 */

bool wallet_generate_provider_key(const FFIWallet *wallet,
                                  FFINetworks network,
                                  FFIProviderKeyType key_type,
                                  unsigned int key_index,
                                  bool include_private,
                                  FFIProviderKeyInfo *info_out,
                                  FFIError *error)
;

/*
 Free provider key info

 # Safety

 - `info` must be a valid pointer to an FFIProviderKeyInfo
 - This function must only be called once per info structure
 */
 void provider_key_info_free(FFIProviderKeyInfo *info) ;

/*
 Sign data with a provider key

 This signs arbitrary data with the provider key at the specified index.
 For BLS keys, this produces a BLS signature.
 For EdDSA keys, this produces an Ed25519 signature.

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `data` must be a valid pointer to data with at least `data_len` bytes
 - `signature_out` must be a valid pointer to store the signature pointer
 - `signature_len_out` must be a valid pointer to store the signature length
 - `error` must be a valid pointer to an FFIError or null
 - The returned signature must be freed with `libc::free`
 */

bool wallet_sign_with_provider_key(const FFIWallet *wallet,
                                   FFINetworks network,
                                   FFIProviderKeyType key_type,
                                   unsigned int _key_index,
                                   const uint8_t *data,
                                   size_t data_len,
                                   uint8_t **signature_out,
                                   size_t *signature_len_out,
                                   FFIError *error)
;

/*
 Build a transaction

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `outputs` must be a valid pointer to an array of FFITxOutput with at least `outputs_count` elements
 - `tx_bytes_out` must be a valid pointer to store the transaction bytes pointer
 - `tx_len_out` must be a valid pointer to store the transaction length
 - `error` must be a valid pointer to an FFIError
 - The returned transaction bytes must be freed with `transaction_bytes_free`
 */

bool wallet_build_transaction(FFIWallet *wallet,
                              FFINetworks _network,
                              unsigned int account_index,
                              const FFITxOutput *outputs,
                              size_t outputs_count,
                              uint64_t fee_per_kb,
                              uint8_t **tx_bytes_out,
                              size_t *tx_len_out,
                              FFIError *error)
;

/*
 Sign a transaction

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `tx_bytes` must be a valid pointer to transaction bytes with at least `tx_len` bytes
 - `signed_tx_out` must be a valid pointer to store the signed transaction bytes pointer
 - `signed_len_out` must be a valid pointer to store the signed transaction length
 - `error` must be a valid pointer to an FFIError
 - The returned signed transaction bytes must be freed with `transaction_bytes_free`
 */

bool wallet_sign_transaction(const FFIWallet *wallet,
                             FFINetworks _network,
                             const uint8_t *tx_bytes,
                             size_t tx_len,
                             uint8_t **signed_tx_out,
                             size_t *signed_len_out,
                             FFIError *error)
;

/*
 Check if a transaction belongs to the wallet using ManagedWalletInfo

 # Safety

 - `wallet` must be a valid mutable pointer to an FFIWallet
 - `tx_bytes` must be a valid pointer to transaction bytes with at least `tx_len` bytes
 - `inputs_spent_out` must be a valid pointer to store the spent inputs count
 - `addresses_used_out` must be a valid pointer to store the used addresses count
 - `new_balance_out` must be a valid pointer to store the new balance
 - `new_address_out` must be a valid pointer to store the address array pointer
 - `new_address_count_out` must be a valid pointer to store the address count
 - `error` must be a valid pointer to an FFIError
 */

bool wallet_check_transaction(FFIWallet *wallet,
                              FFINetworks network,
                              const uint8_t *tx_bytes,
                              size_t tx_len,
                              FFITransactionContext context_type,
                              uint32_t block_height,
                              const uint8_t *block_hash,
                              uint64_t timestamp,
                              bool update_state,
                              FFITransactionCheckResult *result_out,
                              FFIError *error)
;

/*
 Free transaction bytes

 # Safety

 - `tx_bytes` must be a valid pointer created by transaction functions or null
 - After calling this function, the pointer becomes invalid
 */
 void transaction_bytes_free(uint8_t *tx_bytes) ;

/*
 Create a managed wallet from a regular wallet

 This creates a ManagedWalletInfo instance from a Wallet, which includes
 address pools and transaction checking capabilities.

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `error` must be a valid pointer to an FFIError or null
 - The returned pointer must be freed with `ffi_managed_wallet_free`
 */
 FFIManagedWallet *wallet_create_managed_wallet(const FFIWallet *wallet, FFIError *error) ;

/*
 Check if a transaction belongs to the wallet

 This function checks a transaction against all relevant account types in the wallet
 and returns detailed information about which accounts are affected.

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWallet
 - `wallet` must be a valid pointer to an FFIWallet (needed for address generation)
 - `tx_bytes` must be a valid pointer to transaction bytes with at least `tx_len` bytes
 - `result_out` must be a valid pointer to store the result
 - `error` must be a valid pointer to an FFIError
 - The affected_accounts array in the result must be freed with `transaction_check_result_free`
 */

bool managed_wallet_check_transaction(FFIManagedWallet *managed_wallet,
                                      const FFIWallet *wallet,
                                      FFINetworks network,
                                      const uint8_t *tx_bytes,
                                      size_t tx_len,
                                      FFITransactionContext context_type,
                                      unsigned int block_height,
                                      const uint8_t *block_hash,
                                      uint64_t timestamp,
                                      bool update_state,
                                      FFITransactionCheckResult *result_out,
                                      FFIError *error)
;

/*
 Free a transaction check result

 # Safety

 - `result` must be a valid pointer to an FFITransactionCheckResult
 - This function must only be called once per result
 */
 void transaction_check_result_free(FFITransactionCheckResult *result) ;

/*
 Free a managed wallet (FFIManagedWallet type)

 # Safety

 - `managed_wallet` must be a valid pointer to an FFIManagedWallet
 - This function must only be called once per managed wallet
 */
 void ffi_managed_wallet_free(FFIManagedWallet *managed_wallet) ;

/*
 Get the transaction classification for routing

 Returns a string describing the transaction type (e.g., "Standard", "CoinJoin",
 "AssetLock", "AssetUnlock", "ProviderRegistration", etc.)

 # Safety

 - `tx_bytes` must be a valid pointer to transaction bytes with at least `tx_len` bytes
 - `error` must be a valid pointer to an FFIError or null
 - The returned string must be freed by the caller
 */
 char *transaction_classify(const uint8_t *tx_bytes, size_t tx_len, FFIError *error) ;

/*
 Free a string

 # Safety

 - `s` must be a valid pointer created by C string creation functions or null
 - After calling this function, the pointer becomes invalid
 */
 void string_free(char *s) ;

/*
 Get all UTXOs from managed wallet info

 # Safety

 - `managed_info` must be a valid pointer to an FFIManagedWalletInfo instance
 - `utxos_out` must be a valid pointer to store the UTXO array pointer
 - `count_out` must be a valid pointer to store the UTXO count
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 - The returned UTXO array must be freed with `utxo_array_free` when no longer needed
 */

bool managed_wallet_get_utxos(const FFIManagedWalletInfo *managed_info,
                              FFINetworks network,
                              FFIUTXO **utxos_out,
                              size_t *count_out,
                              FFIError *error)
;

/*
 Get all UTXOs (deprecated - use managed_wallet_get_utxos instead)

 # Safety

 This function is deprecated and returns an empty list.
 Use `managed_wallet_get_utxos` with a ManagedWalletInfo instead.
 */

bool wallet_get_utxos(const FFIWallet *_wallet,
                      FFINetworks _network,
                      FFIUTXO **utxos_out,
                      size_t *count_out,
                      FFIError *error)
;

/*
 Free UTXO array

 # Safety

 - `utxos` must be a valid pointer to an array of FFIUTXO structs allocated by this library
 - `count` must match the number of UTXOs in the array
 - The pointer must not be used after calling this function
 - This function must only be called once per array
 */
 void utxo_array_free(FFIUTXO *utxos, size_t count) ;

/*
 Create a new wallet from mnemonic with options

 # Safety

 - `mnemonic` must be a valid pointer to a null-terminated C string
 - `passphrase` must be a valid pointer to a null-terminated C string or null
 - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 - The returned pointer must be freed with `wallet_free` when no longer needed
 */

FFIWallet *wallet_create_from_mnemonic_with_options(const char *mnemonic,
                                                    const char *passphrase,
                                                    FFINetworks networks,
                                                    const FFIWalletAccountCreationOptions *account_options,
                                                    FFIError *error)
;

/*
 Create a new wallet from mnemonic (backward compatibility - single network)

 # Safety

 - `mnemonic` must be a valid pointer to a null-terminated C string
 - `passphrase` must be a valid pointer to a null-terminated C string or null
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 - The returned pointer must be freed with `wallet_free` when no longer needed
 */

FFIWallet *wallet_create_from_mnemonic(const char *mnemonic,
                                       const char *passphrase,
                                       FFINetworks network,
                                       FFIError *error)
;

/*
 Create a new wallet from seed with options

 # Safety

 - `seed` must be a valid pointer to a byte array of `seed_len` length
 - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

FFIWallet *wallet_create_from_seed_with_options(const uint8_t *seed,
                                                size_t seed_len,
                                                FFINetworks networks,
                                                const FFIWalletAccountCreationOptions *account_options,
                                                FFIError *error)
;

/*
 Create a new wallet from seed (backward compatibility)

 # Safety

 - `seed` must be a valid pointer to a byte array of `seed_len` length
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

FFIWallet *wallet_create_from_seed(const uint8_t *seed,
                                   size_t seed_len,
                                   FFINetworks network,
                                   FFIError *error)
;

/*
 Create a new random wallet with options

 # Safety

 - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

FFIWallet *wallet_create_random_with_options(FFINetworks networks,
                                             const FFIWalletAccountCreationOptions *account_options,
                                             FFIError *error)
;

/*
 Create a new random wallet (backward compatibility)

 # Safety

 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure the pointer remains valid for the duration of this call
 */
 FFIWallet *wallet_create_random(FFINetworks network, FFIError *error) ;

/*
 Get wallet ID (32-byte hash)

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet
 - `id_out` must be a valid pointer to a 32-byte buffer
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */
 bool wallet_get_id(const FFIWallet *wallet, uint8_t *id_out, FFIError *error) ;

/*
 Check if wallet has mnemonic

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet instance
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */
 bool wallet_has_mnemonic(const FFIWallet *wallet, FFIError *error) ;

/*
 Check if wallet is watch-only

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet instance
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */
 bool wallet_is_watch_only(const FFIWallet *wallet, FFIError *error) ;

/*
 Get extended public key for account

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet instance
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 - The returned C string must be freed by the caller when no longer needed
 */

char *wallet_get_xpub(const FFIWallet *wallet,
                      FFINetworks network,
                      unsigned int account_index,
                      FFIError *error)
;

/*
 Free a wallet

 # Safety

 - `wallet` must be a valid pointer to an FFIWallet that was created by this library
 - The pointer must not be used after calling this function
 - This function must only be called once per wallet
 */
 void wallet_free(FFIWallet *wallet) ;

/*
 Free a const wallet handle

 This is a const-safe wrapper for wallet_free() that accepts a const pointer.
 Use this function when you have a *const FFIWallet that needs to be freed,
 such as wallets returned from wallet_manager_get_wallet().

 # Safety

 - `wallet` must be a valid pointer created by wallet creation functions or null
 - After calling this function, the pointer becomes invalid
 - This function must only be called once per wallet
 - The wallet must have been allocated by this library (not stack or static memory)
 */
 void wallet_free_const(const FFIWallet *wallet) ;

/*
 Add an account to the wallet without xpub

 # Safety

 This function dereferences a raw pointer to FFIWallet.
 The caller must ensure that:
 - The wallet pointer is either null or points to a valid FFIWallet
 - The FFIWallet remains valid for the duration of this call
 */

FFIAccountResult wallet_add_account(FFIWallet *wallet,
                                    FFINetworks network,
                                    FFIAccountType account_type,
                                    unsigned int account_index)
;

/*
 Add an account to the wallet with xpub as byte array

 # Safety

 This function dereferences raw pointers.
 The caller must ensure that:
 - The wallet pointer is either null or points to a valid FFIWallet
 - The xpub_bytes pointer is either null or points to at least xpub_len bytes
 - The FFIWallet remains valid for the duration of this call
 */

FFIAccountResult wallet_add_account_with_xpub_bytes(FFIWallet *wallet,
                                                    FFINetworks network,
                                                    FFIAccountType account_type,
                                                    unsigned int account_index,
                                                    const uint8_t *xpub_bytes,
                                                    size_t xpub_len)
;

/*
 Add an account to the wallet with xpub as string

 # Safety

 This function dereferences raw pointers.
 The caller must ensure that:
 - The wallet pointer is either null or points to a valid FFIWallet
 - The xpub_string pointer is either null or points to a valid null-terminated C string
 - The FFIWallet remains valid for the duration of this call
 */

FFIAccountResult wallet_add_account_with_string_xpub(FFIWallet *wallet,
                                                     FFINetworks network,
                                                     FFIAccountType account_type,
                                                     unsigned int account_index,
                                                     const char *xpub_string)
;

/*
 Create a new wallet manager
 */
 FFIWalletManager *wallet_manager_create(FFIError *error) ;

/*
 Add a wallet from mnemonic to the manager with options

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `mnemonic` must be a valid pointer to a null-terminated C string
 - `passphrase` must be a valid pointer to a null-terminated C string or null
 - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

bool wallet_manager_add_wallet_from_mnemonic_with_options(FFIWalletManager *manager,
                                                          const char *mnemonic,
                                                          const char *passphrase,
                                                          FFINetworks network,
                                                          const FFIWalletAccountCreationOptions *account_options,
                                                          FFIError *error)
;

/*
 Add a wallet from mnemonic to the manager (backward compatibility)

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `mnemonic` must be a valid pointer to a null-terminated C string
 - `passphrase` must be a valid pointer to a null-terminated C string or null
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

bool wallet_manager_add_wallet_from_mnemonic(FFIWalletManager *manager,
                                             const char *mnemonic,
                                             const char *passphrase,
                                             FFINetworks network,
                                             FFIError *error)
;

/*
 Add a wallet from mnemonic to the manager and return serialized bytes

 Creates a wallet from a mnemonic phrase, adds it to the manager, optionally downgrading it
 to a pubkey-only wallet (watch-only or externally signable), and returns the serialized wallet bytes.

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `mnemonic` must be a valid pointer to a null-terminated C string
 - `passphrase` must be a valid pointer to a null-terminated C string or null
 - `birth_height` is optional, pass 0 for default
 - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null
 - `downgrade_to_pubkey_wallet` if true, creates a watch-only or externally signable wallet
 - `allow_external_signing` if true AND downgrade_to_pubkey_wallet is true, creates an externally signable wallet
 - `wallet_bytes_out` must be a valid pointer to a pointer that will receive the serialized bytes
 - `wallet_bytes_len_out` must be a valid pointer that will receive the byte length
 - `wallet_id_out` must be a valid pointer to a 32-byte array that will receive the wallet ID
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 - The caller must free the returned wallet_bytes using wallet_manager_free_wallet_bytes()
 */

bool wallet_manager_add_wallet_from_mnemonic_return_serialized_bytes(FFIWalletManager *manager,
                                                                     const char *mnemonic,
                                                                     const char *passphrase,
                                                                     FFINetworks network,
                                                                     unsigned int birth_height,
                                                                     const FFIWalletAccountCreationOptions *account_options,
                                                                     bool downgrade_to_pubkey_wallet,
                                                                     bool allow_external_signing,
                                                                     uint8_t **wallet_bytes_out,
                                                                     size_t *wallet_bytes_len_out,
                                                                     uint8_t *wallet_id_out,
                                                                     FFIError *error)
;

/*
 Free wallet bytes buffer

 # Safety

 - `wallet_bytes` must be a valid pointer to a buffer allocated by wallet_manager_add_wallet_from_mnemonic_return_serialized_bytes
 - `bytes_len` must match the original allocation size
 - The pointer must not be used after calling this function
 - This function must only be called once per buffer
 */

void wallet_manager_free_wallet_bytes(uint8_t *wallet_bytes,
                                      size_t bytes_len)
;

/*
 Import a wallet from bincode-serialized bytes

 Deserializes a wallet from bytes and adds it to the manager.
 Returns a 32-byte wallet ID on success.

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `wallet_bytes` must be a valid pointer to bincode-serialized wallet bytes
 - `wallet_bytes_len` must be the exact length of the wallet bytes
 - `wallet_id_out` must be a valid pointer to a 32-byte array that will receive the wallet ID
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

bool wallet_manager_import_wallet_from_bytes(FFIWalletManager *manager,
                                             const uint8_t *wallet_bytes,
                                             size_t wallet_bytes_len,
                                             uint8_t *wallet_id_out,
                                             FFIError *error)
;

/*
 Get wallet IDs

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager
 - `wallet_ids_out` must be a valid pointer to a pointer that will receive the wallet IDs
 - `count_out` must be a valid pointer to receive the count
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

bool wallet_manager_get_wallet_ids(const FFIWalletManager *manager,
                                   uint8_t **wallet_ids_out,
                                   size_t *count_out,
                                   FFIError *error)
;

/*
 Get a wallet from the manager

 Returns a reference to the wallet if found

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 - The returned wallet must be freed with wallet_free_const()
 */

const FFIWallet *wallet_manager_get_wallet(const FFIWalletManager *manager,
                                           const uint8_t *wallet_id,
                                           FFIError *error)
;

/*
 Get managed wallet info from the manager

 Returns a reference to the managed wallet info if found

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 - The returned managed wallet info must be freed with managed_wallet_info_free()
 */

FFIManagedWalletInfo *wallet_manager_get_managed_wallet_info(const FFIWalletManager *manager,
                                                             const uint8_t *wallet_id,
                                                             FFIError *error)
;

/*
 Get next receive address for a wallet

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

char *wallet_manager_get_receive_address(FFIWalletManager *manager,
                                         const uint8_t *wallet_id,
                                         FFINetworks network,
                                         unsigned int account_index,
                                         FFIError *error)
;

/*
 Get next change address for a wallet

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

char *wallet_manager_get_change_address(FFIWalletManager *manager,
                                        const uint8_t *wallet_id,
                                        FFINetworks network,
                                        unsigned int account_index,
                                        FFIError *error)
;

/*
 Get wallet balance

 Returns the confirmed and unconfirmed balance for a specific wallet

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `wallet_id` must be a valid pointer to a 32-byte wallet ID
 - `confirmed_out` must be a valid pointer to a u64 (maps to C uint64_t)
 - `unconfirmed_out` must be a valid pointer to a u64 (maps to C uint64_t)
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

bool wallet_manager_get_wallet_balance(const FFIWalletManager *manager,
                                       const uint8_t *wallet_id,
                                       uint64_t *confirmed_out,
                                       uint64_t *unconfirmed_out,
                                       FFIError *error)
;

/*
 Process a transaction through all wallets

 Checks a transaction against all wallets and updates their states if relevant.
 Returns true if the transaction was relevant to at least one wallet.

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `tx_bytes` must be a valid pointer to transaction bytes
 - `tx_len` must be the length of the transaction bytes
 - `network` is the network type
 - `context` must be a valid pointer to FFITransactionContextDetails
 - `update_state_if_found` indicates whether to update wallet state when transaction is relevant
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

bool wallet_manager_process_transaction(FFIWalletManager *manager,
                                        const uint8_t *tx_bytes,
                                        size_t tx_len,
                                        FFINetworks network,
                                        const FFITransactionContextDetails *context,
                                        bool update_state_if_found,
                                        FFIError *error)
;

/*
 Get monitored addresses for a network

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager
 - `addresses_out` must be a valid pointer to a pointer that will receive the addresses array
 - `count_out` must be a valid pointer to receive the count
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

bool wallet_manager_get_monitored_addresses(const FFIWalletManager *manager,
                                            FFINetworks network,
                                            char ***addresses_out,
                                            size_t *count_out,
                                            FFIError *error)
;

/*
 Update block height for a network

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

bool wallet_manager_update_height(FFIWalletManager *manager,
                                  FFINetworks network,
                                  unsigned int height,
                                  FFIError *error)
;

/*
 Get current height for a network

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */

unsigned int wallet_manager_current_height(const FFIWalletManager *manager,
                                           FFINetworks network,
                                           FFIError *error)
;

/*
 Get wallet count

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager instance
 - `error` must be a valid pointer to an FFIError structure or null
 - The caller must ensure all pointers remain valid for the duration of this call
 */
 size_t wallet_manager_wallet_count(const FFIWalletManager *manager, FFIError *error) ;

/*
 Free wallet manager

 # Safety

 - `manager` must be a valid pointer to an FFIWalletManager that was created by this library
 - The pointer must not be used after calling this function
 - This function must only be called once per manager
 */
 void wallet_manager_free(FFIWalletManager *manager) ;

/*
 Free wallet IDs buffer

 # Safety

 - `wallet_ids` must be a valid pointer to a buffer allocated by this library
 - `count` must match the number of wallet IDs in the buffer
 - The pointer must not be used after calling this function
 - This function must only be called once per buffer
 */
 void wallet_manager_free_wallet_ids(uint8_t *wallet_ids, size_t count) ;

/*
 Free address array

 # Safety

 - `addresses` must be a valid pointer to an array of C string pointers allocated by this library
 - `count` must match the original allocation size
 - Each address pointer in the array must be either null or a valid C string allocated by this library
 - The pointers must not be used after calling this function
 - This function must only be called once per allocation
 */

void wallet_manager_free_addresses(char **addresses,
                                   size_t count)
;

/*
 Encrypt a private key with BIP38

 # Safety

 This function is unsafe because it dereferences raw pointers:
 - `private_key` must be a valid, null-terminated C string
 - `passphrase` must be a valid, null-terminated C string
 - `error` must be a valid pointer to an FFIError or null
 */

char *bip38_encrypt_private_key(const char *private_key,
                                const char *passphrase,
                                FFINetworks _network,
                                FFIError *error)
;

/*
 Decrypt a BIP38 encrypted private key

 # Safety

 This function is unsafe because it dereferences raw pointers:
 - `encrypted_key` must be a valid, null-terminated C string
 - `passphrase` must be a valid, null-terminated C string
 - `error` must be a valid pointer to an FFIError or null
 */

char *bip38_decrypt_private_key(const char *encrypted_key,
                                const char *passphrase,
                                FFIError *error)
;

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* KEY_WALLET_FFI_H */