Skip to main content Link Menu Expand (external link) Document Search Copy Copied


In Towns, an entitlement is smart contract module that grants permission, such as the permission to add or ban users. Entitlements determine “who can do what” — which users can take specific actions in a space.

Entitlements are a key part of Town’s flexibility and community-centered infrastructure: instead of relying on basic binary token-gating, you can use Towns entitlements to define complex logic that meets your community’s specific access control needs.


A permission is the ability to take an action, such as writing to a channel or banning a user from a channel. Permissions can apply to any Towns activity you want to allow or disallow, and they can be based on any composable attribute. Permissions can even reflect real-world access credentials, such as event tickets and badges. Permissions are strings, allowing for any level of customization desired for gating. By default the contracts define a set of convenience permissions specifically for interacting with a communication protocol.


A role is a group of permissions that reflect a user’s capacities and typical activities, such as Member, Moderator, or Administrator. Roles are “higher” than user-level permissions: for example, moderators can always perform moderator actions, regardless of whether their individual user entitlements include those specific permissions.

Types of role entitlements

Towns sets two types of entitlements at the role level:

entitlement description
UserEntitlement A role that’s explicitly assigned to a user’s address.
TokenEntitlement A role that’s assigned to a user automatically, based on token holdings.

Space contract entitlement functions


The <isEntitled> function is simple yet powerful: it loops through all the entitlements set for a space and returns a definitive answer to the question “Is this user entitled to this permission?”


Gets all of the entitlements for a given space or channel.


Sets an entitlement for a given space or channel.


Adds a role to a given entitlement.


Removes a role from a given entitlement.

Standard Roles and Entitlements

Permissions can be set as any string, but there are a set of default permissions deployed specifically for interacting with a communication protocol.

Default Permissions


Every Town is created with a default Owner Role which contains every one of the Default Permissions. When a Town is minted, the Town NFT is minted and transferred to the creator. Whoever holds the Town’s NFT is automatically given the Owner Role of the Town, giving them complete control over the Town itself.