antelopeql 1.0.0

package/mutation_resolver.mjs

@@ -0,0 +1,234 @@
+import serialize from "eosio-wasm-js/serialize.mjs";
+import serialize_transaction_header from "eosio-wasm-js/transaction_header.mjs";
+import { GraphQLError } from "graphql";
+
+const defeaul_config = {
+  blocksBehind: 3,
+  expireSeconds: 30,
+  max_net_usage_words: 0,
+  max_cpu_usage_ms: 0,
+  delay_sec: 0
+};
+
+const validate_actions = () => {
+  throw new GraphQLError(`Invalid AntelopeQL query.`, {
+    extensions: {
+      why: "AntelopeQL enforces one action per object in the list to preserve the top to bottom execution order.",
+      example: "actions: [{ action1: … }, { action2: … }]"
+    }
+  });
+};
+
+/**
+ * Serializes GraphQL mutation actions into binary instructions.
+ * @param {Array<Object>} actions List of actions to serialize.
+ * @param {Array<Object>} ast_list Abstract syntax tree list of data to serialize.
+ * @returns {String} Serialized transaction body as hexadecimal string.
+ */
+async function get_transaction_body(actions, ast_list) {
+  let actions_list_to_serialize = [];
+
+  for (const action of actions) {
+    if (Object.values(action).length > 1) validate_actions(action);
+
+    const [contract] = Object.keys(action);
+    const [values] = Object.values(action);
+    const action_fields = Object.keys(values);
+    if (action_fields.length > 1) validate_actions(action);
+
+    actions_list_to_serialize.push(
+      ...action_fields.map((action) => ({
+        contract,
+        action,
+        data: values[action]
+      }))
+    );
+  }
+
+  let _actions = [];
+  let _context_free_actions = [];
+
+  let transaction_extensions =
+    "000000000000000000000000000000000000000000000000000000000000000000";
+
+  for (const action of actions_list_to_serialize) {
+    const {
+      contract,
+      action: action_name,
+      data: { authorization, ...data }
+    } = action;
+
+    const build_serialize_list = async (data, instructions) => {
+      let serialize_list = [];
+      for (const instruction of instructions) {
+        const { $info, name, type } = instruction;
+        const datum = data[name];
+        const next_instruction = ast_list[contract][type]; // Indicates that the AST type is not serialisable, but is another type on the AST list.
+
+        // Handles ABI variant types see https://en.cppreference.com/w/cpp/utility/variant
+        if ($info.variant) {
+          if (Object.keys(data).length > 1)
+            throw new Error(`Must only include one type for variant.`);
+          if (!datum) continue;
+          else
+            serialize_list.push({
+              type: "varuint32",
+              value: instructions.findIndex((i) => i.type == type)
+            });
+        }
+
+        if ($info.binary_ex) $info.optional = false; // Binary extentions are optional (GraphQL types) but should not serialize an optional type.
+
+        if ($info.optional)
+          serialize_list.push({ type: "bool", value: datum != undefined }); // Add an optional item to serialize list.
+
+        if ($info.list)
+          if (datum !== undefined)
+            serialize_list.push({ type: "varuint32", value: datum.length }); // Add an length of list to serialize list.
+
+        // Indicates that we need to recursion loop through each data item.
+        if (next_instruction)
+          if ($info.list) {
+            if (datum != undefined && !$info.binary_ex)
+              for await (const d of datum)
+                serialize_list.push(
+                  ...(await build_serialize_list(await d, next_instruction))
+                );
+          }
+          // None list recursion
+          else
+            serialize_list.push(
+              ...(await build_serialize_list(datum, next_instruction))
+            );
+        // Indicates that the list of data can be serilaized and so is pushed into serialize_list.
+        else if ($info.list && datum !== undefined)
+          for await (const d of datum) serialize_list.push({ type, value: d });
+        else if (datum !== undefined)
+          serialize_list.push({ type, value: datum }); // Native eoio types than can be serialized.
+      }
+
+      return serialize_list;
+    };
+
+    const hex_string = await build_serialize_list(
+      data,
+      ast_list[contract][action_name]
+    ).then(async (list) => {
+      let hex_string = "";
+      for await (const { type, value } of list)
+        hex_string += await serialize[type](await value);
+      return hex_string;
+    });
+
+    if (authorization?.length)
+      _actions.push({
+        account: contract.replace(/_/gmu, "."),
+        action: action_name.replace(/_/gmu, "."),
+        authorization,
+        data,
+        hex_data: hex_string
+      });
+    else
+      _context_free_actions.push({
+        account: contract.replace(/_/gmu, "."),
+        action: action_name.replace(/_/gmu, "."),
+        authorization: [],
+        data,
+        hex_data: hex_string
+      });
+  }
+
+  return {
+    context_free_actions: _context_free_actions.map(
+      ({ action: name, ...action }) => ({ ...action, name })
+    ),
+    actions: _actions.map(({ action: name, ...action }) => ({
+      ...action,
+      name
+    })),
+    transaction_extensions: [],
+    transaction_body:
+      serialize.actions(_context_free_actions) +
+      serialize.actions(_actions) +
+      transaction_extensions
+  };
+}
+
+/**
+ * Mutation resolver for serializing EOSIO transactions.
+ * @param {Object} args Args.
+ * @param {Object} args.actions Actions list to be serialized.
+ * @param {Object} [args.configuration] Action configuaration.
+ * @param {AntelopeQLRPC} network AntelopeQL context contain fetch and url string.
+ * @param {Object} ast_list Abstract syntax tree list of the contract actions.
+ * @returns {Object} Transaction object.
+ */
+async function mutation_resolver(
+  { actions, configuration = defeaul_config },
+  network,
+  ast_list
+) {
+  if (configuration.max_cpu_usage_ms > 0xff)
+    throw new Error("Invalid max_cpu_usage_ms value (maximum 255).");
+  if (configuration.max_net_usage_words > 0xffffffff)
+    throw new Error(
+      "Invalid max_net_usage_words value (maximum 4,294,967,295)."
+    );
+
+  const { fetch, rpc_url, ...fetchOptions } = network;
+  const { transaction_body, ...transaction_list } = await get_transaction_body(
+    actions,
+    ast_list
+  );
+
+  const { chain_id, head_block_num } = await fetch(
+    `${rpc_url}/v1/chain/get_info`,
+    {
+      method: "POST",
+      ...fetchOptions
+    }
+  ).then((req) => req.json());
+
+  const block_num_or_id = head_block_num - configuration.blocksBehind;
+
+  const { timestamp, block_num, ref_block_prefix } = await fetch(
+    `${rpc_url}/v1/chain/get_block`,
+    {
+      method: "POST",
+      ...fetchOptions,
+      body: JSON.stringify({
+        block_num_or_id
+      })
+    }
+  ).then((req) => req.json());
+
+  // // TaPoS expiry time.
+  const expiration =
+    Math.round(Date.parse(timestamp + "Z") / 1000) +
+    configuration.expireSeconds;
+
+  const txn_header = {
+    expiration,
+    ref_block_num: block_num & 0xffff,
+    ref_block_prefix,
+    max_net_usage_words: configuration.max_net_usage_words,
+    max_cpu_usage_ms: configuration.max_cpu_usage_ms,
+    delay_sec: configuration.delay_sec
+  };
+
+  // Generates a transaction header for a EOS transaction.
+  const transaction_header = serialize_transaction_header(txn_header);
+  txn_header.expiration = timestamp;
+
+  return {
+    chain_id,
+    transaction_header,
+    transaction_body,
+    transaction: {
+      ...txn_header,
+      ...transaction_list
+    }
+  };
+}
+
+export default mutation_resolver;

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "antelopeql",
+  "version": "1.0.0",
+  "description": "A GraphQL implementation for interacting with Antelope based blockchains.",
+  "repository": "github:pur3miish/antelopeql",
+  "bugs": "https://github.com/pur3miish/antelopeql/issues",
+  "homepage": "https://github.com/pur3miish/antelopeql#readme",
+  "author": "pur3miish",
+  "license": "MIT",
+  "scripts": {
+    "eslint": "eslint .",
+    "prettier": "prettier -c .",
+    "prettier:readme": "prettier --write readme.md",
+    "types": "tsc -p jsconfig.json",
+    "snapshot": "SAVE_SNAPSHOTS=1 coverage-node test/index.test.mjs",
+    "coverage": "coverage-node test/index.test.mjs",
+    "tests": "node test/index.test.mjs",
+    "test": "npm run eslint && npm run prettier && npm run types && npm run tests",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": "^16.0.0 || >= 17.0.0 || >= 18.0.0"
+  },
+  "files": [
+    "blockchain/*.mjs",
+    "eosio_types/*.mjs",
+    "graphql_input_types/*.mjs",
+    "graphql_object_types/*.mjs",
+    "blockchain_query_field.mjs",
+    "build_graphql_fields_from_abis.mjs",
+    "eosio_abi_to_graphql_ast.mjs",
+    "eosio_types.mjs",
+    "mutation_resolver.mjs",
+    "push_serialized_transaction.mjs",
+    "push_transaction_rpc.mjs",
+    "push_transaction.mjs",
+    "query_resolver.mjs",
+    "serialize_transaction.mjs",
+    "antelopeql.mjs",
+    "types.mjs"
+  ],
+  "sideEffects": false,
+  "exports": {
+    "./blockchain/*.mjs": "./blockchain/*.mjs",
+    "./eosio_types/*.mjs": "./eosio_types/*.mjs",
+    "./graphql_input_types/*.mjs": "./graphql_input_types/*.mjs",
+    "./graphql_object_types/*.mjs": "./graphql_object_types/*.mjs",
+    "./blockchain_query_field.mjs": "./blockchain_query_field.mjs",
+    "./build_graphql_fields_from_abis.mjs": "./build_graphql_fields_from_abis.mjs",
+    "./eosio_abi_to_graphql_ast.mjs": "./eosio_abi_to_graphql_ast.mjs",
+    "./eosio_types.mjs": "./eosio_types.mjs",
+    "./mutation_resolver.mjs": "./mutation_resolver.mjs",
+    "./push_serialized_transaction.mjs": "./push_serialized_transaction.mjs",
+    "./push_transaction_rpc.mjs": "./push_transaction_rpc.mjs",
+    "./push_transaction.mjs": "./push_transaction.mjs",
+    "./query_resolver.mjs": "./query_resolver.mjs",
+    "./serialize_transaction.mjs": "./serialize_transaction.mjs",
+    "./antelopeql.mjs": "./antelopeql.mjs",
+    "./types.mjs": "./types.mjs"
+  },
+  "browserslist": [
+    "> 0.5%, not OperaMini all, not IE > 0, not dead"
+  ],
+  "keywords": [
+    "blockchain",
+    "graphql",
+    "smart",
+    "contract",
+    "bitcoin",
+    "eosio",
+    "eos",
+    "query",
+    "language"
+  ],
+  "devDependencies": {
+    "@types/node": "^18.13.0",
+    "coverage-node": "^8.0.0",
+    "eslint": "^8.34.0",
+    "eslint-plugin-simple-import-sort": "^10.0.0",
+    "graphql": "^16.6.0",
+    "node-fetch": "^3.3.0",
+    "nodemon": "^2.0.20",
+    "prettier": "^2.8.4",
+    "snapshot-assertion": "^5.0.0",
+    "test-director": "^10.0.0",
+    "typescript": "^4.9.5"
+  },
+  "peerDependencies": {
+    "graphql": "^16.6.0"
+  },
+  "dependencies": {
+    "base58-js": "^2.0.0",
+    "eosio-ecc": "^1.0.1",
+    "eosio-wasm-js": "^4.0.1",
+    "ripemd160-js": "*"
+  }
+}

package/push_serialized_transaction.mjs

@@ -0,0 +1,24 @@
+import { GraphQLList, GraphQLNonNull } from "graphql";
+
+import bytes_type from "./eosio_types/bytes_type.mjs";
+import signature_type from "./eosio_types/signature_type.mjs";
+import transaction_receipt from "./graphql_object_types/transaction_receipt.mjs";
+import push_transaction_rpc from "./push_transaction_rpc.mjs";
+
+/**
+ * Push transaction type.
+ */
+const push_serialized_transaction = {
+  description: "Pushes a serialized transaction to the blockchain.",
+  type: new GraphQLNonNull(transaction_receipt),
+  args: {
+    transaction_header: { type: new GraphQLNonNull(bytes_type) },
+    transaction_body: { type: new GraphQLNonNull(bytes_type) },
+    signaures: { type: new GraphQLNonNull(new GraphQLList(signature_type)) }
+  },
+  resolve(_, args, ctx) {
+    return push_transaction_rpc(args, ctx.network);
+  }
+};
+
+export default push_serialized_transaction;

package/push_transaction.mjs

@@ -0,0 +1,75 @@
+import private_key_to_legacy from "eosio-ecc/private_key_to_legacy.mjs";
+import get_public_key from "eosio-ecc/public_key_from_private.mjs";
+import sign_packed_txn from "eosio-ecc/sign_packed_txn.mjs";
+import { GraphQLError, GraphQLNonNull } from "graphql";
+
+import configuration_type from "./graphql_input_types/configuration.mjs";
+import transaction_receipt from "./graphql_object_types/transaction_receipt.mjs";
+import mutation_resolver from "./mutation_resolver.mjs";
+import push_transaction_rpc from "./push_transaction_rpc.mjs";
+
+const push_transaction = (actions, ast_list) => ({
+  description:
+    "Serialize a list of actions and push them to the blockchain in one step, requires private keys to be supplied to AntelopeQL.",
+  type: new GraphQLNonNull(transaction_receipt),
+  args: {
+    actions: {
+      type: actions
+    },
+    configuration: {
+      type: configuration_type
+    }
+  },
+  async resolve(_, args, { network, private_keys }) {
+    const { chain_id, transaction_header, transaction_body, transaction } =
+      await mutation_resolver(args, network, ast_list);
+
+    const key_pairs = {};
+    for await (const key of private_keys) {
+      const PVT = await private_key_to_legacy(key);
+      const PUB = await get_public_key(PVT);
+      key_pairs[PUB] = PVT;
+    }
+    const available_keys = Object.keys(key_pairs);
+
+    const { fetch, rpc_url, ...fetchOptions } = network;
+
+    if (!available_keys.length)
+      throw new GraphQLError("No private keys found.");
+
+    const { required_keys, ...errors } = await fetch(
+      `${rpc_url}/v1/chain/get_required_keys`,
+      {
+        method: "POST",
+        ...fetchOptions,
+        body: JSON.stringify({
+          available_keys,
+          transaction
+        })
+      }
+    ).then((res) => res.json());
+
+    if (errors.message)
+      throw new GraphQLError("No transaction sent", {
+        extensions: errors
+      });
+
+    const signatures = await Promise.all(
+      required_keys.map((pub) =>
+        sign_packed_txn({
+          chain_id,
+          transaction_body,
+          transaction_header,
+          wif_private_key: key_pairs[pub]
+        })
+      )
+    );
+
+    return push_transaction_rpc(
+      { transaction_body, transaction_header, signatures },
+      network
+    );
+  }
+});
+
+export default push_transaction;

package/push_transaction_rpc.mjs

@@ -0,0 +1,37 @@
+import { GraphQLError } from "graphql";
+
+/**
+ * Pushes a serialized transaction to the blockchain.
+ * @param {Object} root Argument
+ * @param {String} root.transaction_header Serialized transaction header.
+ * @param {String} root.transaction_body Serialized transaction body.
+ * @param {Array<String>} root.signatures List of signatures to validate transaction.
+ * @param {Object} network Argument
+ * @param {fetch} network.fetch Custom fetch.
+ * @param {String} network.rpc_url Chain rpc url.
+ * @param {Object} network.headers transaction headers.
+ *
+ */
+export default async function push_transaction_rpc(
+  { transaction_header, transaction_body, signatures },
+  network
+) {
+  const { fetch, rpc_url, ...fetchOptions } = network;
+  const pushed_txn_req = await fetch(`${rpc_url}/v1/chain/push_transaction`, {
+    method: "POST",
+    ...fetchOptions,
+    body: JSON.stringify({
+      signatures,
+      compression: 0,
+      packed_context_free_data: "",
+      packed_trx: transaction_header + transaction_body
+    })
+  });
+  const pushed_transaction = await pushed_txn_req.json();
+  if (pushed_transaction.error)
+    throw new GraphQLError(pushed_transaction.message, {
+      extensions: pushed_transaction.error
+    });
+
+  return pushed_transaction;
+}

package/query_resolver.mjs

@@ -0,0 +1,43 @@
+import { GraphQLError } from "graphql";
+
+/**
+ * AntelopeQL Query resolver.
+ * @param {Object} root GraphQL resolver root query.
+ * @param {String} root.code Contract code calling, passed from antelopeql_fields resolver.
+ * @param {Object} args Query arguments.
+ * @param {Object} args.arg argument data.
+ * @param {Object} ctx GraphQL context.
+ * @param {AntelopeQLRPC} ctx.network Object containing connection url and fetch.
+ * @param {Object} info GraphQL resovler info argument.
+ * @returns {Object} Returned data from table.
+ */
+export default async function query_resolver(
+  { code },
+  { arg },
+  { network },
+  info
+) {
+  const { fetch, rpc_url, ...fetchOptions } = network;
+  const { fieldName: query_name } = info;
+  const table = query_name.replace(/_/gmu, ".");
+
+  if (
+    arg.key_type == "i256" ||
+    arg.key_type == "ripemd160" ||
+    arg.key_type == "sha256"
+  ) {
+    arg.encode_type = "hex";
+    arg.lower_bound = arg.lower_bound ?? "00";
+  }
+  const uri = rpc_url + "/v1/chain/get_table_rows";
+
+  const data = await fetch(uri, {
+    method: "POST",
+    ...fetchOptions,
+    body: JSON.stringify({ json: true, code, table, ...arg })
+  }).then((req) => req.json());
+
+  if (data.error) throw new GraphQLError(data.message, { extensions: data });
+
+  return data.rows;
+}

package/readme.md

@@ -0,0 +1,164 @@
+![antelopeql logo](https://raw.githubusercontent.com/pur3miish/antelope/main/static/antelopeql.svg)
+
+# AntelopeQL
+
+[![NPM Package](https://img.shields.io/npm/v/antelopeql.svg)](https://www.npmjs.org/package/antelopeql) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/pur3miish/antelopeql/blob/main/LICENSE)
+
+AntelopeQL is a [GraphQL](https://graphql.org/) implementation for interacting with [Antelope](https://antelope.io/) blockchains. Query and mutate your smart contracts with a GraphQL tool that provides comprehensive documentation about the entire blockchain.
+
+**For a live example of AntelopeQL GUI see: [antelope.relocke.io](https://antelope.relocke.io).**
+
+![antelopeql screenshot](https://raw.githubusercontent.com/pur3miish/antelopeql/main/static/antelopeql-screen.png)
+
+## Installation
+
+For [Node.js](https://nodejs.org), to install [`AntelopeQL`](https://npm.im/antelopeql) and the peer dependency [`graphql`](https://npm.im/graphql) run:
+
+```sh
+npm install antelopeql graphql
+```
+
+For [Deno.js](https://deno.land), to install [`AntelopeQL`](https://deno.land/x/antelopeql) add to your `deno.json` configuration file these imports:
+
+```json
+{
+  "imports": {
+    "universal-sha256-js/": "https://deno.land/x/sha256js/",
+    "universal-hmac-sha256-js/": "https://deno.land/x/hmacsha256/",
+    "universal-hmac-sha256-js/hmac-sha256-node.mjs": "https://deno.land/x/hmacsha256/hmac-sha256-deno.mjs",
+    "base58-js/": "https://deno.land/x/base58/",
+    "isomorphic-secp256k1-js/": "https://deno.land/x/secp256k1js/",
+    "ripemd160-js/": "https://deno.land/x/ripemd160js@v2.0.3/",
+    "eosio-wasm-js/": "https://deno.land/x/eosio_wasm_js/",
+    "eosio-ecc/": "https://deno.land/x/eosio_ecc/",
+    "graphql": "https://cdn.skypack.dev/graphql"
+  }
+}
+```
+
+## Examples
+
+See the examples folder on how to run AntelopeQL as a [Node.js](https://nodejs.org) endpoint.
+
+### Query a blockchain account
+
+```js
+import fetch from "node-fetch";
+import AntelopeQL from "antelopeql/antelopeql.mjs";
+
+const { data } = await AntelopeQL(
+  {
+    query: /*GraphQL*/ `{
+    blockchain{
+      get_account(account_name:"relockeblock") {
+        core_liquid_balance
+        ram_quota
+        net_weight
+        cpu_weight
+        ram_usage
+        permissions {
+          linked_actions {
+            account
+            action
+          }
+          required_auth {
+            keys {
+              key
+              weight
+            }
+            threshold
+          }
+        }
+      }
+    }
+  }`
+  fetch,
+  rpc_url: "https://jungle.relocke.io",
+  headers: {
+    "content-type": "application/json"
+  }
+  },
+);
+
+console.log(data);
+```
+
+> Logged output included an account infomation.
+
+### Transfer EOS cryptocurrency
+
+```js
+import fetch from "node-fetch";
+import AntelopeQL from "antelopeql/antelopeql.mjs";
+
+const { data } = await AntelopeQL({
+  query: /*GraphQL*/ `mutation{
+      push_transaction(actions: [{
+        eosio_token:{
+          transfer: {
+            authorization:{
+              actor:"relockeblock"
+            }
+            to:"relockechain"
+            from:"relockeblock"
+            memo: ""
+            quantity: "0.0002 EOS"
+          }
+        }
+      }]) {
+        transaction_id
+        block_num
+      }
+    }`,
+  contracts: ["eosio.token"],
+  private_keys: ["PVT_K1_…"], // legacy keys support.
+  fetch,
+  rpc_url: "https://eos.relocke.io", // eos blockchain.
+  headers: {
+    "content-type": "application/json"
+  }
+});
+
+console.log(data);
+```
+
+> Logged output includes transaction_id and block_num
+
+### Ways to require in CJS
+
+> **Note**
+>
+> As this package is [ESM](https://nodejs.org/docs/latest-v16.x/api/esm.html) if you need to require it in a [Common JS](https://nodejs.org/docs/latest-v16.x/api/modules.html) package, then you can import like this:
+
+```js
+(async function () {
+  const { default: AntelopeQL } = await import("antelopeql/antelopeql.mjs");
+  const { data } = await AntelopeQL({…})
+})();
+```
+
+## Requirements
+
+Supported runtime environments:
+
+- [Node.js](https://nodejs.org) versions `>=16.0.0`.
+- Browsers matching the [Browserslist](https://browsersl.ist) query [`> 0.5%, not OperaMini all, not dead`](https://browsersl.ist/?q=%3E+0.5%25%2C+not+OperaMini+all%2C+not+dead).
+- [Deno](https://deno.land) version `>=1.30.0`.
+
+## Exports
+
+The [npm](https://npmjs.com) package [`AntelopeQL`](https://npm.im/antelopeql) features [optimal JavaScript module design](https://jaydenseric.com/blog/optimal-javascript-module-design). It doesn’t have a main index module, so use deep imports from the ECMAScript modules that are exported via the [`package.json`](./package.json) field [`exports`](https://nodejs.org/api/packages.html#exports):
+
+- [`antelopeql.mjs`](./antelopeql.mjs)
+- [`blockchain_query_field.mjs`](blockchain_query_field.mjs)
+- [`build_graphql_fields_from_abis.mjs`](build_graphql_fields_from_abis.mjs)
+- [`eosio_abi_to_graphql_ast.mjs`](eosio_abi_to_graphql_ast.mjs)
+- [`eosio_types.mjs`](eosio_types.mjs)
+- [`mutation_resolver.mjs`](mutation_resolver.mjs)
+- [`push_serialized_transaction.mjs`](push_serialized_transaction.mjs)
+- [`push_transaction_rpc.mjs`](push_transaction_rpc.mjs)
+- [`push_transaction.mjs`](push_transaction.mjs)
+- [`query_resolver.mjs`](query_resolver.mjs)
+- [`serialize_transaction.mjs`](serialize_transaction.mjs)
+- [`antelopeql.mjs`](antelopeql.mjs)
+- [`types.mjs`](types.mjs)