MetaMUI Crypto Primitives - API Reference

Overview

This document provides comprehensive API documentation for the MetaMUI crypto primitives, including exact function signatures, struct names, and error types for all modules.

Rust Crypto Libraries Structure

The metamui-crypto-rust now use a flat structure with standalone modules:

Each module is independent with its own error types and API.

MetaMUI Hash Module (metamui-hash)

Main Types

Key Functions

Legacy Functions

MetaMUI Ed25519 Module (metamui-ed25519)

Main Types

Key Functions

MetaMUI Sr25519 Module (metamui-sr25519)

Main Types

Key Functions

Derivation Functions (Substrate paths, as sp_core::sr25519::Pair::derive computes them)

MetaMUI Mnemonic Module (metamui-mnemonic)

Main Types

Key Functions

MetaMUI ChaCha20 Module (metamui-chacha20)

Main Types

Key Functions

Legacy SubCrypto-RS (backup/subcrypto-rs/)

Note: This implementation has been moved to backup/subcrypto-rs/ and is no longer actively developed.

For new projects, use the individual metamui-* modules in rust-crypto-libraries/ instead.

Migration Guide from Legacy Implementation

If migrating from the legacy subcrypto-rs implementation:

Key Differences

Platform-Specific APIs

Kotlin/Android APIs

Hash Functions

class MetaMUIBlake2b256 {
    fun hash(input: ByteArray): ByteArray
    fun hashToHex(input: ByteArray): String
    fun hashString(input: String): String
}

class MetaMUISha256 {
    fun hash(input: ByteArray): ByteArray
    fun hashToHex(input: ByteArray): String
    fun hashString(input: String): String
}

Digital Signatures

class MetaMUIEd25519 {
    fun generateKeyPair(): KeyPair
    fun sign(message: ByteArray, privateKey: ByteArray): ByteArray
    fun verify(signature: ByteArray, message: ByteArray, publicKey: ByteArray): Boolean
    fun signString(message: String, privateKeyHex: String): String
    fun verifyString(signature: String, message: String, publicKeyHex: String): Boolean
}

Encryption

class MetaMUIChaCha20 {
    data class EncryptionResult(val ciphertext: ByteArray, val nonce: ByteArray)
    
    fun generateKey(): ByteArray
    fun encrypt(plaintext: ByteArray, key: ByteArray): EncryptionResult
    fun decrypt(ciphertext: ByteArray, nonce: ByteArray, key: ByteArray): ByteArray
}

Swift/iOS APIs

Hash Functions

public class Blake2b256 {
    public static func hash(_ data: Data) -> Data
    public static func hashToHex(_ data: Data) -> String
    public static func hashString(_ input: String) -> String
}

public class SHA256 {
    public static func hash(_ data: Data) -> Data
    public static func hashToHex(_ data: Data) -> String
    public static func hashString(_ input: String) -> String
}

Digital Signatures

public class Ed25519 {
    public struct KeyPair {
        public let publicKey: Data
        public let privateKey: Data
    }
    
    public static func generateKeyPair() -> KeyPair
    public static func sign(_ message: Data, privateKey: Data) -> Data
    public static func verify(_ signature: Data, message: Data, publicKey: Data) -> Bool
}

Python APIs

Hash Functions

class Blake2b256:
    @staticmethod
    def hash(data: bytes) -> bytes:
    
    @staticmethod
    def hash_to_hex(data: bytes) -> str:
    
    @staticmethod
    def hash_string(input_str: str) -> str:

class SHA256:
    @staticmethod
    def hash(data: bytes) -> bytes:
    
    @staticmethod
    def hash_to_hex(data: bytes) -> str:
    
    @staticmethod
    def hash_string(input_str: str) -> str:

Digital Signatures

class Ed25519:
    @dataclass
    class KeyPair:
        public_key: bytes
        private_key: bytes
    
    @staticmethod
    def generate_keypair() -> KeyPair:
    
    @staticmethod
    def sign(message: bytes, private_key: bytes) -> bytes:
    
    @staticmethod
    def verify(signature: bytes, message: bytes, public_key: bytes) -> bool:

TypeScript/JavaScript APIs

Hash Functions

export class Blake2b256 {
    static hash(data: Uint8Array): Uint8Array;
    static hashToHex(data: Uint8Array): string;
    static hashString(input: string): string;
}

export class SHA256 {
    static hash(data: Uint8Array): Uint8Array;
    static hashToHex(data: Uint8Array): string;
    static hashString(input: string): string;
}

Digital Signatures

export interface KeyPair {
    publicKey: Uint8Array;
    privateKey: Uint8Array;
}

export class Ed25519 {
    static generateKeyPair(): KeyPair;
    static sign(message: Uint8Array, privateKey: Uint8Array): Uint8Array;
    static verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
}

MetaMUI Falcon-512 Module (metamui-falcon512)

Rust API

// Main Types
pub struct PublicKey { /* ... */ }
pub struct PrivateKey { /* ... */ }
pub struct KeyPair { pub public_key: PublicKey, pub private_key: PrivateKey }
pub struct Signature { /* ... */ }

// Key Functions
pub fn generate_keypair<R: Rng>(rng: &mut R) -> Result<KeyPair, Falcon512Error>
pub fn sign<R: Rng>(message: &[u8], private_key: &PrivateKey, rng: &mut R) -> Result<Signature, Falcon512Error>
pub fn verify(message: &[u8], signature: &Signature, public_key: &PublicKey) -> bool
pub fn serialize_public_key(public_key: &PublicKey) -> Result<Vec<u8>, Falcon512Error>
pub fn deserialize_public_key(bytes: &[u8]) -> Result<PublicKey, Falcon512Error>

TypeScript API

export interface Falcon512KeyPair {
    publicKey: PublicKey;
    privateKey: PrivateKey;
}

export class Falcon512 {
    static generateKeyPair(): KeyPair;
    static sign(message: Uint8Array, privateKey: PrivateKey): Signature;
    static verify(message: Uint8Array, signature: Signature, publicKey: PublicKey): boolean;
    static serializePublicKey(publicKey: PublicKey): Uint8Array;
    static deserializePublicKey(bytes: Uint8Array): PublicKey;
}

Python API

@dataclass
class KeyPair:
    public_key: PublicKey
    private_key: PrivateKey

def generate_keypair() -> KeyPair:
def sign(message: bytes, private_key: PrivateKey) -> Signature:
def verify(message: bytes, signature: Signature, public_key: PublicKey) -> bool:
def serialize_public_key(public_key: PublicKey) -> bytes:
def deserialize_public_key(data: bytes) -> PublicKey:

Kotlin API

data class Falcon512KeyPair(val publicKey: PublicKey, val privateKey: PrivateKey)

object Falcon512 {
    fun generateKeyPair(): KeyPair
    fun sign(message: ByteArray, privateKey: PrivateKey): Signature
    fun verify(message: ByteArray, signature: Signature, publicKey: PublicKey): Boolean
    fun serializePublicKey(publicKey: PublicKey): ByteArray
    fun deserializePublicKey(bytes: ByteArray): PublicKey
}

Swift API

public struct Falcon512KeyPair {
    public let publicKey: Falcon512PublicKey
    public let privateKey: Falcon512PrivateKey
}

public struct Falcon512 {
    public static func generateKeyPair() throws -> Falcon512KeyPair
    public static func sign(message: Data, privateKey: Falcon512PrivateKey) throws -> Falcon512Signature
    public static func verify(message: Data, signature: Falcon512Signature, publicKey: Falcon512PublicKey) -> Bool
    public static func serializePublicKey(_ publicKey: Falcon512PublicKey) -> Data
    public static func deserializePublicKey(_ data: Data) throws -> Falcon512PublicKey
}

Error Handling

All APIs use consistent error handling patterns:

Module Independence

The new flat structure provides:

Test Status Summary

✅ Working Implementations

The modular API provides:

  1. Independent modules for specific cryptographic operations
  2. Platform-specific wrappers for native language integration
  3. Consistent error handling across all modules
  4. Memory-safe implementations using Rust
  5. Cross-platform compatibility testing