@witnet/sdk 1.0.0-beta.0

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@witnet/sdk",
+  "version": "1.0.0-beta.0",
+  "description": "Typescript library and CLI tooling for Web3 buidlers willing to interact with the Witnet blockchain.",
+  "author": "Witnet Foundation",
+  "license": "MIT",
+  "private": false,
+  "type": "commonjs",
+  "bin": {
+    "witnet": "src/bin/toolkit.js",
+    "witnet-toolkit": "src/bin/toolkit.js"
+  },
+  "files": [
+    "dist",
+    "src/bin",
+    "src/lib/cli",
+    "src/lib/helpers.js",
+    "witnet/witnet.proto.json",
+    "witnet/assets"
+  ],
+  "exports": {
+    ".": {
+      "require": "./dist/src/index.js",
+      "default": "./dist/src/index.js",
+      "types": "./dist/src/*.d.ts"
+    },
+    "./assets": "./dist/witnet/assets/index.js",
+    "./utils": {
+      "require": "./dist/src/lib/utils.js",
+      "default": "./dist/src/lib/utils.js",
+      "types": "./dist/src/lib/*.d.ts"
+    }
+  },
+  "types": "./dist",
+  "scripts": {
+    "build": "pbjs --target json witnet/witnet.proto -o witnet/witnet.proto.json && tsc -p tsconfig.json",
+    "fmt": "eslint --ext .js,.cjs . --ignore-path .gitignore --ignore-pattern _*",
+    "fmt!": "eslint --ext .js,.cjs . --fix --ignore-path .gitignore --ignore-pattern _*",
+    "postinstall": "node src/bin/postinstall.js",
+    "prepare": "pnpm run build",
+    "test": "cross-env-shell WITNET_SDK_RADON_ASSETS_PATH='../../../witnet/assets' node ./src/bin/toolkit.js"
+  },
+  "dependencies": {
+    "axios": "^1.7.9",
+    "bech32": "~2.0.0",
+    "bip32": "^4.0.0",
+    "cbor": "^10.0.3",
+    "dotenv": "^16.4.1",
+    "graphql-query-compress": "1.2.4",
+    "inquirer": "^12.4.2",
+    "json-bigint": "^1.0.0",
+    "lodash.merge": "^4.6.2",
+    "long": "^5.3.2",
+    "moment": "^2.30.1",
+    "promise-poller": "~1.9.1",
+    "protobufjs": "^7.4.0",
+    "qrcode-terminal": "^0.12.0",
+    "secp256k1": "^5.0.1",
+    "tiny-secp256k1": "~2.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "cross-env": "7.0.3",
+    "eslint": "8.56.0",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-n": "^17.15.0",
+    "eslint-plugin-promise": "^7.2.1",
+    "protobufjs-cli": "^1.1.3",
+    "typescript": "^5.7.2"
+  }
+}

package/src/bin/cli/history.js

@@ -0,0 +1,31 @@
+/// ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/// CLI SUBMODULE CONSTANTS ===========================================================================================
+
+module.exports = {
+  flags: {
+    start: {
+      hint: "Epoch from which search starts (default: -2048).",
+      param: ":epoch",
+    },
+    end: {
+      hint: "Epoch on which search ends (default: -1).",
+      param: ":epoch",
+    },
+    limit: { hint: "Limit output records (default: 100).", param: ":number" },
+  },
+  router: {
+    miners: {
+      hint: "Report most successful miners.",
+    },
+    requests: {
+      hint: "Report most successful data requests.",
+    },
+    witnesses: {
+      hint: "Report most successful witnesses.",
+    },
+  },
+  subcommands: {},
+}
+
+/// ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/// CLI SUBMODULE COMMANDS ============================================================================================

package/src/bin/cli/inspect.js

@@ -0,0 +1,359 @@
+const moment = require("moment")
+
+const helpers = require("../helpers")
+const { utils, Witnet } = require("../../../dist/src")
+
+const { cyan, gray, green, lyellow, magenta, mgreen, mmagenta, myellow, yellow } = helpers.colors
+
+/// ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/// CLI SUBMODULE CONSTANTS ===========================================================================================
+
+module.exports = {
+  envars: {
+    WITNET_SDK_PROVIDER_URL: "=> Wit/Oracle RPC provider(s) to connect to, if no otherwise specified.",
+  },
+  flags: {
+    provider: {
+      hint: "Public Wit/Oracle JSON-RPC provider, other than default.",
+      param: ":http-url",
+    },
+    verbose: {
+      hint: "Outputs validators' nonce and last validation epochs.",
+    },
+  },
+  router: {
+    balance: {
+      hint: "Show available Wits on given address.",
+      params: "WIT_ADDRESS",
+    },
+    block: {
+      hint: "Get block data given its block hash.",
+      params: "BLOCK_HASH",
+    },
+    dataRequest: {
+      hint: "Report resolution workflow for the specified data request transaction.",
+      params: "DR_TX_HASH",
+    },
+    "dataRequests*": {
+      hint: "Search for in-flight or recently solved data request transactions.",
+      params: "BYTECODE | RAD_HASH | DDR_HASH",
+      options: {
+        limit: { hint: "Limit output records (default: 100).", param: "LIMIT" },
+        since: {
+          hint: "Number of past epochs to search for (default: 256; max: 2048).",
+          param: "EPOCH|MINUS_EPOCHS",
+        },
+        "min-unitary-reward": {
+          hint: "Filters out those providing less unitary reward than specified.",
+          param: "NANOWITS",
+        },
+        "min-witnesses": {
+          hint: "Filters out those solved with less than specified witnesses.",
+          param: "NUM_WITNESSES",
+        },
+      },
+    },
+    superblock: {
+      hint: "Show superblock metadata for given epoch.",
+      params: "EPOCH",
+    },
+    transaction: {
+      hint: "Report transaction details given its transaction hash.",
+      params: "TX_HASH",
+    },
+    validators: {
+      hint: "List validators treasuring delegated stake from the specified address.",
+      params: "WIT_ADDRESS",
+    },
+    withdrawers: {
+      hint: "List withdrawers currently delegating stake to the specified address.",
+      params: "WIT_ADDRESS",
+    },
+    utxos: {
+      hint: "List UTXOs available to the specified address.",
+      params: "WIT_ADDRESS",
+      options: {
+        "small-first": {
+          hint: "Outputs smallest UTXOs first (default: false).",
+        },
+      },
+    },
+  },
+  subcommands: {
+    balance, block, dataRequest, superblock, transaction, validators, withdrawers, utxos,
+  },
+}
+
+/// ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/// CLI SUBMODULE COMMANDS ============================================================================================
+
+async function balance (options = {}, args = []) {
+  if (args.length === 0) {
+    throw Error("No WIT_ADDRESS was specified")
+  }
+  const pkh = args[0]
+  const provider = new Witnet.JsonRpcProvider(options?.provider)
+  const balance = await provider.getBalance(pkh)
+  const records = []
+  records.push([
+    Witnet.Coins.fromNanowits(balance.locked).wits,
+    Witnet.Coins.fromNanowits(balance.staked).wits,
+    Witnet.Coins.fromNanowits(balance.unlocked).wits,
+    Witnet.Coins.fromNanowits(balance.locked + balance.staked + balance.unlocked).wits,
+  ])
+  helpers.traceTable(records, {
+    headlines: ["Locked ($WIT)", "Staked ($WIT)", "Available ($WIT)", "BALANCE ($WIT)"],
+    humanizers: [helpers.commas, helpers.commas, helpers.commas, helpers.commas],
+    colors: [gray, yellow, myellow, lyellow],
+  })
+}
+
+async function block (options = {}, args = []) {
+  if (args.length === 0) {
+    throw Error("No BLOCK_HASH was specified")
+  }
+  const blockHash = args[0].startsWith("0x") ? args[0].slice(2) : args[0]
+  if (!helpers.isHexString(blockHash)) {
+    throw Error("Invalid BLOCK_HASH was provided")
+  }
+  const provider = await Witnet.JsonRpcProvider.fromEnv(options?.provider)
+  const block = await provider.getBlock(blockHash)
+  console.info(gray(JSON.stringify(block, (key, value) => {
+    switch (key) {
+      case "bytes":
+      case "der":
+      case "proof":
+        return Array.isArray(value) ? helpers.toHexString(value, true) : value
+
+      case "public_key":
+        return Array.isArray(value) 
+          ? helpers.toHexString(value, true) 
+          : (typeof value === 'object' ? Witnet.PublicKey.fromProtobuf(value).hash().toBech32(provider.network) : value)
+      
+          default:
+        return value
+    }
+  }, 2)))
+}
+
+async function dataRequest (options = {}, args = []) {
+  if (args.length === 0) {
+    throw Error("No DR_TX_HASH was specified")
+  }
+  const drTxHash = args[0].startsWith("0x") ? args[0].slice(2) : args[0]
+  if (!helpers.isHexString(drTxHash)) {
+    throw Error("Invalid DR_TX_HASH was provided")
+  }
+  const provider = new Witnet.JsonRpcProvider(options?.provider)
+
+  const drTxJsonReplacer = (key, value) => {
+    switch (key) {
+      case "proof":
+      case "public_key":
+      case "signature":
+      case "signatures":
+        return undefined
+
+      case "reveal":
+      case "tally":
+        if (Array.isArray(value)) {
+          const result = utils.cbor.decode(Uint8Array.from(value))
+          return Buffer.isBuffer(result) ? utils.toHexString(value) : result
+        }
+
+      default:
+        return value
+    }
+  }
+
+  const report = await provider.getDataRequest(drTxHash)
+  console.info(JSON.stringify(report, drTxJsonReplacer, 4))
+}
+
+async function superblock (options = {}, args = []) {
+  if (args.length === 0) {
+    throw Error("No EPOCH was specified")
+  }
+  const provider = new Witnet.JsonRpcProvider(options?.provider)
+  const superblock = await provider.getSuperblock(args[0])
+  console.info(superblock)
+}
+
+async function transaction (options = {}, args = []) {
+  if (args.length === 0) {
+    throw Error("No TX_HASH was specified")
+  }
+  const txHash = args[0].startsWith("0x") ? args[0].slice(2) : args[0]
+  if (!helpers.isHexString(txHash)) {
+    throw Error("Invalid TX_HASH was provided")
+  }
+  const provider = new Witnet.JsonRpcProvider(options?.provider)
+  const transaction = await provider.getTransaction(txHash)
+  console.info(
+    `${yellow(JSON.stringify(transaction, utils.txJsonReplacer, 2))}`
+  )
+}
+
+async function utxos (options = {}, args = []) {
+  if (args.length < 1) {
+    throw Error("No WIT_ADDRESS was specified")
+  }
+  const now = Math.floor(Date.now() / 1000)
+  const provider = new Witnet.JsonRpcProvider(options?.provider)
+  let utxos = await provider.getUtxos(args[0], options["small-first"] || false)
+  let totalBalance = 0n
+  if (!options?.verbose) {
+    utxos = utxos
+      .filter(utxo => utxo.timelock <= now)
+      .map(utxo => {
+        totalBalance += utxo.value
+        return [
+          utxo.output_pointer,
+          utxo.value,
+        ]
+      })
+    helpers.traceTable(utxos, {
+      headlines: [":UTXOs", "Value ($pedros)"],
+      humanizers: [, helpers.commas],
+      colors: [, myellow],
+    })
+  } else {
+    utxos = utxos
+      .map(utxo => {
+        totalBalance += utxo.value
+        return [
+          utxo.output_pointer,
+          utxo.timelock > now ? gray(moment.unix(utxo.timelock).fromNow()) : "",
+          utxo.timelock > now ? gray(helpers.commas(utxo.value)) : myellow(helpers.commas(utxo.value)),
+        ]
+      })
+    helpers.traceTable(utxos, {
+      headlines: [":UTXOs", "Timelock", "Value ($pedros)"],
+    })
+  }
+  console.info(`^ Showing ${utxos.length} UTXOs: ${lyellow(helpers.whole_wits(totalBalance, 2))}.`)
+}
+
+async function validators (options = {}, args = []) {
+  if (args.length === 0) {
+    throw Error("No WIT_ADDRESS was specified")
+  }
+  const provider = new Witnet.JsonRpcProvider(options?.provider)
+  const query = {
+    filter: { withdrawer: args[0] },
+  }
+  const records = await provider.stakes(query)
+  let nanowits = 0
+  if (records.length > 0) {
+    helpers.traceTable(
+      records.map((record, index) => {
+        nanowits += record.value.coins
+        return [
+          1 + index,
+          record.key.validator,
+          ...(
+            options?.verbose
+              ? [record.value.nonce, record.value.epochs.witnessing, record.value.epochs.mining]
+              : []
+          ),
+          Witnet.Coins.fromNanowits(record.value.coins).wits,
+        ]
+      }), {
+        headlines: [
+          "RANK",
+          "VALIDATORS",
+          ...(
+            options?.verbose
+              ? ["Nonce", "LW_Epoch", "LM_Epoch"]
+              : []
+          ),
+          "STAKED ($WIT)",
+        ],
+        humanizers: [
+          ,, ...(
+            options?.verbose
+              ? [helpers.commas, helpers.commas, helpers.commas]
+              : []
+          ),
+          helpers.commas,
+        ],
+        colors: [, green, ...(
+          options?.verbose
+            ? [, magenta, cyan, myellow]
+            : [myellow]
+        )],
+      }
+    )
+    console.info(
+      `^ ${records.length} validators for withdrawer ${
+        mgreen(args[0])
+      }: ${
+        lyellow(helpers.whole_wits(nanowits, 2))
+      }`
+    )
+  } else {
+    console.info(`> No validators found for withdrawer ${mmagenta(args[0])}.`)
+  }
+}
+
+async function withdrawers (options = {}, args = []) {
+  if (args.length === 0) {
+    throw Error("No WIT_ADDRESS was specified")
+  }
+  const provider = new Witnet.JsonRpcProvider(options?.provider)
+  const query = {
+    filter: { validator: args[0] },
+  }
+  const records = await provider.stakes(query)
+  let nanowits = 0
+  if (records.length > 0) {
+    helpers.traceTable(
+      records.map((record, index) => {
+        nanowits += record.value.coins
+        return [
+          1 + index,
+          record.key.withdrawer,
+          ...(
+            options?.verbose
+              ? [record.value.nonce, record.value.epochs.witnessing, record.value.epochs.mining]
+              : []
+          ),
+          Witnet.Coins.fromNanowits(record.value.coins).wits,
+        ]
+      }), {
+        headlines: [
+          "RANK",
+          "WITHDRAWERS",
+          ...(
+            options?.verbose
+              ? ["Nonce", "LW_Epoch", "LM_Epoch"]
+              : []
+          ),
+          "STAKED ($WIT)",
+        ],
+        humanizers: [
+          ,, ...(
+            options?.verbose
+              ? [helpers.commas, helpers.commas, helpers.commas]
+              : []
+          ),
+          helpers.commas,
+        ],
+        colors: [, green, ...(
+          options?.verbose
+            ? [, magenta, cyan, myellow]
+            : [myellow]
+        )],
+      }
+    )
+    console.info(
+      `^ ${records.length} withdrawers for validator ${
+        mgreen(args[0])
+      }: ${
+        lyellow(helpers.whole_wits(nanowits, 2))
+      }`
+    )
+  } else {
+    console.info(`> No withdrawers found for validator ${mmagenta(args[0])}.`)
+  }
+}