Skip to main content

Contributing to tari.js 🤝

Welcome, builder! We're thrilled you want to contribute to tari.js. Whether you're fixing bugs, adding features, improving docs, or sharing ideas — every contribution makes the Tari ecosystem stronger.

We welcome contributions to tari.js! This guide will help you get started with contributing to the project, whether you're fixing bugs, adding features, improving documentation, or helping with testing.

🌟 Ways to Contribute​

🛠️ Code Contributions​

  • 🐛 Fix bugs — Help resolve issues and improve stability
  • ✨ Add features — Implement new functionality and enhancements
  • 🔧 Optimize performance — Make tari.js faster and more efficient
  • 🧪 Write tests — Improve code coverage and reliability

📚 Documentation​

  • 📝 Improve guides — Make tutorials clearer and more helpful
  • 📖 Add examples — Show real-world usage patterns
  • 🎥 Create tutorials — Video guides and walkthroughs
  • 🌐 Translate content — Help make tari.js globally accessible

💡 Ideas & Feedback​

  • 💭 Share use cases — Tell us how you're using tari.js
  • 🗳️ Vote on features — Help prioritize development
  • 🎯 Request features — Suggest improvements and new capabilities
  • 🐛 Report bugs — Help us find and fix issues

🚀 Quick Start​

Prerequisites​

Before contributing, ensure you have:

  • Node.js 18+ and pnpm installed
  • Git for version control
  • tari-ootle repository cloned at the same folder level as tari.js
  • Basic knowledge of TypeScript, React, and blockchain concepts

Development Setup​

  1. Fork and Clone

    # Fork the repository on GitHub, then:
    git clone https://github.com/YOUR-USERNAME/tari.js.git
    cd tari.js

    # Add upstream remote
    git remote add upstream https://github.com/tari-project/tari.js.git

  2. Install Dependencies

    pnpm install

  3. Build the Project

    moon tarijs:build

  4. Run Tests

    moon :test

  5. Start Documentation Site

    moon tari-docs:start

📋 Development Workflow​

Branch Strategy​

We use a feature branch workflow:

  • main - Production-ready code
  • develop - Integration branch for features
  • feature/feature-name - Individual features
  • bugfix/bug-description - Bug fixes
  • docs/documentation-updates - Documentation changes

Creating a Feature Branch​

# Update your fork
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

# Make your changes...
git add .
git commit -m "feat: add new wallet integration"

# Push to your fork
git push origin feature/your-feature-name

Commit Message Format​

We follow the Conventional Commits specification:

type(scope): brief description

[optional body]

[optional footer]

Types:

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

Examples:

feat(signer): add TariUniverse wallet integration
fix(provider): handle connection timeout properly
docs(api): update TransactionBuilder examples
test(integration): add end-to-end wallet tests

🛠️ Project Structure​

Monorepo Organization​

tari.js/
├── packages/
│   ├── tarijs/                 # Main package (aggregates all functionality)
│   ├── tari_provider/          # Base provider interface
│   ├── tari_signer/            # Base signer interface
│   ├── indexer_provider/       # Indexer provider implementation
│   ├── wallet_daemon/          # Wallet daemon integration
│   ├── metamask_signer/        # MetaMask integration
│   ├── tari_universe/          # Tari Universe wallet integration
│   ├── walletconnect/          # WalletConnect integration
│   ├── builders/               # Transaction building utilities
│   ├── tarijs_types/           # Shared TypeScript types
│   └── tari_permissions/       # Permission system
├── docusaurus/                 # Documentation website
├── scripts/                    # Build and utility scripts
└── .github/                    # CI/CD workflows

Package Development​

Each package follows a consistent structure:

packages/package-name/
├── src/
│   ├── index.ts               # Public API exports
│   ├── types.ts               # Package-specific types
│   └── [implementation files]
├── test/
│   ├── unit-tests/            # Unit tests
│   └── integration-tests/     # Integration tests
├── package.json               # Package configuration
├── tsconfig.json              # TypeScript configuration
└── moon.yml                   # Moon task configuration

🧪 Testing Guidelines​

Test Types​

  1. Unit Tests - Test individual functions and classes
  2. Integration Tests - Test package interactions
  3. End-to-End Tests - Test complete user workflows

Writing Tests​

We use Vitest for testing. Test files should be co-located with source files or in dedicated test directories.

// Example unit test
import { describe, it, expect, beforeEach } from 'vitest';
import { TransactionBuilder } from '../src/TransactionBuilder';

describe('TransactionBuilder', () => {
  let builder: TransactionBuilder;

  beforeEach(() => {
    builder = new TransactionBuilder(Network.LocalNet);
  });

  it('should set fee correctly', () => {
    const transaction = builder
      .fee(100)
      .build();

    expect(transaction.feeInstructions).toContain(
      expect.objectContaining({ amount: 100 })
    );
  });

  it('should throw on invalid fee amount', () => {
    expect(() => builder.fee(-1)).toThrow('Fee must be positive');
  });
});

Integration Tests​

// Example integration test
import { describe, it, expect } from 'vitest';
import { WalletDaemonTariSigner, IndexerProvider } from '../src';

describe('Wallet Integration', () => {
  it('should connect to wallet daemon and submit transaction', async () => {
    const signer = new WalletDaemonTariSigner({
      endpoint: 'http://localhost:18103'
    });

    const provider = new IndexerProvider({
      endpoint: 'http://localhost:18300'
    });

    // Test connection
    expect(signer.isConnected()).toBe(true);
    
    // Test account retrieval
    const account = await signer.getAccount();
    expect(account.address).toMatch(/^account_[a-f0-9]{64}$/);

    // Test transaction submission
    const transaction = new TransactionBuilder()
      .fee(100)
      .createAccount(account.public_key)
      .build();

    const result = await signer.submitTransaction({ transaction });
    expect(result.transactionId).toBeDefined();
  });
});

Running Tests​

# Run all tests
moon :test

# Run tests for specific package
moon wallet-daemon:test

# Run tests in watch mode
moon wallet-daemon:test -- --watch

# Run integration tests only
moon :test -- --run integration

📝 Documentation Guidelines​

Types of Documentation​

  1. API Documentation - Generated from TypeScript types and JSDoc
  2. User Guides - Step-by-step tutorials and explanations
  3. Developer Documentation - Architecture and contributing guides
  4. Code Comments - Inline documentation for complex logic

Writing Documentation​

JSDoc Comments​

/**
 * Submits a transaction to the Tari network
 * 
 * @param request - Transaction request containing the transaction and options
 * @param request.transaction - The transaction to submit
 * @param request.is_dry_run - Whether to perform a dry run (default: false)
 * @returns Promise resolving to transaction submission result
 * 
 * @throws {ConnectionError} When the wallet is not connected
 * @throws {ValidationError} When the transaction is invalid
 * 
 * @example
 * ```typescript
 * const transaction = new TransactionBuilder()
 *   .fee(100)
 *   .callMethod(account, 'transfer', { amount: 1000, destination: 'account_...' })
 *   .build();
 * 
 * const result = await signer.submitTransaction({ transaction });
 * console.log('Transaction ID:', result.transactionId);
 * ```
 */
async submitTransaction(request: SubmitTransactionRequest): Promise<SubmitTransactionResponse> {
  // Implementation...
}

Markdown Documentation​

Follow these guidelines for documentation:

  • Clear headings with proper hierarchy
  • Code examples for all API methods
  • Prerequisites section for setup requirements
  • Troubleshooting section for common issues
  • Cross-references to related documentation

Documentation Development​

# Start documentation development server
moon tari-docs:start

# Build documentation
moon tari-docs:build

# Deploy documentation (maintainers only)
moon tari-docs:deploy

🔧 Code Style and Standards​

TypeScript Standards​

  • Strict TypeScript configuration enabled
  • Explicit types for public APIs
  • Interface segregation principle followed
  • Consistent naming conventions
// Good: Explicit types and clear naming
interface WalletConnectionConfig {
  endpoint: string;
  timeout?: number;
  retryAttempts?: number;
}

class WalletService {
  async connect(config: WalletConnectionConfig): Promise<TariSigner> {
    // Implementation with proper error handling
  }
}

// Avoid: Any types and unclear naming
class Service {
  async connect(config: any): Promise<any> {
    // Implementation
  }
}

Code Formatting​

We use Prettier for code formatting:

# Format all files
pnpm run format

# Check formatting
pnpm run format:check

Linting​

We use ESLint for code quality:

# Lint all files
pnpm run lint

# Fix linting issues
pnpm run lint:fix

Import Organization​

// 1. Node.js built-ins
import { readFileSync } from 'fs';

// 2. External packages
import React from 'react';
import { describe, it, expect } from 'vitest';

// 3. Internal packages (monorepo)
import { TariSigner } from '@tari-project/tari-signer';
import { TransactionBuilder } from '@tari-project/builders';

// 4. Relative imports
import { validateAddress } from '../utils/validation';
import { ConnectionError } from './errors';

🐛 Bug Reports and Feature Requests​

Reporting Bugs​

When reporting bugs, include:

  1. Environment Information

    • OS and browser version
    • Node.js and pnpm versions
    • tari.js version
    • Wallet type and version

  2. Clear Description

    • What you expected to happen
    • What actually happened
    • Steps to reproduce

  3. Code Examples

    • Minimal reproduction case
    • Error messages and stack traces

  4. Additional Context

    • Screenshots or videos if applicable
    • Related issues or discussions

Feature Requests​

For feature requests, provide:

  1. Problem Statement - What problem does this solve?
  2. Proposed Solution - How should it work?
  3. Alternatives - What other solutions have you considered?
  4. Use Cases - Specific scenarios where this would be useful

🔍 Code Review Process​

Submitting Pull Requests​

  1. Create Feature Branch from main
  2. Implement Changes with tests and documentation
  3. Run Quality Checks 
    pnpm run lint
    pnpm run format:check
    moon :test
    moon :build
  4. Create Pull Request with clear description
  5. Address Review Feedback promptly

Pull Request Template​

## Description
Brief description of changes and motivation.

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

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or clearly documented)

Review Criteria​

Reviewers check for:

  • Functionality - Does it work as intended?
  • Code Quality - Is it maintainable and readable?
  • Performance - Any performance implications?
  • Security - Are there security considerations?
  • Documentation - Is it properly documented?
  • Tests - Are there adequate tests?

🏗️ Architecture Guidelines​

Design Principles​

  1. Interface Segregation - Small, focused interfaces
  2. Dependency Inversion - Depend on abstractions, not concretions
  3. Single Responsibility - Each class/function has one purpose
  4. Open/Closed - Open for extension, closed for modification

Adding New Wallet Integrations​

To add a new wallet type:

  1. Create Package in packages/ directory
  2. Implement TariSigner interface
  3. Add Configuration Types for wallet-specific options
  4. Write Unit Tests for all methods
  5. Add Integration Tests with actual wallet
  6. Update Main Package to export new signer
  7. Add Documentation with usage examples
// Example new signer implementation
export class NewWalletSigner implements TariSigner {
  readonly signerName = 'NewWallet';
  
  constructor(private config: NewWalletConfig) {
    // Initialize wallet connection
  }

  isConnected(): boolean {
    // Check connection status
  }

  async getAccount(): Promise<AccountData> {
    // Implement account retrieval
  }

  async submitTransaction(request: SubmitTransactionRequest): Promise<SubmitTransactionResponse> {
    // Implement transaction submission
  }

  // ... implement other TariSigner methods
}

🤝 Community Guidelines​

Communication​

  • Be respectful and professional in all interactions
  • Ask questions when you need clarification
  • Provide context when reporting issues or requesting help
  • Be patient with review processes and responses

Getting Help​

  • GitHub Discussions - For questions and general discussion
  • GitHub Issues - For bug reports and feature requests
  • Discord - Real-time chat with the community
  • Documentation - Check existing docs before asking

Recognition​

Contributors are recognized through:

  • GitHub Contributors page
  • Release Notes acknowledgments
  • Community Highlights in project updates

🚢 Release Process​

Versioning​

We follow Semantic Versioning:

  • MAJOR version for breaking changes
  • MINOR version for new features
  • PATCH version for bug fixes

Release Workflow​

  1. Feature Freeze - No new features in release branch
  2. Testing Phase - Comprehensive testing of release candidate
  3. Documentation Update - Update all relevant documentation
  4. Release Notes - Document all changes and breaking changes
  5. Publication - Publish to npm registry
  6. Announcement - Notify community of new release

📞 Contact and Support​

Maintainers​

  • Core Team - GitHub: @tari-project/tari-js-maintainers
  • Documentation - Contributions welcome via GitHub

Community​

Reporting Security Issues​

For security-related issues, please email: security@tari.com

Do not report security issues through public GitHub issues.

🎉 Ready to Contribute?​

🚀 Quick Start Checklist​

🏆 Join Our Community of Builders​

Thank you for contributing to tari.js! Your efforts help make the Tari ecosystem more accessible and robust for everyone. Together, we're building the future of decentralized applications with privacy at the core.

  • 🌟 Star the repo to show your support
  • 📢 Share tari.js with fellow developers
  • 💬 Connect with us on Discord and GitHub
  • 🚀 Build something amazing and share it with the community

Happy coding, and welcome to the Tari family! 🎉