> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darknyx.trade/llms.txt
> Use this file to discover all available pages before exploring further.

> A public, unauthenticated proof-of-reserves covering per-mint outstanding liabilities versus vault balances, plus the engine's attested identity.

# Transparency

<Info>
  **TL;DR**

  `GET /transparency` is a **public solvency snapshot**: for every mint it reports
  the outstanding note value (the venue's liability) against the actual SPL balance
  held in the vault (the assets). Treat the endpoint as a convenience view and
  verify the same `OutstandingMint` and vault token accounts directly on Solana
  when making a trust decision.
</Info>

A dark pool hides individual orders and balances, but solvency should still be
publicly checkable. Transparency squares that circle: it never reveals who owns
what, but it makes aggregate assets and liabilities easy to compare. The values
remain independently verifiable from Solana, while engine identity is verified
through a separate fresh attestation.

## GET /transparency

Public, with no authentication.

### Response

```json theme={null}
{
  "reserves": {
    "shards": [
      { "tree_id": 0, "merkle_root": "…", "leaf_count": 1024 },
      { "tree_id": 1, "merkle_root": "…", "leaf_count": 1024 },
      { "tree_id": 2, "merkle_root": "…", "leaf_count": 1024 },
      { "tree_id": 3, "merkle_root": "…", "leaf_count": 1024 }
    ],
    "shard0_merkle_root": "…",
    "total_leaf_count": 4096,
    "per_mint": [
      {
        "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "outstanding": "1250000000000",
        "vault_balance": "1250000000000",
        "stale": false
      }
    ]
  },
  "tee": {
    "app_id": "…",
    "compose_hash": "…",
    "mrtd": "…",
    "signer_pubkey": "…"
  },
  "stats": {
    "batches": 12,
    "jobs": 48
  }
}
```

## Reserves

| Field                         | Type    | Description                                                                                                                                                                          |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reserves.shards[]`           | array   | One entry per shard: `tree_id`, that shard's `merkle_root`, and the `leaf_count` **under that root**. There is no single global root, so this is the only lossless form — prefer it. |
| `reserves.shard0_merkle_root` | string  | Shard 0's root, kept for pre-sharding consumers.                                                                                                                                     |
| `reserves.total_leaf_count`   | integer | Total note commitments across **all** shards — not the count under `shard0_merkle_root`.                                                                                             |
| `per_mint[].mint`             | string  | The SPL mint, base58.                                                                                                                                                                |
| `per_mint[].outstanding`      | string  | Sum of unspent note value for this mint in smallest token units, the venue's liability.                                                                                              |
| `per_mint[].vault_balance`    | string  | Actual SPL balance held in the vault in smallest token units, the assets.                                                                                                            |
| `per_mint[].stale`            | boolean | `true` if an on-chain read was degraded; treat the numbers as unknown, not zero, when set.                                                                                           |

**The solvency check is `vault_balance >= outstanding` for every mint.** When it
holds, the pool can honor every withdrawal: the tokens are there. If a row is
`stale`, an on-chain read failed and you should ignore that row's numbers rather
than read a transient `0` as insolvency.

## Engine identity

| Field               | Description                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `tee.app_id`        | The deployment's application id.                                                                   |
| `tee.compose_hash`  | The server's convenience copy of its compose hash; use the quote-bound event log for verification. |
| `tee.mrtd`          | The TDX measurement of the running VM.                                                             |
| `tee.signer_pubkey` | The enclave's on-chain settlement signer (base58).                                                 |

These fields identify what the server claims to be. They are **not** an
attestation proof: derive the compose hash from the DCAP-verified quote event log
and compare the quote-bound full signer set with finalized on-chain
`VaultConfig.tee_pubkeys`. The transparency response exposes only the primary
signer.

## Stats

| Field           | Description                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stats.batches` | Settlement batches currently retained by the scheduler. Terminal history is capped; active batches are never evicted. This is not a lifetime counter. |
| `stats.jobs`    | Per-match settlement jobs belonging to those retained batches. This is not a lifetime counter.                                                        |

Aggregate operational gauges, useful for a public health dashboard. They reveal
nothing about any individual order; terminal entries age out, so do not sum
deltas or treat the values as historical volume.

## How to use it

* **Independent solvency monitoring.** Poll it and alert if any non-stale mint
  shows `vault_balance < outstanding`.
* **Pre-trade trust check.** Confirm reserves cover liabilities, then perform the
  independent quote, measurement, and full signer-set checks described in
  [Transport & Attestation](../getting-started/transport-and-attestation.mdx).
* **Public dashboards.** Because it is unauthenticated and leaks nothing about
  individuals, it is safe to surface on a status page.


## OpenAPI

````yaml api-reference/openapi/darknyx-public.yaml GET /transparency
openapi: 3.1.0
info:
  title: Darknyx TEE API
  version: 4.1.0
  description: |
    Public + authenticated REST and WebSocket API for the Darknyx dark pool
    TEE matching layer. One attested endpoint may expose several independently
    routed spot markets. Pairs with the v2 on-chain custody program
    (vault, program ID `C63vKvysCzX55PKraas4Wc22ijqjGJQdPC1mrzCFVWZx`).
  contact:
    name: Darknyx engineering
  license:
    name: PolyForm Perimeter License 1.0.1
    url: https://polyformproject.org/licenses/perimeter/1.0.1
servers:
  - url: https://api.darknyx.example.com
    description: Mainnet placeholder; use the origin published with a deployment.
  - url: https://api.devnet.darknyx.example.com
    description: Devnet placeholder; use the origin published with a deployment.
security: []
tags:
  - name: auth
    description: OAuth2 client-credentials and bearer-token lifecycle.
  - name: attestation
    description: |
      Darknyx engine and transport attestation plus the deployment gateway's
      separate evidence bundle. Programmatic clients verify the certificate on
      their actual connection with `/transport-attestation` before any
      credential or sensitive write. `/evidences/*` describes surrounding
      ingress infrastructure and is not a substitute for the engine check.
  - name: info
    description: |
      Application/instance metadata, boot-session id, and settlement signers.
      Verify measured identity through `/attestation`, not self-reported fields.
  - name: instruments
    description: Public market metadata.
  - name: orders
    description: Place / cancel / modify / inspect orders.
  - name: system
    description: Public engine liveness + server time (GTT slot conversion).
  - name: account
    description: Per-account open orders and preferences. Balances remain client-derived.
  - name: tree
    description: >-
      Convenience Merkle-tree mirror; clients can verify the same state on
      Solana.
  - name: transparency
    description: Public solvency snapshot + engine identity + aggregate stats.
  - name: settlement
    description: Batch settlement status (TEE → L1 tx_signature lookup).
paths:
  /transparency:
    get:
      tags:
        - transparency
      summary: |
        Public solvency snapshot + engine identity + aggregate stats.
        Unauthenticated.
      responses:
        '200':
          description: Transparency snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransparencySnapshot'
        '429':
          $ref: '#/components/responses/PublicRateLimited'
components:
  schemas:
    TransparencySnapshot:
      type: object
      required:
        - reserves
        - tee
        - stats
      description: |
        Public, unauthenticated convenience snapshot. Independently read the
        corresponding Solana accounts and verify `/attestation` before treating
        the reserve or engine-identity fields as trusted evidence.
      properties:
        reserves:
          type: object
          required:
            - shards
            - shard0_merkle_root
            - total_leaf_count
            - per_mint
          properties:
            shards:
              type: array
              description: |
                Per-shard root + leaf count. There is no single global root —
                each shard has its own — so this is the only lossless form.

                This replaces a bare `merkle_root` (shard 0's) that sat beside a
                `leaf_count` (the all-shard SUM). Both were documented, but as
                adjacent fields they read as a matched pair, and folding the
                count against that root yields a root the tree never had
                (SW-06).
              items:
                type: object
                required:
                  - tree_id
                  - merkle_root
                  - leaf_count
                properties:
                  tree_id:
                    type: integer
                  merkle_root:
                    type: string
                  leaf_count:
                    type: integer
            shard0_merkle_root:
              type: string
              description: |
                Shard 0's root, kept for pre-sharding consumers. Prefer
                `shards`.
            total_leaf_count:
              type: integer
              description: |
                Total leaves SUMMED across all `num_trees` shards — NOT the leaf
                count under `shard0_merkle_root`.
            per_mint:
              type: array
              items:
                type: object
                required:
                  - mint
                  - outstanding
                  - vault_balance
                  - stale
                properties:
                  mint:
                    type: string
                  outstanding:
                    type: string
                    description: |
                      Sum of unspent note amounts for this mint, in the mint's
                      smallest integer units.
                  vault_balance:
                    type: string
                    description: |
                      SPL balance in the vault token account, in the mint's
                      smallest integer units. Solvency requires this to be at
                      least `outstanding`.
                  stale:
                    type: boolean
                    description: |
                      true if either on-chain read was DEGRADED (RPC
                      error or malformed account); outstanding /
                      vault_balance are then "unknown", not a real 0 —
                      ignore the numbers for a solvency check.
        tee:
          type: object
          description: |
            Engine attestation IDENTITY — enough to tie this response to
            a measured image. The full challenge-response quote is at
            GET /attestation.
          required:
            - app_id
            - compose_hash
            - mrtd
            - signer_pubkey
          properties:
            app_id:
              type: string
            compose_hash:
              type: string
            mrtd:
              type: string
            signer_pubkey:
              type: string
              description: >-
                Shard-0 Ed25519 signer (base58); verify the full set via `/info`
                and `/attestation`.
        stats:
          type: object
          description: Aggregate settlement-scheduler counters.
          required:
            - batches
            - jobs
          properties:
            batches:
              type: integer
              description: >-
                Settle batches currently retained by the scheduler. Terminal
                history is capped; active batches are never evicted. Not a
                lifetime counter.
            jobs:
              type: integer
              description: >-
                Per-match settle jobs belonging to retained batches; not a
                lifetime counter.
    Error:
      type: object
      description: |
        The error envelope. Every non-2xx response renders as this shape, with
        the mapped HTTP status. Success responses are NOT enveloped (their typed
        body is returned directly). Every response — success and error — carries
        an `x-request-id` header for correlation with server logs.
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: |
            Stable numeric error code. Ranges: 1000–1099 request validation,
            1100–1199 auth, 1200–1299 conflict, 1300–1399 not found, 1400–1499
            rate limit, 5000+ server. See the Error Codes reference.

            One exception to the ranges: `1402` is returned with HTTP 503, not
            429. It signals that credential verification is momentarily at
            capacity and was refused rather than queued. Branch on the numeric
            code rather than inferring the status from its range.
          example: 1102
        message:
          type: string
          example: trading_key_signature does not verify against the canonical body
  responses:
    PublicRateLimited:
      description: |
        The venue-wide public-route allowance is exhausted (SW-02). Every
        unauthenticated route shares one weighted bucket: client traffic reaches
        the enclave through the dstack gateway, so all requests present the same
        source address and a per-caller limit here would bound the venue rather
        than any individual caller.

        Weights follow real cost — `/attestation` (a TDX quote per request,
        uncacheable because the caller's nonce is the point) is the heaviest,
        `/transparency` is moderate, and in-memory reads are ~100x lighter.
        Honest polling sits far inside the budget.

        `POST /auth/token` is deliberately EXEMPT from this bucket and cannot
        return this response: metering it venue-wide would let junk credentials
        exhaust a shared allowance and lock every real account out of
        authenticating. Its own `429`, documented on that operation, comes from
        the per-account login bucket instead.

        `Retry-After` carries the back-off in seconds.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

````