feat: add bond endpoints

.github/workflows/ci.yml

@@ -72,17 +72,18 @@ jobs:
             api:transactions,
             api:v2-proxy,
             api:v3,
-            krypton:bns-e2e,
-            krypton:faucet-btc,
-            krypton:faucet-stx,
-            krypton:pox-4-btc-address-formats,
-            krypton:pox-4-burnchain-delegate-stx,
-            krypton:pox-4-burnchain-stack-stx,
-            krypton:pox-4-delegate-aggregation,
-            krypton:pox-4-delegate-revoked-stacking,
-            krypton:pox-4-delegate-stacking,
-            krypton:pox-4-stack-extend-increase,
-            krypton:rpc,
+            api:pox5,
+            # krypton:bns-e2e,
+            # krypton:faucet-btc,
+            # krypton:faucet-stx,
+            # krypton:pox-4-btc-address-formats,
+            # krypton:pox-4-burnchain-delegate-stx,
+            # krypton:pox-4-burnchain-stack-stx,
+            # krypton:pox-4-delegate-aggregation,
+            # krypton:pox-4-delegate-revoked-stacking,
+            # krypton:pox-4-delegate-stacking,
+            # krypton:pox-4-stack-extend-increase,
+            # krypton:rpc,
             snp,
           ]
     runs-on: ubuntu-latest

migrations/1779392293803_pox5-events.ts

@@ -22,14 +22,29 @@ export const up = (pgm: MigrationBuilder) => {
       type: 'integer',
       notNull: true,
     },
+    block_hash: {
+      type: 'bytea',
+    },
+    block_time: {
+      type: 'bigint',
+    },
     index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    parent_block_hash: {
+      type: 'bytea',
+    },
     parent_index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    burn_block_height: {
+      type: 'integer',
+    },
+    burn_block_time: {
+      type: 'bigint',
+    },
     microblock_hash: {
       type: 'bytea',
       notNull: true,

migrations/1779487960678_bonds.ts

@@ -20,14 +20,34 @@ export const up = (pgm: MigrationBuilder) => {
       type: 'integer',
       notNull: true,
     },
+    block_hash: {
+      type: 'bytea',
+      notNull: true,
+    },
+    block_time: {
+      type: 'bigint',
+      notNull: true,
+    },
     index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    parent_block_hash: {
+      type: 'bytea',
+      notNull: true,
+    },
     parent_index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    burn_block_height: {
+      type: 'integer',
+      notNull: true,
+    },
+    burn_block_time: {
+      type: 'bigint',
+      notNull: true,
+    },
     microblock_hash: {
       type: 'bytea',
       notNull: true,
@@ -87,6 +107,7 @@ export const up = (pgm: MigrationBuilder) => {
     btc_capacity: {
       type: 'numeric',
       notNull: true,
+      default: 0,
     },
     btc_locked: {
       type: 'numeric',

migrations/1779487971367_bond-allowlist-entries.ts

@@ -20,14 +20,29 @@ export const up = (pgm: MigrationBuilder) => {
       type: 'integer',
       notNull: true,
     },
+    block_hash: {
+      type: 'bytea',
+    },
+    block_time: {
+      type: 'bigint',
+    },
     index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    parent_block_hash: {
+      type: 'bytea',
+    },
     parent_index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    burn_block_height: {
+      type: 'integer',
+    },
+    burn_block_time: {
+      type: 'bigint',
+    },
     microblock_hash: {
       type: 'bytea',
       notNull: true,

migrations/1779487975550_bond-registrations.ts

@@ -20,14 +20,29 @@ export const up = (pgm: MigrationBuilder) => {
       type: 'integer',
       notNull: true,
     },
+    block_hash: {
+      type: 'bytea',
+    },
+    block_time: {
+      type: 'bigint',
+    },
     index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    parent_block_hash: {
+      type: 'bytea',
+    },
     parent_index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    burn_block_height: {
+      type: 'integer',
+    },
+    burn_block_time: {
+      type: 'bigint',
+    },
     microblock_hash: {
       type: 'bytea',
       notNull: true,

migrations/1779742831642_principal-bond-positions.ts

@@ -28,14 +28,29 @@ export function up(pgm: MigrationBuilder): void {
       type: 'integer',
       notNull: true,
     },
+    block_hash: {
+      type: 'bytea',
+    },
+    block_time: {
+      type: 'bigint',
+    },
     index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    parent_block_hash: {
+      type: 'bytea',
+    },
     parent_index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    burn_block_height: {
+      type: 'integer',
+    },
+    burn_block_time: {
+      type: 'bigint',
+    },
     microblock_hash: {
       type: 'bytea',
       notNull: true,

migrations/1779745340752_bond-reward-distributions.ts

@@ -20,14 +20,29 @@ export function up(pgm: MigrationBuilder): void {
       type: 'integer',
       notNull: true,
     },
+    block_hash: {
+      type: 'bytea',
+    },
+    block_time: {
+      type: 'bigint',
+    },
     index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    parent_block_hash: {
+      type: 'bytea',
+    },
     parent_index_block_hash: {
       type: 'bytea',
       notNull: true,
     },
+    burn_block_height: {
+      type: 'integer',
+    },
+    burn_block_time: {
+      type: 'bigint',
+    },
     microblock_hash: {
       type: 'bytea',
       notNull: true,

package.json

@@ -23,6 +23,7 @@
     "test:api:transactions": "NODE_ENV=test node --import tsx --test --test-global-setup=./tests/api/setup.ts --test-concurrency=1 ./tests/api/transactions/**/*.test.ts",
     "test:api:v2-proxy": "NODE_ENV=test node --import tsx --test --test-global-setup=./tests/api/setup.ts --test-concurrency=1 ./tests/api/v2-proxy/**/*.test.ts",
     "test:api:v3": "NODE_ENV=test node --import tsx --test --test-global-setup=./tests/api/setup.ts --test-concurrency=1 ./tests/api/v3/**/*.test.ts",
+    "test:api:pox5": "NODE_ENV=test node --import tsx --test --test-global-setup=./tests/api/setup.ts --test-concurrency=1 ./tests/api/pox5/**/*.test.ts",
     "test:snp": "NODE_ENV=test node --import tsx --test --test-global-setup=./tests/snp/setup.ts --test-concurrency=1 ./tests/snp/**/*.test.ts",
     "test:krypton:bns-e2e": "NODE_ENV=test node --import tsx --test --test-global-setup=./tests/krypton/setup.ts --test-concurrency=1 ./tests/krypton/bns-e2e/**/*.test.ts",
     "test:krypton:faucet-btc": "NODE_ENV=test node --import tsx --test --test-global-setup=./tests/krypton/setup.ts --test-concurrency=1 ./tests/krypton/faucet-btc/**/*.test.ts",
@@ -70,7 +71,7 @@
     "@stacks/common": "7.3.1",
     "@stacks/encryption": "7.4.0",
     "@stacks/network": "7.3.1",
-    "@stacks/node-publisher-client": "2.2.0",
+    "@stacks/node-publisher-client": "2.2.1",
     "@stacks/stacking": "7.4.0",
     "@stacks/transactions": "7.4.0",
     "bignumber.js": "10.0.2",

src/api/init.ts

@@ -53,6 +53,8 @@ import { PrincipalsRoutes } from './routes/v3/principals.js';
 import { TransactionsRoutes } from './routes/v3/transactions.js';
 import { MempoolRoutes } from './routes/v3/mempool.js';
 import { BlocksRoutes } from './routes/v3/blocks.js';
+import { StakingBondsRoutes } from './routes/v3/staking-bonds.js';
+import { StakingPrincipalsRoutes } from './routes/v3/staking-principals.js';
 
 export interface ApiServer {
   fastifyApp: FastifyInstance;
@@ -105,10 +107,12 @@ export const StacksApiRoutes: FastifyPluginAsync<
 
   await fastify.register(
     async fastify => {
+      await fastify.register(BlocksRoutes);
+      await fastify.register(MempoolRoutes);
       await fastify.register(PrincipalsRoutes);
+      await fastify.register(StakingBondsRoutes);
+      await fastify.register(StakingPrincipalsRoutes);
       await fastify.register(TransactionsRoutes);
-      await fastify.register(MempoolRoutes);
-      await fastify.register(BlocksRoutes);
     },
     { prefix: '/extended/v3' }
   );

src/api/routes/v3/staking-principals.ts

@@ -1,7 +1,10 @@
 import { FastifyPluginAsync } from 'fastify';
 import { Server } from 'node:http';
 import { Type, TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+import { handleChainTipCache } from '../../controllers/cache-controller.js';
 import { PrincipalSchema } from '../../schemas/v3/entities/common.js';
+import { PrincipalBondPositionSchema } from '../../schemas/v3/entities/principal-bond-positions.js';
+import { serializeDbPrincipalBondPosition } from '../../serializers/v3/bonds.js';
 
 export const StakingPrincipalsRoutes: FastifyPluginAsync<
   Record<never, never>,
@@ -11,18 +14,25 @@ export const StakingPrincipalsRoutes: FastifyPluginAsync<
   fastify.get(
     '/staking/principals/:principal/positions',
     {
+      preHandler: handleChainTipCache,
       schema: {
         operationId: 'get_principal_staking_positions',
         summary: 'Get principal staking positions',
-        description: 'Get principal staking positions',
+        description: "Get a principal's bond positions across all bonds it is enrolled in",
         tags: ['Staking'],
         params: Type.Object({
           principal: PrincipalSchema,
         }),
+        response: {
+          200: Type.Array(PrincipalBondPositionSchema),
+        },
       },
     },
-    async (_req, reply) => {
-      await reply.send();
+    async (req, reply) => {
+      const positions = await fastify.db.v3.getPrincipalStakingPositions({
+        principal: req.params.principal,
+      });
+      await reply.send(positions.map(serializeDbPrincipalBondPosition));
     }
   );
 

src/api/schemas/v3/entities/principal-bond-positions.ts

@@ -19,9 +19,6 @@ export const PrincipalBondPositionSchema = Type.Object({
   balances: BondBalancesSchema,
   enrollment: Type.Object({
     tx_id: TransactionIdSchema,
-    pox_address: Type.String({
-      description: 'The POX address of the principal',
-    }),
     btc_lockup: Type.Object({
       amount: Type.String({
         description: 'The amount of BTC that is locked up for this principal',