Chore/harmonize cli

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 The Witnet Project
+Copyright (c) 2025 The Witnet Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1 +1,198 @@
 # Wit/Oracle Ethers SDK and CLI tools
+
+The **Wit/Oracle Ethers SDK** allows you to easily interact with the set of Wit/Oracle appliances deployed on a wide selection of **EVM-compatible ecosystems**, from offchain environments like workstations, Web3 applications, automation scripts, or web services. 
+
+It also allows the interaction with Witnet-aware consuming contracts, so real-world data can get pushed into these contracts only when estrictly needed.
+
+## ✨ Overview
+
+This package contains:
+
+- A **CLI binary** (`npx witeth`) to interact with the Wit/Oracle Framework contracts on supported EVM networks, as to:
+  - List supported ecosystems and chains where the Wit/Oracle Contract Framework is available.
+  - List addresses of the Wit/Oracle Framework artifacts for each supported chain.
+  - Build, leverage, test and deploy your own customized Witnet-compliant data queries. 
+  - Show latest updates of the price feeds subsidized by the Witnet Foundation on each supported chain.
+  - Show latest data queries actively pulled from smart contracts via the Wit/Oracle Framework.
+  - Show latest randomize requests posted to Wit/Randomness contracts. 
+  - Force randomize requests into specific Wit/Randomness contracts. 
+  - Show latest data reports recently pushed into specific Witnet-aware consuming contracts. 
+  - Push notarized data on Witnet into specific Witnet-aware consuming contracts.
+  - Build Solidity contracts capable of interacting with the Wit/Oracle Framework contracts. 
+
+- A **Javascript library** allowing scripts to introspect the set of supported networks, ABIs, addresses and settings, as well as deployed Radon assets. It provides also wrapping Javascript classes for interacting with the Wit/Oracle Framework artifacts.
+
+> *This package imports as a runtime dependency the [**Witnet SDK**](https://github.com/witnet/witnet-toolkit) package, so both the SDK library and the CLI binary (`npx witsdk`) get installed and ready to use right out of the box.*
+
+## 📦 Installation
+
+```bash
+$ npm install --save @witnet/ethers
+```
+
+### Interact with Wit/Oracle appliances on EVM-compatible networks
+  ```typescript
+  import { assets, ethers, utils, WitOracle } from "@witnet/ethers"
+  ```
+### Interact with the Witnet network by using the embedded Witnet SDK library
+  ```typescript
+  import { assets, utils, Witnet } from "@witnet/ethers"
+  ```
+
+## ⚙️ Requirements
+
+- Node.js >= 20
+- Sufficient balance of the EVM's gas currency for transacting in your preferred EVM-compatible network.
+- Sufficient $WIT balance for notarizing real-world data requests in Witnet. 
+
+## 🔧 Configuration
+
+Both the CLI and the Javascript library can be configured using a **.env** file or by setting this environment variable:
+```bash
+  ETHRPC_PRIVATE_KEYS=["your_eth_private_key_1", ..., "your_eth_private_key_n"]
+```
+Additionally, you can settle your preferred ETH/RPC provider when launching the local gateway (see below).
+
+## 🧪 Supported EVM-compatible Networks
+
+> *Please, visit the [Witnet Docs site](https://docs.witnet.io/smart-contracts/supported-chains) to get an up-to-date list of supported EVM chains.*
+
+## 🛠️ Usage
+
+### CLI binary
+
+```bash
+$ npx witeth <command> [<args>] [<flags>] [<options>] [--help]
+```
+
+> *You need to have a local **ETH/RPC gateway** running in order to get access to extra commands. You will only be able to interact with the Wit/Oracle appliances if you connect to a supported EVM network first.*
+
+----
+#### `npx witeth networks`
+Lists EVM networks where the Wit/Oracle Contract Framework is supported.
+
+**Flags**:
+- `--mainnets`: Just list the mainnets.
+- `--testnets`: Just list the testnets.
+
+----
+#### `npx witeth gateway <evm_network>`
+Launches a local ETH/RPC signing gateway to the specified `evm_network`, listening on port 8545 if no otherwise specified.
+
+**Options**:
+  - `--port`: Port where the new gateway should be listening on.
+  - `--remote`: URL of the ETH/RPC remote provider to use instead of the gateway's default for the specified network. 
+
+> *Launch a gateway to your preferred EVM network on a different terminal so you can augment the available commands of the `witeth` CLI binary. If you launch the gateway on a port other than default's, you'll need to specify `--port <PORT>` when invoking other commands of the `witeth` binary.*
+
+----
+#### `npx witeth accounts`
+Lists set of local EVM signing addresses set up in the gateway, as well as their current balance of the EVM's native currency. 
+
+----
+#### `npx witeth assets [<radon_assets> ..]`
+Shows the Radon assets within your project that have been formally verified and deployed into the connected EVM network. It also allows you to verify and deploy additional Radon assets.
+
+**Flags**:
+- `--all`: List all available Radon assets, even if not yet deployed.
+- `--decode`: Decode selected Radon assets, using the currently deployed bytecode.
+- **`--deploy`**: Deploy or replace the selected assets, on the current EVM network.
+- `--dry-run`: Dry-run selected Radon assets, using the currently deployed bytecode (superseded `--decode`).
+- `--legacy`: Filter Radon assets to those declared within the **witnet/assets** folder of your project.
+
+**Options**:
+- `--module`: Specify the NPM package where to fetch declared Radon assets from (supersedes `--legacy`).
+- `--signer`: EVM signer address to use when deploying Radon assets, other than the gateway's default.
+
+----
+#### `npx witeth contracts`
+Lists addresses of all available Wit/Oracle Framework artifacts.
+
+**Flags**:
+- `--templates`: Include parameterized Radon templates deployed specifically for this project, if any.
+
+----
+#### `npx witeth priceFeeds`
+Shows latest updates of the price feeds supported by the specified Wit/PriceFeeds appliance.
+
+For each price feed the following data is shown:
+- The symbol (e.g. Price-ETH/USD-6).
+- Last updated price.
+- Time elapsed since the last price update.
+- API's where price updates are extract from, and aggregated together.
+
+**Flags**:
+- `--trace-back`: Trace witnessing acts on Witnet that actually provided latest updates for each price feed.
+
+----
+#### `npx witeth queries`
+Shows latest Wit/Oracle queries actively pulled from smart contracts.
+
+**Flags**:
+- `--voids`: Include queries that got eventually deleted by their respective requesters.
+- `--trace-back`: Trace the witnessing acts on Witnet that attended each listed query. 
+
+**Options**:
+- `--filter-radHash`: Filter queries referring specified RAD hash.
+- `--filter-requester`: Filter queries triggered from the specified EVM address.
+- `--since`: List queries since the specified EVM block number (default: -5000).
+- `--limit`: Limit number of listed records (default: 64).
+- `--offset`: Filter first records before listing.
+
+----
+#### `npx witeth randomness`
+Shows randomize requests posted on the selected Wit/Randomness appliance. It also allows to force new randomize requests.
+
+**Flags**:
+- **`--randomize`**: Pay for a new randomize request.
+- `--trace-back`: Trace the witnessing acts on Witnet that ultimately provided randomness for each randomization request.
+
+**Options**:
+- `--since`: List randomize requests since the specified EVM block number (default: -5000).
+- `--limit`: Limit number of listed records (default: 64).
+- `--offset`: Filter first records before listing.
+- `--gasPrice`: Max. EVM gas price when requesting a new randomize.
+- `--signer`: EVM signer address that will pay for the new randomize, other than gateway's default.
+
+----
+#### `npx witeth reports`
+Shows verified data reports pushed into `IWitOracleConsumer` contracts. It also allows to push the results of Witnet-notarized queries into consuming contracts (no fees required).
+
+**Flags**:
+- `--parse`: Decode the CBOR-encoded data that got reported. 
+- `--trace-back`: Trace the notarized query on Witnet that produced the reported data. 
+
+**Options**:
+- `--filter-consumer`: Only show data reported into the specified EVM address.
+- `--filter-requester`: Only show data reported from the specified EVM address.
+- `--since`: List pushed data reports since the specified EVM block number (default: -5000).
+- `--limit`: Limit number of listed records (default: 64).
+- `--offset`: Filter first records before listing.
+- **`--push`**: Push the result to some finalized query in Witnet.
+- `--into`: The EVM address where to push the data query result.
+
+---
+### Javascript library
+> *Please, find Javascript and Typescript code snippets in the [Witnet Docs site](https://docs.witnet.io/).*
+
+## 🧱 Built With
+- Axios
+- Ethers v6
+- [ETH/RPC Gateway](https://npmjs.com/ethrpc-gateway) 
+- Node.js
+- [Witnet SDK](https://npmjs.com/@witnet/sdk)
+- [Witnet Solidity Bridge](https://npmjs.com/witnet-solidity-bridge)
+
+## 🔐 Security
+- Do not share your private keys.
+- Use trusted RPC endpoints when using third-party providers.
+
+## 📚 Documentation
+Learn more about Witnet, the $WIT coin and the Wit/Oracle Appliance Framework for smart contracts at:
+
+👉 https://docs.witnet.io 
+👉 https://witnet.io 
+👉 https://witnet.foundation/
+
+## 🧾 License
+MIT © 2025 — Maintained by the [Witnet Project](https://github.com/witnet).

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@witnet/ethers",
-  "version": "1.0.3",
-  "description": "Wit/Oracle SDK Framework package for Solidity projects",
+  "version": "1.0.4",
+  "description": "Wit/Oracle Ethers SDK Framework package for EVM-compatible projects",
   "author": "Witnet Foundation",
   "license": "MIT",
   "repository": {
@@ -51,7 +51,7 @@
     "truffle"
   ],
   "dependencies": {
-    "@witnet/sdk": "^1.0.12",
+    "@witnet/sdk": "^1.0.15",
     "axios": "^1.11.0",
     "cbor": "^10.0.10",
     "cross-env": "^7.0.3",
@@ -62,7 +62,7 @@
     "json-bigint": "^1.0.0",
     "lodash.merge": "^4.6.2",
     "moment": "^2.30.1",
-    "witnet-solidity-bridge": "~2.1.11"
+    "witnet-solidity-bridge": "^2.1.11"
   },
   "devDependencies": {
     "@types/lodash.merge": "^4.6.9",

src/bin/cli/accounts.js

@@ -0,0 +1,42 @@
+const helpers = require("../helpers")
+const { WitOracle } = require("../../../dist/src/lib")
+
+module.exports = async function (flags = {}) {
+  const witOracle = await WitOracle.fromJsonRpcUrl(
+    `http://127.0.0.1:${flags?.port || 8545}`,
+  )
+
+  const { provider, network } = witOracle
+  helpers.traceHeader(`${network.toUpperCase()}`, helpers.colors.lcyan)
+
+  const signers = await provider.listAccounts()
+  const records = []
+  let totalEth = 0n
+  records.push(
+    ...await Promise.all(signers.map(async signer => {
+      const eth = await provider.getBalance(signer.address)
+      totalEth += eth
+      return [signer.address, eth]
+    }))
+  )
+  records.push(["", totalEth])
+
+  helpers.traceTable(
+    records.map(([address, eth], index) => {
+      eth = Number(Number(eth) / 10 ** 18).toFixed(10)
+      return [
+        address !== "" ? index : "",
+        address,
+        address !== "" ? helpers.colors.yellow(helpers.commas(eth)) : helpers.colors.myellow(helpers.commas(eth)),
+      ]
+    }), {
+      headlines: [
+        "INDEX",
+        "EVM SIGNER ADDRESSES",
+        `$${helpers.colors.lwhite("ETH")} BALANCE`,
+      ],
+      humanizers: [helpers.commas,,],
+      colors: [, helpers.colors.mblue],
+    }
+  )
+}

src/bin/cli/contracts.js

@@ -5,7 +5,7 @@ const { utils } = require("../../../dist/src/lib")
 const deployables = helpers.readWitnetJsonFiles("templates")
 
 module.exports = async function (flags = {}, params = []) {
-  const [args] = helpers.deleteExtraFlags(params)
+  let [args] = helpers.deleteExtraFlags(params)
 
   let provider
   try {
@@ -41,6 +41,8 @@ module.exports = async function (flags = {}, params = []) {
           })
       )
     }
+  } else if (!args || args.length === 0) {
+    args = ["WitOracle"]
   }
   helpers.traceHeader(`${network.toUpperCase()}`, helpers.colors.lcyan)
   const addrs = helpers.orderKeys(Object.fromEntries(

src/bin/cli/gateway.js

@@ -17,7 +17,7 @@ module.exports = async function (flags = {}, args = []) {
         "ethrpc",
         network,
         flags?.port || 8545,
-        flags?.provider,
+        flags?.remote,
       ],
       { shell: true }
     )

src/bin/cli/networks.js

@@ -1,29 +1,43 @@
 const helpers = require("../helpers")
 
-// const WITNET_ASSETS_PATH = process.env.WITNET_SOLIDITY_ASSETS_RELATIVE_PATH || "../../../../../witnet/assets"
-// const assets = require(`${WITNET_ASSETS_PATH}`)
-
 const { supportedNetworks } = require("witnet-solidity-bridge")
 
-module.exports = async function (flags = {}, args = []) {
-  [args] = helpers.deleteExtraFlags(args)
+module.exports = async function (flags = {}, [ecosystem]) {
   const networks = Object.fromEntries(
     Object.entries(supportedNetworks())
-      .filter(([network, config]) => {
-        return (!args || !args[0] || network.indexOf(args[0].toLowerCase()) >= 0) && (
+      .filter(([, config]) => {
+        return (
           !flags ||
             (flags?.mainnets && config.mainnet) ||
             (flags?.testnets && !config.mainnet) ||
             (!flags?.mainnets && !flags?.testnets)
         )
       }).map(([network, config]) => [
         network, {
-          Mainnet: config?.mainnet,
-          "Network id": config?.network_id,
-          "Gateway port": config?.port,
-          "Contracts verification explorer URL": config?.verified,
+          browser: config?.verified,
+          id: config?.network_id,
+          mainnet: config?.mainnet,
+          match: ecosystem && network.toLowerCase().indexOf(ecosystem.toLowerCase()) > -1,
+          name: network,
+          symbol: config?.symbol,
         },
       ])
   )
-  console.table(networks)
+  helpers.traceTable(
+    Object.values(networks).map(network => [
+      network.match ? helpers.colors.mcyan(network.name) : helpers.colors.cyan(network.name),
+      network.match ? helpers.colors.lwhite(network.symbol) : helpers.colors.white(network.symbol),
+      network.id,
+      network.match ? helpers.colors.white(network.browser) : helpers.colors.gray(network.browser),
+    ]), {
+      headlines: [
+        ":Network",
+        "Symbol",
+        "Network Id",
+        ":Verified Block Explorer",
+      ],
+      humanizers: [,, helpers.commas],
+      colors: [,, helpers.colors.yellow, ],
+    }
+  )
 }