feat: pox stacker & signer cycle details (#1873)

* feat: pox signer event ingestion * test: add pox_set ingestion tests * feat: progress on associating stacker info to signer data * feat: ingest reward set data from /new_block event * feat: ingest pox4 event cycle IDs * fix: filter signer pox events by cycleID ranges * chore: use nodejs v20 in `launch w/ postgres` * chore: initial test * chore: progress on cycles endpoint * feat: ingest `pox_ustx_threshold` from /new_block reward_set * chore: update reward_set.rewarded_addresses ingestion to new burnchain address string format * feat: cycles table * feat: signers endpoint * feat: single signer * feat: stackers * fix: remove old query * fix: exports * fix: stacker example * fix: tests * fix: test * fix: pox tests * fix: tests * fix: pox cycle signers deterministic ordering --------- Co-authored-by: Rafael Cardenas <rafael@rafaelcr.com>
hirosystems · Mar 20, 2024 · d2c2805 · d2c2805
1 parent 7122a4f
commit d2c2805
Show file tree

Hide file tree

Showing 38 changed files with 1,861 additions and 15 deletions.
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -55,6 +55,7 @@
       "skipFiles": [
         "<node_internals>/**"
       ],
+      "runtimeVersion": "20",
       "runtimeArgs": ["-r", "ts-node/register/transpile-only", "-r", "tsconfig-paths/register"],
       "args": ["${workspaceFolder}/src/index.ts"],
       "outputCapture": "std",

diff --git a/docs/api/stacking/get-pox-cycle-signer-stackers.example.json b/docs/api/stacking/get-pox-cycle-signer-stackers.example.json
@@ -0,0 +1,12 @@
+{
+  "limit": 20,
+  "offset": 0,
+  "total": 1,
+  "results": [
+    {
+      "pox_address": "15Z2sAvjgVDpcBh4vx9g2XKU8FVHYcXNaj",
+      "stacked_amount": "686251350000000000",
+      "stacker_address": "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP"
+    }
+  ]
+}
diff --git a/docs/api/stacking/get-pox-cycle-signer-stackers.schema.json b/docs/api/stacking/get-pox-cycle-signer-stackers.schema.json
@@ -0,0 +1,29 @@
+{
+  "description": "GET request that returns stackers for a signer in a PoX cycle",
+  "additionalProperties": false,
+  "title": "PoxCycleSignerStackersListResponse",
+  "type": "object",
+  "required": ["results", "limit", "offset", "total"],
+  "properties": {
+    "limit": {
+      "type": "integer",
+      "maximum": 200,
+      "description": "The number of stackers to return"
+    },
+    "offset": {
+      "type": "integer",
+      "description": "The number to stackers to skip (starting at `0`)",
+      "default": 0
+    },
+    "total": {
+      "type": "integer",
+      "description": "The total number of stackers"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "$ref": "../../entities/stacking/stacker.schema.json"
+      }
+    }
+  }
+}
diff --git a/docs/api/stacking/get-pox-cycle-signers.example.json b/docs/api/stacking/get-pox-cycle-signers.example.json
@@ -0,0 +1,28 @@
+{
+  "limit": 20,
+  "offset": 0,
+  "total": 3,
+  "results": [
+    {
+      "signing_key": "0x038e3c4529395611be9abf6fa3b6987e81d402385e3d605a073f42f407565a4a3d",
+      "stacked_amount": "686251350000000000",
+      "stacked_amount_percent": 50,
+      "weight": 5,
+      "weight_percent": 55.55555555555556
+    },
+    {
+      "signing_key": "0x029874497a7952483aa23890e9d0898696f33864d3df90939930a1f45421fe3b09",
+      "stacked_amount": "457500900000000000",
+      "stacked_amount_percent": 33.333333333333336,
+      "weight": 3,
+      "weight_percent": 33.33333333333333
+    },
+    {
+      "signing_key": "0x02dcde79b38787b72d8e5e0af81cffa802f0a3c8452d6b46e08859165f49a72736",
+      "stacked_amount": "228750450000000000",
+      "stacked_amount_percent": 16.666666666666668,
+      "weight": 1,
+      "weight_percent": 11.11111111111111
+    }
+  ]
+}
diff --git a/docs/api/stacking/get-pox-cycle-signers.schema.json b/docs/api/stacking/get-pox-cycle-signers.schema.json
@@ -0,0 +1,29 @@
+{
+  "description": "GET request that returns signers for a PoX cycle",
+  "additionalProperties": false,
+  "title": "PoxCycleSignersListResponse",
+  "type": "object",
+  "required": ["results", "limit", "offset", "total"],
+  "properties": {
+    "limit": {
+      "type": "integer",
+      "maximum": 200,
+      "description": "The number of signers to return"
+    },
+    "offset": {
+      "type": "integer",
+      "description": "The number to signers to skip (starting at `0`)",
+      "default": 0
+    },
+    "total": {
+      "type": "integer",
+      "description": "The total number of signers"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "$ref": "../../entities/stacking/signer.schema.json"
+      }
+    }
+  }
+}
diff --git a/docs/api/stacking/get-pox-cycles.example.json b/docs/api/stacking/get-pox-cycles.example.json
@@ -0,0 +1,31 @@
+{
+  "limit": 20,
+  "offset": 0,
+  "total": 3,
+  "results": [
+    {
+      "block_height": 50,
+      "cycle_number": 14,
+      "index_block_hash": "0xf5be33abc4e508bdaf2191e88339372edcb3358c44e2a31e1b9b44f2880dde09",
+      "total_signers": 3,
+      "total_stacked_amount": "1372502700000000000",
+      "total_weight": 9
+    },
+    {
+      "block_height": 22,
+      "cycle_number": 13,
+      "index_block_hash": "0x5077c7d971dd83cd3ba19dca579e3cc8dcf17913186b66093c94520e50d3b7b2",
+      "total_signers": 3,
+      "total_stacked_amount": "1372502700000000000",
+      "total_weight": 9
+    },
+    {
+      "block_height": 13,
+      "cycle_number": 12,
+      "index_block_hash": "0x62d06851fe03f17cb45a488ae70bd8e0c5c308c523f37814ad4df36bd2108713",
+      "total_signers": 3,
+      "total_stacked_amount": "1372502700000000000",
+      "total_weight": 9
+    }
+  ]
+}
diff --git a/docs/api/stacking/get-pox-cycles.schema.json b/docs/api/stacking/get-pox-cycles.schema.json
@@ -0,0 +1,29 @@
+{
+  "description": "GET request that returns PoX cycles",
+  "additionalProperties": false,
+  "title": "PoxCycleListResponse",
+  "type": "object",
+  "required": ["results", "limit", "offset", "total"],
+  "properties": {
+    "limit": {
+      "type": "integer",
+      "maximum": 200,
+      "description": "The number of cycles to return"
+    },
+    "offset": {
+      "type": "integer",
+      "description": "The number to cycles to skip (starting at `0`)",
+      "default": 0
+    },
+    "total": {
+      "type": "integer",
+      "description": "The total number of cycles"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "$ref": "../../entities/stacking/pox-cycle.schema.json"
+      }
+    }
+  }
+}
diff --git a/docs/entities/stacking/pox-cycle.example.json b/docs/entities/stacking/pox-cycle.example.json
@@ -0,0 +1,8 @@
+{
+  "block_height": 50,
+  "cycle_number": 14,
+  "index_block_hash": "0xf5be33abc4e508bdaf2191e88339372edcb3358c44e2a31e1b9b44f2880dde09",
+  "total_signers": 3,
+  "total_stacked_amount": "1372502700000000000",
+  "total_weight": 9
+}
diff --git a/docs/entities/stacking/pox-cycle.schema.json b/docs/entities/stacking/pox-cycle.schema.json
@@ -0,0 +1,33 @@
+{
+  "title": "PoxCycle",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "block_height",
+    "index_block_hash",
+    "cycle_number",
+    "total_weight",
+    "total_stacked_amount",
+    "total_signers"
+  ],
+  "properties": {
+    "block_height": {
+      "type": "integer"
+    },
+    "index_block_hash": {
+      "type": "string"
+    },
+    "cycle_number": {
+      "type": "integer"
+    },
+    "total_weight": {
+      "type": "integer"
+    },
+    "total_stacked_amount": {
+      "type": "string"
+    },
+    "total_signers": {
+      "type": "integer"
+    }
+  }
+}
diff --git a/docs/entities/stacking/signer.example.json b/docs/entities/stacking/signer.example.json
@@ -0,0 +1,7 @@
+{
+  "signing_key": "0x038e3c4529395611be9abf6fa3b6987e81d402385e3d605a073f42f407565a4a3d",
+  "stacked_amount": "686251350000000000",
+  "stacked_amount_percent": 50,
+  "weight": 5,
+  "weight_percent": 55.55555555555556
+}
diff --git a/docs/entities/stacking/signer.schema.json b/docs/entities/stacking/signer.schema.json
@@ -0,0 +1,29 @@
+{
+  "title": "PoxSigner",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "signing_key",
+    "weight",
+    "stacked_amount",
+    "weight_percent",
+    "stacked_amount_percent"
+  ],
+  "properties": {
+    "signing_key": {
+      "type": "string"
+    },
+    "weight": {
+      "type": "integer"
+    },
+    "stacked_amount": {
+      "type": "string"
+    },
+    "weight_percent": {
+      "type": "number"
+    },
+    "stacked_amount_percent": {
+      "type": "number"
+    }
+  }
+}
diff --git a/docs/entities/stacking/stacker.example.json b/docs/entities/stacking/stacker.example.json
@@ -0,0 +1,5 @@
+{
+  "pox_address": "15Z2sAvjgVDpcBh4vx9g2XKU8FVHYcXNaj",
+  "stacked_amount": "686251350000000000",
+  "stacker_address": "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP"
+}
diff --git a/docs/entities/stacking/stacker.schema.json b/docs/entities/stacking/stacker.schema.json
@@ -0,0 +1,21 @@
+{
+  "title": "PoxStacker",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "stacker_address",
+    "stacked_amount",
+    "pox_address"
+  ],
+  "properties": {
+    "stacker_address": {
+      "type": "string"
+    },
+    "stacked_amount": {
+      "type": "string"
+    },
+    "pox_address": {
+      "type": "string"
+    }
+  }
+}
diff --git a/docs/generated.d.ts b/docs/generated.d.ts
@@ -97,6 +97,9 @@ export type SchemaMergeRootStub =
   | SmartContractFound
   | SmartContractNotFound
   | PoolDelegationsResponse
+  | PoxCycleSignerStackersListResponse
+  | PoxCycleSignersListResponse
+  | PoxCycleListResponse
   | {
       [k: string]: unknown | undefined;
     }
@@ -182,6 +185,9 @@ export type SchemaMergeRootStub =
   | RosettaTransaction
   | SmartContractStatus
   | PoolDelegation
+  | PoxCycle
+  | PoxSigner
+  | PoxStacker
   | NonFungibleTokenHistoryEventWithTxId
   | NonFungibleTokenHistoryEventWithTxMetadata
   | NonFungibleTokenHistoryEvent
@@ -3153,6 +3159,80 @@ export interface PoolDelegation {
    */
   tx_id: string;
 }
+/**
+ * GET request that returns stackers for a signer in a PoX cycle
+ */
+export interface PoxCycleSignerStackersListResponse {
+  /**
+   * The number of stackers to return
+   */
+  limit: number;
+  /**
+   * The number to stackers to skip (starting at `0`)
+   */
+  offset: number;
+  /**
+   * The total number of stackers
+   */
+  total: number;
+  results: PoxStacker[];
+}
+export interface PoxStacker {
+  stacker_address: string;
+  stacked_amount: string;
+  pox_address: string;
+}
+/**
+ * GET request that returns signers for a PoX cycle
+ */
+export interface PoxCycleSignersListResponse {
+  /**
+   * The number of signers to return
+   */
+  limit: number;
+  /**
+   * The number to signers to skip (starting at `0`)
+   */
+  offset: number;
+  /**
+   * The total number of signers
+   */
+  total: number;
+  results: PoxSigner[];
+}
+export interface PoxSigner {
+  signing_key: string;
+  weight: number;
+  stacked_amount: string;
+  weight_percent: number;
+  stacked_amount_percent: number;
+}
+/**
+ * GET request that returns PoX cycles
+ */
+export interface PoxCycleListResponse {
+  /**
+   * The number of cycles to return
+   */
+  limit: number;
+  /**
+   * The number to cycles to skip (starting at `0`)
+   */
+  offset: number;
+  /**
+   * The total number of cycles
+   */
+  total: number;
+  results: PoxCycle[];
+}
+export interface PoxCycle {
+  block_height: number;
+  index_block_hash: string;
+  cycle_number: number;
+  total_weight: number;
+  total_stacked_amount: string;
+  total_signers: number;
+}
 /**
  * List of Non-Fungible Token history events
  */