> For the complete documentation index, see [llms.txt](https://docs.uniocean.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uniocean.io/protocol-and-infrastructure/protocol/core-modules/permissions-module.md).

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