Contributing Guide

Principles

See the core principles in the repository's README

Rust crates vs FFI libraries

The implementation of the rust crate should be completely seperate from the foreign interfaces. For example, algokit_transact does not depend on UniFFI or wasm-bindgen. Instead, there's a seperate crate algokit_transact_ffi that provides the foreign interfaces.

Development Tools and Commands

This repository provides several cargo binary commands to help with development and building packages for different languages.

Available Binary Commands

1. Package Building (build_pkgs)

cargo pkg <package> [language]

Examples:

  • cargo pkg algokit_transact typescript - Build TypeScript/WASM bindings
  • cargo pkg algokit_transact python - Build Python bindings
  • cargo pkg algokit_transact swift - Build Swift bindings
  • cargo pkg algokit_transact - Build all languages

2. API Tools (api_tools)

cargo api <subcommand>

Available subcommands:

  • test-oas - Test the OAS generator
  • format-oas - Format the OAS generator code
  • lint-oas - Lint and type-check the OAS generator
  • format-algod - Format generated Rust code
  • generate-algod - Generate algod API client
  • convert-openapi - Convert OpenAPI specification

3. Documentation Building

cargo run --bin build-docs --manifest-path docs/Cargo.toml

4. Cargo Binary Management

cargo bin <args>

5. UniFFI Bindings Generator

cargo run --bin uniffi-bindgen -- <args>

6. Pre-commit Hooks (Optional)

This repository includes pre-commit hooks that run the same checks as scripts/sanity.sh.

Run hooks manually on all files:

pre-commit run --all-files
# or 
pre-commit install # to auto run on each commit

The hooks will automatically run cargo fmt --check, cargo clippy, cargo check, cargo test, and cargo check --no-default-features --features ffi_wasm on every commit.

Development Workflow

When Developing Core Rust Functionality

  1. Make changes to the core crates (e.g., algokit_transact)
  2. Run tests to ensure functionality works:
    cargo test -p algokit_transact
    
  3. Test FFI layer if your changes affect the interface:
    cargo test -p algokit_transact_ffi
    

When Developing Language Bindings

TypeScript/WASM Development

  1. Build the TypeScript bindings after making Rust changes:
    cargo pkg algokit_transact typescript
    
  2. Run TypeScript tests:
    cd packages/typescript/algokit_transact
    bun test
    

Python Development

  1. Build the Python bindings:
    cargo pkg algokit_transact python
    
  2. Test Python bindings:
    cd packages/python/algokit_transact
    poetry run pytest
    

Swift Development

  1. Build the Swift bindings:
    cargo pkg algokit_transact swift
    

Testing Your Changes

  1. Run Rust tests:

    cargo test
    
  2. Run specific crate tests:

    cargo test -p algokit_transact
    cargo test -p algokit_transact_ffi
    
  3. Run language-specific tests:

    # TypeScript
    cd packages/typescript/algokit_transact && bun test
    
    # Python
    cd packages/python/algokit_transact && poetry run pytest
    
  4. Run all tests (as done in CI):

   ./scripts/test-all.sh                         # Comprehensive test script

Or manually:

cargo test                                    # Rust tests
cargo pkg algokit_transact typescript        # Build TS
cd packages/typescript/algokit_transact && bun test  # Test TS
cargo pkg algokit_transact python            # Build Python
cd packages/python/algokit_transact && poetry run pytest  # Test Python

Debugging Rust Code is VS Code

Prerequisites

Install the CodeLLDB extension for Visual Studio Code to debug Rust code.

Debug Configurations

The project includes pre-configured debug configurations in .vscode/launch.json:

  • Debug unit tests in algokit_transact: Debug tests for the core transaction functionality
  • Debug unit tests in algokit_transact_ffi: Debug tests for the FFI bindings

How to Debug

  1. Set breakpoints by clicking in the gutter next to line numbers
  2. Go to the Debug view (Ctrl+Shift+D or Cmd+Shift+D) and select a configuration for the crate you want to debug
  3. Press F5 to start debugging
  4. Use the debug toolbar to step through code (F10 for step over, F11 for step into)