Contributing to CrowdPass

Thank you for your interest in contributing to CrowdPass! We welcome contributions from the community and are excited to have you join us in building the future of decentralized event ticketing.

This document provides guidelines and instructions for contributing to the project.

Code of Conduct
Getting Started
Development Environment Setup
Project Structure
Development Workflow
Code Style and Formatting
Branch Naming Conventions
Commit Message Guidelines
Pull Request Process
Issue Reporting Guidelines
Testing Guidelines
Getting Help

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please be respectful, constructive, and professional in all interactions.

Getting Started

Fork the repository to your GitHub account

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/tokenbound_impl.git
cd tokenbound_impl

Add the upstream remote:

git remote add upstream https://github.com/crowdpass-live/tokenbound_impl.git

Keep your fork synchronized:

git fetch upstream
git checkout main
git merge upstream/main

Development Environment Setup

CrowdPass consists of smart contracts (Rust/Soroban) and frontend clients (React/Vite and Next.js). Follow these steps to set up your development environment:

Prerequisites

Node.js: v18 or higher
npm: v9 or higher
Rust: Latest stable version
Soroban CLI: Latest version
Git: Latest version

1. Install Rust and Cargo

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Verify installation:

rustc --version
cargo --version

2. Install Soroban CLI

cargo install --locked soroban-cli --features opt

Verify installation:

soroban --version

3. Configure Soroban for Stellar Testnet

# Add testnet network
soroban network add \
  --global testnet \
  --rpc-url https://soroban-testnet.stellar.org:443 \
  --network-passphrase "Test SDF Network ; September 2015"

# Create identity for testing
soroban keys generate --global alice --network testnet

4. Install Node.js Dependencies

For the React/Vite Client:

cd client
npm install

For the Next.js Client:

cd tokenbound-client
npm install

For the Soroban Client:

cd soroban-client
npm install

5. Build Smart Contracts

cd soroban-contract
cargo build --target wasm32-unknown-unknown --release

6. Run Development Servers

React/Vite Client:

cd client
npm run dev

Access at http://localhost:5173

Next.js Client:

cd tokenbound-client
npm run dev

Access at http://localhost:3000

Project Structure

tokenbound_impl/
├── client/                    # React/Vite frontend
│   ├── src/
│   ├── public/
│   └── package.json
├── tokenbound-client/         # Next.js frontend
│   ├── src/
│   └── package.json
├── soroban-client/           # JavaScript SDK for Soroban interaction
│   └── package.json
├── soroban-contract/         # Soroban smart contracts
│   ├── contracts/
│   │   ├── event_manager/    # Event creation and management
│   │   ├── ticket_nft/       # NFT ticket implementation
│   │   ├── ticket_factory/   # Ticket minting logic
│   │   ├── tba_account/      # Token-bound account implementation
│   │   └── tba_registry/     # Registry for TBA mappings
│   └── Cargo.toml
├── token_bound/              # Token-bound utilities
├── .github/                  # GitHub configuration
│   ├── ISSUE_TEMPLATE/
│   └── workflows/
├── README.md
└── CONTRIBUTING.md

Development Workflow

Create a new branch for your work (see Branch Naming Conventions)
Make your changes following our code style guidelines
Test your changes thoroughly
Commit your changes with descriptive commit messages
Push to your fork and create a pull request
Address review feedback promptly and professionally

Code Style and Formatting

Rust/Soroban Contracts

Use rustfmt for consistent formatting:
```
cargo fmt --all
```

Use clippy for linting:

cargo clippy --all-targets --all-features -- -D warnings

Follow Rust naming conventions:
- snake_case for functions, variables, and modules
- PascalCase for types and traits
- SCREAMING_SNAKE_CASE for constants
Document public APIs with doc comments (///)
Keep functions focused and under 50 lines when possible
Use descriptive variable names - avoid single-letter variables except for iterators

JavaScript/TypeScript (Frontend)

Use ESLint for linting:
```
npm run lint
```
Follow the project's ESLint configuration (already set up in package.json)
Use modern ES6+ syntax: arrow functions, destructuring, async/await
Component naming:
- PascalCase for React components
- camelCase for functions and variables
File naming:
- PascalCase for component files: EventCard.jsx
- camelCase for utility files: formatDate.js
Use functional components with hooks (no class components)
Keep components small and focused on a single responsibility

General Guidelines

Write clear, self-documenting code
Add comments for complex logic - explain the "why", not the "what"
Keep lines under 100 characters when possible
Use meaningful commit messages (see Commit Message Guidelines)
No console.log statements in production code (use proper logging)
Handle errors gracefully with try-catch blocks

Branch Naming Conventions

Use descriptive branch names that indicate the type and scope of your work:

Format

<type>/<issue-number>-<short-description>

Types

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation updates
refactor/ - Code refactoring without functional changes
test/ - Adding or updating tests
chore/ - Maintenance tasks, dependency updates

Examples

feature/123-add-resale-functionality
fix/456-ticket-transfer-bug
docs/789-update-api-documentation
refactor/321-optimize-contract-storage
test/654-add-integration-tests
chore/987-upgrade-soroban-sdk

Creating a Branch

git checkout -b feature/123-add-resale-functionality

Commit Message Guidelines

Write clear, concise commit messages that explain what changed and why.

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, no functional changes)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples

Simple commit:

feat: add ticket resale functionality

Commit with scope:

fix(event_manager): correct refund calculation logic

Commit with body and footer:

feat(ticket_nft): implement token-bound account support

- Add TBA initialization during minting
- Integrate with tba_registry contract
- Update metadata storage structure

Fixes #123

Guidelines

Use imperative mood: "add" not "added", "fix" not "fixed"
First line under 50 characters: Keep subject line concise
Reference issues: Use Fixes #123 or Closes #456 in footer
Explain the "why": Body should provide context, not just repeat the code
One logical change per commit: Keep commits focused and atomic

Pull Request Process

Before Submitting

Ensure all tests pass:

# Run Rust tests
cd soroban-contract
cargo test

# Run frontend tests
cd client
npm test

Run linters and formatters:

# Rust
cargo fmt --all
cargo clippy --all-targets --all-features

# JavaScript
npm run lint

Update documentation if your changes affect usage or APIs

Rebase on latest main:

git fetch upstream
git rebase upstream/main

Submitting a Pull Request

Push your branch to your fork:

git push origin feature/123-your-feature

Open a Pull Request on GitHub with:
- Clear title following commit message conventions
- Description explaining:
  - What changes were made
  - Why they were made
  - How to test them
  - Related issues (use Fixes #123 to auto-close issues)
- Screenshots or GIFs for UI changes
- Testing instructions for reviewers

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Fixes #123

## How Has This Been Tested?
Describe testing approach

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests pass
- [ ] No new warnings introduced

Review Process

Be patient: Maintainers will review your PR as soon as possible
Be responsive: Address feedback promptly
Be professional: Keep discussions respective and constructive
Be collaborative: Work with reviewers to improve your contribution

After Approval

Maintainers will merge your PR

Delete your branch (optional):

git branch -d feature/123-your-feature
git push origin --delete feature/123-your-feature

Issue Reporting Guidelines

Before Creating an Issue

Search existing issues to avoid duplicates
Check the documentation - your question may already be answered
Try the latest version - the issue may already be fixed

Creating an Issue

Use the appropriate issue template:

Bug Report

**Describe the bug**
Clear and concise description of the bug

**To Reproduce**
Steps to reproduce:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen

**Screenshots**
If applicable, add screenshots

**Environment:**
- OS: [e.g., macOS, Ubuntu]
- Browser: [e.g., Chrome, Firefox]
- Version: [e.g., 1.0.0]

**Additional context**
Any other relevant information

Feature Request

**Is your feature request related to a problem?**
Clear description of the problem

**Describe the solution you'd like**
Clear description of what you want to happen

**Describe alternatives you've considered**
Alternative solutions or features

**Additional context**
Mockups, examples, or other context

Issue Labels

Maintainers will apply appropriate labels:

bug - Something isn't working
enhancement - New feature or request
documentation - Documentation improvements
good first issue - Good for newcomers
help wanted - Extra attention needed
priority:high - Critical issues

Testing Guidelines

Rust/Soroban Contracts

Write unit tests for all contract functions:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_create_event() {
        // Test implementation
    }
}

Run tests:

cd soroban-contract
cargo test

JavaScript/Frontend

Write tests using the project's testing framework:

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import EventCard from './EventCard';

describe('EventCard', () => {
  it('renders event title', () => {
    render(<EventCard title="Test Event" />);
    expect(screen.getByText('Test Event')).toBeInTheDocument();
  });
});

Integration Testing

Test contract interactions:

# Deploy to testnet and test end-to-end flows
soroban contract invoke \
  --id CONTRACT_ID \
  --network testnet \
  -- create_event --params ...

Getting Help

Discord: Join our community server (link in README)
GitHub Discussions: Ask questions and share ideas
GitHub Issues: Report bugs or request features
Email: support@crowdpass.live

Recognition

Contributors will be recognized in:

The project README
Release notes
Our community channels

Thank you for contributing to CrowdPass! Together we're building the future of event ticketing. 🎫✨

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to CrowdPass

Table of Contents

Code of Conduct

Getting Started

Development Environment Setup

Prerequisites

1. Install Rust and Cargo

2. Install Soroban CLI

3. Configure Soroban for Stellar Testnet

4. Install Node.js Dependencies

For the React/Vite Client:

For the Next.js Client:

For the Soroban Client:

5. Build Smart Contracts

6. Run Development Servers

React/Vite Client:

Next.js Client:

Project Structure

Development Workflow

Code Style and Formatting

Rust/Soroban Contracts

JavaScript/TypeScript (Frontend)

General Guidelines

Branch Naming Conventions

Format

Types

Examples

Creating a Branch

Commit Message Guidelines

Format

Types

Examples

Guidelines

Pull Request Process

Before Submitting

Submitting a Pull Request

PR Template

Review Process

After Approval

Issue Reporting Guidelines

Before Creating an Issue

Creating an Issue

Bug Report

Feature Request

Issue Labels

Testing Guidelines

Rust/Soroban Contracts

JavaScript/Frontend

Integration Testing

Getting Help

Recognition