GuildPass Core

Open infrastructure for programmable membership, access control, governance, contributions, rewards, and Stellar-native communities.

What is GuildPass Core?

GuildPass Core is the backend and domain layer of the GuildPass ecosystem.

GuildPass is designed for communities that need more than a simple list of members. It provides infrastructure for:

membership;
roles;
access control;
governance;
contribution tracking;
rewards;
auditability;
Stellar and Soroban integration.

GuildPass Core contains the logic and services that make those capabilities possible.

A GuildPass-powered application should be able to ask questions such as:

Is this person an active member?
Has their membership expired or been suspended?
What roles do they hold?
Are they allowed to access a protected resource?
What contributions have they made?
What rewards are they eligible for?
What governance rules apply?
How should membership interact with Stellar and Soroban?

GuildPass Core is the system responsible for answering those questions.

For Non-Technical Readers

GuildPass Core can be thought of as the engine behind a community platform.

A community application might show:

member profiles;
private spaces;
contributor badges;
governance proposals;
rewards;
wallet-based membership.

The application itself does not need to contain all the logic for deciding who is allowed to do what.

Instead:

Application
    │
    ▼
GuildPass Core
    │
    ├── Membership
    ├── Roles
    ├── Access decisions
    ├── Governance
    ├── Contributions
    ├── Rewards
    └── Stellar / Soroban

GuildPass Core provides the reusable infrastructure underneath those features.

GuildPass Core V2

The current repository contains GuildPass Core V2, a ground-up rebuild of the original Core implementation.

The previous version had accumulated a large amount of functionality and migration history. V2 was created to establish a cleaner and more maintainable foundation.

The rebuild focuses on:

smaller, well-defined modules;
strict TypeScript;
reproducible database migrations;
deterministic domain logic;
clear separation between business rules and infrastructure;
Stellar-first blockchain support;
Soroban smart contracts;
safer CI and contributor workflows;
independently testable components.

The original implementation remains preserved in Git history and the repository's archived pre-rebuild references.

Current Status

GuildPass Core V2 is under active development.

The current V2 foundation includes:

pnpm workspace configuration;
TypeScript monorepo setup;
shared GuildPass domain types;
Fastify API foundation;
environment configuration;
/health endpoint;
PostgreSQL local infrastructure;
Redis local infrastructure;
CI validation;
contributor automation.

Additional functionality is being added through scoped contributor issues.

Not every feature described in this README should be assumed to be fully implemented yet.

Architecture

GuildPass Core V2 follows a modular monorepo structure.

guildpass-core/
│
├── apps/
│   └── api/
│       └── GuildPass HTTP API
│
├── packages/
│   ├── shared-types/
│   │   └── Shared domain types
│   │
│   ├── policy-engine/
│   │   └── Access decision logic
│   │
│   ├── constitutional-engine/
│   │   └── Community constitutional rules
│   │
│   ├── contribution-engine/
│   │   └── Contribution scoring
│   │
│   ├── governance-engine/
│   │   └── Governance rules and calculations
│   │
│   └── reward-engine/
│       └── Reward and progression logic
│
├── contracts/
│   └── soroban/
│       └── Stellar Soroban contracts
│
├── tests/
│   └── integration/
│
├── docs/
├── logo/
├── docker-compose.yml
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── package.json
├── .env.example
└── README.md

Some modules shown above may still be introduced incrementally as their implementation issues are completed.

Core Concepts

Communities

A community is the main organisational boundary in GuildPass.

A community can define its own:

members;
roles;
governance rules;
resources;
access policies;
contribution models;
rewards.

Membership

Membership represents the relationship between a person or wallet and a GuildPass community.

Current membership states include:

active
expired
suspended

Membership logic is expected to support:

creation;
expiry;
suspension;
restoration;
eligibility checks;
future on-chain representation.

Roles

Roles represent permissions or responsibilities inside a community.

Built-in role concepts include:

admin
member
contributor

GuildPass is also designed to support community-defined roles.

Access Control

GuildPass Core is designed around explicit access decisions.

A decision can return more than a simple boolean.

Example:

interface AccessDecision {
  allowed: boolean;
  code: AccessDecisionCode;
  reasons: string[];
}

Possible decision codes include:

ALLOW
NOT_MEMBER
MEMBERSHIP_EXPIRED
MEMBERSHIP_SUSPENDED
INSUFFICIENT_ROLE
DENY

This makes access behaviour easier to:

test;
audit;
debug;
expose through APIs;
reuse across applications.

Governance

GuildPass governance functionality is intended to provide reusable logic for:

rules;
voting;
quorum;
delegation;
eligibility;
proposal constraints;
constitutional requirements.

Governance calculations should remain deterministic and testable independently of API routes.

Contributions

The contribution system is intended to help communities evaluate meaningful participation.

Examples may include:

contribution scores;
activity metrics;
completed tasks;
participation thresholds;
contributor progression.

Rewards

GuildPass rewards may be derived from:

contribution activity;
participation;
governance outcomes;
community-defined rules.

Potential outcomes include:

badges;
recognition;
role progression;
reward allocations.

Stellar and Soroban

GuildPass Core V2 is Stellar-first.

The current blockchain direction uses:

Stellar accounts;
Soroban smart contracts;
Rust for contract development.

The previous EVM-oriented architecture is not the default direction for V2.

Blockchain logic should remain clearly separated from the rest of the application.

Conceptually:

GuildPass API
      │
      ├──────────────┐
      │              │
      ▼              ▼
PostgreSQL        Soroban
      │           Contracts
      │              │
      └──────┬───────┘
             │
             ▼
       GuildPass State

Technology Stack

Backend

Node.js 24+
TypeScript
Fastify
Zod

Package Management

pnpm
pnpm workspaces

Data

PostgreSQL 15
Prisma
Redis 7

Blockchain

Stellar
Soroban
Rust

Tooling

Docker
Docker Compose
GitHub Actions

Prerequisites

Install:

Git
Node.js 24 or newer
pnpm 11.x
Docker
Docker Compose
Rust and Stellar tooling when working on Soroban contracts

Check Node:

node --version

Check pnpm:

pnpm --version

The repository currently uses:

pnpm 11.16.0

Getting Started

1. Fork the repository

Fork:

Adamantine-guild/guildpass-core

2. Clone your fork

git clone https://github.com/<YOUR_USERNAME>/guildpass-core.git
cd guildpass-core

3. Add the upstream repository

git remote add upstream https://github.com/Adamantine-guild/guildpass-core.git

Verify:

git remote -v

4. Install dependencies

pnpm install

For CI-style reproducibility:

pnpm install --frozen-lockfile

If pnpm asks you to approve expected dependency build scripts:

pnpm approve-builds

Environment Configuration

Create your local environment file:

cp .env.example .env

The local defaults are:

NODE_ENV=development
PORT=3000

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/guildpass
DIRECT_URL=postgresql://postgres:postgres@localhost:5432/guildpass

REDIS_URL=redis://localhost:6379

Do not commit .env.

Start Local Infrastructure

GuildPass Core uses Docker Compose for PostgreSQL and Redis.

Start:

docker compose up -d

Check:

docker compose ps

Expected local services:

PostgreSQL : 5432
Redis      : 6379

Stop:

docker compose down

To remove local volumes as well:

docker compose down -v

Use the volume-removal command carefully because it deletes local database data.

Run the API

Start development mode:

pnpm dev

or:

pnpm --filter @guildpass/api dev

Default API address:

http://localhost:3000

Health Check

The API exposes:

GET /health

Test it:

curl http://localhost:3000/health

Expected response:

{
  "status": "ok",
  "service": "guildpass-core-api"
}

Development Commands

Typecheck

pnpm typecheck

Build

pnpm build

Test

pnpm test

Start development server

pnpm dev

Database

GuildPass Core V2 uses PostgreSQL as its primary relational datastore.

The V2 database approach is designed around:

a coherent Prisma schema;
reproducible migrations;
fresh-database compatibility;
explicit constraints;
predictable relations;
CI migration verification.

The intended development flow is:

install dependencies
        ↓
start PostgreSQL
        ↓
generate Prisma client
        ↓
apply migrations
        ↓
typecheck
        ↓
build
        ↓
test

Database migrations should work against a fresh database without requiring manual repair.

Redis

Redis is used for infrastructure concerns such as caching.

Redis must not become the authoritative source of GuildPass domain state.

The database and relevant domain systems remain the source of truth.

Shared Types

Shared domain contracts live under:

packages/shared-types

The package is exposed internally as:

@guildpass/shared-types

Examples include:

export interface Community {
  id: string;
  name: string;
  slug: string;
  createdAt: Date;
}

and:

export interface AccessDecision {
  allowed: boolean;
  code: AccessDecisionCode;
  reasons: string[];
}

Shared types should remain free of unnecessary infrastructure dependencies.

Design Principles

1. Domain logic should be explicit

Business rules should not be hidden inside:

controllers;
database queries;
route handlers;
middleware.

2. Keep modules independently testable

A policy calculator should be testable without starting a database.

A governance calculation should not require the API server.

A Stellar parser should not require a network request.

3. Prefer deterministic behaviour

Given the same inputs and state, domain logic should return the same result.

4. Keep infrastructure separate from business rules

Fastify, PostgreSQL, Redis, and Soroban are infrastructure.

GuildPass domain behaviour should remain understandable without them.

5. Avoid rebuilding V1 accidentally

Core V2 is intentionally smaller.

Do not recreate old architecture unless there is a specific approved requirement.

6. Migrations must be reproducible

Database migrations must work on a fresh database.

Local database history should never be required for a migration to succeed.

7. Tests are part of the implementation

New logic should include relevant tests.

Bug fixes should preferably include regression tests.

Continuous Integration

GuildPass Core uses GitHub Actions to validate pull requests.

The Core pipeline performs:

Install dependencies
        ↓
Typecheck
        ↓
Build
        ↓
Test

The required job is:

Build and Test

Pull requests are not eligible for automatic merging until this check passes.

PR Automation

GuildPass repositories use central PR automation maintained by Adamantine Guild.

The automation can:

inspect CI checks;
detect pending workflows;
detect failed checks;
detect merge conflicts;
comment on blocked pull requests;
approve eligible external-contributor workflows;
merge eligible pull requests.

For guildpass-core, the required CI check must exist and succeed before auto-merge is allowed.

The flow is:

Contributor opens PR
        │
        ├──────────────┐
        │              │
        ▼              ▼
     Core CI      PR Automation
        │              │
        ▼              │
  Build and Test       │
        │              │
        └──────┬───────┘
               │
               ▼
       Evaluate PR state
               │
      ┌────────┼────────┐
      │        │        │
    Failed   Pending   Passed
      │        │        │
      ▼        ▼        ▼
    Block     Wait     Merge

Contributing

Contributions are welcome.

Before contributing, read:

CONTRIBUTING.md
CODE_OF_CONDUCT.md
SECURITY.md

Contributor Workflow

Sync your fork

git checkout main
git fetch upstream
git pull upstream main
git push origin main

Create a feature branch

Do not work directly on main.

Example:

git checkout -b feat/stellar-address-validation

Recommended prefixes:

feat/
fix/
test/
docs/
refactor/
chore/
ci/

Work on one issue

Contributor issues are intentionally scoped so multiple contributors can work concurrently.

Do not make your issue depend on another open issue unless the issue explicitly says so.

Validate your work

Before opening a PR:

pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
pnpm test

Open a pull request

Reference the issue:

Closes #123

Your PR should explain:

what changed;
why;
how it works;
what tests were added;
any important design decisions.

Contributor Issues

GuildPass Core contributor issues may include labels such as:

Third Campaign
advanced
expert
backend
database
stellar
soroban
policy
governance
membership
roles
testing
security
performance

Issues should be treated as the source of truth for implementation scope.

Avoid expanding a contribution far beyond the issue acceptance criteria.

Commit Messages

Use clear scoped commit messages.

Recommended format:

type(scope): description

Examples:

feat(policy): add deterministic rule evaluator
feat(stellar): validate Stellar account IDs
fix(api): reject malformed request metadata
test(governance): cover quorum boundary cases
docs(core): update contributor setup

Security

Never commit:

private keys;
Stellar secret keys;
seed phrases;
API tokens;
database passwords;
production credentials;
.env files containing secrets.

Security vulnerabilities should not be disclosed through public GitHub issues.

Follow:

SECURITY.md

for responsible disclosure instructions.

Repository History

GuildPass Core V2 is a rebuild, not a deletion of the original project.

The pre-rebuild implementation remains available through Git history and preserved archive references.

Contributors should build against the current main branch and current V2 architecture unless an issue explicitly says otherwise.

Documentation

Architecture and implementation documentation belongs under:

docs/

Documentation should be updated when a change materially affects:

architecture;
APIs;
data models;
contributor setup;
CI;
Stellar integration;
Soroban contracts.

Licence

GuildPass Core is distributed under the MIT License.

See:

LICENSE

for the complete terms.

Adamantine Guild

GuildPass is developed as part of the Adamantine Guild open-source ecosystem.

GuildPass Core

https://github.com/Adamantine-guild/guildpass-core

Adamantine Guild

https://github.com/Adamantine-guild

GuildPass Core
Infrastructure for programmable communities.

Name		Name	Last commit message	Last commit date
.github		.github
apps/api		apps/api
docs		docs
logo		logo
packages		packages
.env.example		.env.example
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

GuildPass Core

What is GuildPass Core?

For Non-Technical Readers

GuildPass Core V2

Current Status

Architecture

Core Concepts

Communities

Membership

Roles

Access Control

Governance

Contributions

Rewards

Stellar and Soroban

Technology Stack

Backend

Package Management

Data

Blockchain

Tooling

Prerequisites

Getting Started

1. Fork the repository

2. Clone your fork

3. Add the upstream repository

4. Install dependencies

Environment Configuration

Start Local Infrastructure

Run the API

Health Check

Development Commands

Typecheck

Build

Test

Start development server

Database

Redis

Shared Types

Design Principles

1. Domain logic should be explicit

2. Keep modules independently testable

3. Prefer deterministic behaviour

4. Keep infrastructure separate from business rules

5. Avoid rebuilding V1 accidentally

6. Migrations must be reproducible

7. Tests are part of the implementation

Continuous Integration

PR Automation

Contributing

Contributor Workflow

Sync your fork

Create a feature branch

Work on one issue

Validate your work

Open a pull request

Contributor Issues

Commit Messages

Security

Repository History

Documentation

Licence

Adamantine Guild

GuildPass Core

Adamantine Guild

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages