Whitelabel Communities Registration Flow
How to implement communities registration on your application with Clusters API v1
For projects that want to deploy a registration page quickly, we provide a simple settings panel where you configure some basic settings and be on your way. More information on that here.
For projects that want to implement the community name registration directly into their app, this guide's for you!
What's the Difference?
If you deploy a community name registration page through our settings panel, we'll host the page where you redirect users to when they need/want to claim a community name. In this flow, users register community names by signing a message.
If you implement the community name registration into your hosted app, the flow requires the Cluster owner's Authentication Key to claim a name on behalf of the user.
This simply means the owner's wallet needs to generate a secret key and manage it in your application.
The below guide walks through a NextJS app that enables users to register a name in a Clusters community, using the Clusters API v1 - Communities. The guide uses direct HTTP calls only, making it easy to extend or port to other stacks.
We will reference the claim-community-cluster-demo repo.
Prerequisites
Register a Cluster through our GUI at https://clusters.xyz/register, or programmatically through API v1 - Registration.
Enabling the communities feature on your Clusters requires manual activation. Please contact us to have it enabled for you.
Get the Authentication Key of the owner (the wallet used to register the Cluster).
Authenticate Owner
The owner's Authentication Key is required to register a community name on behalf of a user's wallet address. You only need to generate this secret key once, and can re-use it. This token is used to register a name on behalf of a user's wallet address.
NOTE: The secret Authentication key should only be used server-side to register a name on behalf of the user. Never expose this token client-side.
To generate one quickly, a function called getAuthKey
has been included in the useAuthKey
hook in the claim-community-cluster-demo repo for your convenience.
The following endpoints are in API v1 - Authentication:
Get Signing Message
GET /v1/auth/message
Returns a
message
and asigningDate
Sign the
message
with the owner's wallet
Response
Get Authentication Key
POST /v1/auth/token
Send in body, the
signature
,signingDate
,wallet
as owner's wallet, andtype
as "evm"Save this token, you will need it every time to register a name on behalf of a user
Response
Endpoints Used in Registration Process
GET v1/names/owner/address/:address
Check if a wallet address is part of your Clusters community
Returns all Clusters and community names registered to a single wallet address
Response
GET /v1/names/community/:clusterName/check/:name
Check the availability of a community name before calling the register endpoint.
Response
POST /v1/names/community/:clusterName/register
This call should only be made from your server because the header includes the
AUTHKEY
, which you generated by authenticating the owner's wallet.The body of the call includes the user's desired community name and their associated wallet address.
After a user registers a community name, it cannot be removed and the name cannot be edited. We recommend adding reCAPTCHA verification to register a name.
Response
How it Comes Together in the Demo repo
Below is a breakdown of how claim-community-cluster-demo app uses the Cluster API v1 to create the flow for a user to claim a community name.
Fetch Community Name
When user connects wallet, wagmi useAccount
hook defines address
of connected wallet, triggering tanstack useQuery
hook to call the Get Names by Owner endpoint.
Look for whether this address already has a registered to your Clusters community as the response can contain many unrelated entries (e.g. other communities or personally owned Clusters).
The root of the application reacts to the returned loading state or clusterName
from the useCommunityNameQuery
hook.
Claiming Community Name
When a user types their desired community name, the useCommunityNameAvailability
hook triggers a debounced check for its availability via call to Check Community Name Availability endpoint, after the user pauses typing.
The ClaimModal
component uses the hook's returned state to update UI.
When user triggers claimName
function from useCommunityNameClaim
hook, it communicates with the api/cluster/register_community_name/route.ts
NextJS API route to call Register a Community Name endpoint.
If successful, useCommunityNameQuery
hook will trigger a refetch and the updated community name will display on the UI. Your user is now a bona-fide community member!
Last updated