> ## 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.

# Token security model

> Governance, approvals, idempotency, and audit guarantees for Qustody Token Management.

Token operations affect supply, ownership, and the rules that govern an asset. Treat them with the same rigor you apply to native value movement.

## Privileged operations

The following operations are privileged and **should** be governed by an [approval policy](/concepts/policies) in production:

* `DEPLOY_TOKEN` — deploys new code on chain.
* `MINT` — increases supply.
* `BURN` — reduces supply.
* `GRANT_ROLE` / `REVOKE_ROLE` — changes who can perform privileged actions.
* `PAUSE` / `UNPAUSE` — halts or resumes all activity.
* `FREEZE` / `UNFREEZE` — halts activity for a single account.
* `UPDATE_COMPLIANCE` — changes permissioned-transfer rules.
* `ALLOWLIST_ADD` / `ALLOWLIST_REMOVE` — changes who may hold or transfer the token.

## What Qustody enforces

* **Approval policy.** Qustody can require one or more approvals before an operation is signed and broadcast. Configurable per token via `approvalPolicyId`.
* **Post-quantum signing.** Every broadcasted transaction is signed with a post-quantum signature held by the configured external signer. See [Quantum safety](/concepts/quantum-safety).
* **Idempotency.** All write endpoints accept an `Idempotency-Key` header. Within 24 hours, repeating a request with the same key returns the original result without re-executing.
* **Audit log.** Every state-changing token call writes a hash-chained audit record. Verifiable via `GET /v1/audit/verify`.
* **Webhook delivery.** Operation lifecycle is published as `token.*` events; deliveries are HMAC-SHA256 signed with the per-endpoint secret.
* **Rate limiting.** Token endpoints share the global Qustody rate limits.

## What Qustody does not do

* **Qustody does not replace legal, regulatory, or compliance review.** The compliance endpoints are an integration point for identity and compliance systems — they do not by themselves make a token issuance legally compliant.
* **Qustody does not audit smart-contract source.** Templates ship with a documented `bytecodeHash`; verifying the contract behaviour for your jurisdiction and use case is your responsibility.
* **Qustody does not guarantee on-chain finality.** Confirmation depth is configurable; treat any state before `COMPLETED` as reversible.

## Operational guidance

<Steps>
  <Step title="Use a high-friction approval policy for supply changes">
    Mint and burn should require **multi-approver** quorum and, for sensitive cases, time-delays. The same applies to role changes.
  </Step>

  <Step title="Treat upgrades as deployments">
    If a template supports upgradeability, the upgrade transaction is itself a privileged operation. Govern it identically to deployment.
  </Step>

  <Step title="Always pass an idempotency key">
    Required on every write endpoint. Reuse the same key on retry; never vary the key for the same logical request.
  </Step>

  <Step title="Subscribe to operation webhooks before going live">
    Drive your reconciliation off `token.*` events plus the underlying `transaction.*` events. Polling is acceptable for backfill but not for primary signal.
  </Step>

  <Step title="Test on Quantum Chain testnet first">
    Set `network: "quantum-chain-testnet"` on every token configuration during development.
  </Step>

  <Step title="Verify smart-contract behaviour for your use case">
    Read the template ABI, compare the deployed bytecode hash against the template's `bytecodeHash`, and run end-to-end tests.
  </Step>
</Steps>

## Wording matters

When describing Qustody capabilities to your stakeholders:

* **Good** — "Qustody can enforce approval workflows before token operations are signed and submitted."
* **Bad** — "Qustody guarantees that token operations are compliant."
* **Good** — "Regulated-token workflows can integrate permissioning and compliance-aware transfer controls."
* **Bad** — "Qustody makes securities issuance legally compliant."

## Related

* [Approval policies](/concepts/policies)
* [Quantum safety](/concepts/quantum-safety)
* [Audit log](/qustody/security-model)
* [Compliance and allowlist](/api-reference/tokens/compliance-and-allowlist)