feat: add /extended/v2/smart-contracts/status endpoint (#1833)

rafaelcr · web-flow · commit 3535c113e0d3 · 2024-01-18T11:23:29.000-06:00
* feat: new endpoint

* docs: openapi

* feat: response type

* fix: add route

* fix: new schema

* test: add

* fix: rename result

* docs: example result
diff --git a/docs/api/smart-contracts/get-smart-contracts-status.example.json b/docs/api/smart-contracts/get-smart-contracts-status.example.json
@@ -0,0 +1,31 @@
+{
+  "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridged-v1-1": {
+    "found": true,
+    "result": {
+      "contract_id": "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridged-v1-1",
+      "status": "success",
+      "tx_id": "0x8542d28e427256ea3c29dcd8793222891999ceff4ef1bb062e2f21cb6def6884",
+      "block_height": 111021
+    }
+  },
+  "SP1JTCR202ECC6333N7ZXD7MK7E3ZTEEE1MJ73C60.name-registrar": {
+    "found": true,
+    "result": {
+      "contract_id": "SP1JTCR202ECC6333N7ZXD7MK7E3ZTEEE1MJ73C60.name-registrar",
+      "status": "success",
+      "tx_id": "0x6e1114cce8c6f2e9c8130f9acd75d67bb667ae584f882acdd2db6dd74e6cbe5e",
+      "block_height": 113010
+    }
+  },
+  "SP4SZE494VC2YC5JYG7AYFQ44F5Q4PYV7DVMDPBG.stacking-dao-core-v1": {
+    "found": true,
+    "result": {
+      "contract_id": "SP4SZE494VC2YC5JYG7AYFQ44F5Q4PYV7DVMDPBG.stacking-dao-core-v1",
+      "status": "pending",
+      "tx_id": "0x10bdcf10ffee72994f493ac36760f4e95a76c8471370182fd4705c2153dc173d"
+    }
+  },
+  "SP4SZE494VC2YC5JYG7AYFQ44F5Q4PYV7DVMDPBG.stacking-dao-core": {
+    "found": false
+  }
+}
diff --git a/docs/api/smart-contracts/get-smart-contracts-status.schema.json b/docs/api/smart-contracts/get-smart-contracts-status.schema.json
@@ -0,0 +1,15 @@
+{
+  "description": "GET request that returns the deployment status of multiple smart contracts",
+  "title": "SmartContractsStatusResponse",
+  "type": "object",
+  "additionalProperties": {
+    "anyOf": [
+      {
+        "$ref": "./smart-contract-found.schema.json"
+      },
+      {
+        "$ref": "./smart-contract-not-found.schema.json"
+      }
+    ]
+  }
+}
diff --git a/docs/api/smart-contracts/smart-contract-found.schema.json b/docs/api/smart-contracts/smart-contract-found.schema.json
@@ -0,0 +1,15 @@
+{
+  "type": "object",
+  "title": "SmartContractFound",
+  "additionalProperties": false,
+  "required": ["found", "result"],
+  "properties": {
+    "found": {
+      "type": "boolean",
+      "enum": [true]
+    },
+    "result": {
+      "$ref": "../../entities/smart-contracts/smart-contract-status.schema.json"
+    }
+  }
+}
diff --git a/docs/api/smart-contracts/smart-contract-not-found.schema.json b/docs/api/smart-contracts/smart-contract-not-found.schema.json
@@ -0,0 +1,12 @@
+{
+  "type": "object",
+  "title": "SmartContractNotFound",
+  "additionalProperties": false,
+  "properties": {
+    "found": {
+      "type": "boolean",
+      "enum": [false]
+    }
+  },
+  "required": ["found"]
+}
diff --git a/docs/entities/smart-contracts/smart-contract-status.example.json b/docs/entities/smart-contracts/smart-contract-status.example.json
@@ -0,0 +1,6 @@
+{
+  "contract_id": "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridged-v1-1",
+  "status": "success",
+  "tx_id": "0x8542d28e427256ea3c29dcd8793222891999ceff4ef1bb062e2f21cb6def6884",
+  "block_height": 111021
+}
diff --git a/docs/entities/smart-contracts/smart-contract-status.schema.json b/docs/entities/smart-contracts/smart-contract-status.schema.json
@@ -0,0 +1,29 @@
+{
+  "title": "SmartContractStatus",
+  "description": "Deployment status of a smart contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "tx_id",
+    "contract_id"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "description": "Smart contract deployment transaction status"
+    },
+    "tx_id": {
+      "type": "string",
+      "description": "Deployment transaction ID"
+    },
+    "contract_id": {
+      "type": "string",
+      "description": "Smart contract ID"
+    },
+    "block_height": {
+      "type": "integer",
+      "description": "Height of the transaction confirmation block"
+    }
+  }
+}
diff --git a/docs/generated.d.ts b/docs/generated.d.ts
@@ -93,6 +93,9 @@ export type SchemaMergeRootStub =
   | SearchSuccessResult
   | TxSearchResult
   | SearchResult
+  | SmartContractsStatusResponse
+  | SmartContractFound
+  | SmartContractNotFound
   | PoolDelegationsResponse
   | {
       [k: string]: unknown | undefined;
@@ -177,6 +180,7 @@ export type SchemaMergeRootStub =
   | RosettaSyncStatus
   | TransactionIdentifier
   | RosettaTransaction
+  | SmartContractStatus
   | PoolDelegation
   | NonFungibleTokenHistoryEventWithTxId
   | NonFungibleTokenHistoryEventWithTxMetadata
@@ -3059,6 +3063,40 @@ export interface TxSearchResult {
     metadata?: Transaction;
   };
 }
+/**
+ * GET request that returns the deployment status of multiple smart contracts
+ */
+export interface SmartContractsStatusResponse {
+  [k: string]: (SmartContractFound | SmartContractNotFound) | undefined;
+}
+export interface SmartContractFound {
+  found: true;
+  result: SmartContractStatus;
+}
+/**
+ * Deployment status of a smart contract
+ */
+export interface SmartContractStatus {
+  /**
+   * Smart contract deployment transaction status
+   */
+  status: string;
+  /**
+   * Deployment transaction ID
+   */
+  tx_id: string;
+  /**
+   * Smart contract ID
+   */
+  contract_id: string;
+  /**
+   * Height of the transaction confirmation block
+   */
+  block_height?: number;
+}
+export interface SmartContractNotFound {
+  found: false;
+}
 /**
  * GET request that returns stacking pool member details for a given pool (delegator) principal
  */
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
@@ -834,6 +834,36 @@ paths:
               example:
                 $ref: ./api/transaction/get-transactions.example.json
 
+  /extended/v2/smart-contracts/status:
+    get:
+      summary: Get smart contracts status
+      description: |
+        Retrieves the deployment status of multiple smart contracts.
+      tags:
+        - Smart Contracts
+      operationId: get_smart_contracts_status
+      parameters:
+        - name: contract_id
+          in: query
+          description: contract ids to fetch status for
+          required: true
+          style: form
+          explode: true
+          schema:
+            type: array
+            example: "SPQZF23W7SEYBFG5JQ496NMY0G7379SRYEDREMSV.Candy"
+            items:
+              type: string
+      responses:
+        200:
+          description: List of smart contract status
+          content:
+            application/json:
+              schema:
+                $ref: ./api/smart-contracts/get-smart-contracts-status.schema.json
+              example:
+                $ref: ./api/smart-contracts/get-smart-contracts-status.example.json
+
   /extended/v1/block:
     get:
       summary: Get recent blocks
diff --git a/src/api/controllers/db-controller.ts b/src/api/controllers/db-controller.ts
@@ -149,7 +149,9 @@ export function getTxTypeId(typeString: Transaction['tx_type']): DbTxTypeId[] {
   }
 }
 
-function getTxStatusString(txStatus: DbTxStatus): TransactionStatus | MempoolTransactionStatus {
+export function getTxStatusString(
+  txStatus: DbTxStatus
+): TransactionStatus | MempoolTransactionStatus {
   switch (txStatus) {
     case DbTxStatus.Pending:
       return 'pending';
diff --git a/src/api/init.ts b/src/api/init.ts
@@ -53,6 +53,7 @@ import { createV2BlocksRouter } from './routes/v2/blocks';
 import { getReqQuery } from './query-helpers';
 import { createV2BurnBlocksRouter } from './routes/v2/burn-blocks';
 import { createMempoolRouter } from './routes/v2/mempool';
+import { createV2SmartContractsRouter } from './routes/v2/smart-contracts';
 
 export interface ApiServer {
   expressApp: express.Express;
@@ -234,6 +235,7 @@ export async function startApiServer(opts: {
           const v2 = express.Router();
           v2.use('/blocks', createV2BlocksRouter(datastore));
           v2.use('/burn-blocks', createV2BurnBlocksRouter(datastore));
+          v2.use('/smart-contracts', createV2SmartContractsRouter(datastore));
           v2.use('/mempool', createMempoolRouter(datastore));
           return v2;
         })()
diff --git a/src/api/routes/v2/helpers.ts b/src/api/routes/v2/helpers.ts
@@ -1,6 +1,8 @@
-import { BurnBlock, NakamotoBlock } from 'docs/generated';
-import { DbBlock, DbBurnBlock } from '../../../datastore/common';
+import { BurnBlock, NakamotoBlock, SmartContractsStatusResponse } from 'docs/generated';
+import { DbBlock, DbBurnBlock, DbSmartContractStatus } from '../../../datastore/common';
 import { unixEpochToIso } from '../../../helpers';
+import { SmartContractStatusParams } from './schemas';
+import { getTxStatusString } from '../../../api/controllers/db-controller';
 
 export function parseDbNakamotoBlock(block: DbBlock): NakamotoBlock {
   const apiBlock: NakamotoBlock = {
@@ -35,3 +37,27 @@ export function parseDbBurnBlock(block: DbBurnBlock): BurnBlock {
   };
   return burnBlock;
 }
+
+export function parseDbSmartContractStatusArray(
+  params: SmartContractStatusParams,
+  status: DbSmartContractStatus[]
+): SmartContractsStatusResponse {
+  const ids = new Set(
+    Array.isArray(params.contract_id) ? params.contract_id : [params.contract_id]
+  );
+  const response: SmartContractsStatusResponse = {};
+  for (const s of status) {
+    ids.delete(s.smart_contract_contract_id);
+    response[s.smart_contract_contract_id] = {
+      found: true,
+      result: {
+        contract_id: s.smart_contract_contract_id,
+        block_height: s.block_height,
+        status: getTxStatusString(s.status),
+        tx_id: s.tx_id,
+      },
+    };
+  }
+  for (const missingId of ids) response[missingId] = { found: false };
+  return response;
+}
diff --git a/src/api/routes/v2/schemas.ts b/src/api/routes/v2/schemas.ts
@@ -125,3 +125,15 @@ const BlockParamsSchema = Type.Object(
 );
 export type BlockParams = Static<typeof BlockParamsSchema>;
 export const CompiledBlockParams = ajv.compile(BlockParamsSchema);
+
+const SmartContractPrincipal = Type.RegExp(
+  /^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$/
+);
+const SmartContractStatusParamsSchema = Type.Object(
+  {
+    contract_id: Type.Union([Type.Array(SmartContractPrincipal), SmartContractPrincipal]),
+  },
+  { additionalProperties: false }
+);
+export type SmartContractStatusParams = Static<typeof SmartContractStatusParamsSchema>;
+export const CompiledSmartContractStatusParams = ajv.compile(SmartContractStatusParamsSchema);
diff --git a/src/api/routes/v2/smart-contracts.ts b/src/api/routes/v2/smart-contracts.ts
@@ -0,0 +1,30 @@
+import * as express from 'express';
+import { PgStore } from '../../../datastore/pg-store';
+import { getETagCacheHandler, setETagCacheHeaders } from '../../controllers/cache-controller';
+import { asyncHandler } from '../../async-handler';
+import {
+  validRequestQuery,
+  CompiledSmartContractStatusParams,
+  SmartContractStatusParams,
+} from './schemas';
+import { parseDbSmartContractStatusArray } from './helpers';
+
+export function createV2SmartContractsRouter(db: PgStore): express.Router {
+  const router = express.Router();
+  const cacheHandler = getETagCacheHandler(db);
+
+  router.get(
+    '/status',
+    cacheHandler,
+    asyncHandler(async (req, res) => {
+      if (!validRequestQuery(req, res, CompiledSmartContractStatusParams)) return;
+      const query = req.query as SmartContractStatusParams;
+
+      const result = await db.v2.getSmartContractStatus(query);
+      setETagCacheHeaders(res);
+      res.json(parseDbSmartContractStatusArray(query, result));
+    })
+  );
+
+  return router;
+}
diff --git a/src/datastore/common.ts b/src/datastore/common.ts
@@ -1554,3 +1554,10 @@ export enum IndexesState {
   Off = 0,
   On = 1,
 }
+
+export interface DbSmartContractStatus {
+  smart_contract_contract_id: string;
+  tx_id: string;
+  status: DbTxStatus;
+  block_height?: number;
+}
diff --git a/src/datastore/pg-store-v2.ts b/src/datastore/pg-store-v2.ts
@@ -6,6 +6,7 @@ import {
   TransactionLimitParamSchema,
   BlockParams,
   BlockPaginationQueryParams,
+  SmartContractStatusParams,
 } from '../api/routes/v2/schemas';
 import { InvalidRequestError, InvalidRequestErrorType } from '../errors';
 import { normalizeHashString } from '../helpers';
@@ -16,6 +17,9 @@ import {
   DbTx,
   TxQueryResult,
   DbBurnBlock,
+  DbTxTypeId,
+  DbSmartContractStatus,
+  DbTxStatus,
 } from './common';
 import { BLOCK_COLUMNS, parseBlockQueryResult, TX_COLUMNS, parseTxQueryResult } from './helpers';
 
@@ -230,4 +234,39 @@ export class PgStoreV2 extends BasePgStoreModule {
       if (blockQuery.count > 0) return blockQuery[0];
     });
   }
+
+  async getSmartContractStatus(args: SmartContractStatusParams): Promise<DbSmartContractStatus[]> {
+    return await this.sqlTransaction(async sql => {
+      const statusArray: DbSmartContractStatus[] = [];
+      const contractArray = Array.isArray(args.contract_id) ? args.contract_id : [args.contract_id];
+
+      // Search confirmed txs.
+      const confirmed = await sql<DbSmartContractStatus[]>`
+        SELECT DISTINCT ON (smart_contract_contract_id) smart_contract_contract_id, tx_id, block_height, status
+        FROM txs
+        WHERE type_id IN ${sql([DbTxTypeId.SmartContract, DbTxTypeId.VersionedSmartContract])}
+          AND smart_contract_contract_id IN ${sql(contractArray)}
+          AND canonical = TRUE
+          AND microblock_canonical = TRUE
+        ORDER BY smart_contract_contract_id, block_height DESC, microblock_sequence DESC, tx_index DESC, status
+      `;
+      statusArray.push(...confirmed);
+      if (confirmed.count < contractArray.length) {
+        // Search mempool txs.
+        const confirmedIds = confirmed.map(c => c.smart_contract_contract_id);
+        const remainingIds = contractArray.filter(c => !confirmedIds.includes(c));
+        const mempool = await sql<DbSmartContractStatus[]>`
+          SELECT DISTINCT ON (smart_contract_contract_id) smart_contract_contract_id, tx_id, status
+          FROM mempool_txs
+          WHERE pruned = FALSE
+            AND type_id IN ${sql([DbTxTypeId.SmartContract, DbTxTypeId.VersionedSmartContract])}
+            AND smart_contract_contract_id IN ${sql(remainingIds)}
+          ORDER BY smart_contract_contract_id, nonce
+        `;
+        statusArray.push(...mempool);
+      }
+
+      return statusArray;
+    });
+  }
 }
diff --git a/src/tests/smart-contract-tests.ts b/src/tests/smart-contract-tests.ts

Original file line number	Diff line number	Diff line change
`@@ -149,7 +149,9 @@ export function getTxTypeId(typeString: Transaction['tx_type']): DbTxTypeId[] {`
`149`	`149`	`}`
`150`	`150`	`}`
`151`	`151`
`152`		`-function getTxStatusString(txStatus: DbTxStatus): TransactionStatus \| MempoolTransactionStatus {`
	`152`	`+export function getTxStatusString(`
	`153`	`+ txStatus: DbTxStatus`
	`154`	`+): TransactionStatus \| MempoolTransactionStatus {`
`153`	`155`	`switch (txStatus) {`
`154`	`156`	`case DbTxStatus.Pending:`
`155`	`157`	`return 'pending';`