Contributing Guide

Principles

See the core principles in the repository's README

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

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

When Developing Language Bindings

TypeScript/WASM Development

Build the TypeScript bindings after making Rust changes:
```
cargo pkg algokit_transact typescript
```

Run TypeScript tests:

cd packages/typescript/algokit_transact
bun test

Python Development

Build the Python bindings:
```
cargo pkg algokit_transact python
```

Test Python bindings:

cd packages/python/algokit_transact
poetry run pytest

Swift Development

Build the Swift bindings:
```
cargo pkg algokit_transact swift
```

Testing Your Changes

Run Rust tests:
```
cargo test
```

Run specific crate tests:

cargo test -p algokit_transact
cargo test -p algokit_transact_ffi

Run language-specific tests:

# TypeScript
cd packages/typescript/algokit_transact && bun test

# Python
cd packages/python/algokit_transact && poetry run pytest

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

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

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

AlgoKit Core Documentation