CommunityContributing
Community

Contributing

Build Turmite from source, run the tests and send a pull request.

Markdown

Turmite is a community project. The code, the issues and the pull requests are on GitHub. Contributions are under the MIT license.

Report security problems in private. Do not open a public issue. See Reporting a vulnerability.

Repository layout

Path Contents
crates/turmite/ The library and the turmite binary (Rust 2024)
crates/turmite/src/http/ Merchant API, checkout, dashboard, assets, middleware
crates/turmite/src/chains/ One driver per chain family, the mock driver, the network catalog, node health and failover
crates/turmite/src/worker/ Background loops: chain watching, sweeps, the EVM sweeper, the address pool
crates/turmite/src/payouts/ Payouts: limits, approvals, signing per chain
crates/turmite/src/exchange/ Pay with any coin through Trocador
crates/turmite/src/db/ Database access, one file per area
crates/turmite/templates/ Server-rendered templates: dashboard and checkout
crates/turmite/migrations/ Database migrations
contracts/ Foundry project: EVM DepositFactory and DepositWallet
sdk/typescript/ @turmite/sdk
plugins/woocommerce/ The WooCommerce plugin
deploy/ Compose file, Caddyfile, install.sh, Kubernetes manifests, testnet stack
site/ This website
openapi.yaml OpenAPI 3.1 description of the merchant API and the webhook payloads

Requirements

  • Rust 1.99.1. rust-toolchain.toml selects it when you use rustup.
  • Docker with the Compose plugin, for PostgreSQL 18 and the testnet stack.
  • Foundry, only to change the EVM contracts.
  • Node.js 26 and pnpm 12, only for the SDK and the site. CI uses these versions.

Build and run

  1. Clone the repository:

    git clone https://github.com/loruorg/turmite.git
cd turmite

  2. Start PostgreSQL. It listens on 127.0.0.1:5433:

    docker compose -f deploy/testnets/docker-compose.yml up -d postgres

  3. Run the server with mock chains:

    cargo run -- serve --demo

    The defaults of TURMITE_DATABASE_URL and TURMITE_SITE_URL point to this database and to http://localhost:8080. With --demo, Turmite makes a random TURMITE_SECRET when none is set.

  4. Open http://localhost:8080/dashboard and create the first user.

Tests

cargo test

The tests need the PostgreSQL server from step 2. Each test makes its own database there. To use another server, set TURMITE_TEST_PG=postgres://user:pass@host:port. The default features build every chain, so the tests need no feature flag.

The real-chain tests skip unless TURMITE_TEST_CHAINS names their chain (bitcoin,monero) or is all. They need the local testnet stack.

Before you send a pull request, also run:

cargo fmt --all --check
cargo clippy --locked --all-targets -- -D warnings

For the EVM contracts:

cd contracts && forge test

Do not change the deployed contract bytecode without a migration plan. The factory bytecode decides every EVM deposit address.

Local testnet stack

deploy/testnets runs PostgreSQL and a local node for each chain. All images run on arm64 and amd64.

docker compose -f deploy/testnets/docker-compose.yml up -d                # PostgreSQL, Bitcoin, Monero, EVM
docker compose -f deploy/testnets/docker-compose.yml --profile all up -d  # adds Solana, Tron, TON

deploy/testnets/verify.sh     # checks each local node
scripts/e2e.sh                # every test, with the real-chain tests on every chain

scripts/e2e.sh fails when a real-chain test skips. The profile public adds clients for the public testnets (Bitcoin Signet, Monero Stagenet). Optional settings, such as API keys for verify.sh --public, go in deploy/testnets/.env. See .env.example. deploy/testnets/README.md lists the ports, the funding commands and the faucets.

Pull requests

  • Keep each pull request to one change.
  • Add or update tests for the change.
  • Update the docs in site/src/content/docs/ when behaviour changes.
  • Write user-facing text in ASD-STE100 Simplified Technical English: short sentences, active voice, one fact per sentence.
  • Do not add telemetry, analytics or third-party trackers.
  • Do not add an environment variable that turns a feature on or off. Settings belong in the dashboard. Open an issue first if you think a new variable is necessary.

The website

The site is an Astro project in site/:

cd site
pnpm install
pnpm dev

pnpm build writes the static site to site/dist/ and builds the search index.