yotquitas-core

Core library for the Yotquitas blockchain providing foundational data structures, cryptographic primitives, and transaction handling.

This crate is the foundation of the Yotquitas blockchain, providing all the essential building blocks for creating transactions, blocks, accounts, and cryptographic operations.

Features

• 🔐 Cryptographic Primitives:

  • SHA-256 hashing (single and double)
  • Ed25519 digital signatures (key generation, signing, verification)
  • Address derivation from public keys
  • Hex encoding/decoding utilities

• 📝 Transaction Structures:

  • Multiple transaction types (Transfer, ContractCall, DeployContract, DeployModule, MoveCall)
  • Transaction signing and verification
  • Transaction serialization (JSON)
  • Transaction receipts and logs

• 🧱 Block Structures:

  • Block headers with Merkle root computation
  • Block creation and verification
  • Double SHA-256 hashing for block integrity

• 👤 Account Management:

  • Account types (User, Validator, Contract, Treasury)
  • Account capabilities and permissions
  • Address-based account creation

• 🔄 Serialization:

  • Full serde support with JSON serialization/deserialization
  • Custom serializers for cryptographic types
  • Transaction and block serialization

Installation

Add this to your Cargo.toml:

[dependencies]
yotquitas-core = "0.1.0"

Or install from crates.io:

cargo add yotquitas-core

Quick Start

Generate a Keypair

use yotquitas_core::{generate_keypair, SigningKey};

// Generate a new Ed25519 keypair
let (signing_key, public_key) = generate_keypair();

// The signing_key is your private key (SigningKey type)
// The public_key is your public key (PublicKey/VerifyingKey type)

Create and Sign a Transaction

use yotquitas_core::{Transaction, TransactionPayload, generate_keypair, SigningKey};

// Generate keypair
let (signing_key, public_key) = generate_keypair();

// Create a transfer transaction
let payload = TransactionPayload::Transfer {
    to: [0u8; 32],  // recipient address (32 bytes)
    amount: 100,     // amount in AEQ
};

// Create unsigned transaction
let tx = Transaction::new(
    public_key,  // sender's public key
    payload,
    1,           // fee
    0,           // nonce
);

// Sign the transaction
let signed_tx = tx.sign(&signing_key);

// Verify the signature
assert!(signed_tx.verify());

// Get transaction hash
let tx_hash = signed_tx.hash();

// Get sender address
let sender_address = signed_tx.sender_address();

Serialize and Deserialize Transactions

use yotquitas_core::Transaction;

// Serialize to JSON
let json = serde_json::to_string(&signed_tx).unwrap();

// Deserialize from JSON
let deserialized: Transaction = serde_json::from_str(&json).unwrap();

// Verify signature still works after deserialization
assert!(deserialized.verify());

Create a Block

use yotquitas_core::{Block, BlockHeader, Transaction, TransactionPayload, generate_keypair};

// Create transactions
let (_, pubkey) = generate_keypair();
let tx = Transaction::new(
    pubkey,
    TransactionPayload::Transfer {
        to: [0u8; 32],
        amount: 100,
    },
    1,
    0,
);

// Create block header
let header = BlockHeader::new(
    0,              // block index
    1000,           // timestamp
    [0u8; 32],      // previous block hash
);

// Create block with transactions
let block = Block::new(header, vec![tx]);

// Verify block integrity
assert!(block.verify());

// Get block hash
let block_hash = block.hash();

Work with Accounts

use yotquitas_core::{Account, AccountType, generate_keypair, address_from_public_key};

// Create account from public key
let (_, public_key) = generate_keypair();
let account = Account::new_user_from_pubkey(public_key);

// Check account capabilities
assert!(account.can_send());
assert!(account.can_receive());
assert!(account.can_deploy());

// Create contract account
let contract_address = [1u8; 32];
let contract_account = Account::new_contract(contract_address);
assert!(!contract_account.can_send()); // Contracts can't send

Module Overview

crypto - Cryptographic Operations

Core cryptographic functions for the blockchain:

• Key Generation: generate_keypair() - Creates Ed25519 keypairs
• Signing: sign(signing_key, data) - Signs data with private key
• Verification: verify(public_key, data, signature) - Verifies signatures
• Hashing: sha256(), double_sha256() - SHA-256 hashing
• Address Derivation: address_from_public_key() - Derives 32-byte address from public key
• Hex Encoding: encode_hex(), decode_hex() - Hex string utilities

Types:

• Hash - 32-byte hash (SHA-256 output)
• PublicKey - Ed25519 public key (VerifyingKey)
• Signature - Ed25519 signature
• SigningKey - Ed25519 private key (re-exported from ed25519_dalek)

transaction - Transaction Handling

Transaction creation, signing, and verification:

• Transaction Types:

  • Transfer - Simple token transfer
  • ContractCall - Call a smart contract function
  • DeployContract - Deploy a WASM contract
  • DeployModule - Deploy a Move module
  • MoveCall - Call a Move function

• Transaction Methods:

  • new() - Create unsigned transaction
  • sign() - Sign transaction with private key
  • verify() - Verify transaction signature
  • hash() - Get transaction hash
  • sender_address() - Get sender's address
  • recipient_address() - Get recipient address (if applicable)

Types:

• Transaction - Main transaction structure
• TransactionPayload - Transaction payload variants
• TransactionReceipt - Transaction execution result
• TransactionLog - Event log entry
• Address - 32-byte address (type alias for Hash)

block - Block Structures

Block creation and verification:

• Block Methods:

  • new() - Create new block with transactions
  • verify() - Verify block integrity
  • hash() - Get block hash
  • index() - Get block index
  • previous_hash() - Get previous block hash

• Block Header Methods:

  • new() - Create new block header
  • hash() - Compute header hash

• Utilities:

  • compute_merkle_root() - Compute Merkle root from transactions

Types:

• Block - Complete block with header and transactions
• BlockHeader - Block header structure

account - Account Management

Account types and capabilities:

• Account Types:

  • User - Standard user account
  • Validator - Validator account (can produce blocks)
  • Contract - Smart contract account
  • Treasury - System treasury account

• Account Methods:

  • new_user() - Create user account from address
  • new_user_from_pubkey() - Create user account from public key
  • new_validator() - Create validator account
  • new_contract() - Create contract account
  • new_treasury() - Create treasury account
  • can_send() - Check if account can send transactions
  • can_receive() - Check if account can receive transactions
  • can_deploy() - Check if account can deploy contracts

Types:

• Account - Account structure
• AccountType - Account type enumeration

Detailed Examples

Exporting and Importing Private Keys

use yotquitas_core::{generate_keypair, SigningKey};
use hex;

// Generate keypair
let (signing_key, public_key) = generate_keypair();

// Export private key as bytes (32 bytes)
let private_key_bytes: [u8; 32] = signing_key.to_bytes();

// Export as hex string (64 hex characters)
let private_key_hex = hex::encode(private_key_bytes);

// Import from bytes
let imported_signing_key = SigningKey::from_bytes(&private_key_bytes);

// Import from hex
let bytes_from_hex = hex::decode(&private_key_hex).unwrap();
let signing_key_from_hex = SigningKey::from_bytes(
    bytes_from_hex.try_into().unwrap()
);

Creating Different Transaction Types

use yotquitas_core::{Transaction, TransactionPayload, generate_keypair};

let (signing_key, public_key) = generate_keypair();

// Transfer transaction
let transfer_tx = Transaction::new(
    public_key,
    TransactionPayload::Transfer {
        to: [0u8; 32],
        amount: 1000,
    },
    1,
    0,
).sign(&signing_key);

// Contract call transaction
let contract_call_tx = Transaction::new(
    public_key,
    TransactionPayload::ContractCall {
        contract_address: [1u8; 32],
        function: "transfer".to_string(),
        args: vec![1, 2, 3],
    },
    10,
    1,
).sign(&signing_key);

// Deploy contract transaction
let deploy_tx = Transaction::new(
    public_key,
    TransactionPayload::DeployContract {
        wasm_bytecode: vec![0, 1, 2, 3], // WASM bytecode
        init_args: vec![],              // Initialization arguments
    },
    100,
    2,
).sign(&signing_key);

Working with Addresses

use yotquitas_core::{generate_keypair, address_from_public_key, validate_address, encode_hex};

// Generate keypair
let (_, public_key) = generate_keypair();

// Derive address from public key
let address = address_from_public_key(&public_key);

// Validate address (must be 32 bytes)
assert!(validate_address(&address));

// Encode address as hex string
let address_hex = encode_hex(&address);
println!("Address: 0x{}", address_hex);

Type Aliases

• Address - 32-byte address (alias for Hash)
• Hash - 32-byte hash (SHA-256 output)
• PublicKey - Ed25519 public key (alias for VerifyingKey)
• Signature - Ed25519 signature

Dependencies

• ed25519-dalek - Ed25519 signature scheme
• sha2 - SHA-256 hashing
• serde - Serialization framework
• serde_json - JSON serialization
• hex - Hex encoding/decoding
• rand - Random number generation

Security Considerations

1. Private Key Storage: Never store SigningKey in plain text. Always export as bytes or hex and use secure storage.

2. Transaction Signing: Always sign transactions client-side. Never send private keys to servers.

3. Address Validation: Always validate addresses are 32 bytes before using them.

4. Signature Verification: Always verify transaction signatures before processing.

5. Merkle Root: Block Merkle roots are computed automatically. Don't modify them manually.

Testing

Run the test suite:

cargo test

Run tests for a specific module:

cargo test --lib crypto
cargo test --lib transaction
cargo test --lib block
cargo test --lib account

Documentation

Generate full API documentation:

cargo doc --open

License

Licensed under the MIT license.

See LICENSE-MIT or http://opensource.org/licenses/MIT for details.

Contributing

Contributions are welcome! Please see the main project contributing guide for more details.

Links

• Repository: https://github.com/Joel-Ajayi/yotquitas
• Crates.io: https://crates.io/crates/yotquitas-core
• Documentation: https://docs.rs/yotquitas-core

Version

Current version: 0.1.0