@qorechain/react 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,401 @@
+import { ReactNode, CSSProperties } from 'react';
+import { CreateClientOptions, QoreChainClient, TxClient, Coin, TxFeeInput, EncodeObject, BroadcastResult, PqcStatus } from '@qorechain/sdk';
+
+/**
+ * The QoreChain React context: a {@link QoreChainProvider} that holds a single
+ * composed {@link QoreChainClient} (from `@qorechain/sdk`'s {@link createClient})
+ * plus the live wallet connection state, and the {@link useQoreContext} hook the
+ * other hooks build on.
+ *
+ * One provider near the root of the app is enough; every hook
+ * ({@link useQoreClient}, {@link useAccount}, {@link useBalance},
+ * {@link useConnect}, {@link useTx}, {@link usePqcStatus}) reads from it.
+ */
+
+/** A connected wallet's resolved addresses, by VM family. */
+interface ConnectedAddresses {
+    /** Native bech32 (`qor1...`) address, when a Cosmos wallet is connected. */
+    native?: string;
+    /** EVM (`0x...`) address, when an EVM wallet is connected. */
+    evm?: string;
+    /** SVM (base58) address, when an SVM wallet is connected. */
+    svm?: string;
+}
+/** The live connection status of the provider. */
+type ConnectionStatus = "disconnected" | "connecting" | "connected" | "error";
+/** Which wallet family is connected. */
+type ConnectedWalletKind = "keplr" | "leap" | "evm" | "svm";
+/** The full context value exposed by {@link QoreChainProvider}. */
+interface QoreContextValue {
+    /** The composed read client (created once from the provider config). */
+    client: QoreChainClient;
+    /** Current connection status. */
+    status: ConnectionStatus;
+    /** The connected addresses, keyed by VM family. Empty when disconnected. */
+    addresses: ConnectedAddresses;
+    /** Which wallet is connected, if any. */
+    wallet?: ConnectedWalletKind;
+    /** The connected signing client, if any (set by `useConnect`). */
+    tx?: TxClient;
+    /** The last connection error, if `status === "error"`. */
+    error?: Error;
+    /**
+     * Internal: replace the connection state. Used by {@link useConnect}; apps use
+     * the hooks rather than calling this directly.
+     */
+    setConnection(next: {
+        status: ConnectionStatus;
+        addresses?: ConnectedAddresses;
+        wallet?: ConnectedWalletKind;
+        tx?: TxClient;
+        error?: Error;
+    }): void;
+}
+/** Configuration for {@link QoreChainProvider}, forwarded to `createClient`. */
+interface QoreChainProviderConfig {
+    /** Network preset to target. Defaults to `"testnet"`. */
+    network?: CreateClientOptions["network"];
+    /** Endpoint overrides merged over the preset's defaults. */
+    endpoints?: CreateClientOptions["endpoints"];
+    /** Chain id override. */
+    chainId?: CreateClientOptions["chainId"];
+    /** Additional HTTP transport options shared by the read clients. */
+    http?: CreateClientOptions["http"];
+}
+/** Props for {@link QoreChainProvider}. */
+interface QoreChainProviderProps {
+    /** Network + endpoint configuration for the underlying read client. */
+    config: QoreChainProviderConfig;
+    /**
+     * A pre-built client to use instead of constructing one from `config`. Useful
+     * for tests (inject a mocked client) and advanced composition.
+     */
+    client?: QoreChainClient;
+    /** The app subtree that consumes the QoreChain hooks. */
+    children: ReactNode;
+}
+/**
+ * Provide a single composed QoreChain client + connection state to the subtree.
+ *
+ * The client is created once (memoized on the config identity), so place the
+ * provider above any component that uses the hooks. Pass `client` to inject a
+ * pre-built (or mocked) client instead.
+ */
+declare function QoreChainProvider(props: QoreChainProviderProps): ReactNode;
+/**
+ * Read the raw {@link QoreContextValue}. Throws when used outside a
+ * {@link QoreChainProvider}. Most apps use the purpose-built hooks instead.
+ */
+declare function useQoreContext(): QoreContextValue;
+
+/**
+ * {@link useQoreClient} — the composed read client held by the provider.
+ */
+
+/**
+ * Return the {@link QoreChainClient} created by the nearest
+ * {@link QoreChainProvider}. Use it for ad-hoc reads (`client.rest`,
+ * `client.qor`, `client.fees`, ...) not already covered by a dedicated hook.
+ */
+declare function useQoreClient(): QoreChainClient;
+
+/**
+ * {@link useAccount} — the connected wallet's addresses and status.
+ */
+
+/** The shape returned by {@link useAccount}. */
+interface UseAccountResult {
+    /** All connected addresses, by VM family (native / evm / svm). */
+    addresses: ConnectedAddresses;
+    /** The primary address (native preferred, then evm, then svm), if any. */
+    address?: string;
+    /** Whether a wallet is connected. */
+    isConnected: boolean;
+    /** The current connection status. */
+    status: ConnectionStatus;
+    /** Which wallet is connected, if any. */
+    wallet?: ConnectedWalletKind;
+}
+/**
+ * Return the connected account's address(es) — native (bech32), EVM (`0x...`),
+ * and/or SVM (base58) — plus a convenience primary `address` and connection
+ * status. Empty until a wallet is connected via {@link useConnect}.
+ */
+declare function useAccount(): UseAccountResult;
+
+/**
+ * {@link useBalance} — a bank balance with optional auto-refresh.
+ */
+
+/** Options for {@link useBalance}. */
+interface UseBalanceOptions {
+    /**
+     * The denom to read. Defaults to the network's base denom (e.g. `uqor`).
+     */
+    denom?: string;
+    /**
+     * Auto-refresh interval in milliseconds. `0` (the default) disables polling;
+     * the balance is then fetched once on mount / address change.
+     */
+    refreshInterval?: number;
+    /** Skip fetching entirely (e.g. while disconnected). Defaults to `false`. */
+    enabled?: boolean;
+}
+/** The shape returned by {@link useBalance}. */
+interface UseBalanceResult {
+    /** The balance coin (`{ denom, amount }`), once loaded. */
+    data?: Coin;
+    /** Whether a fetch is in flight. */
+    isLoading: boolean;
+    /** The last fetch error, if any. */
+    error?: Error;
+    /** Manually re-fetch the balance. */
+    refetch(): Promise<void>;
+}
+/**
+ * Read the bank balance of `address` (or the connected account when omitted) in
+ * a denom. Re-fetches on address / denom change and, when `refreshInterval > 0`,
+ * polls on that interval. Returns `{ data, isLoading, error, refetch }`.
+ */
+declare function useBalance(address?: string, options?: UseBalanceOptions): UseBalanceResult;
+
+/**
+ * {@link useConnect} / {@link useWallet} — multi-wallet connect.
+ *
+ * Wraps the EXISTING wallet adapters so a component connects with one call and
+ * the resolved signer + addresses land in the provider's connection state:
+ *  - Keplr / Leap (Cosmos) via `@qorechain/sdk`'s {@link getCosmosWallet}, which
+ *    suggests + enables the chain and returns a CosmJS signer; the signer is
+ *    connected through `client.connectTx` so `useTx` can sign.
+ *  - MetaMask / any EIP-1193 wallet (EVM) via `eth_requestAccounts` on the
+ *    injected provider (`window.ethereum` by default).
+ *  - Phantom / Wallet-Standard (SVM) via the injected Solana provider
+ *    (`window.solana`); returns the connected base58 address.
+ *
+ * The hook keeps its dependencies light: the EVM and SVM paths talk to the
+ * injected provider's standard request API directly, so neither viem nor a
+ * Solana SDK is pulled in. For full EVM/SVM tooling, use `@qorechain/evm` /
+ * `@qorechain/svm` alongside this hook.
+ */
+
+/** A minimal EIP-1193 provider surface (MetaMask et al.). */
+interface Eip1193Like {
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+}
+/** A minimal injected Solana provider surface (Phantom / Wallet-Standard). */
+interface SolanaProviderLike {
+    connect(): Promise<{
+        publicKey: {
+            toString(): string;
+        };
+    }>;
+    publicKey?: {
+        toString(): string;
+    } | null;
+}
+/** Which wallet to connect via {@link UseConnectResult.connect}. */
+type ConnectKind = "keplr" | "leap" | "evm" | "svm";
+/** Options for a single {@link UseConnectResult.connect} call. */
+interface ConnectOptions {
+    /** Which wallet to connect. Defaults to `"keplr"`. */
+    kind?: ConnectKind;
+    /**
+     * Inject the wallet provider directly instead of reading it off `window`
+     * (primarily for tests). The accepted shape depends on `kind`.
+     */
+    provider?: unknown;
+    /** Use Amino signing for the Cosmos path (forwarded to `getCosmosWallet`). */
+    preferAmino?: boolean;
+}
+/** The shape returned by {@link useConnect} / {@link useWallet}. */
+interface UseConnectResult {
+    /** Connect a wallet; updates the provider's connection state. */
+    connect(opts?: ConnectOptions): Promise<void>;
+    /** Disconnect: clears the connection state. */
+    disconnect(): void;
+    /** The current connection status. */
+    status: ReturnType<typeof useQoreContext>["status"];
+    /** Whether a connection attempt is in flight. */
+    isConnecting: boolean;
+    /** The last connection error, if any. */
+    error?: Error;
+}
+/**
+ * Multi-wallet connect bound to the {@link QoreChainProvider}.
+ *
+ * On success the provider's connection state holds the resolved addresses, the
+ * connected wallet kind, and (for Cosmos) a `TxClient` for signing.
+ */
+declare function useConnect(): UseConnectResult;
+/** Alias for {@link useConnect} — the multi-wallet connect hook. */
+declare const useWallet: typeof useConnect;
+
+/**
+ * {@link useTx} — send a transaction and track its status.
+ */
+
+/** The lifecycle status of a {@link useTx} send. */
+type TxStatus = "idle" | "pending" | "success" | "error";
+/** Options for {@link UseTxResult.send}. */
+interface SendOptions {
+    /** Fee: an explicit `StdFee` or `"auto"`. Default `"auto"`. */
+    fee?: TxFeeInput;
+    /** Optional memo. */
+    memo?: string;
+}
+/** The shape returned by {@link useTx}. */
+interface UseTxResult {
+    /** Sign + broadcast arbitrary messages with the connected signer. */
+    send(messages: EncodeObject[], opts?: SendOptions): Promise<BroadcastResult>;
+    /** Convenience: send a bank transfer of `amount` to `toAddress`. */
+    sendTokens(toAddress: string, amount: Coin[], opts?: SendOptions): Promise<BroadcastResult>;
+    /** The current send status. */
+    status: TxStatus;
+    /** The last broadcast result, on success. */
+    data?: BroadcastResult;
+    /** The last error, on failure. */
+    error?: Error;
+    /** Whether a send is in flight. */
+    isPending: boolean;
+    /** Reset status/data/error back to idle. */
+    reset(): void;
+}
+/**
+ * Send transactions with the connected signer and track `{ status, data, error }`.
+ *
+ * Requires a connected wallet that produced a `TxClient` (the Cosmos path of
+ * {@link useConnect}). `send` takes raw `{ typeUrl, value }` messages (use the
+ * `msg.*` composers from `@qorechain/sdk`); `sendTokens` is a bank-transfer
+ * shortcut.
+ */
+declare function useTx(): UseTxResult;
+
+/**
+ * {@link usePqcStatus} — read an address's quantum-safe (PQC) registration state.
+ *
+ * Built on the SDK's quantum-safe DX helpers ({@link getPqcStatus} /
+ * {@link isPqcRegistered}), which call `qor_getPQCKeyStatus`. Powers the
+ * {@link QuantumSafeBadge} component.
+ */
+
+/** Options for {@link usePqcStatus}. */
+interface UsePqcStatusOptions {
+    /** Skip fetching (e.g. while disconnected). Defaults to `false`. */
+    enabled?: boolean;
+    /**
+     * Auto-refresh interval in milliseconds. `0` (default) disables polling; the
+     * status is fetched once per address change.
+     */
+    refreshInterval?: number;
+}
+/** The shape returned by {@link usePqcStatus}. */
+interface UsePqcStatusResult {
+    /** The normalized PQC status, once loaded. */
+    data?: PqcStatus;
+    /** Whether the address has a registered PQC key (convenience). */
+    isRegistered: boolean;
+    /** Whether a fetch is in flight. */
+    isLoading: boolean;
+    /** The last fetch error, if any. */
+    error?: Error;
+    /** Manually re-fetch the status. */
+    refetch(): Promise<void>;
+}
+/**
+ * Read whether `address` (or the connected account when omitted) is quantum-safe
+ * — i.e. has a registered PQC key on QoreChain. Returns
+ * `{ data, isRegistered, isLoading, error, refetch }`.
+ */
+declare function usePqcStatus(address?: string, options?: UsePqcStatusOptions): UsePqcStatusResult;
+
+/**
+ * {@link ConnectButton} — a minimal, headless-ish multi-wallet connect control.
+ *
+ * Renders a connect button (or a small picker when multiple wallet kinds are
+ * offered) wired to {@link useConnect}; once connected it shows the truncated
+ * address and a disconnect action. Styling is intentionally light — pass
+ * `className` / `style` to theme it, or rebuild your own UI on the hooks.
+ */
+
+/** Props for {@link ConnectButton}. */
+interface ConnectButtonProps {
+    /**
+     * The wallet kinds to offer. With one entry the button connects it directly;
+     * with several it renders a button per kind. Defaults to `["keplr"]`.
+     */
+    wallets?: ConnectKind[];
+    /** Optional class applied to the root element. */
+    className?: string;
+    /** Optional inline styles merged onto the root element. */
+    style?: CSSProperties;
+    /** Label shown before connecting. Defaults to `"Connect Wallet"`. */
+    label?: string;
+    /** Render-prop override: full control over the rendered UI. */
+    children?: (state: ConnectButtonRenderState) => ReactNode;
+}
+/** State passed to the {@link ConnectButtonProps.children} render-prop. */
+interface ConnectButtonRenderState {
+    /** Whether a wallet is connected. */
+    isConnected: boolean;
+    /** Whether a connection attempt is in flight. */
+    isConnecting: boolean;
+    /** The connected primary address, if any. */
+    address?: string;
+    /** Connect a specific wallet kind. */
+    connect(kind?: ConnectKind): void;
+    /** Disconnect. */
+    disconnect(): void;
+    /** The last connection error, if any. */
+    error?: Error;
+}
+/**
+ * A small connect / disconnect control. Single-wallet by default; pass
+ * `wallets` for a multi-wallet picker, or `children` for full custom rendering.
+ */
+declare function ConnectButton(props: ConnectButtonProps): ReactNode;
+
+/**
+ * {@link QuantumSafeBadge} — a "Quantum-safe" indicator for an address.
+ *
+ * Reads the address's PQC registration via {@link usePqcStatus} and renders a
+ * compact badge: a positive "Quantum-safe" state when a PQC key is registered,
+ * otherwise a muted "Not quantum-safe" state (or nothing, with
+ * `hideWhenUnsafe`). Styling is minimal; theme it via `className` / `style` or
+ * supply a `children` render-prop.
+ */
+
+/** Props for {@link QuantumSafeBadge}. */
+interface QuantumSafeBadgeProps {
+    /** Address to check. Defaults to the connected account. */
+    address?: string;
+    /** When `true`, render nothing if the address is not quantum-safe. */
+    hideWhenUnsafe?: boolean;
+    /** Label for the safe state. Defaults to `"Quantum-safe"`. */
+    safeLabel?: string;
+    /** Label for the unsafe state. Defaults to `"Not quantum-safe"`. */
+    unsafeLabel?: string;
+    /** Optional class applied to the root element. */
+    className?: string;
+    /** Optional inline styles merged onto the root element. */
+    style?: CSSProperties;
+    /** Render-prop override for full control over the rendered UI. */
+    children?: (state: QuantumSafeRenderState) => ReactNode;
+}
+/** State passed to the {@link QuantumSafeBadgeProps.children} render-prop. */
+interface QuantumSafeRenderState {
+    /** Whether the address has a registered PQC key. */
+    isRegistered: boolean;
+    /** Whether the status is still loading. */
+    isLoading: boolean;
+    /** The last fetch error, if any. */
+    error?: Error;
+}
+/**
+ * A badge showing whether an address is quantum-safe (has a registered PQC key).
+ */
+declare function QuantumSafeBadge(props: QuantumSafeBadgeProps): ReactNode;
+
+export { ConnectButton, type ConnectButtonProps, type ConnectButtonRenderState, type ConnectKind, type ConnectOptions, type ConnectedAddresses, type ConnectedWalletKind, type ConnectionStatus, type Eip1193Like, QoreChainProvider, type QoreChainProviderConfig, type QoreChainProviderProps, type QoreContextValue, QuantumSafeBadge, type QuantumSafeBadgeProps, type QuantumSafeRenderState, type SendOptions, type SolanaProviderLike, type TxStatus, type UseAccountResult, type UseBalanceOptions, type UseBalanceResult, type UseConnectResult, type UsePqcStatusOptions, type UsePqcStatusResult, type UseTxResult, useAccount, useBalance, useConnect, usePqcStatus, useQoreClient, useQoreContext, useTx, useWallet };