Permissioned Tokens

Permissioned Tokens is the Cocoon component for issuing and managing regulated on-chain assets. It implements the ERC-3643 T-REX standard 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.

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.

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.

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.

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.

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.

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

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.

Issuance

Queries and Pricing

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.