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

# Architecture

> Non-custodial signing model, transaction lifecycle, and system design

The Qustody API is a **non-custodial** orchestration layer. It manages transaction lifecycle, policy enforcement, and event delivery, but never holds private keys.

## Non-custodial signing model

Unlike traditional custodial solutions, the Custody API delegates all signing to your infrastructure. This means:

* **You control the keys.** Post-quantum private keys live in your HSM, secure enclave, or key management system
* **The API orchestrates.** It creates transactions, enforces policies, and broadcasts signed transactions to the Quantum Chain network
* **Signing is a callback.** When a transaction needs signing, you retrieve the payload, sign it externally, and submit the signature back

```mermaid theme={null}
graph LR
    A[Your App] -->|Create tx| B[Custody API]
    B -->|Broadcast| C[Quantum Chain Network]
    C -->|Confirmations| B
    B -->|Status updates| A
    B -->|signing_payload| A
    A -->|submit signature| B
```

## Transaction lifecycle

Every transaction moves through a deterministic state machine of **14 states**. The diagram below shows the most common transitions; see [Transaction state machine](/concepts/state-machine) for the full table.

```mermaid theme={null}
stateDiagram-v2
    [*] --> SUBMITTED: POST /v1/transactions
    SUBMITTED --> PENDING_AUTHORIZATION: Policy requires approval
    SUBMITTED --> PENDING_AML_SCREENING: Screening required
    SUBMITTED --> PENDING_SIGNATURE: Auto-approved
    SUBMITTED --> REJECTED: Policy denied

    PENDING_AUTHORIZATION --> APPROVED: POST /approve
    PENDING_AUTHORIZATION --> REJECTED: POST /reject
    PENDING_AUTHORIZATION --> CANCELLED: POST /cancel

    APPROVED --> PENDING_SIGNATURE: Authorization complete

    PENDING_AML_SCREENING --> PENDING_SIGNATURE: Cleared
    PENDING_AML_SCREENING --> BLOCKED: Flagged / blocked

    PENDING_SIGNATURE --> SIGNED: Signature submitted
    PENDING_SIGNATURE --> FAILED: Invalid signature
    PENDING_SIGNATURE --> CANCELLED: POST /cancel

    SIGNED --> BROADCASTING: Assembling tx
    BROADCASTING --> CONFIRMING: Broadcast success
    BROADCASTING --> FAILED: Broadcast rejected

    CONFIRMING --> COMPLETED: Confirmed
    CONFIRMING --> FAILED: Reverted/dropped

    COMPLETED --> [*]
    FAILED --> [*]
    REJECTED --> [*]
    CANCELLED --> [*]
    BLOCKED --> [*]
```

| State                   | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `SUBMITTED`             | Accepted; awaiting policy and screening evaluation            |
| `QUEUED`                | Held briefly because of an idempotency conflict or rate limit |
| `PENDING_AUTHORIZATION` | Awaiting manual approval per policy                           |
| `PENDING_AML_SCREENING` | Compliance screening in flight                                |
| `APPROVED`              | Authorization granted, transitioning to signing               |
| `PENDING_SIGNATURE`     | Ready for external post-quantum signature                     |
| `SIGNED`                | Signature received and verified                               |
| `BROADCASTING`          | Submitted to Quantum Chain nodes                              |
| `CONFIRMING`            | Included in a block, waiting for confirmation depth           |
| `COMPLETED`             | Confirmed with sufficient block depth                         |
| `FAILED`                | Transaction reverted, broadcast failure, or invalid signature |
| `REJECTED`              | Denied by policy or approver                                  |
| `CANCELLED`             | Cancelled before signing or broadcasting                      |
| `BLOCKED`               | Compliance screening flagged or blocked the transaction       |

## Request flow

A typical transfer follows this sequence:

<Steps>
  <Step title="Create transaction">
    Your application calls `POST /v1/transactions` with source, destination, and amount. The API validates the request and runs it through the policy engine.
  </Step>

  <Step title="Policy evaluation">
    Configured policies are evaluated: spending limits, whitelist/blacklist checks, approval requirements, and time windows. If a policy requires approval, the transaction moves to `PENDING_AUTHORIZATION`.
  </Step>

  <Step title="Retrieve signing payload">
    Call `GET /v1/transactions/{id}/signing_payload` to get the unsigned transaction digest as a hex-encoded byte array.
  </Step>

  <Step title="Sign externally">
    Sign the digest with your post-quantum private key using your key management solution.
  </Step>

  <Step title="Submit signature">
    Call `POST /v1/transactions/{id}/signature` with the base64-encoded signature and the signer's public key. The API verifies the signature before accepting it.
  </Step>

  <Step title="Broadcast and confirm">
    The API broadcasts the signed transaction to the Quantum Chain network via the node pool and tracks confirmation depth.
  </Step>

  <Step title="Webhook notification">
    Status change events are delivered to your registered webhook endpoints with HMAC-SHA256 signatures.
  </Step>
</Steps>

## System components

| Component                | Role                                                         |
| ------------------------ | ------------------------------------------------------------ |
| **API Server**           | HTTP handlers, authentication, rate limiting                 |
| **Policy Engine**        | Pre-broadcast rule evaluation and enforcement                |
| **Node Pool**            | Manages multiple Quantum Chain RPC connections with failover |
| **Deposit Monitor**      | Watches for inbound transfers to registered wallets          |
| **Confirmation Tracker** | Monitors block depth for pending transactions                |
| **Webhook Dispatcher**   | Delivers events with HMAC signing, retry, and dead-letter    |
| **Recovery Worker**      | Re-processes stuck transactions after restarts               |
| **Idempotency Cleanup**  | Prunes expired idempotency keys                              |

## Multi-tenancy

The API supports multiple tenants with full isolation:

* Each tenant has its own API credentials, vaults, wallets, policies, and webhook endpoints
* Cross-tenant access is prevented at the middleware layer
* Tenant context is extracted from the API key and propagated through all service calls

## Post-quantum signatures

Quantum Chain uses a **post-quantum digital signature scheme** offering security equivalent to \~192-bit classical cryptography:

| Property    | Value                          |
| ----------- | ------------------------------ |
| Security    | \~192-bit classical equivalent |
| Digest size | 32 bytes                       |

The API verifies signatures server-side before broadcasting to ensure only valid transactions reach the network.