@qorechain/evm 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,1145 @@
+import { Transport, PublicClient, Account, WalletClient, Chain, Hex, PrivateKeyAccount, Address, Hash, Abi, WatchBlocksParameters, WatchContractEventParameters, WatchEventParameters, WatchPendingTransactionsParameters } from 'viem';
+
+/**
+ * Client factory for the QoreChain EVM Engine.
+ *
+ * This is a thin convenience layer over viem: it builds a viem `Chain` object
+ * from the network's EVM endpoints, resolves the numeric EVM chain id (either
+ * supplied explicitly or auto-detected via `eth_chainId`), and returns ready-to-
+ * use viem public and wallet clients.
+ *
+ * The numeric EVM chain id for QoreChain networks is intentionally not hardcoded
+ * here: it is auto-detected at connect time unless the caller provides it.
+ */
+
+/** Subset of a qorechain-sdk network's endpoints relevant to the EVM Engine. */
+interface EvmEndpoints {
+    /** EVM JSON-RPC HTTP endpoint. */
+    evmRpc: string;
+    /** EVM JSON-RPC WebSocket endpoint (optional). */
+    evmWs?: string;
+}
+/** Options for {@link createEvmClient}. */
+interface CreateEvmClientOptions {
+    /** EVM JSON-RPC HTTP URL. Mutually exclusive with `endpoints`. */
+    rpcUrl?: string;
+    /** EVM JSON-RPC WebSocket URL. */
+    wsUrl?: string;
+    /** A qorechain-sdk network endpoints object (uses `evmRpc`/`evmWs`). */
+    endpoints?: EvmEndpoints;
+    /**
+     * Numeric EVM chain id. If omitted, it is auto-detected via `eth_chainId`.
+     *
+     * The canonical chain id for QoreChain networks is not pinned in this package
+     * on purpose — always detect it, or pass it explicitly here.
+     */
+    chainId?: number;
+    /**
+     * Native currency decimals for EVM display. Defaults to 18 (the EVM
+     * convention). Note: this is the EVM-side representation of QOR and is
+     * distinct from the Cosmos `uqor` base denomination (10^6). Confirm the
+     * canonical wrapped/native EVM decimals against your target node.
+     */
+    decimals?: number;
+    /**
+     * Custom viem transport. When provided it is used instead of an HTTP
+     * transport built from the resolved RPC URL — primarily for testing.
+     */
+    transport?: Transport;
+}
+/** A configured QoreChain EVM client bundle. */
+interface EvmClient {
+    /** viem public (read) client bound to the resolved chain + transport. */
+    publicClient: PublicClient;
+    /** Build a viem wallet (write) client for the given account. */
+    getWalletClient: (account: Account) => WalletClient;
+    /** The viem `Chain` object describing the connected network. */
+    chain: Chain;
+    /** Return the resolved numeric EVM chain id. */
+    getChainId: () => Promise<number>;
+}
+/**
+ * Create a QoreChain EVM client bundle.
+ *
+ * Auto-detects the EVM chain id via `eth_chainId` unless `chainId` is supplied.
+ */
+declare function createEvmClient(opts: CreateEvmClientOptions): Promise<EvmClient>;
+
+/**
+ * Account helpers for the QoreChain EVM Engine.
+ *
+ * These re-expose viem's account utilities so callers don't need a second import
+ * path. `@qorechain/sdk`'s `deriveEvmAccount` returns a `privateKey` you can pass
+ * straight into {@link evmAccountFromPrivateKey}.
+ */
+
+/**
+ * Create a viem account from a `0x`-prefixed private key.
+ *
+ * Pair with `@qorechain/sdk`'s `deriveEvmAccount(mnemonic)`, which provides the
+ * `privateKey` derived for the EVM coin type.
+ */
+declare function evmAccountFromPrivateKey(privateKey: Hex): PrivateKeyAccount;
+
+/**
+ * ERC-20 conveniences over viem's `readContract` / `writeContract`, using a
+ * bundled minimal ERC-20 ABI. Read helpers take a viem `PublicClient`; write
+ * helpers take a viem `WalletClient`.
+ */
+
+/** Token metadata returned by {@link metadata}. */
+interface Erc20Metadata {
+    name: string;
+    symbol: string;
+    decimals: number;
+}
+/** Read the token balance of `account`. */
+declare function balanceOf$2(client: PublicClient, token: Address, account: Address): Promise<bigint>;
+/** Read the remaining allowance `spender` may draw from `owner`. */
+declare function allowance(client: PublicClient, token: Address, owner: Address, spender: Address): Promise<bigint>;
+/** Read name/symbol/decimals in parallel. */
+declare function metadata$1(client: PublicClient, token: Address): Promise<Erc20Metadata>;
+/** Transfer `amount` tokens to `to`. Returns the transaction hash. */
+declare function transfer(client: WalletClient, token: Address, to: Address, amount: bigint): Promise<Hash>;
+/** Approve `spender` to draw up to `amount`. Returns the transaction hash. */
+declare function approve$1(client: WalletClient, token: Address, spender: Address, amount: bigint): Promise<Hash>;
+/** Namespaced ERC-20 helpers. */
+declare const erc20: {
+    readonly balanceOf: typeof balanceOf$2;
+    readonly allowance: typeof allowance;
+    readonly metadata: typeof metadata$1;
+    readonly transfer: typeof transfer;
+    readonly approve: typeof approve$1;
+};
+
+/**
+ * ERC-721 conveniences over viem's `readContract` / `writeContract`, using a
+ * bundled minimal ERC-721 ABI. Read helpers take a viem `PublicClient`; write
+ * helpers take a viem `WalletClient`. Mirrors the {@link erc20} style.
+ */
+
+/** Collection metadata returned by {@link metadata}. */
+interface Erc721Metadata {
+    name: string;
+    symbol: string;
+}
+/** Read the number of tokens owned by `owner`. */
+declare function balanceOf$1(client: PublicClient, token: Address, owner: Address): Promise<bigint>;
+/** Read the owner of `tokenId`. */
+declare function ownerOf(client: PublicClient, token: Address, tokenId: bigint): Promise<Address>;
+/** Read the metadata URI for `tokenId`. */
+declare function tokenURI(client: PublicClient, token: Address, tokenId: bigint): Promise<string>;
+/** Read the approved address for a single `tokenId`. */
+declare function getApproved(client: PublicClient, token: Address, tokenId: bigint): Promise<Address>;
+/** Read whether `operator` is approved to manage all of `owner`'s tokens. */
+declare function isApprovedForAll$1(client: PublicClient, token: Address, owner: Address, operator: Address): Promise<boolean>;
+/** Read the collection name. */
+declare function name(client: PublicClient, token: Address): Promise<string>;
+/** Read the collection symbol. */
+declare function symbol(client: PublicClient, token: Address): Promise<string>;
+/** Read name/symbol in parallel. */
+declare function metadata(client: PublicClient, token: Address): Promise<Erc721Metadata>;
+/** Approve `to` to transfer `tokenId`. Returns the transaction hash. */
+declare function approve(client: WalletClient, token: Address, to: Address, tokenId: bigint): Promise<Hash>;
+/** Set or revoke `operator` as an approved manager for all caller tokens. */
+declare function setApprovalForAll$1(client: WalletClient, token: Address, operator: Address, approved: boolean): Promise<Hash>;
+/** Transfer `tokenId` from `from` to `to`. Returns the transaction hash. */
+declare function transferFrom(client: WalletClient, token: Address, from: Address, to: Address, tokenId: bigint): Promise<Hash>;
+/**
+ * Safe-transfer `tokenId` from `from` to `to`. Pass `data` to invoke the
+ * 4-argument `safeTransferFrom(from,to,tokenId,bytes)` overload.
+ */
+declare function safeTransferFrom$1(client: WalletClient, token: Address, from: Address, to: Address, tokenId: bigint, data?: Hex): Promise<Hash>;
+/** Namespaced ERC-721 helpers. */
+declare const erc721: {
+    readonly balanceOf: typeof balanceOf$1;
+    readonly ownerOf: typeof ownerOf;
+    readonly tokenURI: typeof tokenURI;
+    readonly getApproved: typeof getApproved;
+    readonly isApprovedForAll: typeof isApprovedForAll$1;
+    readonly name: typeof name;
+    readonly symbol: typeof symbol;
+    readonly metadata: typeof metadata;
+    readonly approve: typeof approve;
+    readonly setApprovalForAll: typeof setApprovalForAll$1;
+    readonly transferFrom: typeof transferFrom;
+    readonly safeTransferFrom: typeof safeTransferFrom$1;
+};
+
+/**
+ * ERC-1155 conveniences over viem's `readContract` / `writeContract`, using a
+ * bundled minimal ERC-1155 ABI. Read helpers take a viem `PublicClient`; write
+ * helpers take a viem `WalletClient`. Mirrors the {@link erc20} style.
+ */
+
+/** Read the balance of token `id` held by `account`. */
+declare function balanceOf(client: PublicClient, token: Address, account: Address, id: bigint): Promise<bigint>;
+/** Read balances of `(accounts[i], ids[i])` pairs in a single call. */
+declare function balanceOfBatch(client: PublicClient, token: Address, accounts: readonly Address[], ids: readonly bigint[]): Promise<readonly bigint[]>;
+/** Read the metadata URI template for token `id`. */
+declare function uri(client: PublicClient, token: Address, id: bigint): Promise<string>;
+/** Read whether `operator` is approved to manage all of `account`'s tokens. */
+declare function isApprovedForAll(client: PublicClient, token: Address, account: Address, operator: Address): Promise<boolean>;
+/** Set or revoke `operator` as an approved manager for all caller tokens. */
+declare function setApprovalForAll(client: WalletClient, token: Address, operator: Address, approved: boolean): Promise<Hash>;
+/** Transfer `amount` of token `id` from `from` to `to`. */
+declare function safeTransferFrom(client: WalletClient, token: Address, from: Address, to: Address, id: bigint, amount: bigint, data?: Hex): Promise<Hash>;
+/** Batch-transfer `amounts[i]` of token `ids[i]` from `from` to `to`. */
+declare function safeBatchTransferFrom(client: WalletClient, token: Address, from: Address, to: Address, ids: readonly bigint[], amounts: readonly bigint[], data?: Hex): Promise<Hash>;
+/** Namespaced ERC-1155 helpers. */
+declare const erc1155: {
+    readonly balanceOf: typeof balanceOf;
+    readonly balanceOfBatch: typeof balanceOfBatch;
+    readonly uri: typeof uri;
+    readonly isApprovedForAll: typeof isApprovedForAll;
+    readonly setApprovalForAll: typeof setApprovalForAll;
+    readonly safeTransferFrom: typeof safeTransferFrom;
+    readonly safeBatchTransferFrom: typeof safeBatchTransferFrom;
+};
+
+/**
+ * Fee estimation conveniences over viem.
+ *
+ * {@link estimateEip1559Fees} wraps viem's `estimateFeesPerGas` to return the
+ * EIP-1559 `maxFeePerGas` / `maxPriorityFeePerGas` pair; {@link gasPrice} is a
+ * legacy helper returning a single gas price. Both take a viem `PublicClient`.
+ */
+
+/** EIP-1559 fee suggestion. */
+interface Eip1559Fees {
+    /** Maximum total fee per gas (base + priority). */
+    maxFeePerGas: bigint;
+    /** Maximum priority (miner tip) fee per gas. */
+    maxPriorityFeePerGas: bigint;
+}
+/**
+ * Suggest EIP-1559 fees from the network, via viem's `estimateFeesPerGas`.
+ *
+ * @returns `{ maxFeePerGas, maxPriorityFeePerGas }`.
+ */
+declare function estimateEip1559Fees(client: PublicClient): Promise<Eip1559Fees>;
+/** Legacy (pre-EIP-1559) gas price via viem's `getGasPrice`. */
+declare function gasPrice(client: PublicClient): Promise<bigint>;
+/** Namespaced fee helpers. */
+declare const fees: {
+    readonly estimateEip1559Fees: typeof estimateEip1559Fees;
+    readonly gasPrice: typeof gasPrice;
+};
+
+/**
+ * Thin contract deploy/call wrappers over viem that default to the QoreChain
+ * chain bound on the supplied client. These exist so the common cases need no
+ * extra `chain`/`account` plumbing; for advanced use, call viem directly.
+ */
+
+/** Arguments for {@link deployContract}. */
+interface DeployContractArgs {
+    /** Contract ABI (used for typed constructor args). */
+    abi: Abi;
+    /** Creation bytecode (`0x`-prefixed). */
+    bytecode: Hex;
+    /** Constructor arguments, if any. */
+    args?: readonly unknown[];
+}
+/**
+ * Deploy a contract using the wallet client's bound account and chain.
+ * Returns the deployment transaction hash.
+ */
+declare function deployContract(client: WalletClient, { abi, bytecode, args }: DeployContractArgs): Promise<Hash>;
+/**
+ * Typed `readContract` passthrough. Defaults nothing beyond viem; provided so
+ * callers can stay on a single import surface.
+ */
+declare function readContract(client: PublicClient, params: Parameters<PublicClient["readContract"]>[0]): ReturnType<PublicClient["readContract"]>;
+/**
+ * Typed `writeContract` wrapper that defaults `account` and `chain` from the
+ * wallet client when the caller omits them.
+ */
+declare function writeContract(client: WalletClient, params: Parameters<WalletClient["writeContract"]>[0]): Promise<Hash>;
+
+/**
+ * Typed bindings for QoreChain's EVM precompiles — the headline capability of
+ * the QoreChain EVM Engine. Each helper issues an `eth_call` against the fixed
+ * precompile address using the corresponding bundled interface ABI.
+ *
+ * Availability note: on a default or community node these precompiles may return
+ * a "not available" error; they are available on QoreChain network nodes. Handle
+ * a thrown error from any of these helpers as "feature not present on this node".
+ */
+
+/**
+ * Fixed 20-byte precompile addresses (zero-padded), matching the chain's
+ * published interface registrations.
+ */
+declare const PRECOMPILE_ADDRESSES: {
+    /** CrossVM Bridge precompile. */
+    readonly crossVmBridge: "0x0000000000000000000000000000000000000901";
+    /** PQC signature verification (`IQorePQC.pqcVerify`). */
+    readonly pqcVerify: "0x0000000000000000000000000000000000000A01";
+    /** PQC key registration status (`IQorePQC.pqcKeyStatus`). */
+    readonly pqcKeyStatus: "0x0000000000000000000000000000000000000A02";
+    /** AI transaction risk score (`IQoreAI.aiRiskScore`). */
+    readonly aiRiskScore: "0x0000000000000000000000000000000000000B01";
+    /** AI anomaly check (`IQoreAI.aiAnomalyCheck`). */
+    readonly aiAnomalyCheck: "0x0000000000000000000000000000000000000B02";
+    /** Consensus parameters (`IQoreConsensus.rlConsensusParams`). */
+    readonly rlConsensusParams: "0x0000000000000000000000000000000000000C01";
+};
+/** Arguments for {@link pqcVerify}. */
+interface PqcVerifyArgs {
+    pubkey: Hex;
+    signature: Hex;
+    message: Hex;
+}
+/** Verify a post-quantum signature on-chain. Returns `true` when valid. */
+declare function pqcVerify(client: PublicClient, { pubkey, signature, message }: PqcVerifyArgs): Promise<boolean>;
+/** Result of {@link pqcKeyStatus}. */
+interface PqcKeyStatus {
+    registered: boolean;
+    algorithmId: number;
+    pubkey: Hex;
+}
+/** Query the on-chain post-quantum key registration status for an account. */
+declare function pqcKeyStatus(client: PublicClient, account: Address): Promise<PqcKeyStatus>;
+/** Result of {@link aiRiskScore}. */
+interface AiRiskScore {
+    score: bigint;
+    level: number;
+}
+/** Compute an on-chain risk score for raw transaction data. */
+declare function aiRiskScore(client: PublicClient, txData: Hex): Promise<AiRiskScore>;
+/** Arguments for {@link aiAnomalyCheck}. */
+interface AiAnomalyCheckArgs {
+    sender: Address;
+    amount: bigint;
+}
+/** Result of {@link aiAnomalyCheck}. */
+interface AiAnomalyCheck {
+    anomalyScore: bigint;
+    flagged: boolean;
+}
+/** Check whether a (sender, amount) pair is anomalous. */
+declare function aiAnomalyCheck(client: PublicClient, { sender, amount }: AiAnomalyCheckArgs): Promise<AiAnomalyCheck>;
+/** Result of {@link rlConsensusParams}. */
+interface ConsensusParams {
+    blockTime: bigint;
+    baseGasPrice: bigint;
+    validatorSetSize: bigint;
+    epoch: bigint;
+}
+/** Read the live, adaptively-tuned consensus parameters. */
+declare function rlConsensusParams(client: PublicClient): Promise<ConsensusParams>;
+/** Namespaced precompile helpers. */
+declare const precompiles: {
+    readonly pqcVerify: typeof pqcVerify;
+    readonly pqcKeyStatus: typeof pqcKeyStatus;
+    readonly aiRiskScore: typeof aiRiskScore;
+    readonly aiAnomalyCheck: typeof aiAnomalyCheck;
+    readonly rlConsensusParams: typeof rlConsensusParams;
+};
+
+/**
+ * Bundled ABIs used by the QoreChain EVM adapter.
+ *
+ * These are declared `as const` so viem can infer fully typed argument and
+ * return types from them. The QoreChain precompile ABIs mirror the chain's
+ * published Solidity interfaces exactly.
+ */
+/** Minimal ERC-20 ABI covering the helpers this package exposes. */
+declare const ERC20_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "name";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "symbol";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "decimals";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "totalSupply";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "allowance";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "transfer";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "approve";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "Transfer";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "Approval";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+}];
+/** Minimal ERC-721 ABI covering the helpers this package exposes. */
+declare const ERC721_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "name";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "symbol";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "ownerOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "tokenURI";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getApproved";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isApprovedForAll";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "operator";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "approve";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "setApprovalForAll";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "approved";
+        readonly type: "bool";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "transferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "safeTransferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "safeTransferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "event";
+    readonly name: "Transfer";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "Approval";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "approved";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "ApprovalForAll";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "approved";
+        readonly type: "bool";
+    }];
+}];
+/** Minimal ERC-1155 ABI covering the helpers this package exposes. */
+declare const ERC1155_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOfBatch";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "accounts";
+        readonly type: "address[]";
+    }, {
+        readonly name: "ids";
+        readonly type: "uint256[]";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256[]";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "uri";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isApprovedForAll";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly name: "operator";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "setApprovalForAll";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "approved";
+        readonly type: "bool";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "safeTransferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "safeBatchTransferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "ids";
+        readonly type: "uint256[]";
+    }, {
+        readonly name: "amounts";
+        readonly type: "uint256[]";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "event";
+    readonly name: "TransferSingle";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "id";
+        readonly type: "uint256";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "ApprovalForAll";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "approved";
+        readonly type: "bool";
+    }];
+}];
+/**
+ * Post-quantum cryptography precompile interface (`IQorePQC`).
+ *
+ * Exposes signature verification and on-chain key registration status for
+ * QoreChain's quantum-resistant key material (Dilithium / ML-DSA family).
+ */
+declare const IQORE_PQC_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "pqcVerify";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "pubkey";
+        readonly type: "bytes";
+    }, {
+        readonly name: "signature";
+        readonly type: "bytes";
+    }, {
+        readonly name: "message";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "valid";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "pqcKeyStatus";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "registered";
+        readonly type: "bool";
+    }, {
+        readonly name: "algorithmId";
+        readonly type: "uint8";
+    }, {
+        readonly name: "pubkey";
+        readonly type: "bytes";
+    }];
+}];
+/**
+ * On-chain risk/anomaly intelligence precompile interface (`IQoreAI`).
+ */
+declare const IQORE_AI_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "aiRiskScore";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "txData";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "score";
+        readonly type: "uint256";
+    }, {
+        readonly name: "level";
+        readonly type: "uint8";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "aiAnomalyCheck";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "sender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "anomalyScore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "flagged";
+        readonly type: "bool";
+    }];
+}];
+/**
+ * Consensus parameters precompile interface (`IQoreConsensus`).
+ *
+ * Surfaces live, adaptively-tuned consensus parameters from the network.
+ */
+declare const IQORE_CONSENSUS_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "rlConsensusParams";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "blockTime";
+        readonly type: "uint256";
+    }, {
+        readonly name: "baseGasPrice";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validatorSetSize";
+        readonly type: "uint256";
+    }, {
+        readonly name: "epoch";
+        readonly type: "uint256";
+    }];
+}];
+
+/**
+ * EVM browser-wallet integration for QoreChain (MetaMask and any EIP-1193
+ * provider, with optional EIP-6963 multi-wallet discovery).
+ *
+ * Builds a viem `WalletClient` over an injected provider so dApps can request
+ * accounts, add/switch the QoreChain EVM network, and sign + send transactions.
+ *
+ * ```ts
+ * import { getEvmWalletClient, addQoreChainNetwork } from "@qorechain/evm";
+ * import { getNetwork } from "@qorechain/sdk";
+ *
+ * await addQoreChainNetwork(window.ethereum, getNetwork("mainnet"));
+ * const { walletClient, address } = await getEvmWalletClient();
+ * ```
+ */
+
+/**
+ * The minimal EIP-1193 provider surface used here. Declared structurally so no
+ * wallet types package is required; `window.ethereum` is structurally
+ * compatible.
+ */
+interface Eip1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[] | object;
+    }): Promise<unknown>;
+    on?(event: string, listener: (...args: unknown[]) => void): void;
+    removeListener?(event: string, listener: (...args: unknown[]) => void): void;
+}
+/** Subset of a qorechain-sdk network needed to add the EVM chain to a wallet. */
+interface EvmNetworkInfo {
+    /** EVM endpoints (`evmRpc`, optional `evmWs`). */
+    endpoints: {
+        evmRpc: string;
+        evmWs?: string;
+    };
+    /** Display coin info (used for the native currency). */
+    coin: {
+        display: string;
+    };
+}
+/** Options for {@link getEvmWalletClient}. */
+interface GetEvmWalletClientOptions {
+    /** The EIP-1193 provider to use. Defaults to `window.ethereum`. */
+    provider?: Eip1193Provider;
+    /**
+     * Numeric EVM chain id. If omitted, it is auto-detected via `eth_chainId` on
+     * the connected provider.
+     */
+    chainId?: number;
+    /** Native currency decimals for the viem chain. Defaults to 18. */
+    decimals?: number;
+}
+/** The result of {@link getEvmWalletClient}. */
+interface EvmWalletConnection {
+    /** viem wallet client bound to the connected account and chain. */
+    walletClient: WalletClient;
+    /** The connected (first) account address. */
+    address: Address;
+    /** The underlying EIP-1193 provider. */
+    provider: Eip1193Provider;
+    /** The viem `Chain` object describing the connected network. */
+    chain: Chain;
+}
+/** Convert a numeric chain id to its `0x`-prefixed hex form. */
+declare function toHexChainId(chainId: number): `0x${string}`;
+/**
+ * Request the provider's accounts via `eth_requestAccounts`.
+ *
+ * @returns The authorized account addresses (the first is the active account).
+ */
+declare function requestAccounts(provider: Eip1193Provider): Promise<Address[]>;
+/**
+ * Add the QoreChain EVM network to the wallet via `wallet_addEthereumChain`.
+ *
+ * The EVM chain id is auto-detected (via `eth_chainId` against the network's
+ * `evmRpc`) unless provided. Native currency is QOR with 18 decimals (the EVM
+ * convention).
+ */
+declare function addQoreChainNetwork(provider: Eip1193Provider, network: EvmNetworkInfo, opts?: {
+    chainId?: number;
+    blockExplorerUrl?: string;
+}): Promise<void>;
+/**
+ * Switch the wallet to the given EVM chain via `wallet_switchEthereumChain`.
+ */
+declare function switchChain(provider: Eip1193Provider, chainId: number): Promise<void>;
+/**
+ * Connect to an injected EVM wallet and return a viem `WalletClient`.
+ *
+ * Requests accounts (`eth_requestAccounts`), resolves the EVM chain id (supplied
+ * or auto-detected), and builds a wallet client over a viem `custom` transport.
+ *
+ * Browser-only: throws a clear error if no `window` or no injected provider.
+ */
+declare function getEvmWalletClient(opts?: GetEvmWalletClientOptions): Promise<EvmWalletConnection>;
+/** A provider announced via the EIP-6963 discovery protocol. */
+interface Eip6963ProviderDetail {
+    info: {
+        uuid: string;
+        name: string;
+        icon: string;
+        rdns: string;
+    };
+    provider: Eip1193Provider;
+}
+/**
+ * Discover injected EVM providers via EIP-6963 (`eip6963:requestProvider`).
+ *
+ * Returns the providers that announce themselves within `timeoutMs` (default
+ * 200ms). `window.ethereum` remains the baseline default for the other helpers;
+ * use this when you want to let the user pick among multiple installed wallets.
+ *
+ * Resolves to an empty array outside a browser environment.
+ */
+declare function discoverEvmProviders(timeoutMs?: number): Promise<Eip6963ProviderDetail[]>;
+
+/**
+ * Human-readable decoding of EVM execution errors.
+ *
+ * viem throws richly-typed error objects, but the useful detail (a revert
+ * reason, a custom-error name and args, or a low-level RPC message) is often
+ * buried several layers deep in the error's `cause` chain. {@link decodeEvmError}
+ * walks that chain with viem's `BaseError.walk`, decodes custom-error revert
+ * data against an optional ABI via `decodeErrorResult`, and returns a flat,
+ * readable summary.
+ */
+
+/** A decoded EVM error. */
+interface DecodedEvmError {
+    /** A readable summary message. */
+    message: string;
+    /** A short, stable kind discriminator. */
+    kind: "revert" | "custom_error" | "panic" | "rpc" | "execution" | "unknown";
+    /** The custom-error or revert function name, when decoded. */
+    errorName?: string;
+    /** Decoded custom-error arguments, when available. */
+    args?: readonly unknown[];
+    /** The raw revert data, when present. */
+    data?: Hex;
+}
+/**
+ * Decode an EVM error thrown by viem into a readable, structured form.
+ *
+ * @param error - The thrown error (a viem `BaseError`, an RPC error, or any value).
+ * @param abi - Optional contract ABI used to decode custom-error revert data.
+ * @returns A {@link DecodedEvmError}.
+ */
+declare function decodeEvmError(error: unknown, abi?: Abi): DecodedEvmError;
+
+/**
+ * Real-time EVM watchers for QoreChain, over a viem websocket transport.
+ *
+ * {@link createEvmSubscriptionClient} builds a viem public client on a
+ * `webSocket` transport pointed at the network's `evmWs` endpoint, and the
+ * `watch*` helpers are thin passthroughs to viem's polling/subscription
+ * watchers scoped to that client. Each returns viem's `unwatch` function.
+ *
+ * These are deliberately minimal: viem owns the subscription lifecycle and
+ * reconnection; this module just wires the QoreChain endpoint and re-exports a
+ * focused surface so callers don't construct the transport themselves.
+ */
+
+/** Subset of a qorechain-sdk network's endpoints relevant to EVM subscriptions. */
+interface EvmWsEndpoints {
+    /** EVM JSON-RPC WebSocket endpoint. */
+    evmWs: string;
+}
+/** Options for {@link createEvmSubscriptionClient}. */
+interface CreateEvmSubscriptionClientOptions {
+    /** EVM websocket URL. Mutually exclusive with `endpoints`. */
+    wsUrl?: string;
+    /** A qorechain-sdk network endpoints object (uses `evmWs`). */
+    endpoints?: EvmWsEndpoints;
+    /** Optional viem `Chain` to bind. */
+    chain?: Chain;
+    /** Custom viem transport (primarily for testing). Overrides `wsUrl`/`endpoints`. */
+    transport?: Transport;
+}
+/** A function that stops a watcher. */
+type Unwatch = () => void;
+/**
+ * Create a viem public client on a websocket transport for subscriptions.
+ *
+ * The returned client is a standard viem `PublicClient`; the `watch*` helpers in
+ * this module accept it (or any viem public client).
+ */
+declare function createEvmSubscriptionClient(opts: CreateEvmSubscriptionClientOptions): PublicClient;
+/** Watch for new blocks. Returns viem's `unwatch`. */
+declare function watchBlocks(client: PublicClient, args: WatchBlocksParameters): Unwatch;
+/** Watch for logs matching an event filter. Returns viem's `unwatch`. */
+declare function watchEvent(client: PublicClient, args: WatchEventParameters): Unwatch;
+/** Watch a specific contract's events (decoded). Returns viem's `unwatch`. */
+declare function watchContractEvent(client: PublicClient, args: WatchContractEventParameters): Unwatch;
+/** Watch the mempool for pending transaction hashes. Returns viem's `unwatch`. */
+declare function watchPendingTransactions(client: PublicClient, args: WatchPendingTransactionsParameters): Unwatch;
+
+/**
+ * `@qorechain/evm` — a thin, type-safe adapter over [viem](https://viem.sh) for
+ * the QoreChain EVM Engine.
+ *
+ * It does not reimplement an EVM client; viem is a peer dependency. This package
+ * adds QoreChain-specific conveniences: a chain-aware client factory with EVM
+ * chain-id auto-detection, ERC-20 helpers, contract deploy/call wrappers, and
+ * typed bindings for QoreChain's EVM precompiles.
+ */
+/** Package version. */
+declare const VERSION = "0.3.0";
+
+export { type AiAnomalyCheck, type AiAnomalyCheckArgs, type AiRiskScore, type ConsensusParams, type CreateEvmClientOptions, type CreateEvmSubscriptionClientOptions, type DecodedEvmError, type DeployContractArgs, ERC1155_ABI, ERC20_ABI, ERC721_ABI, type Eip1193Provider, type Eip1559Fees, type Eip6963ProviderDetail, type Erc20Metadata, type Erc721Metadata, type EvmClient, type EvmEndpoints, type EvmNetworkInfo, type EvmWalletConnection, type EvmWsEndpoints, type GetEvmWalletClientOptions, IQORE_AI_ABI, IQORE_CONSENSUS_ABI, IQORE_PQC_ABI, PRECOMPILE_ADDRESSES, type PqcKeyStatus, type PqcVerifyArgs, type Unwatch, VERSION, addQoreChainNetwork, aiAnomalyCheck, aiRiskScore, allowance, approve$1 as approve, balanceOf$2 as balanceOf, createEvmClient, createEvmSubscriptionClient, decodeEvmError, deployContract, discoverEvmProviders, erc1155, erc20, erc721, estimateEip1559Fees, evmAccountFromPrivateKey, fees, gasPrice, getEvmWalletClient, metadata$1 as metadata, pqcKeyStatus, pqcVerify, precompiles, readContract, requestAccounts, rlConsensusParams, switchChain, toHexChainId, transfer, watchBlocks, watchContractEvent, watchEvent, watchPendingTransactions, writeContract };