Reformat ipo-service into general-service and implement balances for multiple identities request.

Author: LINCKODE

…b/workflows/push-docker-ipo-service.yaml …rkflows/push-docker-general-service.yaml.github/workflows/push-docker-ipo-service.yaml renamed to .github/workflows/push-docker-general-service.yaml .github/workflows/push-docker-ipo-service.yaml renamed to .github/workflows/push-docker-general-service.yaml

@@ -1,24 +1,24 @@
-name: Deploy ipo-service image to GHCR
+name: Deploy general-service image to GHCR
 
 on:
   push:
     tags:
-      - 'ipo-service/v*.*.*'
+      - 'general-service/v*.*.*'
 
 jobs:
   test:
     runs-on: ubuntu-latest
     defaults:
       run:
-        working-directory: ./ipo-service
+        working-directory: ./general-service
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version-file: ipo-service/go.mod
+          go-version-file: general-service/go.mod
 
       - name: Run tests
         run: go test ./...
@@ -55,7 +55,7 @@ jobs:
       - name: Build and push Docker image
         uses: docker/build-push-action@v5
         with:
-          context: ./ipo-service
-          file: ./ipo-service/Dockerfile
+          context: ./general-service
+          file: ./general-service/Dockerfile
           push: true
-          tags: ghcr.io/qubic/qubic-aggregation-ipo-service:${{ steps.extract.outputs.version }}
+          tags: ghcr.io/qubic/qubic-aggregation-general-service:${{ steps.extract.outputs.version }}

.github/workflows/test-general-service.yaml

@@ -0,0 +1,29 @@
+name: Test general-service
+
+on:
+  push:
+    paths:
+      - 'general-service/**'
+      - 'shared/**'
+  pull_request:
+    paths:
+      - 'general-service/**'
+      - 'shared/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./general-service
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: general-service/go.mod
+
+      - name: Run tests
+        run: go test ./...

README.md

@@ -6,10 +6,10 @@ exposes the results via its own gRPC + HTTP/REST API.
 
 ## Services
 
-| Service                     | Description                                                    | Status      |
-|-----------------------------|----------------------------------------------------------------|-------------|
-| [ipo-service](ipo-service/) | IPO bid aggregation for wallet integration                     | Implemented |
-| [shared](shared/)           | Common infrastructure (gRPC client/server, config, middleware) | Implemented |
+| Service                               | Description                                                    | Status      |
+|---------------------------------------|----------------------------------------------------------------|-------------|
+| [general-service](general-service/)   | IPO bid aggregation and identity balances                      | Implemented |
+| [shared](shared/)                     | Common infrastructure (gRPC client/server, config, middleware) | Implemented |
 
 ## Architecture
 
@@ -18,9 +18,9 @@ exposes the results via its own gRPC + HTTP/REST API.
                                  |
                     +------------v------------+
                     |    Aggregation Layer    |
-                    |  +-------------------+  |
-                    |  |   ipo-service     |  |
-                    |  +--------+----------+  |
+                    |  +---------------------+  |
+                    |  |  general-service    |  |
+                    |  +--------+-----------+  |
                     |           |             |
                     |  +--------v----------+  |
                     |  |  shared module    |  |

buf.yaml

@@ -1,6 +1,6 @@
 version: v2
 modules:
-  - path: ipo-service/api
+  - path: general-service/api
 deps:
   - buf.build/googleapis/googleapis
   - buf.build/grpc-ecosystem/grpc-gateway

general-service/Dockerfile

@@ -0,0 +1,18 @@
+FROM golang:1.26 AS builder
+ENV CGO_ENABLED=0
+
+WORKDIR /src
+COPY . /src
+
+RUN go build -o "./bin/general-service" "./cmd/general-service"
+
+FROM alpine
+COPY --from=builder /src/bin/general-service /app/general-service
+
+EXPOSE 8000
+EXPOSE 8001
+EXPOSE 9999
+
+WORKDIR /app
+
+ENTRYPOINT ["./general-service"]

ipo-service/Makefile general-service/Makefileipo-service/Makefile renamed to general-service/Makefile

@@ -2,12 +2,12 @@
 
 proto-gen:
 	buf generate
-	mv api/openapi.yaml api/ipo-service.openapi.yaml
+	mv api/openapi.yaml api/general-service.openapi.yaml
 
-PROTO_GEN_DIR = api/qubic/aggregation/ipo/v1
+PROTO_GEN_DIR = api/qubic/aggregation/general/v1
 
 proto-clean:
-	rm -f $(PROTO_GEN_DIR)/*.pb.go $(PROTO_GEN_DIR)/*.pb.gw.go api/ipo-service.openapi.yaml
+	rm -f $(PROTO_GEN_DIR)/*.pb.go $(PROTO_GEN_DIR)/*.pb.gw.go api/general-service.openapi.yaml
 
 proto-lint:
 	buf lint

ipo-service/README.md general-service/README.mdipo-service/README.md renamed to general-service/README.md

@@ -1,12 +1,12 @@
-# IPO Service
+# General Service
 
-Aggregates IPO bid transaction data. Given a set of bidder identities, returns their bid transactions for all currently active IPOs with parsed bid data (price, quantity).
+General-purpose aggregation service. Currently provides IPO bid transaction aggregation and batch identity balance lookups.
 
 ## API
 
 ### `GetCurrentIpoBids`
 
-**gRPC**: `qubic.aggregation.ipo.v1.AggregationIpoService/GetCurrentIpoBids`
+**gRPC**: `qubic.aggregation.general.v1.AggregationGeneralService/GetCurrentIpoBids`
 **HTTP**: `POST /getCurrentIpoBids`
 
 **Request**: up to 15 identity strings.
@@ -46,27 +46,68 @@ Aggregates IPO bid transaction data. Given a set of bidder identities, returns t
 }
 ```
 
+### `GetIdentitiesBalances`
+
+**gRPC**: `qubic.aggregation.general.v1.AggregationGeneralService/GetIdentitiesBalances`
+**HTTP**: `POST /getIdentitiesBalances`
+
+**Request**: up to 15 identity strings.
+
+```json
+{
+  "identities": ["IDENTITY_A", "IDENTITY_B"]
+}
+```
+
+**Response**: balance data for each identity.
+
+```json
+{
+  "balances": [
+    {
+      "id": "IDENTITY_A",
+      "balance": 1000000,
+      "valid_for_tick": 22150100,
+      "latest_incoming_transfer_tick": 22150090,
+      "latest_outgoing_transfer_tick": 22150080,
+      "incoming_amount": 5000000,
+      "outgoing_amount": 4000000,
+      "number_of_incoming_transfers": 10,
+      "number_of_outgoing_transfers": 5
+    }
+  ]
+}
+```
+
 ## How It Works
 
+### IPO Bids
+
 1. Fetches active IPO contract indices from qubic-http (`GetActiveIpos`), cached with configurable TTL.
 2. Derives smart contract addresses from contract indices (contract index in lower 32 bits of the 256-bit public key, remaining bits zeroed).
 3. Gets current epoch tick bounds from status-service (`GetTickIntervals`), cached with configurable TTL.
 4. For each identity, queries archive-query-service (`GetTransactionsForIdentity`) with destination = SC address, tick range = current epoch, amount = 0.
 5. Filters results by `input_size == 10` and `amount == 0` to isolate IPO bid transactions.
 6. Parses `input_data` (base64) as `ContractIPOBid`: price (int64 LE, 8 bytes) + quantity (uint16 LE, 2 bytes).
 
+### Identity Balances
+
+1. For each identity, concurrently fetches the balance from qubic-http (`GetBalance`).
+2. Returns all balance fields (current balance, transfer ticks, amounts, transfer counts).
+
 ## Upstream Dependencies
 
 | Service | Method | Purpose |
 |---------|--------|---------|
 | qubic-http | `GetActiveIpos` | Active IPO contract indices |
 | qubic-http | `GetTickInfo` | Current epoch for tick range |
+| qubic-http | `GetBalance` | Identity balance data |
 | status-service | `GetTickIntervals` | Epoch tick boundaries |
 | archive-query-service | `GetTransactionsForIdentity` | Bid transaction queries |
 
 ## Configuration
 
-Environment variable prefix: `QUBIC_AGGREGATION_IPO_SERVICE`
+Environment variable prefix: `QUBIC_AGGREGATION_GENERAL_SERVICE`
 
 | Variable | Default | Description |
 |----------|---------|-------------|
@@ -92,19 +133,19 @@ make mocks
 make test
 
 # Build
-go build ./cmd/ipo-service
+go build ./cmd/general-service
 
 # Build Docker image
-docker build -t ipo-service .
+docker build -t general-service .
 ```
 
 ## Project Structure
 
 ```
-ipo-service/
-  cmd/ipo-service/    Entry point, config, bootstrap
-  api/                Proto definitions + generated gRPC/gateway code
-  domain/             Business logic, interfaces, models
-  grpc/               gRPC service handler + server setup
-  clients/            Upstream service client wrappers
+general-service/
+  cmd/general-service/    Entry point, config, bootstrap
+  api/                    Proto definitions + generated gRPC/gateway code
+  domain/                 Business logic, interfaces, models
+  grpc/                   gRPC service handler + server setup
+  clients/                Upstream service client wrappers
 ```

ipo-service/api/ipo-service.openapi.yaml …service/api/general-service.openapi.yamlipo-service/api/ipo-service.openapi.yaml renamed to general-service/api/general-service.openapi.yaml ipo-service/api/ipo-service.openapi.yaml renamed to general-service/api/general-service.openapi.yaml

@@ -3,19 +3,19 @@
 
 openapi: 3.0.3
 info:
-    title: Qubic IPO Aggregation Service
-    description: API for querying transactions related to smart contract IPO bids.
+    title: Qubic General Aggregation Service
+    description: General API for aggregated data / requests.
     version: 1.0.0
 servers:
     - url: https://TO-DEFINE
 paths:
     /getCurrentIpoBids:
         post:
             tags:
-                - AggregationIpoService
+                - AggregationGeneralService
             summary: Get bidder bid transactions for currently active IPOs.
             description: Allows for requesting the transactions associated with bids of currently active IPOs for a number of bidder identities.
-            operationId: AggregationIpoService_GetCurrentIpoBids
+            operationId: AggregationGeneralService_GetCurrentIpoBids
             requestBody:
                 content:
                     application/json:
@@ -29,6 +29,26 @@ paths:
                         application/json:
                             schema:
                                 $ref: '#/components/schemas/GetCurrentIpoBidsResponse'
+    /getIdentitiesBalances:
+        post:
+            tags:
+                - AggregationGeneralService
+            summary: Get balances for a list of identities.
+            description: Allows for requesting the balances for a number of Qubic wallet identities.
+            operationId: AggregationGeneralService_GetIdentitiesBalances
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/GetIdentitiesBalancesRequest'
+                required: true
+            responses:
+                "200":
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/GetIdentitiesBalancesResponse'
 components:
     schemas:
         BidTransaction:
@@ -75,6 +95,46 @@ components:
                     type: array
                     items:
                         $ref: '#/components/schemas/IpoBidTransactions'
+        GetIdentitiesBalancesRequest:
+            type: object
+            properties:
+                identities:
+                    type: array
+                    items:
+                        type: string
+        GetIdentitiesBalancesResponse:
+            type: object
+            properties:
+                balances:
+                    type: array
+                    items:
+                        $ref: '#/components/schemas/IdentityBalance'
+        IdentityBalance:
+            type: object
+            properties:
+                id:
+                    type: string
+                balance:
+                    type: string
+                validForTick:
+                    type: integer
+                    format: uint32
+                latestIncomingTransferTick:
+                    type: integer
+                    format: uint32
+                latestOutgoingTransferTick:
+                    type: integer
+                    format: uint32
+                incomingAmount:
+                    type: string
+                outgoingAmount:
+                    type: string
+                numberOfIncomingTransfers:
+                    type: integer
+                    format: uint32
+                numberOfOutgoingTransfers:
+                    type: integer
+                    format: uint32
         IpoBid:
             type: object
             properties:
@@ -98,7 +158,7 @@ components:
                     items:
                         $ref: '#/components/schemas/BidTransaction'
 tags:
-    - name: AggregationIpoService
+    - name: AggregationGeneralService
 externalDocs:
     description: GitHub
     url: https://github.com/qubic/qubic-aggregation