Roles - Towns

Bots can create and manage roles in Towns spaces. Roles control what users can do - from reading messages to banning members. You can also create token-gated roles that require users to hold specific NFTs or tokens.

Role management requires your bot to have admin permissions in the space. All role operations are onchain transactions that require gas.

Creating Roles

import { Permission } from '@towns-protocol/web3'

const { roleId } = await bot.createRole(spaceId, {
  name: 'Moderator',
  permissions: [Permission.Read, Permission.Write, Permission.ModifyBanning],
  users: ['0x...', '0x...'] // optional: only assign to specific users
})

CreateRoleParams

Parameter	Type	Description
`name`	`string`	Display name for the role
`permissions`	`Permission[]`	Array of permissions to grant
`users`	`string[]`	(Optional) User addresses to assign the role
`rule`	`Operation`	(Optional) Token-gating rule (see below)

Token-Gated Roles

Create roles that require users to hold specific tokens using the Rules API:

import { Permission, Rules } from '@towns-protocol/web3'

const townsHolderRule = Rules.checkErc20({
  chainId: 8453n,
  contractAddress: '0x00000000A22C618fd6b4D7E9A335C4B96B189a38',
  threshold: 1n
})

const role = await bot.createRole(spaceId, {
  name: 'Towns Holder',
  permissions: [Permission.Read, Permission.Write],
  rule: townsHolderRule
})

You can apply the role to a channel by calling bot.addRoleToChannel(channelId, roleId). This will gate the channel to only users who hold the required tokens.

await bot.addRoleToChannel(channelId, role.roleId)

Available Rule Types

Rule	Description
`Rules.checkErc721({ chainId, contractAddress, threshold })`	Check ERC721 NFT balance
`Rules.checkErc20({ chainId, contractAddress, threshold })`	Check ERC20 token balance
`Rules.checkErc1155({ chainId, contractAddress, tokenId, threshold })`	Check ERC1155 balance for a specific token ID
`Rules.checkEthBalance({ threshold })`	Check native ETH balance
`Rules.checkIsEntitled({ chainId, contractAddress, params? })`	Check cross-chain entitlement

Combining Rules

import { Rules } from '@towns-protocol/web3'
import { parseEther } from 'viem'

// AND: both conditions must pass
const andRule = Rules.and(
  Rules.checkErc721({ chainId: 8453n, contractAddress: nftContract, threshold: 1n }),
  Rules.checkErc20({ chainId: 8453n, contractAddress: tokenContract, threshold: parseEther('100') })
)

// OR: either condition must pass
const orRule = Rules.or(
  Rules.checkErc721({ chainId: 8453n, contractAddress: nftContract, threshold: 1n }),
  Rules.checkEthBalance({ threshold: parseEther('0.1') })
)

// All rules must pass. Does not allow failure. Can be nested.
const allRule = Rules.every(ruleA, ruleB, ruleC)
// Any rule can pass, allowing failure. Can be nested.
const anyRule = Rules.some(ruleA, ruleB, ruleC)

Managing Roles

// Get all roles in a space
// Returns: Array<{ id, name, permissions, disabled }>
const roles = await bot.getAllRoles(spaceId)

// Get full details of a specific role
// Returns: { id, name, permissions, users, ruleData, disabled } | null
const role = await bot.getRole(spaceId, roleId)

// Update a role. Fields are optional and will only update the fields that are provided.
// Returns: Transaction hash
await bot.updateRole(spaceId, roleId, {
  name: 'New Name',
  users: ['0x...', '0x...'],
  permissions: [Permission.Read, Permission.Write]
})

// Delete a role
// Returns: Transaction hash
await bot.deleteRole(spaceId, roleId)

// Add role to a channel, applying the role's rules to the channel
// Returns: Transaction hash
await bot.addRoleToChannel(channelId, roleId)

Available Permissions

See Roles & Entitlements for the full list of available permissions.

​Creating Roles

​CreateRoleParams

​Token-Gated Roles

​Available Rule Types

​Combining Rules

​Managing Roles

​Available Permissions

Creating Roles

CreateRoleParams

Token-Gated Roles

Available Rule Types

Combining Rules

Managing Roles

Available Permissions