Add utils module with script to display top address balances

* feat: add utils module, get first balances * fix: add dummy node balance for now * fix: consider block height * feat: allow querying node addr balance by block height * feat: query nodes for balances via RPC * feat: calculate absolute balance delta * fix: consider locked node balance * fix: ignore utils dir on main lint config * chore: print usage
2026-01-12 08:34:40 +08:00 · 2021-11-09 15:27:05 -06:00
parent e790109030
commit 67553ff45b
8 changed files with 690 additions and 2 deletions
--- a/.eslintignore
+++ b/.eslintignore
@@ -15,3 +15,4 @@ src/tests-rosetta-cli/
 src/tests-bns/
 client/src/
 config/
+utils/src/
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -9,7 +9,7 @@ module.exports = {
    ecmaVersion: 2020,
    sourceType: 'module',
  },
-  ignorePatterns: ['lib/*', 'client/*'],
+  ignorePatterns: ['lib/*', 'client/*', 'utils/*'],
  rules: {
    'prettier/prettier': 'error',

--- a/src/core-rpc/client.ts
+++ b/src/core-rpc/client.ts
@@ -8,6 +8,7 @@ export interface CoreRpcAccountInfo {
  balance: string;
  /** Hex-prefixed binary blob. */
  balance_proof: string;
+  locked: string;
  nonce: number;
  /** Hex-prefixed binary blob. */
  nonce_proof: string;
@@ -150,7 +151,11 @@ export class StacksCoreRpcClient {
    return result;
  }

-  async getAccount(principal: string, atUnanchoredChainTip = false): Promise<CoreRpcAccountInfo> {
+  async getAccount(
+    principal: string,
+    atUnanchoredChainTip = false,
+    indexBlockHash?: string
+  ): Promise<CoreRpcAccountInfo> {
    const requestOpts: RequestOpts = {
      method: 'GET',
      queryParams: {
@@ -160,6 +165,8 @@ export class StacksCoreRpcClient {
    if (atUnanchoredChainTip) {
      const info = await this.getInfo();
      requestOpts.queryParams!.tip = info.unanchored_tip;
+    } else if (indexBlockHash) {
+      requestOpts.queryParams!.tip = indexBlockHash;
    }
    const result = await this.fetchJson<CoreRpcAccountInfo>(
      `v2/accounts/${principal}`,
--- a/utils/.eslintrc.js
+++ b/utils/.eslintrc.js
@@ -0,0 +1,19 @@
+module.exports = {
+  root: true,
+  extends: ['@stacks/eslint-config', 'prettier'],
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint', 'prettier'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: './tsconfig.json',
+    ecmaVersion: 2017,
+    sourceType: 'module',
+  },
+  ignorePatterns: ['lib/*', 'test/*', '.eslintrc.js'],
+  rules: {
+    'prettier/prettier': 'error',
+    '@typescript-eslint/no-non-null-assertion': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/restrict-template-expressions': 'off',
+  },
+};
--- a/utils/package-lock.json
+++ b/utils/package-lock.json
@@ -0,0 +1,463 @@
+{
+  "name": "@stacks/blockchain-api-utils",
+  "version": "0.1.0",
+  "lockfileVersion": 1,
+  "requires": true,
+  "dependencies": {
+    "@types/node": {
+      "version": "16.11.2",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-16.11.2.tgz",
+      "integrity": "sha512-w34LtBB0OkDTs19FQHXy4Ig/TOXI4zqvXS2Kk1PAsRKZ0I+nik7LlMYxckW0tSNGtvWmzB+mrCTbuEjuB9DVsw==",
+      "dev": true
+    },
+    "@types/pg": {
+      "version": "8.6.1",
+      "resolved": "https://registry.npmjs.org/@types/pg/-/pg-8.6.1.tgz",
+      "integrity": "sha512-1Kc4oAGzAl7uqUStZCDvaLFqZrW9qWSjXOmBfdgyBP5La7Us6Mg4GBvRlSoaZMhQF/zSj1C8CtKMBkoiT8eL8w==",
+      "dev": true,
+      "requires": {
+        "@types/node": "*",
+        "pg-protocol": "*",
+        "pg-types": "^2.2.0"
+      }
+    },
+    "ajv": {
+      "version": "8.6.3",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.6.3.tgz",
+      "integrity": "sha512-SMJOdDP6LqTkD0Uq8qLi+gMwSt0imXLSV080qFVwJCpH9U6Mb+SUGHAXM0KNbcBPguytWyvFxcHgMLe2D2XSpw==",
+      "requires": {
+        "fast-deep-equal": "^3.1.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2",
+        "uri-js": "^4.2.2"
+      }
+    },
+    "ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="
+    },
+    "ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "requires": {
+        "color-convert": "^2.0.1"
+      }
+    },
+    "astral-regex": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/astral-regex/-/astral-regex-2.0.0.tgz",
+      "integrity": "sha512-Z7tMw1ytTXt5jqMcOP+OQteU1VuNK9Y02uuJtKQ1Sv69jXQKKg5cibLwGJow8yzZP+eAc18EmLGPal0bp36rvQ=="
+    },
+    "balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "dev": true
+    },
+    "bignumber.js": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.0.1.tgz",
+      "integrity": "sha512-IdZR9mh6ahOBv/hYGiXyVuyCetmGJhtYkqLBpTStdhEGjegpPlUawydyaF3pbIOFynJTpllEs+NP+CS9jKFLjA=="
+    },
+    "brace-expansion": {
+      "version": "1.1.11",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
+      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "dev": true,
+      "requires": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "buffer-writer": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/buffer-writer/-/buffer-writer-2.0.0.tgz",
+      "integrity": "sha512-a7ZpuTZU1TRtnwyCNW3I5dc0wWNC3VR9S++Ewyk2HHZdrO3CQJqSpd+95Us590V6AL7JqUAH2IwZ/398PmNFgw=="
+    },
+    "color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "requires": {
+        "color-name": "~1.1.4"
+      }
+    },
+    "color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="
+    },
+    "concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=",
+      "dev": true
+    },
+    "debug": {
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.2.tgz",
+      "integrity": "sha512-mOp8wKcvj7XxC78zLgw/ZA+6TSgkoE2C/ienthhRD298T7UNwAg9diBpLRxC0mOezLl4B0xV7M0cCO6P/O0Xhw==",
+      "requires": {
+        "ms": "2.1.2"
+      }
+    },
+    "dotenv": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-10.0.0.tgz",
+      "integrity": "sha512-rlBi9d8jpv9Sf1klPjNfFAuWDjKLwTIJJ/VxtoTwIR6hnZxcEOQCZg2oIL3MWBYw5GpUDKOEnND7LXTbIpQ03Q=="
+    },
+    "emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="
+    },
+    "extra-bigint": {
+      "version": "0.0.62",
+      "resolved": "https://registry.npmjs.org/extra-bigint/-/extra-bigint-0.0.62.tgz",
+      "integrity": "sha512-Uv+k7mKgWPPCm0z4TqEPj5L9t2g598btvJWhJ/oVOz2UBkvI0t1l1SseLJkFZ3lRBFJ2EHk4pxx/W8lVa0PICA=="
+    },
+    "fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="
+    },
+    "fs.realpath": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
+      "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=",
+      "dev": true
+    },
+    "getopts": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/getopts/-/getopts-2.3.0.tgz",
+      "integrity": "sha512-5eDf9fuSXwxBL6q5HX+dhDj+dslFGWzU5thZ9kNKUkcPtaPdatmUFKwHFrLb/uf/WpA4BHET+AX3Scl56cAjpA=="
+    },
+    "glob": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz",
+      "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==",
+      "dev": true,
+      "requires": {
+        "fs.realpath": "^1.0.0",
+        "inflight": "^1.0.4",
+        "inherits": "2",
+        "minimatch": "^3.0.4",
+        "once": "^1.3.0",
+        "path-is-absolute": "^1.0.0"
+      }
+    },
+    "inflight": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
+      "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=",
+      "dev": true,
+      "requires": {
+        "once": "^1.3.0",
+        "wrappy": "1"
+      }
+    },
+    "inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="
+    },
+    "is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="
+    },
+    "json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="
+    },
+    "lodash.clonedeep": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/lodash.clonedeep/-/lodash.clonedeep-4.5.0.tgz",
+      "integrity": "sha1-4j8/nE+Pvd6HJSnBBxhXoIblzO8="
+    },
+    "lodash.truncate": {
+      "version": "4.4.2",
+      "resolved": "https://registry.npmjs.org/lodash.truncate/-/lodash.truncate-4.4.2.tgz",
+      "integrity": "sha1-WjUNoLERO4N+z//VgSy+WNbq4ZM="
+    },
+    "minimatch": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz",
+      "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==",
+      "dev": true,
+      "requires": {
+        "brace-expansion": "^1.1.7"
+      }
+    },
+    "ms": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
+      "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w=="
+    },
+    "obuf": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/obuf/-/obuf-1.1.2.tgz",
+      "integrity": "sha512-PX1wu0AmAdPqOL1mWhqmlOd8kOIZQwGZw6rh7uby9fTc5lhaOWFLX3I6R1hrF9k3zUY40e6igsLGkDXK92LJNg=="
+    },
+    "once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
+      "dev": true,
+      "requires": {
+        "wrappy": "1"
+      }
+    },
+    "packet-reader": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/packet-reader/-/packet-reader-1.0.0.tgz",
+      "integrity": "sha512-HAKu/fG3HpHFO0AA8WE8q2g+gBJaZ9MG7fcKk+IJPLTGAD6Psw4443l+9DGRbOIh3/aXr7Phy0TjilYivJo5XQ=="
+    },
+    "path-is-absolute": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
+      "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=",
+      "dev": true
+    },
+    "pg": {
+      "version": "8.2.1",
+      "resolved": "https://registry.npmjs.org/pg/-/pg-8.2.1.tgz",
+      "integrity": "sha512-DKzffhpkWRr9jx7vKxA+ur79KG+SKw+PdjMb1IRhMiKI9zqYUGczwFprqy+5Veh/DCcFs1Y6V8lRLN5I1DlleQ==",
+      "requires": {
+        "buffer-writer": "2.0.0",
+        "packet-reader": "1.0.0",
+        "pg-connection-string": "^2.2.3",
+        "pg-pool": "^3.2.1",
+        "pg-protocol": "^1.2.4",
+        "pg-types": "^2.1.0",
+        "pgpass": "1.x",
+        "semver": "4.3.2"
+      }
+    },
+    "pg-connection-string": {
+      "version": "2.5.0",
+      "resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.5.0.tgz",
+      "integrity": "sha512-r5o/V/ORTA6TmUnyWZR9nCj1klXCO2CEKNRlVuJptZe85QuhFayC7WeMic7ndayT5IRIR0S0xFxFi2ousartlQ=="
+    },
+    "pg-copy-streams": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/pg-copy-streams/-/pg-copy-streams-5.1.1.tgz",
+      "integrity": "sha512-ieW6JuiIo/4WQ7n+Wevr9zYvpM1AwUs6EwNCCA0VgKZ6ZQ7Y9k3IW00vqc6svX9FtENhbaTbLN7MxekraCrbfg==",
+      "requires": {
+        "obuf": "^1.1.2"
+      }
+    },
+    "pg-cursor": {
+      "version": "2.6.0",
+      "resolved": "https://registry.npmjs.org/pg-cursor/-/pg-cursor-2.6.0.tgz",
+      "integrity": "sha512-BFLg40CTgBJ+LX9EwqjztUYaKxpxLffMmDTmlQNMCustX/JxMTYimxRkdhZvPYZGp++/2LjuqkKtO5DVVq0FNg=="
+    },
+    "pg-format": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/pg-format/-/pg-format-1.0.4.tgz",
+      "integrity": "sha1-J3NCNsKtP05QZJFaWTNOIAQKgo4="
+    },
+    "pg-int8": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/pg-int8/-/pg-int8-1.0.1.tgz",
+      "integrity": "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw=="
+    },
+    "pg-listen": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/pg-listen/-/pg-listen-1.7.0.tgz",
+      "integrity": "sha512-MKDwKLm4ryhy7iq1yw1K1MvUzBdTkaT16HZToddX9QaT8XSdt3Kins5mYH6DLECGFzFWG09VdXvWOIYogjXrsg==",
+      "requires": {
+        "debug": "^4.1.1",
+        "pg-format": "^1.0.4",
+        "typed-emitter": "^0.1.0"
+      }
+    },
+    "pg-pool": {
+      "version": "3.4.1",
+      "resolved": "https://registry.npmjs.org/pg-pool/-/pg-pool-3.4.1.tgz",
+      "integrity": "sha512-TVHxR/gf3MeJRvchgNHxsYsTCHQ+4wm3VIHSS19z8NC0+gioEhq1okDY1sm/TYbfoP6JLFx01s0ShvZ3puP/iQ=="
+    },
+    "pg-protocol": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/pg-protocol/-/pg-protocol-1.5.0.tgz",
+      "integrity": "sha512-muRttij7H8TqRNu/DxrAJQITO4Ac7RmX3Klyr/9mJEOBeIpgnF8f9jAfRz5d3XwQZl5qBjF9gLsUtMPJE0vezQ=="
+    },
+    "pg-types": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/pg-types/-/pg-types-2.2.0.tgz",
+      "integrity": "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==",
+      "requires": {
+        "pg-int8": "1.0.1",
+        "postgres-array": "~2.0.0",
+        "postgres-bytea": "~1.0.0",
+        "postgres-date": "~1.0.4",
+        "postgres-interval": "^1.1.0"
+      }
+    },
+    "pgpass": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/pgpass/-/pgpass-1.0.4.tgz",
+      "integrity": "sha512-YmuA56alyBq7M59vxVBfPJrGSozru8QAdoNlWuW3cz8l+UX3cWge0vTvjKhsSHSJpo3Bom8/Mm6hf0TR5GY0+w==",
+      "requires": {
+        "split2": "^3.1.1"
+      }
+    },
+    "postgres-array": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz",
+      "integrity": "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA=="
+    },
+    "postgres-bytea": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/postgres-bytea/-/postgres-bytea-1.0.0.tgz",
+      "integrity": "sha1-AntTPAqokOJtFy1Hz5zOzFIazTU="
+    },
+    "postgres-date": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/postgres-date/-/postgres-date-1.0.7.tgz",
+      "integrity": "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q=="
+    },
+    "postgres-interval": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/postgres-interval/-/postgres-interval-1.2.0.tgz",
+      "integrity": "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==",
+      "requires": {
+        "xtend": "^4.0.0"
+      }
+    },
+    "punycode": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz",
+      "integrity": "sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A=="
+    },
+    "readable-stream": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.0.tgz",
+      "integrity": "sha512-BViHy7LKeTz4oNnkcLJ+lVSL6vpiFeX6/d3oSH8zCW7UxP2onchk+vTGB143xuFjHS3deTgkKoXXymXqymiIdA==",
+      "requires": {
+        "inherits": "^2.0.3",
+        "string_decoder": "^1.1.1",
+        "util-deprecate": "^1.0.1"
+      }
+    },
+    "require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="
+    },
+    "rimraf": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz",
+      "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==",
+      "dev": true,
+      "requires": {
+        "glob": "^7.1.3"
+      }
+    },
+    "safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="
+    },
+    "semver": {
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-4.3.2.tgz",
+      "integrity": "sha1-x6BxWKgL7dBSNVt3DYLWZA+AO+c="
+    },
+    "slice-ansi": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-4.0.0.tgz",
+      "integrity": "sha512-qMCMfhY040cVHT43K9BFygqYbUPFZKHOg7K73mtTWJRb8pyP3fzf4Ixd5SzdEJQ6MRUg/WBnOLxghZtKKurENQ==",
+      "requires": {
+        "ansi-styles": "^4.0.0",
+        "astral-regex": "^2.0.0",
+        "is-fullwidth-code-point": "^3.0.0"
+      }
+    },
+    "split2": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/split2/-/split2-3.2.2.tgz",
+      "integrity": "sha512-9NThjpgZnifTkJpzTZ7Eue85S49QwpNhZTq6GRJwObb6jnLFNGB7Qm73V5HewTROPyxD0C29xqmaI68bQtV+hg==",
+      "requires": {
+        "readable-stream": "^3.0.0"
+      }
+    },
+    "string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "requires": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      }
+    },
+    "string_decoder": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
+      "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
+      "requires": {
+        "safe-buffer": "~5.2.0"
+      }
+    },
+    "strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "requires": {
+        "ansi-regex": "^5.0.1"
+      }
+    },
+    "table": {
+      "version": "6.7.2",
+      "resolved": "https://registry.npmjs.org/table/-/table-6.7.2.tgz",
+      "integrity": "sha512-UFZK67uvyNivLeQbVtkiUs8Uuuxv24aSL4/Vil2PJVtMgU8Lx0CYkP12uCGa3kjyQzOSgV1+z9Wkb82fCGsO0g==",
+      "requires": {
+        "ajv": "^8.0.1",
+        "lodash.clonedeep": "^4.5.0",
+        "lodash.truncate": "^4.4.2",
+        "slice-ansi": "^4.0.0",
+        "string-width": "^4.2.3",
+        "strip-ansi": "^6.0.1"
+      }
+    },
+    "typed-emitter": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/typed-emitter/-/typed-emitter-0.1.0.tgz",
+      "integrity": "sha512-Tfay0l6gJMP5rkil8CzGbLthukn+9BN/VXWcABVFPjOoelJ+koW8BuPZYk+h/L+lEeIp1fSzVRiWRPIjKVjPdg=="
+    },
+    "typescript": {
+      "version": "4.4.2",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.4.2.tgz",
+      "integrity": "sha512-gzP+t5W4hdy4c+68bfcv0t400HVJMMd2+H9B7gae1nQlBzCqvrXX+6GL/b3GAgyTH966pzrZ70/fRjwAtZksSQ==",
+      "dev": true
+    },
+    "uri-js": {
+      "version": "4.4.1",
+      "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz",
+      "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==",
+      "requires": {
+        "punycode": "^2.1.0"
+      }
+    },
+    "util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha1-RQ1Nyfpw3nMnYvvS1KKJgUGaDM8="
+    },
+    "wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=",
+      "dev": true
+    },
+    "xtend": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz",
+      "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ=="
+    }
+  }
+}
--- a/utils/package.json
+++ b/utils/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@stacks/blockchain-api-utils",
+  "version": "0.1.0",
+  "description": "Utilities for Stacks Blockchain API",
+  "main": "lib/index.js",
+  "scripts": {
+    "build": "rimraf ./lib && npm run build:node",
+    "build:node": "tsc",
+    "start": "node ./lib/utils/src/index.js"
+  },
+  "prettier": "@stacks/prettier-config",
+  "dependencies": {
+    "bignumber.js": "^9.0.1",
+    "dotenv": "^10.0.0",
+    "extra-bigint": "0.0.62",
+    "getopts": "^2.3.0",
+    "pg": "^8.2.1",
+    "pg-copy-streams": "^5.1.1",
+    "pg-cursor": "^2.6.0",
+    "pg-listen": "^1.7.0",
+    "table": "^6.7.2"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.6.1",
+    "rimraf": "^3.0.2",
+    "typescript": "^4.4.2"
+  }
+}
--- a/utils/src/index.ts
+++ b/utils/src/index.ts
@@ -0,0 +1,149 @@
+import * as dotenv from 'dotenv';
+import * as getopts from 'getopts';
+import * as bigint from 'extra-bigint';
+import { table } from 'table';
+import { StacksCoreRpcClient } from '../../src/core-rpc/client';
+import { PgDataStore } from '../../src/datastore/postgres-store';
+
+type AddressBalanceResult = {
+  count: number;
+  address: string;
+  apiBalance?: bigint;
+  nodeBalance?: bigint;
+};
+
+type BlockInfo = {
+  block_height: number;
+  block_hash: Buffer;
+  index_block_hash: Buffer;
+};
+
+type TableCellValue = string | number | bigint | undefined;
+
+/**
+ * Prints the account balance as reported by the local DB and the Stacks node of the `count`
+ * accounts with the greatest number of STX transfer events.
+ * @param count Number of top accounts to query
+ * @param blockHeight Specific block height at which to query balances
+ */
+async function printTopAccountBalances(count: number, blockHeight: number) {
+  const db = await PgDataStore.connect(true);
+
+  const heightText = blockHeight == 0 ? 'chain tip' : `block height ${blockHeight}`;
+  console.log(`Calculating balances for top ${count} accounts at ${heightText}...`);
+  const blockInfo = await db.query(async client => {
+    const result = await client.query<BlockInfo>(
+      `
+      SELECT block_height, block_hash, index_block_hash
+      FROM blocks
+      WHERE canonical = true AND block_height = (
+        CASE
+          WHEN $1=0 THEN (SELECT MAX(block_height) FROM blocks)
+          ELSE $1
+        END
+      )
+      `,
+      [blockHeight]
+    );
+    return result.rows[0];
+  });
+  // First, get the top addresses.
+  const addressBalances = await db.query(async client => {
+    const result = await client.query<AddressBalanceResult>(
+      `
+      WITH addresses AS ((
+        SELECT
+          sender AS address
+        FROM
+          stx_events
+        WHERE
+          sender IS NOT NULL
+          AND block_height <= $1)
+      UNION ALL (
+        SELECT
+          recipient AS address
+        FROM
+          stx_events
+        WHERE
+          recipient IS NOT NULL
+          AND block_height <= $1)
+      )
+      SELECT
+        COUNT(*) AS count, address
+      FROM
+        addresses
+      GROUP BY
+        address
+      ORDER BY
+        count DESC
+      LIMIT $2;
+      `,
+      [blockInfo.block_height, count]
+    );
+    return result.rows;
+  });
+  // Next, fill them up with balances from DB and node.
+  const dbBalances = addressBalances.map(async item => {
+    const balance = await db.getStxBalanceAtBlock(item.address, blockInfo.block_height);
+    item.apiBalance = balance.balance;
+  });
+  const nodeBalances = addressBalances.map(async item => {
+    const account = await new StacksCoreRpcClient().getAccount(
+      item.address,
+      false,
+      blockInfo.index_block_hash.toString('hex')
+    );
+    item.nodeBalance = BigInt(account.balance) + BigInt(account.locked);
+  });
+  await Promise.all(dbBalances.concat(nodeBalances));
+
+  const tabularData: TableCellValue[][] = [
+    ['event count', 'address', 'api balance', 'node balance', 'delta'],
+  ];
+  addressBalances.forEach(item => {
+    tabularData.push([
+      item.count,
+      item.address,
+      item.apiBalance,
+      item.nodeBalance,
+      bigint.abs((item.apiBalance ?? BigInt(0)) - (item.nodeBalance ?? BigInt(0))),
+    ]);
+  });
+  console.log(table(tabularData));
+
+  await db.close();
+}
+
+function printUsage() {
+  console.log(`Usage:`);
+  console.log(`  node ./index.js stx-balances [--count=<count>] [--block-height=<height>]`);
+}
+
+async function handleProgramArgs() {
+  const parsedOpts = getopts(process.argv.slice(2));
+  const args = {
+    operand: parsedOpts._[0],
+    options: parsedOpts,
+  } as {
+    operand: 'stx-balances';
+    options: {
+      ['count']?: number;
+      ['block-height']?: number;
+    };
+  };
+
+  if (args.operand === 'stx-balances') {
+    await printTopAccountBalances(args.options.count ?? 10, args.options['block-height'] ?? 0);
+  } else if (parsedOpts._[0]) {
+    printUsage();
+    throw new Error(`Unexpected program argument: ${parsedOpts._[0]}`);
+  } else {
+    printUsage();
+  }
+}
+
+dotenv.config({ path: '../.env' });
+void handleProgramArgs().catch(error => {
+  console.error(error);
+  process.exit(1);
+});
--- a/utils/tsconfig.json
+++ b/utils/tsconfig.json
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "declaration": false,
+    "strict": true,
+    "sourceMap": true,
+    "esModuleInterop": false,
+    "allowSyntheticDefaultImports": false,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "outDir": "lib",
+    "baseUrl": ".",
+    "paths": {
+      "@stacks/stacks-blockchain-api-types": ["../docs"]
+    }
+  },
+  "include": ["./src/**/*.ts", "../src/@types/pg-cursor/*.ts"],
+  "exclude": ["lib", "node_modules"]
+}