# Permissions Module

The Permissions Module provides a chain-native authorization and transfer-restriction framework for fungible assets on Uniocean. Rather than treating every token as universally transferable by default, the module allows an asset issuer or authorized controller to attach a dedicated *namespace* to a denom and define fine-grained policies governing minting, sending, receiving, burning, administrative mutation, and contract-hook enforcement.

At runtime, this module is wired directly into the bank transfer pipeline through a global send-restriction hook, allowing permission checks and contract-based policy evaluation to execute synchronously during token transfers.

## Namespace-Centric Authorization Model

Permissions are organized per-denom through a `Namespace` object with the following logical components:

* **Denom Binding:** Each namespace is scoped to exactly one denom.
* **Role Permissions:** A set of named roles, each mapped to a bitmask of allowed actions.
* **Actor Roles:** Address-to-role assignments determining which actors inherit which permissions.
* **Role Managers:** Addresses authorized to grant or revoke specific roles for other actors.
* **Policy Statuses:** Per-action switches that can disable or permanently seal actions at the namespace level.
* **Policy Manager Capabilities:** Per-action capabilities determining which managers may disable or seal each policy.
* **Optional Contract Hooks:** A CosmWasm hook (`WasmHook`) and/or an EVM hook (`EvmHook`) that can apply additional dynamic transfer restrictions.

## Supported Actions

| Action                    | Description                     |
| ------------------------- | ------------------------------- |
| `MINT`                    | Mint new tokens                 |
| `RECEIVE`                 | Receive token transfers         |
| `BURN`                    | Self-burn tokens                |
| `SEND`                    | Send token transfers            |
| `SUPER_BURN`              | Burn from another address       |
| `MODIFY_POLICY_MANAGERS`  | Modify policy manager list      |
| `MODIFY_CONTRACT_HOOK`    | Modify contract hook config     |
| `MODIFY_ROLE_PERMISSIONS` | Modify role permission bitmasks |
| `MODIFY_ROLE_MANAGERS`    | Modify role manager assignments |

A special role named `EVERYONE` is mandatory at namespace creation and acts as the fallback role for addresses that have not been explicitly assigned any other role. The `EVERYONE` role may **not** include administrative capabilities.

## Policy Statuses and Sealing Mechanics

Each action may be governed by a `PolicyStatus` object with two booleans:

* **IsDisabled:** Temporarily disables an action.
* **IsSealed:** Permanently seals the policy against future modification (one-way hardening).

## Transfer Enforcement in the Bank Layer

The module is appended directly to the bank module as a global `SendRestrictionFn`. For each transferred coin, the runtime logic performs the following sequence:

1. Resolve whether the denom has a namespace. If not, the transfer proceeds unmodified.
2. Determine whether module-to-module exemptions apply.
3. Check sender permissions for `SEND`.
4. Check receiver permissions for `RECEIVE`.
5. Execute the optional CosmWasm restriction hook, if configured.
6. Execute the optional EVM restriction hook, if configured.

## Wasm and EVM Hook-Based Restriction Logic

* **CosmWasm Hook:** The module issues a smart query to a configured Wasm contract using a `send_restriction` payload.
* **EVM Hook:** The module executes a view call against a configured EVM contract implementing:

```solidity
isTransferRestricted(address from, address to, Coin coin) returns (bool)
```

Both hook paths are gas-bounded using the module parameter `ContractHookMaxGas`.

## Voucher Fallback and Fail-Soft Delivery

In some consensus-critical flows, the permissions module can reroute blocked transfers into an internal voucher balance for the intended recipient. The receiver may later claim the voucher using `MsgClaimVoucher`.


---

# 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://uniocean.gitbook.io/uniocean-docs/core-platform-modules/permissions-module.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.