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

# Commodity Token License

> ERC-20 tokens backed by physical commodity reserves with MiCA-compliant controls, reserve enforcement, and primary market sales.

The Commodity Token License is a smart contract suite for issuing ERC-20 tokens that represent ownership of physical commodity reserves - gold, silver, platinum, or any gram-denominated asset. Every token is backed by a fixed quantity of the underlying commodity, enforced on-chain at the protocol level.

The suite covers the full token lifecycle: deployment via factory, reserve-enforced minting through a request system, physical and cash redemption, primary market sales, and transfer compliance via an integrated identity registry.

## Contract Suite

The license includes six core contracts and four interfaces:

<CardGroup cols={2}>
  <Card title="CommodityTokenFactoryUpgradeable" icon="industry" href="/licenses/commodities/contracts#factory">
    Deploys commodity tokens as UUPS proxies with shared implementation. Manages implementation approvals and batch upgrade proposals.
  </Card>

  <Card title="CommodityTokenUpgradeable" icon="coins" href="/licenses/commodities/contracts#token">
    The token itself. ERC-20 with reserve enforcement, sub-issuer architecture, fee distribution, whitelist/blacklist, and dual-path redemption.
  </Card>

  <Card title="IdentityRegistryUpgradeable" icon="id-card" href="/licenses/commodities/contracts#identity-registry">
    MiCA/eWpG-compliant KYC registry. Role-based access, claim management, expiry tracking, and transfer compliance checks.
  </Card>

  <Card title="BasicComplianceModule" icon="scale-balanced" href="/licenses/commodities/contracts#compliance-module">
    Holding limits, minimum balances, and lockup periods. Plugs into the identity registry as a modular compliance rule.
  </Card>

  <Card title="CommodityTokenSale" icon="cart-shopping" href="/licenses/commodities/contracts#sale">
    Primary market sale contract. Fixed or oracle-priced sales, mint-on-purchase, per-buyer limits, and slippage protection.
  </Card>

  <Card title="CommodityTokenSaleFactory" icon="warehouse" href="/licenses/commodities/contracts#sale-factory">
    Deploys sale contracts per commodity token. Tracks all sale rounds per token and per issuer.
  </Card>
</CardGroup>

## Key Capabilities

**Reserve enforcement.** Each token is backed by a configurable `gramsPerToken` value. The contract validates that `totalSupply * gramsPerToken <= totalGramsReserve * 1e18` on every mint. Reserve data includes vault location hashes and attestation URIs for off-chain verification.

**Request-based minting.** Mints go through a request system with four modes: `INSTANT` (executes immediately), `MANUAL_APPROVAL` (requires issuer sign-off), `TIMELOCK` (delayed execution), and `CONDITIONAL` (EIP-712 signature authorization). Sub-issuers can mint within configurable per-address limits.

**Dual-path redemption.** Token holders can redeem through physical delivery (burn tokens, receive commodity) or cash settlement (burn tokens, receive USDC at oracle price with decimal normalization). Physical redemption supports unit-based validation for standard bar sizes.

**Transfer compliance.** Optional KYC enforcement via `IdentityRegistryUpgradeable` with the full `canTransfer` pipeline - identity status, expiry checks, freeze status, and pluggable compliance modules. Independent whitelist/blacklist restrictions at the issuer level.

**Fee distribution.** Configurable mint and burn fees (up to 10% each) split 75/25 between the issuer and the platform wallet.

**Upgrade governance.** TrussetDAO proposes upgrades, the issuer accepts or rejects. Neither party can unilaterally upgrade a token contract. The factory manages implementation approvals and can propose upgrades to multiple tokens in batch.

## Architecture

```
CommodityTokenFactoryUpgradeable
  └── deploys → CommodityTokenUpgradeable (UUPS Proxy)
                  ├── reads → IdentityRegistryUpgradeable
                  │              └── calls → BasicComplianceModule[]
                  └── called by → CommodityTokenSale
                                    └── deployed by → CommodityTokenSaleFactory
```

The factory deploys each token as an `ERC1967Proxy` pointing to a shared implementation. Tokens are fully independent after deployment - each has its own state, issuer, and upgrade lifecycle. The identity registry is shared across tokens within the same instance but can be overridden per token with a custom registry at deployment time.

## Next Steps

<CardGroup cols={3}>
  <Card title="Contracts" icon="code" href="/licenses/commodities/contracts">
    Detailed contract reference with all functions, events, and storage.
  </Card>

  <Card title="Integration" icon="plug" href="/licenses/commodities/integration">
    Deployment sequence, configuration, and connecting to the Trusset API layer.
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/licenses/commodities/best-practices">
    Security considerations, operational patterns, and regulatory alignment.
  </Card>
</CardGroup>