@qorechain/evm 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -285,6 +285,18 @@ declare const PRECOMPILE_ADDRESSES: {
     /** Consensus parameters (`IQoreConsensus.rlConsensusParams`). */
     readonly rlConsensusParams: "0x0000000000000000000000000000000000000C01";
 };
+/**
+ * Fixed address of the AI transaction risk-score precompile (`IQoreAI.aiRiskScore`).
+ *
+ * Convenience alias of {@link PRECOMPILE_ADDRESSES.aiRiskScore}.
+ */
+declare const AI_RISK_SCORE_ADDRESS: Address;
+/**
+ * Fixed address of the AI anomaly-check precompile (`IQoreAI.aiAnomalyCheck`).
+ *
+ * Convenience alias of {@link PRECOMPILE_ADDRESSES.aiAnomalyCheck}.
+ */
+declare const AI_ANOMALY_CHECK_ADDRESS: Address;
 /** Arguments for {@link pqcVerify}. */
 interface PqcVerifyArgs {
     pubkey: Hex;
@@ -307,7 +319,7 @@ interface AiRiskScore {
     level: number;
 }
 /** Compute an on-chain risk score for raw transaction data. */
-declare function aiRiskScore(client: PublicClient, txData: Hex): Promise<AiRiskScore>;
+declare function aiRiskScore$1(client: PublicClient, txData: Hex | Uint8Array): Promise<AiRiskScore>;
 /** Arguments for {@link aiAnomalyCheck}. */
 interface AiAnomalyCheckArgs {
     sender: Address;
@@ -319,7 +331,7 @@ interface AiAnomalyCheck {
     flagged: boolean;
 }
 /** Check whether a (sender, amount) pair is anomalous. */
-declare function aiAnomalyCheck(client: PublicClient, { sender, amount }: AiAnomalyCheckArgs): Promise<AiAnomalyCheck>;
+declare function aiAnomalyCheck$1(client: PublicClient, { sender, amount }: AiAnomalyCheckArgs): Promise<AiAnomalyCheck>;
 /** Result of {@link rlConsensusParams}. */
 interface ConsensusParams {
     blockTime: bigint;
@@ -333,9 +345,122 @@ declare function rlConsensusParams(client: PublicClient): Promise<ConsensusParam
 declare const precompiles: {
     readonly pqcVerify: typeof pqcVerify;
     readonly pqcKeyStatus: typeof pqcKeyStatus;
+    readonly aiRiskScore: typeof aiRiskScore$1;
+    readonly aiAnomalyCheck: typeof aiAnomalyCheck$1;
+    readonly rlConsensusParams: typeof rlConsensusParams;
+};
+
+/**
+ * AI pre-flight risk scoring — a QoreChain-unique capability.
+ *
+ * QoreChain ships an on-chain inference engine (QCAI) exposed to the EVM through
+ * two read-only precompiles. Any dApp can score a transaction *before* it is
+ * broadcast, using nothing but `eth_call`s, and combine that with a gas estimate
+ * to make an informed, policy-driven decision off-chain.
+ *
+ *  - {@link aiRiskScore} — a model-derived risk score + bucketed level for raw
+ *    transaction calldata (precompile `0x..0B01`).
+ *  - {@link aiAnomalyCheck} — an anomaly score + boolean flag for a
+ *    `(sender, amount)` pair (precompile `0x..0B02`).
+ *  - {@link simulateWithRiskScore} — one call that bundles a gas estimate, a risk
+ *    score, and an anomaly check into a single advisory verdict.
+ *
+ * These bindings re-use the precompile address constants and ABIs in
+ * `./precompiles` / `./abi`. They expose the *high-level, positional-argument*
+ * surface the SDK documents; the namespaced `precompiles.*` bindings remain the
+ * low-level form.
+ *
+ * Availability note: on a default or community node these precompiles may return
+ * a "not available" error; they are available on QoreChain network nodes. Treat a
+ * thrown error from any of these helpers as "feature not present on this node".
+ */
+
+/**
+ * Risk level at which {@link simulateWithRiskScore} stops reporting a transaction
+ * as `safe`. The chain's example policy uses `require(level < 3)`, so a level of
+ * `3` or above is treated as unsafe here.
+ *
+ * This threshold is **advisory**. The precompiles do not block anything on their
+ * own — an off-chain dApp should pick and enforce its own policy (and a contract
+ * can enforce its own on-chain `require`). It is exported so callers can reference
+ * the same default the SDK documents.
+ */
+declare const RISK_LEVEL_UNSAFE_THRESHOLD = 3;
+/**
+ * Compute an on-chain risk score for raw transaction calldata.
+ *
+ * Issues an `eth_call` against the AI risk-score precompile, encoding
+ * `aiRiskScore(bytes)` and decoding the `(uint256 score, uint8 level)` tuple.
+ * Higher `level` means riskier (the chain's example policy uses `level < 3`).
+ *
+ * @param client - A viem public client bound to a QoreChain EVM endpoint.
+ * @param txData - The transaction calldata, as hex or raw bytes.
+ */
+declare function aiRiskScore(client: PublicClient, txData: Hex | Uint8Array): Promise<AiRiskScore>;
+/**
+ * Check whether a `(sender, amount)` pair is anomalous.
+ *
+ * Issues an `eth_call` against the AI anomaly-check precompile, encoding
+ * `aiAnomalyCheck(address,uint256)` and decoding the
+ * `(uint256 anomalyScore, bool flagged)` tuple.
+ *
+ * @param client - A viem public client bound to a QoreChain EVM endpoint.
+ * @param sender - The transaction sender to evaluate.
+ * @param amount - The transferred value (in wei) to evaluate.
+ */
+declare function aiAnomalyCheck(client: PublicClient, sender: Address, amount: bigint): Promise<AiAnomalyCheck>;
+/** A transaction shape for {@link simulateWithRiskScore}. */
+interface PreflightTx {
+    /** The sender address (used for the anomaly check and gas estimate). */
+    from: Address;
+    /** The destination address (optional for contract-creation txs). */
+    to?: Address;
+    /** The transaction calldata, if any. */
+    data?: Hex;
+    /** The value to transfer, in wei. Defaults to `0`. */
+    value?: bigint;
+}
+/** The combined result of {@link simulateWithRiskScore}. */
+interface PreflightResult {
+    /** Estimated gas for the transaction (`eth_estimateGas`). */
+    gas: bigint;
+    /** On-chain risk score for the transaction calldata. */
+    risk: AiRiskScore;
+    /** On-chain anomaly check for `(from, value)`. */
+    anomaly: AiAnomalyCheck;
+    /**
+     * Advisory verdict: `risk.level < RISK_LEVEL_UNSAFE_THRESHOLD && !anomaly.flagged`.
+     *
+     * This is a convenience signal only; enforce your own policy (see
+     * {@link RISK_LEVEL_UNSAFE_THRESHOLD}).
+     */
+    safe: boolean;
+}
+/**
+ * Run an AI pre-flight on a transaction: estimate gas, score its risk, and check
+ * for anomalies — all read-only, before anything is signed or broadcast.
+ *
+ * This is a first-in-industry capability: the risk model runs *on-chain* and is
+ * reachable from any dApp via plain `eth_call`/`eth_estimateGas`. The returned
+ * `safe` flag is **advisory** — off-chain dApps should set and enforce their own
+ * policy (and contracts can `require` on the level on-chain).
+ *
+ *  - `gas` — `eth_estimateGas` for the transaction.
+ *  - `risk` — {@link aiRiskScore} over `tx.data` (or, when absent, the deployed
+ *    bytecode at `tx.to`, so a plain transfer to a contract is still scored).
+ *  - `anomaly` — {@link aiAnomalyCheck} over `(tx.from, tx.value ?? 0)`.
+ *  - `safe` — `risk.level < {@link RISK_LEVEL_UNSAFE_THRESHOLD} && !anomaly.flagged`.
+ *
+ * @param client - A viem public client bound to a QoreChain EVM endpoint.
+ * @param tx - The transaction to evaluate.
+ */
+declare function simulateWithRiskScore(client: PublicClient, tx: PreflightTx): Promise<PreflightResult>;
+/** Namespaced AI pre-flight helpers. */
+declare const ai: {
     readonly aiRiskScore: typeof aiRiskScore;
     readonly aiAnomalyCheck: typeof aiAnomalyCheck;
-    readonly rlConsensusParams: typeof rlConsensusParams;
+    readonly simulateWithRiskScore: typeof simulateWithRiskScore;
+    readonly RISK_LEVEL_UNSAFE_THRESHOLD: 3;
 };
 
 /**
@@ -1140,6 +1265,6 @@ declare function watchPendingTransactions(client: PublicClient, args: WatchPendi
  * typed bindings for QoreChain's EVM precompiles.
  */
 /** Package version. */
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.5.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 };
+export { AI_ANOMALY_CHECK_ADDRESS, AI_RISK_SCORE_ADDRESS, 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 PreflightResult, type PreflightTx, RISK_LEVEL_UNSAFE_THRESHOLD, type Unwatch, VERSION, addQoreChainNetwork, ai, 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, simulateWithRiskScore, switchChain, toHexChainId, transfer, watchBlocks, watchContractEvent, watchEvent, watchPendingTransactions, writeContract };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { http, createPublicClient, defineChain, createWalletClient, custom, BaseError, ContractFunctionRevertedError, decodeErrorResult, getAddress, webSocket } from 'viem';
+import { http, createPublicClient, defineChain, encodeFunctionData, getAddress, decodeFunctionResult, createWalletClient, custom, BaseError, ContractFunctionRevertedError, decodeErrorResult, toHex, webSocket } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 
 // src/client.ts
@@ -724,6 +724,11 @@ var PRECOMPILE_ADDRESSES = {
   /** Consensus parameters (`IQoreConsensus.rlConsensusParams`). */
   rlConsensusParams: "0x0000000000000000000000000000000000000C01"
 };
+var AI_RISK_SCORE_ADDRESS = PRECOMPILE_ADDRESSES.aiRiskScore;
+var AI_ANOMALY_CHECK_ADDRESS = PRECOMPILE_ADDRESSES.aiAnomalyCheck;
+function toHexData(data) {
+  return typeof data === "string" ? data : toHex(data);
+}
 var addr = (a) => getAddress(a);
 function pqcVerify(client, { pubkey, signature, message }) {
   return client.readContract({
@@ -747,7 +752,7 @@ async function aiRiskScore(client, txData) {
     address: addr(PRECOMPILE_ADDRESSES.aiRiskScore),
     abi: IQORE_AI_ABI,
     functionName: "aiRiskScore",
-    args: [txData]
+    args: [toHexData(txData)]
   });
   return { score, level };
 }
@@ -775,6 +780,69 @@ var precompiles = {
   aiAnomalyCheck,
   rlConsensusParams
 };
+var RISK_LEVEL_UNSAFE_THRESHOLD = 3;
+function toHexData2(data) {
+  return typeof data === "string" ? data : toHex(data);
+}
+async function aiRiskScore2(client, txData) {
+  const data = encodeFunctionData({
+    abi: IQORE_AI_ABI,
+    functionName: "aiRiskScore",
+    args: [toHexData2(txData)]
+  });
+  const result = await client.call({
+    to: getAddress(AI_RISK_SCORE_ADDRESS),
+    data
+  });
+  const [score, level] = decodeFunctionResult({
+    abi: IQORE_AI_ABI,
+    functionName: "aiRiskScore",
+    data: result.data ?? "0x"
+  });
+  return { score, level };
+}
+async function aiAnomalyCheck2(client, sender, amount) {
+  const data = encodeFunctionData({
+    abi: IQORE_AI_ABI,
+    functionName: "aiAnomalyCheck",
+    args: [sender, amount]
+  });
+  const result = await client.call({
+    to: getAddress(AI_ANOMALY_CHECK_ADDRESS),
+    data
+  });
+  const [anomalyScore, flagged] = decodeFunctionResult({
+    abi: IQORE_AI_ABI,
+    functionName: "aiAnomalyCheck",
+    data: result.data ?? "0x"
+  });
+  return { anomalyScore, flagged };
+}
+async function simulateWithRiskScore(client, tx) {
+  const value = tx.value ?? 0n;
+  let riskData = tx.data ?? "0x";
+  if ((riskData === "0x" || riskData.length <= 2) && tx.to) {
+    riskData = await client.getCode({ address: tx.to }).then((c) => c ?? "0x");
+  }
+  const [gas, risk, anomaly] = await Promise.all([
+    client.estimateGas({
+      account: tx.from,
+      to: tx.to,
+      data: tx.data,
+      value
+    }),
+    aiRiskScore2(client, riskData),
+    aiAnomalyCheck2(client, tx.from, value)
+  ]);
+  const safe = risk.level < RISK_LEVEL_UNSAFE_THRESHOLD && !anomaly.flagged;
+  return { gas, risk, anomaly, safe };
+}
+var ai = {
+  aiRiskScore: aiRiskScore2,
+  aiAnomalyCheck: aiAnomalyCheck2,
+  simulateWithRiskScore,
+  RISK_LEVEL_UNSAFE_THRESHOLD
+};
 function resolveProvider(provider) {
   if (provider) return provider;
   if (typeof window === "undefined") {
@@ -960,8 +1028,8 @@ function watchPendingTransactions(client, args) {
 }
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.5.0";
 
-export { ERC1155_ABI, ERC20_ABI, ERC721_ABI, IQORE_AI_ABI, IQORE_CONSENSUS_ABI, IQORE_PQC_ABI, PRECOMPILE_ADDRESSES, VERSION, addQoreChainNetwork, aiAnomalyCheck, aiRiskScore, allowance, approve, balanceOf, createEvmClient, createEvmSubscriptionClient, decodeEvmError, deployContract, discoverEvmProviders, erc1155, erc20, erc721, estimateEip1559Fees, evmAccountFromPrivateKey, fees, gasPrice, getEvmWalletClient, metadata, pqcKeyStatus, pqcVerify, precompiles, readContract, requestAccounts, rlConsensusParams, switchChain, toHexChainId, transfer, watchBlocks, watchContractEvent, watchEvent, watchPendingTransactions, writeContract };
+export { AI_ANOMALY_CHECK_ADDRESS, AI_RISK_SCORE_ADDRESS, ERC1155_ABI, ERC20_ABI, ERC721_ABI, IQORE_AI_ABI, IQORE_CONSENSUS_ABI, IQORE_PQC_ABI, PRECOMPILE_ADDRESSES, RISK_LEVEL_UNSAFE_THRESHOLD, VERSION, addQoreChainNetwork, ai, aiAnomalyCheck2 as aiAnomalyCheck, aiRiskScore2 as aiRiskScore, allowance, approve, balanceOf, createEvmClient, createEvmSubscriptionClient, decodeEvmError, deployContract, discoverEvmProviders, erc1155, erc20, erc721, estimateEip1559Fees, evmAccountFromPrivateKey, fees, gasPrice, getEvmWalletClient, metadata, pqcKeyStatus, pqcVerify, precompiles, readContract, requestAccounts, rlConsensusParams, simulateWithRiskScore, switchChain, toHexChainId, transfer, watchBlocks, watchContractEvent, watchEvent, watchPendingTransactions, writeContract };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map