🔏GuildSafe - Discord Version

Token-gating and decentralized governance all-in-one - with zero community risk.

GuildSafe Discord: User Manual

Welcome to GuildSafe! This powerful tool allows you to automatically assign roles to users based on their token and NFT holdings, creating exclusive, verifiable communities.

This manual is divided into two sections:

1. Server Administrator Guide: For setting up and managing the bot.

2. Server User Guide: For members who want to verify their wallets and get roles.

1. Server Administrator Guide

This guide will walk you through setting up and managing the bot for your server.

Initial Setup: 4 Essential Steps

Before users can get roles, you need to configure the bot.

Step 1: Invite the Bot

• Use the bot's unique invite link to add it to your Discord server.

• Ensure the bot has the necessary permissions to read messages, manage roles, and see channels.

Step 2: Create Roles in Discord The bot manages existing roles; it does not create them. Go to your Server Settings > Roles > Create Role to create the roles you want to automate (e.g., "Whale," "Collector," "Pug Holder").

Step 3: Set the Primary Token or NFT Collection All role assignments are based on a primary token or NFT collection. You must set one of these first.

• To set a token:

  /set_token token_address:<your_token_address> decimals:<decimals>
  

  Example: /set_token token_address:0x123...abc decimals:6

• To set an NFT Collection:

  /set_nft collection_id:<your_collection_id>
  

  This collection ID will be used for all NFT-based roles (total count, traits, and categories).

Step 4: Configure Role Requirements Now, tell the bot which roles to assign and what the requirements are.

Configuring Roles

Here’s how to set up different types of role requirements.

A. Total Holdings Roles

Assign a role based on the total amount of a token or the total number of NFTs a user owns.

• Command: /add_role

• Example (Token): To give the "Whale" role to users with 10,000+ tokens:

  /add_role role:@Whale threshold_type:token threshold:10000
  

• Example (NFT): To give the "Collector" role to users with 5+ NFTs from the primary collection:

  /add_role role:@Collector threshold_type:nft threshold:5
  

B. Specific NFT Trait Roles

Assign a role based on owning an NFT with a specific trait.

• Command: /add_trait_role

• Important: The trait_name (category) and trait_value must be an exact, case-sensitive match to the NFT's metadata. Check a marketplace like Tradeport to confirm the correct syntax.

• Example: To give the "Ika Wearer" role to users owning an NFT with the "Hat" trait of "Ika Hat":

  /add_trait_role role:@Ika Wearer trait_name:Hat trait_value:Ika Hat threshold:1
  

C. NFT Trait Category Roles

Assign a role based on owning an NFT that has any trait within a specific category.

• Command: /add_category_role

• Example: To give the "Hat Enthusiast" role to users owning an NFT with any kind of "Hat":

  /add_category_role role:@Hat Enthusiast trait_name:Hat threshold:1
  

Managing the Bot

• View Configuration: See all current settings and role requirements.

  /server_info
  

• Manually Update All Roles: Force the bot to immediately re-check every registered user's wallet and update their roles. This bypasses the cache to fetch fresh on-chain data.

  /force_check
  

• Remove a Role Configuration: If you make a mistake or want to remove a role requirement, use this command.

  /remove_role role:<role_to_remove>
  

  If you get an error that the role is "not configured," but you believe it should be, it may be because the role was deleted and re-created in Discord. The error message will show you a list of currently configured roles to help you troubleshoot.

2. Server User Guide

This guide explains how to verify your wallet to get your roles in the server.

How to Get Your Roles

The process is simple and involves three steps: Register, Verify, and Check.

Step 1: Check the Server Requirements First, see which tokens or NFTs you need to hold to be eligible for roles.

/server_info

Step 2: Register Your Wallet Tell the bot which wallet address you want to use.

/register wallet_address:<your_wallet_address>

The bot will confirm that your wallet has been registered and is now pending verification.

Step 3: Verify Wallet Ownership To prove you own the wallet, you must complete a one-time verification.

1. Send a small amount of SUI (0.01 or more) from your registered wallet to the server's donation wallet. The bot will show you the address after you register. Any additional amount is an optional donation.

2. Once the transaction is complete, run the verify command.

   /verify
   

   You don't need to enter your address again! The bot is smart enough to find your pending wallet automatically. If you have multiple wallets pending, it will ask you to specify one.

After a few moments, the bot will confirm the transaction and assign your roles. Welcome to the community!

Managing Your Wallets and Status

• Check Your Status: To see your verified wallets, current holdings, and assigned roles at any time, use:

  /check
  

  This command forces a fresh API call, so it's a great way to update your roles if you've recently bought or sold assets.

• See All Wallet Statuses: To see which of your registered wallets are verified or still pending, use:

  /status
  

• Remove a Wallet: If you no longer wish to use a wallet, you can remove it.

  /remove_wallet wallet_address:<wallet_to_remove>