Kalatori

Imported from Kalapaja/Kalatori (AGENTS.md). Install upstream with npx skills add Kalapaja/Kalatori. Copyright stays with the author.

Kalatori — AI Agent Guide

Self-hosted, non-custodial blockchain payment gateway daemon for Polkadot Asset Hub and Polygon. Derives unique HD payment accounts per invoice, monitors chains for incoming payments, auto-withdraws to merchant recipient. License: GPLv3. Rust edition 2024, MSRV 1.91. Status: Public Beta.

Critical Pitfalls

• Metadata regen required when updating subxt or connecting to new chain version: make setup-utils && make download-node-metadata
• Version sync: subxt-cli must match subxt in Cargo.toml (both 0.44), sqlx-cli must match sqlx (both 0.8) — versions pinned in [workspace.metadata.bin] in the root Cargo.toml (subxt-cli is pinned a second time in the Dockerfile; keep both in step)
• Clippy: the PR clippy job — and only that job — runs RUSTFLAGS="-Dwarnings", so every enabled lint fails it. The enabled set is small and pedantic is not in it. See docs/conventions.md before assuming a lint protects you
• Checked arithmetic: clippy::arithmetic_side_effects is enabled workspace-wide. Decimal's operators panic on overflow — money/fee/gas paths must use checked_*/saturating_* and return a domain error, not #[expect]
• Profiles live in the root manifest: Cargo silently ignores [profile.*] in non-root workspace members. Never put them in daemon/Cargo.toml; verify with cargo build --release -vv
• Never use mod.rs — self-named modules only (enforced by mod_module_files clippy lint)
• Nightly rustfmt: cargo +nightly fmt --all
• SQLite >= 3.47.0 required at runtime (see README.md for build-from-source instructions)
• Seed security: Zeroized on drop, env vars removed after loading, never log private keys
• Legacy vs new errors: daemon/src/error.rs is the legacy monolithic enum; new code should use domain-specific error types per docs/error-handling.md

How We Work

Documentation Policy

• Done something — write it down. Every architectural decision, troubleshooting finding, or pattern change gets recorded in docs/.
• When a doc contradicts code, ask the user which is correct and update the other.
• When a new subsystem emerges, create docs/<name>.md and add it to the Documentation Map below.
• See docs/doc-update-triggers.md for the mandatory update checklist.

Research Policy

• Never assume library APIs from memory — look up in Context7 or Exa first.

Trust Hierarchy

When sources disagree, trust in this order:

1. Code, build files, CI workflows — canonical source of truth
2. Tests — verify behavior claims
3. Specific docs (e.g., docs/error-handling.md) override general docs (e.g., AGENTS.md)
4. Docs describe intent and patterns — not guaranteed implementation truth
5. When unsure, ask the user which is correct and update the other

Editing Strategy

• Prefer minimal, surgical edits. Don't refactor adjacent code opportunistically.
• Preserve local module conventions even if globally suboptimal — unless explicitly refactoring.
• When modifying legacy modules (e.g., code using daemon/src/error.rs), follow existing local patterns. Only introduce new error architecture at clear boundaries.
• Add or update tests when behavior changes.
• Check docs/doc-update-triggers.md after changes.

Writing Style

• Context-aware, terse, informative, concise.
• No unnecessary abstractions — three similar lines > premature helper.

Tech Stack

• Workspace: daemon (main binary), client (public client library)
• Runtime: tokio (multi-threaded)
• Web: axum 0.8
• Database: SQLite via sqlx 0.8 (migrations in ./migrations/)
• Chains: Asset Hub (subxt 0.44, sr25519) + Polygon (alloy 1.5, secp256k1, Pimlico paymaster)
• Key derivation: BIP39 seed → Keyring actor (mpsc channel) → per-chain derivation
• Config: JSON files + env var overrides ({PREFIX}_{CONFIG}_{FIELD})
• Testing: nextest, llvm-cov, cargo-mutants, Rust example-based integration tests
• CI: GitHub Actions with reusable _job-*.yml workflow templates

Repository Layout

daemon/src/
  main.rs                     Entry point, component initialization
  state.rs                    AppState struct (Arc, direct async methods)
  api.rs + api/               Axum server: /public, /private, /internal, /dev
  chain.rs + chain/           TransfersTracker, TransfersExecutor, InvoiceRegistry, TransactionsRecorder
  chain_client.rs + chain_client/  BlockChainClient trait, asset_hub.rs, polygon.rs, keyring.rs, errors.rs
  dao.rs + dao/               SQLite DAO: DaoInterface trait, per-entity CRUD modules
  types.rs + types/           Domain types: Invoice, Payout, Transaction, Refund, Swap, etc.
  configs.rs + configs/       JSON config loading + env var overrides
  error.rs                    Legacy error types (being migrated)
  expiration_detector.rs      Periodic invoice expiration handling
  webhook_sender.rs           Periodic webhook dispatch with HMAC
  etherscan_client.rs         Etherscan/Polygonscan API client
  utils/                      logger, logging constants, task_tracker, shutdown

client/src/                   Public client library: types, HTTP client, HMAC utils, Axum middleware
configs/                      Example JSON config files
migrations/                   SQLite migration SQL files
chopsticks/                   Chopsticks (Substrate fork simulator) Docker setup
daemon/examples/              Integration test examples (crud, webhook)

Essential Commands

Prefer make targets over calling cargo directly.

Documentation Map

MCP Tooling Summary

Details: docs/mcp-tooling.md

Key Links

• V2 API spec
• Kalatori Matrix
• GitHub Discussions
• Roadmap and Milestones