# Permissioned Tokens

Permissioned Tokens is the Cocoon component for issuing and managing regulated on-chain assets. It implements the [ERC-3643 T-REX standard](https://erc3643.org/) without modification, meaning any tooling or auditing built for T-REX works with Cocoon tokens out of the box. On top of the standard, Cocoon adds a distribution layer (subscriptions, redemptions, NAV pricing), atomic delivery-versus-payment settlement using Confidential Cash, and encrypted document management for fund documents. Every token carries an `assetType` field (`stablecoin`, `fund`, `bond`, `equity`, or `commodity`) that drives settlement behaviour, UI rendering, and oracle integration.

Typical use cases include tokenized funds, structured products, digital bonds, and any regulated instrument that requires know-your-customer checks, transfer restrictions, and lifecycle management.

{% hint style="info" %}
Permissioned Tokens depends on the Identity component for investor verification. Before a token can be deployed in production, the Identity component must be active and at least one trusted claim issuer must be registered.
{% endhint %}

## Role Model

Three roles exist on every token. Roles are enforced by the smart contracts — there is no off-chain privilege escalation path.

| Role         | Held By                             | Capabilities                                                                              |
| ------------ | ----------------------------------- | ----------------------------------------------------------------------------------------- |
| **Owner**    | Issuer or fund administrator        | Deploy token, configure compliance, manage trusted issuers, pause/unpause, force-transfer |
| **Agent**    | Transfer agent or automated service | Mint, burn, freeze individual wallets, execute batch operations                           |
| **Investor** | End investor wallet                 | Hold, transfer (subject to compliance), subscribe, redeem                                 |

Roles map to UCAN capability namespaces: `/token/owner/*`, `/token/agent/*`, and `/token/investor/*`. This means the Authorization component enforces role boundaries at the RPC layer before any transaction reaches the chain.

## Transfer Compliance Flow

Every transfer — whether initiated by an investor, an agent, or a batch operation — passes through the same validation pipeline. The pipeline is synchronous and will revert the transaction at the first failing check, returning a machine-readable reason code.

```mermaid
flowchart TD
    A([Transfer requested]) --> B{Sender balance\nsufficient?}
    B -- No --> FAIL1([Revert: insufficient balance])
    B -- Yes --> C{Sender wallet\nfrozen?}
    C -- Yes --> FAIL2([Revert: sender frozen])
    C -- No --> D{Token\npaused?}
    D -- Yes --> FAIL3([Revert: token paused])
    D -- No --> E{IIdentityRegistry:\nsender verified?}
    E -- No --> FAIL4([Revert: sender not verified])
    E -- Yes --> F{IIdentityRegistry:\nreceiver verified?}
    F -- No --> FAIL5([Revert: receiver not verified])
    F -- Yes --> G{Compliance\nmodules pass?}
    G -- No --> FAIL6([Revert: compliance rejection\n+ reason code])
    G -- Yes --> H([Transfer executed])
```

The `token_canTransfer` RPC method runs this pipeline as a read-only dry run and returns a structured result including which module rejected the transfer and why. This is useful for pre-flight checks in investor portals before presenting a transaction to the user.

### Compliance Modules

Compliance is modular. Modules are attached to a token at deployment and can be added or removed by the Owner (subject to the token's governance rules). Each module implements a single `canTransfer` function.

| Module                    | Behaviour                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Country Allow List**    | Rejects transfers to or from wallets whose identity carries a country claim that is not on the token's permitted-country list.       |
| **Max Balance**           | Rejects transfers that would cause the receiver's balance to exceed a configured ceiling (useful for investor concentration limits). |
| **Time-Locked Transfers** | Rejects transfers before a cliff date; commonly used for lockup periods post-subscription.                                           |
| **Custom Modules**        | Any contract implementing the `ICompliance` interface can be plugged in without redeploying the token.                               |

## Asset Classification

Every token has an `assetType` field that classifies its economic nature and controls how the platform treats it.

| Asset Type   | Description                  | Settlement Behaviour                                                                                                          |
| ------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `stablecoin` | Fiat-pegged digital currency | No NAV; uses simple ERC-20-style transfers; price is 1:1 with `denominatedCcy`.                                               |
| `fund`       | Tokenized investment fund    | Requires subscribe/redeem flows; exposes a fund balance sheet via `token_getFundBalanceSheet`; NAV is published periodically. |
| `bond`       | Tokenized debt instrument    | Defined but not yet deployed in production.                                                                                   |
| `equity`     | Tokenized equity share       | Defined but not yet deployed in production.                                                                                   |
| `commodity`  | Tokenized physical commodity | Defined but not yet deployed in production.                                                                                   |

The `denominatedCcy` field records the currency in which the NAV (for funds) or market price (for other asset types) is quoted — for example `"USD"`, `"EUR"`, or `"CHF"`. Stablecoins default to using their token symbol as the denomination currency; all other asset types default to `"USD"`.

The investor portal uses the `fx_` oracle namespace to convert all holdings to the user's configured base currency, enabling a unified portfolio view across multi-currency instruments.

## On-Chain Interfaces (T-REX)

The component adopts ERC-3643 interfaces without modification:

* **IToken** — the ERC-20-compatible token with additional pause, freeze, and forced-transfer functions.
* **ICompliance** — the orchestrator that chains compliance module results.
* **IIdentityRegistry** — maps wallet addresses to OnchainID identity contracts.
* **ITrustedIssuersRegistry** — records which claim issuers are trusted for which claim topics.
* **IClaimTopicsRegistry** — defines which claim topics (e.g. KYC, AML, accreditation) are required to hold the token.

## Investor Onboarding

Onboarding an investor from zero to holding-eligible is a single RPC call:

```
token_onboardInvestor(tokenAddress, investorWallet, claims[], countryCode)
```

Internally this call:

1. Deploys an OnchainID identity contract for the investor wallet (if one does not already exist).
2. Issues the required claims (KYC, AML, country) to the identity contract, referencing encrypted documents stored via the Data Storage component.
3. Registers the identity in the token's IIdentityRegistry.

After this call completes, the investor's wallet will pass the `IIdentityRegistry` checks in the transfer compliance flow.

## Distribution: Subscriptions and Redemptions

For funds and other NAV-priced instruments, the component provides a primary-market distribution layer on top of the base token.

```mermaid
sequenceDiagram
    participant Investor
    participant SubscriptionContract
    participant DBC as Confidential Cash (DBC)
    participant Token

    Investor->>SubscriptionContract: subscribe(amount, navPrice)
    SubscriptionContract->>DBC: lock(payment in DBC)
    Note over SubscriptionContract: Wait for agent NAV confirmation
    SubscriptionContract->>Token: mint(shares to investor)
    SubscriptionContract->>DBC: release(payment to issuer)
```

Payment for subscriptions and redemptions flows through the Confidential Cash (DBC) component. This means the cash leg of a subscription is confidential — the amount an investor pays is hidden from other participants on-chain, while the token leg (shares minted) remains transparent for regulatory reporting.

**NAV pricing** is published on-chain by the Owner or an authorized Oracle integration:

```
token_publishNAV(tokenAddress, nav, timestamp, oracleSignature)
```

The subscription contract validates the oracle signature before accepting the NAV for a settlement cycle.

## Delivery vs. Payment (DVP) Settlement

For secondary-market trades, the component supports atomic DVP using an escrow contract:

1. Seller locks tokens in escrow.
2. Buyer deposits DBC payment into escrow.
3. When both sides are present, the escrow contract atomically transfers tokens to the buyer and DBC to the seller.
4. If either side times out, both sides are refunded.

Atomicity is guaranteed at the contract level — there is no settlement risk window.

## Document Management

Fund documents (prospectus, annual reports, audit reports, NAV history) are stored encrypted via the Data Storage component and referenced from the token contract by their content hash. This means:

* Documents are immutable once published (tampering changes the hash and breaks the reference).
* Only authorized parties (verified investors, regulators with delegated access) can decrypt the content.
* The on-chain reference provides a permanent, auditable record of which document version was in effect at any point in time.

Document types are typed with standard labels (`PROSPECTUS`, `ANNUAL_REPORT`, `AUDIT_REPORT`, `NAV_HISTORY`, `CUSTOM`) so investor portals can render document lists without custom configuration per token.

## Batch Operations

For transfer agents operating large books, all write operations have batch variants:

| Method                | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `token_batchMint`     | Mint to multiple recipients in a single transaction. |
| `token_batchTransfer` | Execute multiple transfers atomically.               |
| `token_batchBurn`     | Burn from multiple wallets in a single transaction.  |

Batch operations are subject to the same compliance pipeline as individual operations — a single failing compliance check causes the entire batch to revert unless the caller uses the partial-batch flag, in which case passing entries are executed and failing entries are returned as a rejection list.

## Key RPC Methods

{% tabs %}
{% tab title="Token Lifecycle" %}

| Method                 | Description                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------ |
| `token_deploy`         | Deploy a new T-REX token with initial compliance configuration.                      |
| `token_pause`          | Halt all transfers. Owner only.                                                      |
| `token_unpause`        | Resume transfers. Owner only.                                                        |
| `token_freeze`         | Freeze a specific investor wallet. Agent only.                                       |
| `token_unfreeze`       | Unfreeze a wallet. Agent only.                                                       |
| `token_forcedTransfer` | Move tokens between wallets regardless of compliance. Owner only. Emits audit event. |
| {% endtab %}           |                                                                                      |

{% tab title="Issuance" %}

| Method                  | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| `token_mint`            | Mint tokens to a verified wallet. Agent only.          |
| `token_burn`            | Burn tokens from a wallet. Agent only.                 |
| `token_batchMint`       | Mint to multiple wallets in one call.                  |
| `token_batchBurn`       | Burn from multiple wallets in one call.                |
| `token_onboardInvestor` | Deploy identity + issue claims + register in one call. |
| {% endtab %}            |                                                        |

{% tab title="Queries and Pricing" %}

| Method                      | Description                                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `token_canTransfer`         | Dry-run the compliance pipeline. Returns pass/fail and reason code.                                                       |
| `token_getHolders`          | Return paginated list of current token holders with balances.                                                             |
| `token_getTokenInfo`        | Return token metadata, compliance modules, and current NAV.                                                               |
| `token_publishNAV`          | Publish a new NAV price with oracle signature.                                                                            |
| `token_publishPrice`        | Publish an exchange-rate or market price for secondary-market display.                                                    |
| `token_getFundBalanceSheet` | Return a snapshot of the fund's liabilities (shares, NAV, AUM) and assets (stablecoin reserves, DBC reserves, bank cash). |
| {% endtab %}                |                                                                                                                           |
| {% endtabs %}               |                                                                                                                           |

## Integration Points

* **Identity**: Every investor wallet must have a registered OnchainID identity with valid claims before it can hold or transfer tokens.
* **Authorization**: All Owner and Agent RPC calls require a UCAN capability token scoped to `/token/owner/*` or `/token/agent/*`.
* **Confidential Cash**: Subscriptions, redemptions, and DVP settlement use DBC as the cash leg.
* **Data Storage**: Fund documents and claim documents are stored encrypted via torrent-ccip.
* **Oracles**: NAV, exchange rates, and interest rates are published on-chain and validated by signature before use in settlement.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cocoon.erigon.tech/components/permissioned-tokens.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.