From 15bae06184eecf9eb632ab699d84d65998dbc5f0 Mon Sep 17 00:00:00 2001 From: sallymoc Date: Thu, 5 Mar 2026 15:54:59 +0100 Subject: [PATCH 1/2] chore: move OpenAPI adjustments from Makefile to CI workflow Remove yq post-processing from the Makefile and commit raw protoc output. OpenAPI adjustments (delete /health, /getEvents paths, tag modifications) are now applied on-the-fly in the CI workflow before dispatching the base64-encoded spec to consumer repos (integration, docs). --- .github/workflows/api-docs-update-v2.yaml | 25 +- v2/Makefile | 5 - v2/README.md | 9 + .../v2/query_services.openapi.yaml | 1545 +++++++++-------- 4 files changed, 827 insertions(+), 757 deletions(-) diff --git a/.github/workflows/api-docs-update-v2.yaml b/.github/workflows/api-docs-update-v2.yaml index 5dd4070..fc53083 100644 --- a/.github/workflows/api-docs-update-v2.yaml +++ b/.github/workflows/api-docs-update-v2.yaml @@ -12,16 +12,37 @@ jobs: api-docs-update-trigger: runs-on: ubuntu-latest steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Apply OpenAPI adjustments + run: | + cd v2/api/archive-query-service/v2 + cp query_services.openapi.yaml query_services.openapi.adjusted.yaml + yq -i --indent 4 'del(.paths."/health")' query_services.openapi.adjusted.yaml + yq -i --indent 4 'del(.paths."/getEvents")' query_services.openapi.adjusted.yaml + yq -i --indent 4 '(.tags[] | select(.name == "ArchiveQueryService")).x-scalar-ignore = true' query_services.openapi.adjusted.yaml + yq -i --indent 4 'del(.tags[] | select(.name == "Events (Beta)"))' query_services.openapi.adjusted.yaml + yq -i --indent 4 '(.paths[][].tags) -= ["ArchiveQueryService"]' query_services.openapi.adjusted.yaml + + - name: Encode adjusted spec + id: encode + run: | + CONTENT=$(base64 -w 0 v2/api/archive-query-service/v2/query_services.openapi.adjusted.yaml) + echo "spec_base64=$CONTENT" >> "$GITHUB_OUTPUT" + - name: Dispatch to qubic/integration uses: peter-evans/repository-dispatch@v3 with: token: ${{ secrets.GH_PAT }} repository: qubic/integration - event-type: api-docs-update + event-type: query-api-update + client-payload: '{"openapi_spec_base64": "${{ steps.encode.outputs.spec_base64 }}"}' - name: Dispatch to qubic/docs uses: peter-evans/repository-dispatch@v3 with: token: ${{ secrets.GH_PAT }} repository: qubic/docs - event-type: query-api-update \ No newline at end of file + event-type: query-api-update + client-payload: '{"openapi_spec_base64": "${{ steps.encode.outputs.spec_base64 }}"}' diff --git a/v2/Makefile b/v2/Makefile index b4baf24..e07bfa1 100644 --- a/v2/Makefile +++ b/v2/Makefile @@ -36,11 +36,6 @@ openapi-v3-gen: cd "$(PROTO_DIR)" && \ protoc --openapi_out=output_mode=source_relative,default_response=false:. $(OPT_ARGS) -I "$(PROTO_DIR)" \ query_services.proto - @echo "Cleaning up OpenAPI spec..." - cd "$(PROTO_DIR)" && \ - yq -iy 'del(.paths."/health")' query_services.openapi.yaml && \ - yq -iy '(.tags[] | select(.name == "ArchiveQueryService"))."x-scalar-ignore" = true' query_services.openapi.yaml && \ - yq -iy '(.paths[][].tags) -= ["ArchiveQueryService"]' query_services.openapi.yaml test-cover: @echo "Performing Go cover test..." diff --git a/v2/README.md b/v2/README.md index 7b2a4dc..f22c5ed 100644 --- a/v2/README.md +++ b/v2/README.md @@ -223,5 +223,14 @@ See [messages.proto](api/archive-query-service/v2/messages.proto) and [query_services.proto](api/archive-query-service/v2/query_services.proto) for full details. +## Regenerating protobuf and OpenAPI files + +Run `make` (or `make all`) to regenerate all protobuf and OpenAPI files. + +### Dev dependencies + +- `protoc` with Go plugins (`protoc-gen-go`, `protoc-gen-go-grpc`, `protoc-gen-grpc-gateway`) +- `protoc-gen-openapi` (`go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest`) + ## Caching See [CACHE.md](CACHE.md) for details about enabling and using caching in Archive Query Service v2. diff --git a/v2/api/archive-query-service/v2/query_services.openapi.yaml b/v2/api/archive-query-service/v2/query_services.openapi.yaml index 56f316b..d919fb8 100644 --- a/v2/api/archive-query-service/v2/query_services.openapi.yaml +++ b/v2/api/archive-query-service/v2/query_services.openapi.yaml @@ -1,757 +1,802 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + openapi: 3.0.3 info: - title: Qubic Query API - description: API for querying historical Qubic ledger data. - version: 1.0.0 + title: Qubic Query API + description: API for querying historical Qubic ledger data. + version: 1.0.0 servers: - - url: https://rpc.qubic.org/query/v1 + - url: https://rpc.qubic.org/query/v1 paths: - /getComputorListsForEpoch: - post: - tags: - - Network - summary: Get Epoch Computors - description: "Get the list(s) of computors for one epoch. These are the computors\ - \ (IDs signed by the arbitrator) that\n are allowed to make quorum decisions.\ - \ It is possible that this list changes within the epoch in case of\n arbitrator\ - \ intervention." - operationId: ArchiveQueryService_GetComputorsListsForEpoch - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/GetComputorListsForEpochRequest' - required: true - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GetComputorListsForEpochResponse' - /getEvents: - post: - tags: - - Events (Beta) - summary: Get Events - description: Query event logs with optional filters. Beta endpoint. - operationId: ArchiveQueryService_GetEvents - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/GetEventsRequest' - required: true - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GetEventsResponse' - /getLastProcessedTick: - get: - tags: - - Archive - summary: Get Last Processed Tick - description: "Get the last processed tick and other processing information from\ - \ the archive.\n All data queried from the archive is only fully processed\ - \ up to this tick.\n Before calling the service you should check the last\ - \ processed tick to be sure to get\n valid data and do not request data for\ - \ future ticks that are not processed yet. You can use\n the epoch and initial\ - \ tick information in the response to switch to a new interval." - operationId: ArchiveQueryService_GetLastProcessedTick - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GetLastProcessedTickResponse' - /getProcessedTickIntervals: - get: - tags: - - Archive - summary: Get Processed Tick Intervals - description: "Get the tick intervals that are available in the archive. A new\ - \ tick interval is typically\n created on epoch change or network restart\ - \ within the epoch. Use this endpoint to skip the\n tick numbers that are\ - \ not part of the intervals. This endpoint is only necessary for users\n that\ - \ need to process all available ticks. For most users it is enough to switch\ - \ to a new\n interval by using the `get last processed tick` endpoint." - operationId: ArchiveQueryService_GetProcessedTickIntervals - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GetProcessedTickIntervalsResponse' - /getTickData: - post: - tags: - - Ticks - summary: Get Tick Data - description: Get the tick data for one tick. - operationId: ArchiveQueryService_GetTickData - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/GetTickDataRequest' - required: true - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GetTickDataResponse' - /getTransactionByHash: - post: - tags: - - Transactions - summary: Get Transaction By Hash - description: Get a single transaction by its hash. - operationId: ArchiveQueryService_GetTransactionByHash - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/GetTransactionByHashRequest' - required: true - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GetTransactionByHashResponse' - /getTransactionsForIdentity: - post: - tags: - - Transactions - summary: Get Transactions For Identity - description: "Get the transactions for one identity sorted by tick number descending.\n\ - \n ### Request structure\n\n | Name | Type | Necessity\ - \ | Description \ - \ |\n |------------|--------------------|-----------|--------------------------------------------------------------------------------|\n\ - \ | identity | string | required | 60 characters uppercase\ - \ identity. |\n | filters \ - \ | map | optional | Filters that restrict results to single\ - \ value. |\n | ranges | map\ - \ | optional | Filters that restrict results to a value range. \ - \ |\n | pagination | Pagination | optional \ - \ | Allows to specify the first record and the number of records to be retrieved.\ - \ |\n\n Without filters and ranges all transactions from and to that identity\ - \ ordered by tick number descending are returned.\n\n ### Filters\n\n Filters\ - \ restrict the results by single values.\n\n #### Allowed properties\n\n |\ - \ Name | Type | Format | Description \ - \ |\n |-------------|---------|------------------------|--------------------------------------------------------------------|\n\ - \ | source | string | 60 character identity, up to 5, comma separated.\ - \ | Only find transactions that were sent from the specified identities. |\n\ - \ | source-exclude | string | 60 character identity, up to 5, comma separated.\ - \ | Only find transactions that were not sent from the specified identities.\ - \ |\n | destination | string | 60 character identity, up to 5, comma separated.\ - \ | Only find transactions that were sent to the specified identities. \ - \ |\n | destination-exclude | string | 60 character identity, up to 5, comma\ - \ separated. | Only find transactions that were not sent to the specified\ - \ identities. |\n | amount | string | Numeric | Only\ - \ find transactions with the specified amount. |\n | inputType\ - \ | string | Numeric | Only find transactions with the specified\ - \ input type. |\n | tickNumber | string | Numeric \ - \ | Only find transactions with the specified tick number. \ - \ |\n\n source` and `source-exclude` are mutually exclusive.\n destination`\ - \ and `destination-exclude` are mutually exclusive.\n\n #### Examples\n\n\ - \ ```\n \"source\": \"IIJHZSNPDRYYXCQBWNGKBSWYYDCARTYPOBXGOXZEVEZMMWYHPBVXZLJARRCB\"\ - ,\n \"destination\": \"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB\"\ - \n \"amount\": \"1000000\"\n \"inputType\": \"0\"\n ```\n\n ### Ranges\n\n\ - \ Ranges restrict the results by a range of values. On range per property\ - \ is supported.\n\n #### Allowed properties\n\n | Name | Type | Format\ - \ | Description \ - \ |\n |------------|--------|------------------------------------------|---------------------------------------------|\n\ - \ | amount | string | Numeric | Only\ - \ find transactions in amount range. |\n | tickNumber | string | Numeric\ - \ | Only find transactions in tick range.\ - \ |\n | inputType | string | Numeric \ - \ | Only find transactions in input type range. |\n | timestamp | string\ - \ | Numeric (Unix Timestamp in milliseconds) | Only find transactions in time\ - \ range. |\n\n #### Range definition\n\n A range with size of 0 or 1\ - \ is not allowed.\n\n | Name | Type | Necessity | Description \ - \ |\n |-----------|--------|-----------|-------------------------------------------|\n\ - \ | field | string | required | Name of the field you wish to search for.\ - \ |\n | gt | string | optional | Greater than. \ - \ |\n | gte | string | optional | Greater than or equal to.\ - \ |\n | lt | string | optional | Less than. \ - \ |\n | lte | string | optional | Less than\ - \ or equal to. |\n\n Only one lower bound and one upper\ - \ bound can be specified.\n\n #### Examples\n\n ```\n \"amount\": { \"gt\"\ - : \"1000000\" }\n \"tickNumber\": { \"gte\": \"25563000\", \"lte\": \"28300000\"\ - \ }\n \"inputType\": { \"gt\": \"0\" }\n \"timestamp\": { \"lt\": \"1757376000000\"\ - \ }\n ```\n\n ### Pagination\n\n | Name | Type | Necessity | Description\ - \ \ - \ |\n |--------|--------|-----------|-----------------------------------------------------------------------------------------------------|\n\ - \ | offset | uint32 | optional | The offset of the first record to return.\ - \ Defaults to zero (first record). Maximum offset is 10000. |\n | size |\ - \ uint32 | optional | Defaults to 10. Maximum size is 1000. Zero value is\ - \ ignored (uses default). |" - operationId: ArchiveQueryService_GetTransactionsForIdentity - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/GetTransactionsForIdentityRequest' - required: true - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GetTransactionsForIdentityResponse' - /getTransactionsForTick: - post: - tags: - - Transactions - summary: Get Transactions For Tick - description: "Get the transactions that are in included in one tick.\n\n ###\ - \ Request structure\n\n | Name | Type | Necessity | Description\ - \ |\n |------------|--------------------|-----------|-------------------------------------------------|\n\ - \ | identity | string | required | 60 characters uppercase\ - \ identity. |\n | filters | map | optional\ - \ | Filters that restrict results to single value. |\n | ranges | map\ - \ | optional | Filters that restrict results to a value range. |\n\n ###\ - \ Filters\n\n Filters restrict the results by single values.\n\n #### Allowed\ - \ properties\n\n | Name | Type | Format | Description\ - \ |\n |-------------|---------|------------------------|--------------------------------------------------------------------|\n\ - \ | source | string | 60 character identity | Only find transactions\ - \ that were sent from the specified identities. |\n | destination | string\ - \ | 60 character identity | Only find transactions that were sent to the\ - \ specified identities. |\n | amount | string | Numeric \ - \ | Only find transactions with the specified amount. \ - \ |\n | inputType | string | Numeric | Only find transactions\ - \ with the specified input type. |\n\n ### Ranges\n\n Ranges\ - \ restrict the results by a range of values. On range per property is supported.\n\ - \n #### Allowed properties\n\n | Name | Type | Format \ - \ | Description |\n\ - \ |------------|--------|------------------------------------------|---------------------------------------------|\n\ - \ | amount | string | Numeric | Only\ - \ find transactions in amount range. |\n | inputType | string | Numeric\ - \ | Only find transactions in input type\ - \ range. |\n\n #### Range definition\n\n A range with size of 0 or 1 is not\ - \ allowed.\n\n | Name | Type | Necessity | Description \ - \ |\n |-----------|--------|-----------|-------------------------------------------|\n\ - \ | field | string | required | Name of the field you wish to search for.\ - \ |\n | gt | string | optional | Greater than. \ - \ |\n | gte | string | optional | Greater than or equal to.\ - \ |\n | lt | string | optional | Less than. \ - \ |\n | lte | string | optional | Less than\ - \ or equal to. |\n\n Only one lower bound and one upper\ - \ bound can be specified.\n\n For examples how to use filters and ranges see\ - \ the GetTransactionsForIdentity endpoint documentation." - operationId: ArchiveQueryService_GetTransactionsForTick - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/GetTransactionsForTickRequest' - required: true - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GetTransactionsForTickResponse' + /getComputorListsForEpoch: + post: + tags: + - ArchiveQueryService + - Network + summary: Get Epoch Computors + description: |- + Get the list(s) of computors for one epoch. These are the computors (IDs signed by the arbitrator) that + are allowed to make quorum decisions. It is possible that this list changes within the epoch in case of + arbitrator intervention. + operationId: ArchiveQueryService_GetComputorsListsForEpoch + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetComputorListsForEpochRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetComputorListsForEpochResponse' + /getEvents: + post: + tags: + - ArchiveQueryService + - Events (Beta) + summary: Get Events + description: Query event logs with optional filters. Beta endpoint. + operationId: ArchiveQueryService_GetEvents + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetEventsRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetEventsResponse' + /getLastProcessedTick: + get: + tags: + - ArchiveQueryService + - Archive + summary: Get Last Processed Tick + description: |- + Get the last processed tick and other processing information from the archive. + All data queried from the archive is only fully processed up to this tick. + Before calling the service you should check the last processed tick to be sure to get + valid data and do not request data for future ticks that are not processed yet. You can use + the epoch and initial tick information in the response to switch to a new interval. + operationId: ArchiveQueryService_GetLastProcessedTick + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetLastProcessedTickResponse' + /getProcessedTickIntervals: + get: + tags: + - ArchiveQueryService + - Archive + summary: Get Processed Tick Intervals + description: |- + Get the tick intervals that are available in the archive. A new tick interval is typically + created on epoch change or network restart within the epoch. Use this endpoint to skip the + tick numbers that are not part of the intervals. This endpoint is only necessary for users + that need to process all available ticks. For most users it is enough to switch to a new + interval by using the `get last processed tick` endpoint. + operationId: ArchiveQueryService_GetProcessedTickIntervals + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetProcessedTickIntervalsResponse' + /getTickData: + post: + tags: + - ArchiveQueryService + - Ticks + summary: Get Tick Data + description: Get the tick data for one tick. + operationId: ArchiveQueryService_GetTickData + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetTickDataRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetTickDataResponse' + /getTransactionByHash: + post: + tags: + - ArchiveQueryService + - Transactions + summary: Get Transaction By Hash + description: Get a single transaction by its hash. + operationId: ArchiveQueryService_GetTransactionByHash + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetTransactionByHashRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetTransactionByHashResponse' + /getTransactionsForIdentity: + post: + tags: + - ArchiveQueryService + - Transactions + summary: Get Transactions For Identity + description: |- + Get the transactions for one identity sorted by tick number descending. + + ### Request structure + + | Name | Type | Necessity | Description | + |------------|--------------------|-----------|--------------------------------------------------------------------------------| + | identity | string | required | 60 characters uppercase identity. | + | filters | map | optional | Filters that restrict results to single value. | + | ranges | map | optional | Filters that restrict results to a value range. | + | pagination | Pagination | optional | Allows to specify the first record and the number of records to be retrieved. | + + Without filters and ranges all transactions from and to that identity ordered by tick number descending are returned. + + ### Filters + + Filters restrict the results by single values. + + #### Allowed properties + + | Name | Type | Format | Description | + |-------------|---------|------------------------|--------------------------------------------------------------------| + | source | string | 60 character identity, up to 5, comma separated. | Only find transactions that were sent from the specified identities. | + | source-exclude | string | 60 character identity, up to 5, comma separated. | Only find transactions that were not sent from the specified identities. | + | destination | string | 60 character identity, up to 5, comma separated. | Only find transactions that were sent to the specified identities. | + | destination-exclude | string | 60 character identity, up to 5, comma separated. | Only find transactions that were not sent to the specified identities. | + | amount | string | Numeric | Only find transactions with the specified amount. | + | inputType | string | Numeric | Only find transactions with the specified input type. | + | tickNumber | string | Numeric | Only find transactions with the specified tick number. | + + source` and `source-exclude` are mutually exclusive. + destination` and `destination-exclude` are mutually exclusive. + + #### Examples + + ``` + "source": "IIJHZSNPDRYYXCQBWNGKBSWYYDCARTYPOBXGOXZEVEZMMWYHPBVXZLJARRCB", + "destination": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB" + "amount": "1000000" + "inputType": "0" + ``` + + ### Ranges + + Ranges restrict the results by a range of values. On range per property is supported. + + #### Allowed properties + + | Name | Type | Format | Description | + |------------|--------|------------------------------------------|---------------------------------------------| + | amount | string | Numeric | Only find transactions in amount range. | + | tickNumber | string | Numeric | Only find transactions in tick range. | + | inputType | string | Numeric | Only find transactions in input type range. | + | timestamp | string | Numeric (Unix Timestamp in milliseconds) | Only find transactions in time range. | + + #### Range definition + + A range with size of 0 or 1 is not allowed. + + | Name | Type | Necessity | Description | + |-----------|--------|-----------|-------------------------------------------| + | field | string | required | Name of the field you wish to search for. | + | gt | string | optional | Greater than. | + | gte | string | optional | Greater than or equal to. | + | lt | string | optional | Less than. | + | lte | string | optional | Less than or equal to. | + + Only one lower bound and one upper bound can be specified. + + #### Examples + + ``` + "amount": { "gt": "1000000" } + "tickNumber": { "gte": "25563000", "lte": "28300000" } + "inputType": { "gt": "0" } + "timestamp": { "lt": "1757376000000" } + ``` + + ### Pagination + + | Name | Type | Necessity | Description | + |--------|--------|-----------|-----------------------------------------------------------------------------------------------------| + | offset | uint32 | optional | The offset of the first record to return. Defaults to zero (first record). Maximum offset is 10000. | + | size | uint32 | optional | Defaults to 10. Maximum size is 1000. Zero value is ignored (uses default). | + operationId: ArchiveQueryService_GetTransactionsForIdentity + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetTransactionsForIdentityRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetTransactionsForIdentityResponse' + /getTransactionsForTick: + post: + tags: + - ArchiveQueryService + - Transactions + summary: Get Transactions For Tick + description: |- + Get the transactions that are in included in one tick. + + ### Request structure + + | Name | Type | Necessity | Description | + |------------|--------------------|-----------|-------------------------------------------------| + | identity | string | required | 60 characters uppercase identity. | + | filters | map | optional | Filters that restrict results to single value. | + | ranges | map | optional | Filters that restrict results to a value range. | + + ### Filters + + Filters restrict the results by single values. + + #### Allowed properties + + | Name | Type | Format | Description | + |-------------|---------|------------------------|--------------------------------------------------------------------| + | source | string | 60 character identity | Only find transactions that were sent from the specified identities. | + | destination | string | 60 character identity | Only find transactions that were sent to the specified identities. | + | amount | string | Numeric | Only find transactions with the specified amount. | + | inputType | string | Numeric | Only find transactions with the specified input type. | + + ### Ranges + + Ranges restrict the results by a range of values. On range per property is supported. + + #### Allowed properties + + | Name | Type | Format | Description | + |------------|--------|------------------------------------------|---------------------------------------------| + | amount | string | Numeric | Only find transactions in amount range. | + | inputType | string | Numeric | Only find transactions in input type range. | + + #### Range definition + + A range with size of 0 or 1 is not allowed. + + | Name | Type | Necessity | Description | + |-----------|--------|-----------|-------------------------------------------| + | field | string | required | Name of the field you wish to search for. | + | gt | string | optional | Greater than. | + | gte | string | optional | Greater than or equal to. | + | lt | string | optional | Less than. | + | lte | string | optional | Less than or equal to. | + + Only one lower bound and one upper bound can be specified. + + For examples how to use filters and ranges see the GetTransactionsForIdentity endpoint documentation. + operationId: ArchiveQueryService_GetTransactionsForTick + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetTransactionsForTickRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetTransactionsForTickResponse' + /health: + get: + tags: + - ArchiveQueryService + summary: Get Health + description: Health check. This is for internal use only and can change any time. Do not rely on this endpoint. + operationId: ArchiveQueryService_GetHealth + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/HealthResponse' components: - schemas: - AssetIssuanceData: - type: object - properties: - assetIssuer: - type: string - numberOfShares: - type: string - managingContractIndex: - type: string - assetName: - type: string - numberOfDecimalPlaces: - type: integer - format: uint32 - unitOfMeasurement: - type: string - description: AssetIssuanceData contains fields specific to asset issuance events - (type 1). - AssetOwnershipChangeData: - type: object - properties: - source: - type: string - destination: - type: string - assetIssuer: - type: string - assetName: - type: string - numberOfShares: - type: string - description: AssetOwnershipChangeData contains fields specific to asset ownership - change events (type 2). - AssetPossessionChangeData: - type: object - properties: - source: - type: string - destination: - type: string - assetIssuer: - type: string - assetName: - type: string - numberOfShares: - type: string - description: AssetPossessionChangeData contains fields specific to asset possession - change events (type 3). - BurningData: - type: object - properties: - source: - type: string - amount: - type: string - contractIndexBurnedFor: - type: string - description: BurningData contains fields specific to burning events (type 8). - ComputorList: - type: object - properties: - epoch: - type: integer - description: Epoch number. - format: uint32 - tickNumber: - type: integer - description: Tick number when the list was received by the archive after - it was published. - format: uint32 - identities: - type: array - items: - type: string - description: List of computor identities (signed by arbitrator). - signature: - type: string - description: Signature of the arbitrator. - description: ComputorList - ContractReserveDeductionData: - type: object - properties: - deductedAmount: - type: string - remainingAmount: - type: string - contractIndex: - type: string - description: ContractReserveDeductionData contains fields specific to contract - reserve deduction events (type 13). - CustomMessageData: - type: object - properties: - value: - type: string - Event: - type: object - properties: - epoch: - type: integer - format: uint32 - tickNumber: - type: integer - format: uint32 - timestamp: - type: string - transactionHash: - type: string - logType: - type: integer - format: uint32 - logId: - type: string - logDigest: - type: string - categories: - type: array - items: - type: integer - format: int32 - rawPayload: - type: string - format: bytes - quTransfer: - $ref: '#/components/schemas/QuTransferData' - assetIssuance: - $ref: '#/components/schemas/AssetIssuanceData' - assetOwnershipChange: - $ref: '#/components/schemas/AssetOwnershipChangeData' - assetPossessionChange: - $ref: '#/components/schemas/AssetPossessionChangeData' - burning: - $ref: '#/components/schemas/BurningData' - contractReserveDeduction: - $ref: '#/components/schemas/ContractReserveDeductionData' - smartContractMessage: - $ref: '#/components/schemas/SmartContractMessageData' - customMessage: - $ref: '#/components/schemas/CustomMessageData' - description: Event - GetComputorListsForEpochRequest: - type: object - properties: - epoch: - type: integer - description: The epoch number to get the computor lists for. - format: uint32 - description: GetComputorListsForEpochRequest - GetComputorListsForEpochResponse: - type: object - properties: - computorsLists: - type: array - items: - $ref: '#/components/schemas/ComputorList' - description: The lists of computors that voted in this epoch. - description: GetComputorListsForEpochResponse - GetEventsRequest: - example: - filters: - transactionHash: zvqvtjzvgwgpegmalkkjedhbdrnckqcfthpzfqzxbcljttljzidmvaxalxyz - pagination: - offset: 0 - size: 10 - type: object - properties: - filters: - type: object - additionalProperties: - type: string - description: 'Filters restrict the results by single values. Allowed: transactionHash, - tickNumber, eventType' - pagination: - $ref: '#/components/schemas/Pagination' - description: GetEventsRequest - GetEventsResponse: - type: object - properties: - hits: - $ref: '#/components/schemas/Hits' - events: - type: array - items: - $ref: '#/components/schemas/Event' - description: List of events that matched the search criteria. - description: GetEventsResponse - GetLastProcessedTickResponse: - type: object - properties: - tickNumber: - type: integer - description: The last processed tick that is available in the archive. - format: uint32 - epoch: - type: integer - description: The epoch the last processed tick is in. - format: uint32 - intervalInitialTick: - type: integer - description: The initial tick of the current tick interval. - format: uint32 - description: GetLastProcessedTickResponse - GetProcessedTickIntervalsResponse: - type: object - properties: - processedTickIntervals: - type: array - items: - $ref: '#/components/schemas/ProcessedTickInterval' - description: A list of tick intervals that were processed. - description: GetProcessedTickIntervalsResponse - GetTickDataRequest: - type: object - properties: - tickNumber: - type: integer - description: The number of tick the tick data is requested for. - format: uint32 - description: GetTickDataRequest - GetTickDataResponse: - type: object - properties: - tickData: - $ref: '#/components/schemas/TickData' - description: GetTickDataResponse - GetTransactionByHashRequest: - type: object - properties: - hash: - type: string - description: The hash of the transaction. - description: GetTransactionByHashRequest - GetTransactionByHashResponse: - type: object - properties: - transaction: - $ref: '#/components/schemas/Transaction' - description: GetTransactionByHashResponse - GetTransactionsForIdentityRequest: - example: - identity: AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ - filters: - destination: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB - inputType: '0' - ranges: - amount: - gte: '1000000000' - pagination: - offset: 0 - size: 10 - type: object - properties: - identity: - type: string - description: The identity to get the transactions for. Incoming and outgoing - transactions are queried by default. - filters: - type: object - additionalProperties: - type: string - description: Filters restrict the results by single values. - ranges: - type: object - additionalProperties: - $ref: '#/components/schemas/Range' - description: Ranges restrict the results by a maximum and minimum value. - pagination: - $ref: '#/components/schemas/Pagination' - description: GetTransactionsForIdentityRequest - GetTransactionsForIdentityResponse: - type: object - properties: - validForTick: - type: integer - description: The response is valid for this tick number. - format: uint32 - hits: - $ref: '#/components/schemas/Hits' - transactions: - type: array - items: - $ref: '#/components/schemas/Transaction' - description: List of transactions that matched the search criteria. - description: GetTransactionsForIdentityResponse - GetTransactionsForTickRequest: - example: - tickNumber: 42977140 - filters: - destination: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB - ranges: - amount: - gte: '1' - type: object - properties: - tickNumber: - type: integer - description: The tick number to get the transactions for. - format: uint32 - filters: - type: object - additionalProperties: - type: string - description: 'Filters restrict the results by single values. Allowed: source, - destination, amount, inputType' - ranges: - type: object - additionalProperties: - $ref: '#/components/schemas/Range' - description: 'Ranges restrict the results by a maximum and minimum value. - Allowed: amount, inputType' - description: GetTransactionsForTickRequest - GetTransactionsForTickResponse: - type: object - properties: - transactions: - type: array - items: - $ref: '#/components/schemas/Transaction' - description: The transactions for the requested tick number. - description: GetTransactionsForTickResponse - HealthResponse: - type: object - properties: - status: - type: string - description: Health status information. - description: HealthResponse - Hits: - type: object - properties: - total: - type: integer - description: The total number of hits available in the archive. Capped at - 10000. - format: uint32 - from: - type: integer - description: Starting offset of the hits that were returned. - format: uint32 - size: - type: integer - description: Number of returned hits. - format: uint32 - description: Provides information about the number of results. - Pagination: - type: object - properties: - offset: - type: integer - description: The offset specifies the starting point of the returned data. - Defaults to zero. - format: uint32 - size: - type: integer - description: The size specifies how many results should be returned. Defaults - to 10. - format: uint32 - description: The number of maximum results (offset + size) is limited to 10000. - ProcessedTickInterval: - type: object - properties: - epoch: - type: integer - description: The epoch the interval is in. - format: uint32 - firstTick: - type: integer - description: The initial processed tick of the interval. - format: uint32 - lastTick: - type: integer - description: The last processed tick of the interval. - format: uint32 - description: ProcessedTickInterval - QuTransferData: - type: object - properties: - source: - type: string - destination: - type: string - amount: - type: string - description: QuTransferData contains fields specific to QU transfer events (type - 0). - Range: - type: object - properties: - gt: - type: string - description: Greater than. - gte: - type: string - description: Greater than or equal. - lt: - type: string - description: Less than. - lte: - type: string - description: Less than or equal. - description: Range - SmartContractMessageData: - type: object - properties: - emittingContractIndex: - type: string - contractMessageType: - type: string - TickData: - type: object - properties: - tickNumber: - type: integer - format: uint32 - epoch: - type: integer - format: uint32 - computorIndex: - type: integer - format: uint32 - timestamp: - type: string - varStruct: - type: string - timeLock: - type: string - transactionHashes: - type: array - items: - type: string - contractFees: - type: array - items: - type: string - signature: - type: string - description: TickData - Transaction: - type: object - properties: - hash: - type: string - amount: - type: string - source: - type: string - destination: - type: string - tickNumber: - type: integer - format: uint32 - timestamp: - type: string - inputType: - type: integer - description: Smart contract procedure index. (The smart contract procedure - this transaction is supposed to trigger) - format: uint32 - inputSize: - type: integer - description: Size of input_data byte array. - format: uint32 - inputData: - type: string - description: Base64 encoded byte array containing a smart contract payload. - signature: - type: string - description: Base64 encoded byte array representing the transactions's signature. - moneyFlew: - type: boolean - description: Money flew is an additional information provided by some nodes - with the tx status addon patch. - description: Transaction + schemas: + AssetIssuanceData: + type: object + properties: + assetIssuer: + type: string + numberOfShares: + type: string + managingContractIndex: + type: string + assetName: + type: string + numberOfDecimalPlaces: + type: integer + format: uint32 + unitOfMeasurement: + type: string + description: AssetIssuanceData contains fields specific to asset issuance events (type 1). + AssetOwnershipChangeData: + type: object + properties: + source: + type: string + destination: + type: string + assetIssuer: + type: string + assetName: + type: string + numberOfShares: + type: string + description: AssetOwnershipChangeData contains fields specific to asset ownership change events (type 2). + AssetPossessionChangeData: + type: object + properties: + source: + type: string + destination: + type: string + assetIssuer: + type: string + assetName: + type: string + numberOfShares: + type: string + description: AssetPossessionChangeData contains fields specific to asset possession change events (type 3). + BurningData: + type: object + properties: + source: + type: string + amount: + type: string + contractIndexBurnedFor: + type: string + description: BurningData contains fields specific to burning events (type 8). + ComputorList: + type: object + properties: + epoch: + type: integer + description: Epoch number. + format: uint32 + tickNumber: + type: integer + description: Tick number when the list was received by the archive after it was published. + format: uint32 + identities: + type: array + items: + type: string + description: List of computor identities (signed by arbitrator). + signature: + type: string + description: Signature of the arbitrator. + description: ComputorList + ContractReserveDeductionData: + type: object + properties: + deductedAmount: + type: string + remainingAmount: + type: string + contractIndex: + type: string + description: ContractReserveDeductionData contains fields specific to contract reserve deduction events (type 13). + CustomMessageData: + type: object + properties: + value: + type: string + Event: + type: object + properties: + epoch: + type: integer + format: uint32 + tickNumber: + type: integer + format: uint32 + timestamp: + type: string + transactionHash: + type: string + logType: + type: integer + format: uint32 + logId: + type: string + logDigest: + type: string + categories: + type: array + items: + type: integer + format: int32 + rawPayload: + type: string + format: bytes + quTransfer: + $ref: '#/components/schemas/QuTransferData' + assetIssuance: + $ref: '#/components/schemas/AssetIssuanceData' + assetOwnershipChange: + $ref: '#/components/schemas/AssetOwnershipChangeData' + assetPossessionChange: + $ref: '#/components/schemas/AssetPossessionChangeData' + burning: + $ref: '#/components/schemas/BurningData' + contractReserveDeduction: + $ref: '#/components/schemas/ContractReserveDeductionData' + smartContractMessage: + $ref: '#/components/schemas/SmartContractMessageData' + customMessage: + $ref: '#/components/schemas/CustomMessageData' + description: Event + GetComputorListsForEpochRequest: + type: object + properties: + epoch: + type: integer + description: The epoch number to get the computor lists for. + format: uint32 + description: GetComputorListsForEpochRequest + GetComputorListsForEpochResponse: + type: object + properties: + computorsLists: + type: array + items: + $ref: '#/components/schemas/ComputorList' + description: The lists of computors that voted in this epoch. + description: GetComputorListsForEpochResponse + GetEventsRequest: + example: + filters: + transactionHash: zvqvtjzvgwgpegmalkkjedhbdrnckqcfthpzfqzxbcljttljzidmvaxalxyz + pagination: + offset: 0 + size: 10 + type: object + properties: + filters: + type: object + additionalProperties: + type: string + description: 'Filters restrict the results by single values. Allowed: transactionHash, tickNumber, eventType' + pagination: + $ref: '#/components/schemas/Pagination' + description: GetEventsRequest + GetEventsResponse: + type: object + properties: + hits: + $ref: '#/components/schemas/Hits' + events: + type: array + items: + $ref: '#/components/schemas/Event' + description: List of events that matched the search criteria. + description: GetEventsResponse + GetLastProcessedTickResponse: + type: object + properties: + tickNumber: + type: integer + description: The last processed tick that is available in the archive. + format: uint32 + epoch: + type: integer + description: The epoch the last processed tick is in. + format: uint32 + intervalInitialTick: + type: integer + description: The initial tick of the current tick interval. + format: uint32 + description: GetLastProcessedTickResponse + GetProcessedTickIntervalsResponse: + type: object + properties: + processedTickIntervals: + type: array + items: + $ref: '#/components/schemas/ProcessedTickInterval' + description: A list of tick intervals that were processed. + description: GetProcessedTickIntervalsResponse + GetTickDataRequest: + type: object + properties: + tickNumber: + type: integer + description: The number of tick the tick data is requested for. + format: uint32 + description: GetTickDataRequest + GetTickDataResponse: + type: object + properties: + tickData: + $ref: '#/components/schemas/TickData' + description: GetTickDataResponse + GetTransactionByHashRequest: + type: object + properties: + hash: + type: string + description: The hash of the transaction. + description: GetTransactionByHashRequest + GetTransactionByHashResponse: + type: object + properties: + transaction: + $ref: '#/components/schemas/Transaction' + description: GetTransactionByHashResponse + GetTransactionsForIdentityRequest: + example: + identity: AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ + filters: + destination: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB + inputType: "0" + ranges: + amount: + gte: "1000000000" + pagination: + offset: 0 + size: 10 + type: object + properties: + identity: + type: string + description: The identity to get the transactions for. Incoming and outgoing transactions are queried by default. + filters: + type: object + additionalProperties: + type: string + description: Filters restrict the results by single values. + ranges: + type: object + additionalProperties: + $ref: '#/components/schemas/Range' + description: Ranges restrict the results by a maximum and minimum value. + pagination: + $ref: '#/components/schemas/Pagination' + description: GetTransactionsForIdentityRequest + GetTransactionsForIdentityResponse: + type: object + properties: + validForTick: + type: integer + description: The response is valid for this tick number. + format: uint32 + hits: + $ref: '#/components/schemas/Hits' + transactions: + type: array + items: + $ref: '#/components/schemas/Transaction' + description: List of transactions that matched the search criteria. + description: GetTransactionsForIdentityResponse + GetTransactionsForTickRequest: + example: + tickNumber: 42977140 + filters: + destination: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB + ranges: + amount: + gte: "1" + type: object + properties: + tickNumber: + type: integer + description: The tick number to get the transactions for. + format: uint32 + filters: + type: object + additionalProperties: + type: string + description: 'Filters restrict the results by single values. Allowed: source, destination, amount, inputType' + ranges: + type: object + additionalProperties: + $ref: '#/components/schemas/Range' + description: 'Ranges restrict the results by a maximum and minimum value. Allowed: amount, inputType' + description: GetTransactionsForTickRequest + GetTransactionsForTickResponse: + type: object + properties: + transactions: + type: array + items: + $ref: '#/components/schemas/Transaction' + description: The transactions for the requested tick number. + description: GetTransactionsForTickResponse + HealthResponse: + type: object + properties: + status: + type: string + description: Health status information. + description: HealthResponse + Hits: + type: object + properties: + total: + type: integer + description: The total number of hits available in the archive. Capped at 10000. + format: uint32 + from: + type: integer + description: Starting offset of the hits that were returned. + format: uint32 + size: + type: integer + description: Number of returned hits. + format: uint32 + description: Provides information about the number of results. + Pagination: + type: object + properties: + offset: + type: integer + description: The offset specifies the starting point of the returned data. Defaults to zero. + format: uint32 + size: + type: integer + description: The size specifies how many results should be returned. Defaults to 10. + format: uint32 + description: The number of maximum results (offset + size) is limited to 10000. + ProcessedTickInterval: + type: object + properties: + epoch: + type: integer + description: The epoch the interval is in. + format: uint32 + firstTick: + type: integer + description: The initial processed tick of the interval. + format: uint32 + lastTick: + type: integer + description: The last processed tick of the interval. + format: uint32 + description: ProcessedTickInterval + QuTransferData: + type: object + properties: + source: + type: string + destination: + type: string + amount: + type: string + description: QuTransferData contains fields specific to QU transfer events (type 0). + Range: + type: object + properties: + gt: + type: string + description: Greater than. + gte: + type: string + description: Greater than or equal. + lt: + type: string + description: Less than. + lte: + type: string + description: Less than or equal. + description: Range + SmartContractMessageData: + type: object + properties: + emittingContractIndex: + type: string + contractMessageType: + type: string + TickData: + type: object + properties: + tickNumber: + type: integer + format: uint32 + epoch: + type: integer + format: uint32 + computorIndex: + type: integer + format: uint32 + timestamp: + type: string + varStruct: + type: string + timeLock: + type: string + transactionHashes: + type: array + items: + type: string + contractFees: + type: array + items: + type: string + signature: + type: string + description: TickData + Transaction: + type: object + properties: + hash: + type: string + amount: + type: string + source: + type: string + destination: + type: string + tickNumber: + type: integer + format: uint32 + timestamp: + type: string + inputType: + type: integer + description: Smart contract procedure index. (The smart contract procedure this transaction is supposed to trigger) + format: uint32 + inputSize: + type: integer + description: Size of input_data byte array. + format: uint32 + inputData: + type: string + description: Base64 encoded byte array containing a smart contract payload. + signature: + type: string + description: Base64 encoded byte array representing the transactions's signature. + moneyFlew: + type: boolean + description: Money flew is an additional information provided by some nodes with the tx status addon patch. + description: Transaction tags: - - name: Archive - description: Archive processing status and coverage information. - - name: ArchiveQueryService - description: Qubic Query API - x-scalar-ignore: true - - name: Events (Beta) - description: Query event logs from the Qubic blockchain. Beta endpoint. - - name: Network - description: Network status and computor information. - - name: Ticks - description: Query tick data from the archive. - - name: Transactions - description: Search and retrieve transaction history. + - name: Archive + description: Archive processing status and coverage information. + - name: ArchiveQueryService + description: Qubic Query API + - name: Events (Beta) + description: Query event logs from the Qubic blockchain. Beta endpoint. + - name: Network + description: Network status and computor information. + - name: Ticks + description: Query tick data from the archive. + - name: Transactions + description: Search and retrieve transaction history. externalDocs: - description: GitHub - url: https://github.com/qubic/archive-query-service + description: GitHub + url: https://github.com/qubic/archive-query-service From c12b2665ec4cafc4afa419741773d1d7c104d798 Mon Sep 17 00:00:00 2001 From: sallymoc Date: Thu, 5 Mar 2026 15:56:34 +0100 Subject: [PATCH 2/2] ci: add check to verify OpenAPI spec is up to date Fails the PR if the committed OpenAPI YAML doesn't match what protoc would generate from the current proto files. --- .github/workflows/test-v2.yaml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/.github/workflows/test-v2.yaml b/.github/workflows/test-v2.yaml index 0b3d842..05635b3 100644 --- a/.github/workflows/test-v2.yaml +++ b/.github/workflows/test-v2.yaml @@ -45,6 +45,29 @@ jobs: with: version: v2.6 working-directory: v2 + check-openapi: + name: Check OpenAPI spec is up to date + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-go@v4 + with: + go-version: 1.25.x + - name: Install protoc + uses: arduino/setup-protoc@v3 + with: + version: '28.x' + - name: Install protoc-gen-openapi + run: go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest + - name: Regenerate OpenAPI spec + working-directory: v2 + run: make openapi-v3-gen + - name: Check for differences + run: | + if ! git diff --exit-code v2/api/archive-query-service/v2/query_services.openapi.yaml; then + echo "::error::OpenAPI spec is out of date. Run 'make openapi-v3-gen' and commit the result." + exit 1 + fi govulncheck: runs-on: ubuntu-latest name: Run govulncheck v2