1  openapi: "3.1.0"
  2  
  3  info:
  4    title: ACDC Network API
  5    version: "1.0.0"
  6    description: |
  7      REST API for the ACDC Alpha/Delta chains. All responses carry X-Request-Id,
  8      X-ACDC-Finality, X-ACDC-Block-Height, and X-ACDC-Chain headers. Errors use
  9      RFC 7807 application/problem+json format.
 10    contact:
 11      name: ACDC Network
 12      url: https://ac-dc.network
 13    license:
 14      name: CC0-1.0
 15      url: https://creativecommons.org/publicdomain/zero/1.0/
 16  
 17  servers:
 18    - url: https://api.ac-dc.network/api/v1
 19      description: Production (Alpha/Delta mainnet)
 20    - url: http://localhost:3030/api/v1
 21      description: Local development
 22  
 23  security:
 24    - ApiKeyAuth: []
 25    - Anonymous: []
 26  
 27  # ──────────────────────────────────────────────────────────────
 28  # Reusable Components
 29  # ──────────────────────────────────────────────────────────────
 30  
 31  components:
 32  
 33    securitySchemes:
 34      ApiKeyAuth:
 35        type: http
 36        scheme: bearer
 37        description: |
 38          Bearer token issued via ApiRegistry. Prefixed ak_ (Standard) or pk_ (Premium).
 39          ShadowOwner tokens are node-local and match ACDC_OWNER_WALLET exactly.
 40      Anonymous:
 41        type: http
 42        scheme: bearer
 43        description: |
 44          No auth required. Requests without Authorization header receive Anonymous tier
 45          (50 req/s, 2M/epoch limit).
 46  
 47    parameters:
 48      FinalityParam:
 49        name: finality
 50        in: query
 51        required: false
 52        schema:
 53          type: string
 54          enum: [confirmed, optimistic, finalized]
 55          default: confirmed
 56        description: |
 57          Desired finality level for the response.
 58          - confirmed: 1+ confirmations (default)
 59          - optimistic: locally accepted, not yet confirmed
 60          - finalized: irreversible
 61  
 62      LimitParam:
 63        name: limit
 64        in: query
 65        required: false
 66        schema:
 67          type: integer
 68          minimum: 1
 69          maximum: 100
 70          default: 20
 71        description: Maximum number of items per page. Capped at 100.
 72  
 73      CursorParam:
 74        name: cursor
 75        in: query
 76        required: false
 77        schema:
 78          type: string
 79        description: Opaque pagination cursor from a previous response.
 80  
 81      FromHeightParam:
 82        name: from_height
 83        in: query
 84        required: false
 85        schema:
 86          type: integer
 87          format: int64
 88          minimum: 0
 89        description: Start at this block height (inclusive).
 90  
 91      ToHeightParam:
 92        name: to_height
 93        in: query
 94        required: false
 95        schema:
 96          type: integer
 97          format: int64
 98          minimum: 0
 99        description: End at this block height (inclusive).
100  
101    schemas:
102  
103      PaginationMeta:
104        type: object
105        required: [has_more, count]
106        properties:
107          cursor:
108            type: string
109            nullable: true
110            description: Next page cursor. Null if no more pages.
111          has_more:
112            type: boolean
113            description: Whether more pages exist after this one.
114          count:
115            type: integer
116            description: Number of items in this page.
117  
118      FinalityMeta:
119        type: object
120        required: [finality, block_height, block_hash]
121        properties:
122          finality:
123            type: string
124            enum: [confirmed, optimistic, finalized]
125          block_height:
126            type: integer
127            format: int64
128          block_hash:
129            type: string
130  
131      ProblemDetail:
132        type: object
133        required: [type, title, status, detail]
134        properties:
135          type:
136            type: string
137            format: uri
138            description: URI identifying the problem type.
139          title:
140            type: string
141            description: Short human-readable summary.
142          status:
143            type: integer
144            description: HTTP status code.
145          detail:
146            type: string
147            description: Human-readable explanation of the specific occurrence.
148          chain:
149            type: string
150            enum: [alpha, delta]
151            description: Chain context for the error.
152          request_id:
153            type: string
154            description: Request ID for correlation with X-Request-Id header.
155  
156      BlockSummary:
157        type: object
158        required: [height, hash, tx_count, finality]
159        properties:
160          height:
161            type: integer
162            format: int64
163          hash:
164            type: string
165            description: 32-byte block hash (hex).
166          tx_count:
167            type: integer
168          finality:
169            type: string
170            enum: [confirmed, optimistic, finalized]
171  
172      BlockListResponse:
173        type: object
174        required: [blocks, pagination, finality, block_height]
175        properties:
176          blocks:
177            type: array
178            items:
179              $ref: "#/components/schemas/BlockSummary"
180          pagination:
181            $ref: "#/components/schemas/PaginationMeta"
182          finality:
183            type: string
184          block_height:
185            type: integer
186            format: int64
187  
188      AddressBalance:
189        type: object
190        required: [address, balance, finality, block_height, block_hash]
191        properties:
192          address:
193            type: string
194          balance:
195            type: integer
196            format: int64
197            description: Balance in microcredits (u128 range, returned as integer).
198          finality:
199            type: string
200            enum: [confirmed, optimistic, finalized]
201          block_height:
202            type: integer
203            format: int64
204          block_hash:
205            type: string
206  
207      TxEntry:
208        type: object
209        required: [tx_id, block_height, finality]
210        properties:
211          tx_id:
212            type: string
213          block_height:
214            type: integer
215            format: int64
216          finality:
217            type: string
218  
219      AddressTxListResponse:
220        type: object
221        required: [address, transactions, pagination]
222        properties:
223          address:
224            type: string
225          transactions:
226            type: array
227            items:
228              $ref: "#/components/schemas/TxEntry"
229          pagination:
230            $ref: "#/components/schemas/PaginationMeta"
231  
232      PrivateTxSubmission:
233        type: object
234        required: [chain_id, encrypted_tx, fee_estimate]
235        properties:
236          chain_id:
237            type: string
238            enum: [alpha, delta]
239          encrypted_tx:
240            type: string
241            description: Hex-encoded X25519-ChaCha20-Poly1305 encrypted transaction blob.
242          fee_estimate:
243            type: integer
244            format: int64
245            minimum: 1000
246            description: Estimated transaction fee in microcredits (minimum 1000).
247  
248      PrivateTxResponse:
249        type: object
250        required: [tx_id, sequence, m1_depth]
251        properties:
252          tx_id:
253            type: string
254            description: Hex-encoded 32-byte transaction identifier.
255          sequence:
256            type: integer
257            format: int64
258            description: FCFS sequence number assigned by adnet.
259          m1_depth:
260            type: integer
261            description: Number of transactions in M1 before this insertion.
262  
263    responses:
264      BadRequest:
265        description: Invalid request parameters.
266        content:
267          application/problem+json:
268            schema:
269              $ref: "#/components/schemas/ProblemDetail"
270            example:
271              type: "https://errors.ac-dc.network/finality-param-invalid"
272              title: "Invalid Finality Parameter"
273              status: 400
274              detail: "Unknown finality level 'unknown'"
275  
276      Unauthorized:
277        description: Invalid or missing API key.
278        content:
279          application/problem+json:
280            schema:
281              $ref: "#/components/schemas/ProblemDetail"
282            example:
283              type: "https://errors.ac-dc.network/api-key-invalid"
284              title: "Invalid API Key"
285              status: 401
286              detail: "Invalid or unrecognized API key format"
287  
288      RateLimited:
289        description: Rate limit exceeded.
290        content:
291          application/problem+json:
292            schema:
293              $ref: "#/components/schemas/ProblemDetail"
294            example:
295              type: "https://errors.ac-dc.network/api-key-rate-limited"
296              title: "Rate Limit Exceeded"
297              status: 429
298              detail: "Anonymous tier: 50 req/s exceeded"
299  
300      IdempotencyConflict:
301        description: Idempotency key used with a different request body.
302        content:
303          application/problem+json:
304            schema:
305              $ref: "#/components/schemas/ProblemDetail"
306  
307  # ──────────────────────────────────────────────────────────────
308  # Paths
309  # ──────────────────────────────────────────────────────────────
310  
311  paths:
312  
313    /blocks:
314      get:
315        operationId: listBlocks
316        summary: List blocks with pagination
317        description: |
318          Returns a paginated list of blocks. Supports cursor-based pagination,
319          height-range filtering, and finality-aware responses.
320        parameters:
321          - $ref: "#/components/parameters/LimitParam"
322          - $ref: "#/components/parameters/CursorParam"
323          - $ref: "#/components/parameters/FromHeightParam"
324          - $ref: "#/components/parameters/ToHeightParam"
325          - $ref: "#/components/parameters/FinalityParam"
326        responses:
327          "200":
328            description: List of blocks with pagination metadata.
329            headers:
330              X-Request-Id:
331                schema:
332                  type: string
333                  format: uuid
334              X-ACDC-Finality:
335                schema:
336                  type: string
337              X-ACDC-Block-Height:
338                schema:
339                  type: integer
340              X-ACDC-Chain:
341                schema:
342                  type: string
343            content:
344              application/json:
345                schema:
346                  $ref: "#/components/schemas/BlockListResponse"
347          "400":
348            $ref: "#/components/responses/BadRequest"
349          "429":
350            $ref: "#/components/responses/RateLimited"
351  
352    /blocks/{height}:
353      get:
354        operationId: getBlock
355        summary: Get a single block by height
356        parameters:
357          - name: height
358            in: path
359            required: true
360            schema:
361              type: integer
362              format: int64
363              minimum: 0
364          - $ref: "#/components/parameters/FinalityParam"
365        responses:
366          "200":
367            description: Block details.
368            content:
369              application/json:
370                schema:
371                  $ref: "#/components/schemas/BlockSummary"
372          "400":
373            $ref: "#/components/responses/BadRequest"
374          "404":
375            description: Block not found.
376            content:
377              application/problem+json:
378                schema:
379                  $ref: "#/components/schemas/ProblemDetail"
380  
381    /addresses/{address}/balance:
382      get:
383        operationId: getAddressBalance
384        summary: Get address balance with finality metadata
385        parameters:
386          - name: address
387            in: path
388            required: true
389            schema:
390              type: string
391          - $ref: "#/components/parameters/FinalityParam"
392        responses:
393          "200":
394            description: Address balance with finality metadata.
395            content:
396              application/json:
397                schema:
398                  $ref: "#/components/schemas/AddressBalance"
399          "400":
400            $ref: "#/components/responses/BadRequest"
401          "404":
402            description: Address not found.
403            content:
404              application/problem+json:
405                schema:
406                  $ref: "#/components/schemas/ProblemDetail"
407  
408    /addresses/{address}/transactions:
409      get:
410        operationId: listAddressTransactions
411        summary: List transactions for an address
412        parameters:
413          - name: address
414            in: path
415            required: true
416            schema:
417              type: string
418          - $ref: "#/components/parameters/LimitParam"
419          - $ref: "#/components/parameters/CursorParam"
420          - $ref: "#/components/parameters/FromHeightParam"
421          - $ref: "#/components/parameters/ToHeightParam"
422          - $ref: "#/components/parameters/FinalityParam"
423        responses:
424          "200":
425            description: Paginated transaction list.
426            content:
427              application/json:
428                schema:
429                  $ref: "#/components/schemas/AddressTxListResponse"
430          "400":
431            $ref: "#/components/responses/BadRequest"
432  
433    /transactions/submit/private:
434      post:
435        operationId: submitPrivateTransaction
436        summary: Submit a private (encrypted) transaction
437        description: |
438          Submits an encrypted transaction for Alpha or Delta chain. Assigns a FCFS
439          sequence number and inserts into the proof mempool (M1). Supports
440          Idempotency-Key header for exactly-once submission.
441        security:
442          - ApiKeyAuth: []
443        requestBody:
444          required: true
445          content:
446            application/json:
447              schema:
448                $ref: "#/components/schemas/PrivateTxSubmission"
449        responses:
450          "200":
451            description: Transaction accepted.
452            content:
453              application/json:
454                schema:
455                  $ref: "#/components/schemas/PrivateTxResponse"
456          "400":
457            $ref: "#/components/responses/BadRequest"
458          "401":
459            $ref: "#/components/responses/Unauthorized"
460          "422":
461            $ref: "#/components/responses/IdempotencyConflict"
462          "429":
463            $ref: "#/components/responses/RateLimited"
464  
465    /peers:
466      get:
467        operationId: getPeerList
468        summary: Get current active API peer list
469        description: |
470          Returns the current set of active API server endpoints for client-side
471          cache refresh. Ordered by load (LeastUsed strategy, P0).
472        responses:
473          "200":
474            description: Ordered list of active API server endpoints.
475            content:
476              application/json:
477                schema:
478                  type: object
479                  required: [peers]
480                  properties:
481                    peers:
482                      type: array
483                      items:
484                        type: string
485                        format: uri