Entitlements

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.

Permissions

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.

Roles

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:

Space contract entitlement functions

<isEntitled>

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?”

<getEntitlements>

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

<setEntitlement>

Sets an entitlement for a given space or channel.

<addRoleToEntitlement>

Adds a role to a given entitlement.

<removeRoleFromEntitlement>

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

Read
Write
Invite
Redact
Ban
Ping
PinMessage
ModifyChannelPermissions
ModifyProfile
Owner
AddRemoveChannels
ModifySpacePermissions
ModifyChannelDefaults

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.