Contributing to D-ASA

Thank you for contributing to D-ASA.

Prerequisites

The standard contributor workflow assumes:

• AlgoKit for project bootstrap, LocalNet, build, and deployment workflows
• Poetry for the Python environment
• Docker for Algorand LocalNet
• pre-commit for local checks

Docs contributors also need:

• Rust and Cargo
• mdbook
• mdbook-mermaid

Getting Started

Clone the Repository

git clone git@github.com:cusma/d-asa.git
cd d-asa

Bootstrap the Development Environment

The standard setup path is:

algokit project bootstrap all
make pre-commit
make doctor

If you are only setting up Python dependencies:

make install

If you are contributing to docs, install the mdBook toolchain as well:

cargo install mdbook --version 0.5.2 --locked
cargo install mdbook-mermaid --version 0.17.0 --locked
mdbook-mermaid install .

Verify the Environment

Run:

make doctor

make doctor runs algokit doctor, checks core contributor dependencies, checks Docker daemon reachability for LocalNet workflows, and warns if docs-only tools are missing.

Development Workflow

Core Commands

The main contributor commands are:

make help
make build
make test
make test-cov
make lint
make format
make typecheck
make all

make all runs the standard code quality loop for contributors:

• build smart contracts
• run lint and type checks
• run the default non-showcase test suite

It intentionally does not require mdBook tooling.

LocalNet Workflow

Start LocalNet when you need end-to-end execution tests or LocalNet deployment:

make localnet
make deploy-localnet
make showcase
make localnet-stop

These targets map to the existing AlgoKit workflow already used by CI and the project scripts.

Docs Workflow

For docs editing with live reload:

make docs-serve

For docs validation:

make docs

make docs runs both:

• the docs pre-commit hooks:
  • mdbook-build
  • mdbook-test
  • markdownlint
  • trailing-whitespace
• the mdBook build artifacts remain available in book/ until make clean

Pull Requests

When preparing a pull request:

1. Keep changes focused and atomic.
2. Add or update tests when behavior changes.
3. Update docs when user-facing behavior, workflows, or interfaces change.
4. Run the relevant local checks before opening the PR.

Suggested pre-PR checklist:

make doctor
make all

If you changed docs:

make docs

If you changed LocalNet behavior or showcase flows:

make localnet
make showcase
make localnet-stop

Repository Layout

The main top-level layout is:

.algokit/          -> AlgoKit configuration and generators
.github/           -> CI/CD workflows and shared GitHub actions
docs/              -> mdBook source files
modules/           -> D-ASA module implementations
smart_contracts/   -> AVM smart contracts and generated contract artifacts
src/               -> D-ASA SDK, Python-side normalization, helpers, and shared runtime code
tests/             -> SDK, contract, LocalNet, and showcase tests

Style and Quality

Python

The project uses:

• black for formatting
• ruff for linting and import organization
• mypy for type checking
• pytest for tests

Run the standard checks with:

make format
make lint
make typecheck
make test

Markdown and mdBook

The docs are written in CommonMark and validated in CI with markdownlint, trailing whitespace checks, and mdbook test.

Numbered Lists

Numbered lists MUST use 1.-only style.

1. First item
1. Second item
1. Third item

Tables

Table rows MUST keep aligned column widths.

✅ Correct table format

| Month    | Savings |
|----------|---------|
| January  | EUR 250 |
| February | EUR 80  |
| March    | EUR 420 |

❌ Wrong table format

| Month | Savings |
|----------|---------|
| January | EUR 250 |
| February | EUR 80 |
| March | EUR 420 |

Column alignment may be controlled with : markers in the separator row.

Admonitions

An admonition is a special type of callout or notice block used to highlight important information. It is written as a blockquote with a special tag on the first line.

> [!NOTE]
> General information or additional context.

> [!TIP]
> A helpful suggestion or best practice.

> [!IMPORTANT]
> Key information that shouldn't be missed.

> [!WARNING]
> Critical information that highlights a potential risk.

> [!CAUTION]
> Information about potential issues that require caution.

MathJax

Mathematical formulas are rendered with MathJax.

Reference:

• mdBook MathJax documentation

Additional Notes

• Do not remove or hand-edit generated artifacts under smart_contracts/artifacts or src/artifacts unless the change explicitly requires regenerated output.
• Prefer the checked-in algokit commands and make targets over ad-hoc local command variations so contributor workflows stay aligned with CI.