GuildPass SDK

The official TypeScript SDK for the GuildPass protocol.

Features • Installation • Quick Start • Documentation • Development • Contributing

---

Part of the Adamantine-Guild project — a Web3 membership and token-gated community platform for the open-source ecosystem.

🛡️ About GuildPass

GuildPass is a Web3 membership and access-control protocol designed for token-gated communities, guilds, dashboards, and ecosystem integrations. This SDK provides a production-grade interface for developers to build secure, gated experiences in both Node.js and Browser environments.

✨ Features

• 🛡️ Access Control: Check wallet access for resources and roles with ease.
• 💎 Membership Management: Verify active membership status and user roles.
• 🏗️ Guild Configuration: Fetch metadata and custom configurations for any guild.
• ⚡ Pluggable Caching: Built-in TTL cache with optional custom adapter support (Redis, etc.).
• 🧩 Modular Architecture: Clean service-based design for minimal bundle size.
• 💪 Type Safe: First-class TypeScript support with comprehensive definitions.
• 🌐 Universal: Seamless integration with Node.js, modern browsers, and Edge runtimes.

📦 Installation

# Using pnpm (recommended)
pnpm add @guildpass/sdk

# Using npm
npm install @guildpass/sdk

# Using yarn
yarn add @guildpass/sdk

🚀 Quick Start

Initialize the client and check access in seconds.

import { GuildPassClient } from '@guildpass/sdk';

// 1. Initialize the client
const client = new GuildPassClient({
  apiUrl: 'https://api.guildpass.xyz',
  chainId: 8453, // Base Mainnet
});

// 2. Perform an access check
const result = await client.access.checkAccess({
  walletAddress: '0x1234...5678',
  guildId: 'prime-guild',
  resourceId: 'premium-docs',
});

if (result.hasAccess) {
  console.log('✅ Access Granted');
} else {
  console.log(`❌ Denied: ${result.reason}`);
}

🛠️ Service Modules

The SDK is organized into focused service modules accessible via the main client:

Module	Purpose
client.access	Handle resource gating and role-based access checks.
client.membership	Query wallet membership status and join dates.
client.roles	Retrieve available roles and user assignments.
client.guilds	Fetch guild metadata, themes, and social links.
client.contracts	Resolve chain config and read on-chain GuildPass contract data.

⚙️ Configuration

const client = new GuildPassClient({
  apiUrl: string;           // Base API endpoint
  chainId?: number;         // Default chain (default: 1)
  apiKey?: string;          // Optional API key for restricted access
  validateResponses?: boolean; // Validate response shapes at runtime (default: false)
  cache?: CacheAdapter;         // Optional cache adapter (see Caching section below)
  cacheTtl?: number;            // Default TTL in ms for all cached entries
  rpcUrl?: string;          // Optional RPC provider for on-chain checks
  contractAddress?: string; // Optional default contract address
  chains?: Record<number, { // Optional per-chain RPC/contract overrides
    rpcUrl?: string;
    contractAddress?: string;
  }>;
});

⚡ Caching

Passing a cache adapter enables transparent memoization of all read operations (access checks, membership, roles, guild metadata). The public API of every service method is unchanged — caching is completely invisible to callers.

Built-in: InMemoryCacheAdapter

import { GuildPassClient, InMemoryCacheAdapter } from '@guildpass/sdk';

const client = new GuildPassClient({
  apiUrl: 'https://api.guildpass.xyz',
  cache: new InMemoryCacheAdapter(),
  cacheTtl: 60_000, // entries expire after 60 s
});

// First call hits the network; subsequent calls with the same arguments return
// the cached response instantly.
const guild = await client.guilds.getGuild({ guildId: 'prime-guild' });

Custom adapter (e.g. Redis)

Implement the CacheAdapter interface and pass it in. A minimal example:

import { CacheAdapter } from '@guildpass/sdk';
import { createClient } from 'redis';

const redis = createClient();
await redis.connect();

const redisAdapter: CacheAdapter = {
  async get<T>(key: string): Promise<T | null> {
    const raw = await redis.get(key);
    return raw ? (JSON.parse(raw) as T) : null;
  },
  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
    const opts = ttl ? { PX: ttl } : undefined;
    await redis.set(key, JSON.stringify(value), opts);
  },
  async delete(key: string): Promise<void> {
    await redis.del(key);
  },
  async clear(): Promise<void> {
    await redis.flushDb();
  },
};

For production adapters — including TTL semantics, prefix deletion, error isolation, serialisation expectations, and a full Redis example with deleteByPrefix — see the Cache Adapters Guide.

Cache invalidation

// Evict all entries tied to a specific guild (e.g. after an admin change).
await client.invalidateGuildCache('prime-guild');

// Evict all wallet-scoped entries.
await client.invalidateWalletCache('0x1234...5678');

// Full wipe.
await client.clearCache();

Membership token balances

Configure rpcUrl and contractAddress to query the configured membership token:

const client = new GuildPassClient({
  apiUrl: 'https://api.guildpass.xyz',
  rpcUrl: 'https://mainnet.base.org',
  contractAddress: '0x0000000000000000000000000000000000000000',
});

const balance = await client.contracts.getMembershipTokenBalance({
  walletAddress: '0x1234567890123456789012345678901234567890',
});

The lookup uses an eth_call against balanceOf(address) and returns the raw token balance as a decimal string.

📚 Documentation

For more detailed guides and API references, check out:

• Architecture Overview
• SDK Usage Guide
• Full API Reference
• Integration Guide
• Cache Adapters Guide

🏗️ Development

# Install dependencies
pnpm install

# Build for production (tsup)
pnpm build

# Watch mode for development
pnpm dev

# Run unit tests (watch)
pnpm test

# Run tests once (CI mode)
pnpm test:run

# Lint
pnpm lint

# Format
pnpm format

# Type checking
pnpm typecheck

# Generate TypeDoc API docs
pnpm docs

# Validate package metadata (publint — catches malformed exports, missing files, etc.)
pnpm validate

# Run the same quality gates used by releases
pnpm release:check

🚢 Release process

Releases are automated by the Release GitHub Actions workflow. Maintainers can test the workflow safely with Run workflow by leaving dry_run enabled; tag pushes publish to npm only after all quality gates pass.

Quality gates

The workflow installs dependencies with pnpm install --frozen-lockfile and then runs:

1. pnpm lint
2. pnpm typecheck
3. pnpm test:run
4. pnpm build
5. pnpm test:smoke
6. pnpm docs
7. pnpm validate
8. pnpm pack --pack-destination ./artifacts

Versioning and changelog

Release tags must use the package version prefixed with v, for example v0.1.0 for package version 0.1.0. Before creating a tag, update package.json and add a matching ## [x.y.z] entry to CHANGELOG.md; the workflow fails if the tag and package version do not match or if the changelog entry is missing.

Publishing and provenance

Production publishing runs only for pushed v*.*.* tags. The workflow uses npm publish --provenance --access public, requires the id-token: write permission for npm provenance, and reads the npm automation token from the NPM_TOKEN repository or environment secret. Do not hard-code maintainer tokens in the repository. The workflow is assigned to the npm GitHub environment so maintainers can add environment protection rules before publishing.

🗺️ Roadmap

• On-chain Support: Native integration with viem and ethers.
• Auth: Wallet signature verification (SIWE) helpers.
• React: Official @guildpass/react hooks package.

🤝 Contributing

We welcome contributions from the community! See CONTRIBUTING.md for the full guide.

1. Browse open issues tagged good first issue or help wanted.
2. Comment on the GitHub issue you'd like to work on.
3. Fork the repo, create a feature branch, implement your change, open a PR.

Maintainer contact

• Contact: cerealboxx123@gmail.com

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

Built with ❤️ by the GuildPass team

guildpass.xyz