Guild SDK

Beyond simple gating, the SDK enables dynamic role management based on evolving on-chain status. This is used for:

• Automated reward distribution: Assign roles to users who complete specific tasks (e.g., minting an NFT, providing liquidity) to qualify for airdrops.
• Progressive membership: Update a user's role tier as they accumulate more points or complete quests, often visualized as a loyalty program.
• Conditional logic: Combine multiple requirements (e.g., "Hold NFT X AND have transaction volume > 1 ETH") to create complex role hierarchies.

The SDK is designed for seamless integration into popular development environments and platforms.

• Frontend Frameworks: Pre-built hooks and components for React and Next.js to quickly embed gating logic.
• Discord Bots: The underlying logic powers the Guild.xyz Discord bot, allowing community managers to set up token-gated channels without writing code.
• Backend Services: Server-side functions to validate member status for API endpoints or to batch-check qualifications for thousands of users.

Developer DAO uses the Guild SDK to manage its membership and gated resources. The implementation includes:

• Token-Gated Discord: Access to the main community server requires holding a $CODE NFT.
• Specialized Channels: Additional channels are gated for specific NFT traits or sub-DAO membership, creating sub-communities.
• Website Integration: The official website uses the SDK to display gated content and verify membership status for event registrations. This showcases the SDK's ability to unify access control across multiple platforms.

The Guild SDK can be composed with other credential protocols to create richer membership graphs. For instance:

• Ethereum Attestation Service (EAS): Use off-chain attestations (e.g., proof of attendance) as a requirement for a Guild role.
• POAP: Require ownership of a specific POAP to gain access, leveraging proof of participation in an event.
• Cross-Chain: While initially Ethereum-focused, the logic can be extended to verify holdings on other EVM-compatible chains through indexers, enabling multi-chain membership systems.

A typical integration follows this pattern:

1. Define Requirements: Use the Guild API or interface to create a Guild with specific role criteria (e.g., token contract address, minimum balance).
2. Query User Status: In the application, call guild.isMember(userAddress, roleId) or use the React hook useIsMember.
3. Handle Response: The SDK returns a boolean and, optionally, detailed metadata about why a user does/doesn't qualify.
4. Gate UI/Logic: Use the response to render components, redirect users, or unlock features. The entire flow is permissionless and does not require users to hold a platform-specific token.

The SDK's core security model is built on Role-Based Access Control (RBAC), where smart contracts or off-chain services grant permissions based on a user's Guild membership and role. Developers must ensure:

• Permission scoping: Roles should grant the minimum necessary privileges for a specific function.
• Role validation: Always verify role assignments on-chain or via signed messages to prevent spoofing.
• Revocation logic: Implement clear processes for removing roles when a user leaves a Guild or their status changes.

A primary trust assumption is that Guild membership signifies a unique human or entity, resisting Sybil attacks. The SDK often integrates with Proof-of-Personhood (PoP) providers (e.g., Worldcoin, BrightID) or requires soulbound tokens (SBTs). Key considerations:

• Provider trust: The security of the Guild depends on the Sybil-resistance of the underlying identity layer.
• Data privacy: Understand what personal data the PoP provider collects and shares.
• Fallback mechanisms: Plan for scenarios where the identity provider is unavailable or compromised.

When connecting Guild data to smart contracts, several attack vectors emerge:

• Front-running role assignments: Malicious actors could exploit transaction ordering to gain privileges.
• Oracle reliability: Contracts relying on off-chain Guild data via oracles must trust the oracle's liveness and correctness.
• Reentrancy & logic flaws: Custom role-gated functions must follow secure development patterns to prevent exploits like reentrancy attacks, even for privileged users.

The SDK fetches membership and role data from various sources (on-chain registries, subgraphs, API servers). Ensuring data integrity is critical:

• On-chain is authoritative: Favor on-chain checks (e.g., reading from a contract) over off-chain APIs for critical permissions.
• Signature verification: For off-chain data, require cryptographically signed messages (EIP-712) from a trusted signer to prove validity.
• Cache poisoning: Implement proper cache invalidation to prevent stale or malicious data from being served to applications.

Guild administrators hold keys that control membership and roles, creating a central point of failure.

• Multi-signature wallets: Admin actions, especially for high-value Guilds, should require multi-sig approval.
• Key rotation: Establish procedures for regularly rotating admin keys and updating contract authorities.
• Social recovery: Consider implementing social recovery or timelock mechanisms to regain control if admin keys are lost.

While proving membership, users should not leak unnecessary personal data. The SDK should enable:

• Selective disclosure: Use zero-knowledge proofs (ZKPs) where possible to prove membership or role without revealing the specific Guild or identity.
• On-chain privacy: Be aware that membership NFTs or SBTs are public; consider using stealth addresses or privacy-preserving layers if anonymity is required.
• GDPR/CCPA compliance: For applications collecting user data, ensure Guild integration practices align with relevant data protection regulations.

A security model where access to resources is granted based on a user's assigned role within a guild, rather than individual identity. The Guild SDK implements RBAC on-chain, allowing developers to programmatically define permissions for actions like treasury management or content gating.

• Core Mechanism: Roles are represented as Soulbound Tokens (SBTs) or NFTs.
• Example: A 'Moderator' role token grants the ability to approve new member applications.
• Flexibility: Permissions can be updated dynamically by the guild's governance.

Non-transferable, non-financialized tokens that represent a user's identity, affiliations, and achievements. In the Guild SDK, SBTs are the primary vehicle for issuing on-chain credentials that prove membership, roles, and reputation within a guild.

• Key Property: SBTs are bound to a wallet address and cannot be sold or transferred.
• Use Case: Issuing a 'Contributor Level 5' SBT after a user completes specific tasks.
• Contrast with NFTs: Unlike NFTs, SBTs lack a liquid market, emphasizing social capital over monetary value.

The mechanism by which guilds automatically distribute tokens, NFTs, or access based on predefined, verifiable on-chain actions. The Guild SDK provides modules to set up these incentive structures without custom smart contract development.

• Automation: Rewards are triggered by events like transaction completion or role attainment.
• Examples: Distributing a governance token for attending 10 community calls, or granting an NFT for a top contributor.
• Composability: Can integrate with oracles and data feeds to verify real-world tasks.

A quantifiable, immutable record of a user's contributions and behavior within a guild, stored directly on the blockchain. The Guild SDK enables the creation of reputation graphs by aggregating data from SBTs, transaction history, and governance participation.

• Data Sources: Vote history, completed bounties, peer attestations.
• Utility: Used for weighted voting, trustless delegation, and automated role promotion.
• Portability: Reputation is tied to a user's wallet, allowing it to be recognized across different applications in the ecosystem.

A user experience pattern where a third party (a relayer or the guild treasury) pays the network gas fees for a user's transaction. The Guild SDK often incorporates this to lower the barrier to entry for guild interactions.

• How it works: Users sign a message, which is then submitted and paid for by a relay server.
• Benefit: Allows members to claim rewards or vote without holding the native blockchain token.
• Standard: Often implemented via EIP-2771 (Meta Transactions) or ERC-4337 (Account Abstraction).

Pre-built, audited smart contract components that provide specific guild functionalities, such as voting, treasury management, or quest systems. The Guild SDK is typically a collection of these modules, allowing developers to mix and match features.

• Examples: A 'Quadratic Voting' module, a 'Multi-sig Treasury' module, a 'Quest Engine' module.
• Advantage: Accelerates development and enhances security through the use of battle-tested code.
• Ecosystem: Enables standardization, so guilds built with the same SDK can interoperate more easily.