zaru-core 0.1.0

Zaru Core is a Rust-based transaction processing engine designed to model secure, deterministic state transitions in distributed systems.

The project explores how financial-grade systems can enforce:

- Transaction integrity
- Cryptographic authenticity
- Safe state evolution
- Fault-tolerant processing

Built with Tokio for async execution and ed25519 for cryptographic verification, Zaru Core demonstrates how to design systems that remain predictable, verifiable, and resilient under load.

# Fintech System Alignment


This project reflects core principles used in payment platforms:

Idempotent transaction flows (preventing duplicate execution)
Deterministic processing (consistent outcomes under concurrency)
Ledger-style state management
Verification-first architecture (reject invalid transactions early)

These patterns are critical in high-volume payment systems where correctness and reliability are non-negotiable.


# Zaru Core


[![Crates.io](https://img.shields.io/crates/v/zaru-core.svg)](https://crates.io/crates/zaru-core)
[![Documentation](https://docs.rs/zaru-core/badge.svg)](https://docs.rs/zaru-core)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.70%2B-blue.svg)](https://www.rust-lang.org)

A secure, type-safe payment model engine with transaction state machine and cryptographic verification.

## Features


- ✅ **Type-safe Amount handling** - Prevent invalid amounts at compile time
- ✅ **Transaction State Machine** - Unsigned → Signed → Verified
- ✅ **ED25519 Cryptographic Verification** - Secure transaction signing
- ✅ **Wallet Abstraction** - Support for Bank and Crypto wallets
- ✅ **Python Bindings** - Use your payment engine from Python
- ✅ **Async Support** - Built with Tokio
- ✅ **No-Std Compatible** - Works in embedded environments
- ✅ **Serde Support** - Serialize/Deserialize transactions

## Installation


### Rust

```toml
[dependencies]
zaru-core = "0.1.0"

Python

pip install zaru-core

Quick Start

Rust

use zaru_core::{Amount, Transaction, TxId, WalletId, Keypair};

// Create wallets
let from = WalletId::from("bank_account_123");
let to = WalletId::from_crypto("0xabc123");

// Create amount
let amount = Amount::new(1000).unwrap();

// Create transaction
let tx = Transaction::<Unsigned>::new(
    TxId("txn_001".to_string()),
    from,
    to,
    amount,
    1
);

// Sign and verify
let keypair = Keypair::generate();
let signed = tx.sign(&keypair);
let verified = signed.verify().unwrap();

assert_eq!(verified.id.0, "txn_001");


Python

from zaru_core import PaymentEngine, WalletId, Amount

engine = PaymentEngine()

# Create wallets

wallet1 = engine.create_wallet("bank", "Bank of America")
wallet2 = engine.create_wallet("crypto", "0x1234567890abcdef")

# Create transaction

amount = engine.create_amount(1000)
tx = engine.create_transaction(
    "txn_001", 
    wallet1, 
    wallet2, 
    amount, 
    1
)

# Verify

print(tx.to_json())

Architecture

Transaction State Machine

[Unsigned] --sign()--> [Signed] --verify()--> [Verified]

Core Components

* Amount: Safe monetary vlaues with overflow protection
* Transaction: Generic transaction with state markers
* WalletId: Unified wallet abstraction
* CryptoVerifier: ED25519 signature verification

Python Bindings

The Python bindings provide a natural interface to the Rust core:

# Generate a keypair

public_key = generate_keypair()

# Create wallet from public key

wallet = WalletId.from_crypto(public_key)

# Create and verify transactions

tx = engine.create_transaction(...)
is_valid = engine.verify_transaction(tx)

Development

Building

# Build the Rust library

cargo build --release

# Build Python bindings

maturin develop


Running Tests

cargo test
pytest tests/


Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.
License

This project is licensed under either of:

    MIT License (LICENSE-MIT)

    Apache License, Version 2.0 (LICENSE-APACHE)

at your option.
Why "Zaru"?

Zaru (座る) means "to sit" in Japanese, representing the stability and reliability of a financial system that "sits" securely on cryptographic foundations.
Roadmap

    □

    Multi-signature transactions
    □

    Smart contract integration
    □

    More crypto backends
    □

    Database persistence
    □

    REST API
    □

    WebAssembly support

Install dependencies

rustup update
cargo install maturin

Run tests

cargo test
cargo test --features python-bindings


Code Style

    Run cargo fmt before committing

    Run cargo clippy and fix warnings

    Write documentation for public APIs

    Add tests for new features

Pull Request Process

    Fork the repository

    Create a feature branch

    Make your changes

    Run the test suite

    Submit a PR with a clear description

Commit Messages

Follow conventional commits:

    feat: New feature

    fix: Bug fix

    docs: Documentation

    test: Tests

    chore: Maintenance

    refactor: Code refactoring

Testing

    Unit tests in src/

    Integration tests in tests/

    Python tests in tests/python/


Releasing

    Update version in Cargo.toml

    Update CHANGELOG.md

    Commit with chore: release v0.1.0

    Push and create GitHub release

    Publish to crates.io: cargo publish

    Publish to PyPI: maturin publish