Crypto Adapter API Reference¶

The DilithiaCryptoAdapter is the core cryptographic interface shared across all Dilithia SDKs. It provides 25 methods covering mnemonic management, HD wallet derivation, signing, verification, address handling, key generation, and hashing -- all backed by dilithia-core using the ML-DSA-65 (Dilithium) post-quantum signature scheme.

Tip

In TypeScript and Python, each method is available in both sync and async variants. See Sync vs Async for details.

Java package changes (v0.3.0)

Java crypto classes have moved to org.dilithia.sdk.crypto.*. All methods now declare throws CryptoException (from org.dilithia.sdk.crypto.CryptoException) instead of throwing unchecked exceptions.

Mnemonic Operations¶

`generateMnemonic`¶

Generate a new BIP-39 mnemonic phrase for wallet creation.

TypeScriptPythonRustGoJavaC#

generateMnemonic(): Promise<string>

def generate_mnemonic(self) -> str

fn generate_mnemonic(&self) -> Result<String, String>

func (a *CryptoAdapter) GenerateMnemonic(ctx context.Context) (string, error)

String generateMnemonic() throws CryptoException

// NativeCryptoBridge : IDilithiaCryptoAdapter
string GenerateMnemonic()

Returns: A space-separated mnemonic phrase (typically 24 words).

`validateMnemonic`¶

Validate that a mnemonic phrase is well-formed according to BIP-39 rules.

TypeScriptPythonRustGoJavaC#

validateMnemonic(mnemonic: string): Promise<void>

def validate_mnemonic(self, mnemonic: str) -> None

fn validate_mnemonic(&self, mnemonic: &str) -> Result<(), String>

func (a *CryptoAdapter) ValidateMnemonic(ctx context.Context, mnemonic string) error

void validateMnemonic(String mnemonic) throws CryptoException

void ValidateMnemonic(string mnemonic)

Parameter	Type	Description
`mnemonic`	`string`	The mnemonic phrase to check

Returns: Nothing on success. Throws/returns an error if the mnemonic is invalid.

`seedFromMnemonic`¶

Derive a 32-byte seed from a mnemonic phrase. This seed can be used for deterministic key generation.

TypeScriptPythonRustGoJavaC#

seedFromMnemonic(mnemonic: string): Promise<string>

def seed_from_mnemonic(self, mnemonic: str) -> str

fn seed_from_mnemonic(&self, mnemonic: &str) -> Result<String, String>

func (a *CryptoAdapter) SeedFromMnemonic(ctx context.Context, mnemonic string) (string, error)

String seedFromMnemonic(String mnemonic) throws CryptoException

string SeedFromMnemonic(string mnemonic)

Parameter	Type	Description
`mnemonic`	`string`	A valid BIP-39 mnemonic

Returns: Hex-encoded 32-byte seed.

Wallet Operations¶

`recoverHdWallet`¶

Recover the root HD wallet account (index 0) from a mnemonic.

TypeScriptPythonRustGoJavaC#

recoverHdWallet(mnemonic: string): Promise<DilithiaAccount>

def recover_hd_wallet(self, mnemonic: str) -> DilithiaAccount

fn recover_hd_wallet(&self, mnemonic: &str) -> Result<DilithiaAccount, String>

func (a *CryptoAdapter) RecoverHDWallet(ctx context.Context, mnemonic string) (Account, error)

DilithiaAccount recoverHdWallet(String mnemonic) throws CryptoException

DilithiaAccount RecoverHdWallet(string mnemonic)

Parameter	Type	Description
`mnemonic`	`string`	A valid BIP-39 mnemonic

Returns: A DilithiaAccount with address, public key, secret key, and accountIndex = 0.

`recoverHdWalletAccount`¶

Recover a specific HD wallet account by index from a mnemonic.

TypeScriptPythonRustGoJavaC#

recoverHdWalletAccount(mnemonic: string, accountIndex: number): Promise<DilithiaAccount>

def recover_hd_wallet_account(self, mnemonic: str, account_index: int) -> DilithiaAccount

fn recover_hd_wallet_account(&self, mnemonic: &str, account_index: u32) -> Result<DilithiaAccount, String>

func (a *CryptoAdapter) RecoverHDWalletAccount(ctx context.Context, mnemonic string, accountIndex int) (Account, error)

DilithiaAccount recoverHdWalletAccount(String mnemonic, int accountIndex) throws CryptoException

DilithiaAccount RecoverHdWalletAccount(string mnemonic, int accountIndex)

Parameter	Type	Description
`mnemonic`	`string`	A valid BIP-39 mnemonic
`accountIndex`	`uint`	The HD derivation index (0-based)

Returns: A DilithiaAccount for the specified derivation index.

`createHdWalletFileFromMnemonic`¶

Create an encrypted wallet file for the root account (index 0) from a mnemonic and password.

TypeScriptPythonRustGoJavaC#

createHdWalletFileFromMnemonic(mnemonic: string, password: string): Promise<DilithiaAccount>

def create_hd_wallet_file_from_mnemonic(self, mnemonic: str, password: str) -> DilithiaAccount

fn create_hd_wallet_file_from_mnemonic(&self, mnemonic: &str, password: &str) -> Result<DilithiaAccount, String>

func (a *CryptoAdapter) CreateHDWalletFileFromMnemonic(ctx context.Context, mnemonic, password string) (Account, error)

DilithiaAccount createHdWalletFileFromMnemonic(String mnemonic, String password) throws CryptoException

DilithiaAccount CreateHdWalletFileFromMnemonic(string mnemonic, string password)

Parameter	Type	Description
`mnemonic`	`string`	A valid BIP-39 mnemonic
`password`	`string`	Encryption password for the wallet file

Returns: A DilithiaAccount whose walletFile field contains the encrypted wallet data.

`createHdWalletAccountFromMnemonic`¶

Create an encrypted wallet file for a specific HD account index.

TypeScriptPythonRustGoJavaC#

createHdWalletAccountFromMnemonic(mnemonic: string, password: string, accountIndex: number): Promise<DilithiaAccount>

def create_hd_wallet_account_from_mnemonic(self, mnemonic: str, password: str, account_index: int) -> DilithiaAccount

fn create_hd_wallet_account_from_mnemonic(&self, mnemonic: &str, password: &str, account_index: u32) -> Result<DilithiaAccount, String>

func (a *CryptoAdapter) CreateHDWalletAccountFromMnemonic(ctx context.Context, mnemonic, password string, accountIndex int) (Account, error)

DilithiaAccount createHdWalletAccountFromMnemonic(String mnemonic, String password, int accountIndex) throws CryptoException

DilithiaAccount CreateHdWalletAccountFromMnemonic(string mnemonic, string password, int accountIndex)

Parameter	Type	Description
`mnemonic`	`string`	A valid BIP-39 mnemonic
`password`	`string`	Encryption password for the wallet file
`accountIndex`	`uint`	HD derivation index

Returns: A DilithiaAccount with an encrypted walletFile for the given index.

`recoverWalletFile`¶

Recover an account from a previously saved encrypted wallet file.

TypeScriptPythonRustGoJavaC#

recoverWalletFile(walletFile: WalletFile, mnemonic: string, password: string): Promise<DilithiaAccount>

def recover_wallet_file(self, wallet_file: WalletFile, mnemonic: str, password: str) -> DilithiaAccount

fn recover_wallet_file(&self, wallet_file: &WalletFile, mnemonic: &str, password: &str) -> Result<DilithiaAccount, String>

func (a *CryptoAdapter) RecoverWalletFile(ctx context.Context, walletFile WalletFile, mnemonic, password string) (Account, error)

DilithiaAccount recoverWalletFile(Map<String, Object> walletFile, String mnemonic, String password) throws CryptoException

DilithiaAccount RecoverWalletFile(Dictionary<string, object> walletFile, string mnemonic, string password)

Parameter	Type	Description
`walletFile`	`WalletFile`	The encrypted wallet file object
`mnemonic`	`string`	The mnemonic used when creating the wallet
`password`	`string`	The password used when creating the wallet

Returns: A DilithiaAccount with decrypted keys and the wallet file attached.

HD Wallet Derivation¶

`deriveChildSeed`¶

Derive a child seed from a parent seed at a given index. Used for hierarchical deterministic key derivation.

TypeScriptPythonRustGoJavaC#

deriveChildSeed(parentSeedHex: string, index: number): Promise<string>

def derive_child_seed(self, parent_seed_hex: str, index: int) -> str

fn derive_child_seed(&self, parent_seed_hex: &str, index: u32) -> Result<String, String>

func (a *CryptoAdapter) DeriveChildSeed(ctx context.Context, parentSeedHex string, index int) (string, error)

String deriveChildSeed(String parentSeedHex, int index) throws CryptoException

string DeriveChildSeed(string parentSeedHex, int index)

Parameter	Type	Description
`parentSeedHex`	`string`	Hex-encoded 32-byte parent seed
`index`	`uint`	Child derivation index

Returns: Hex-encoded 32-byte child seed.

Address Operations¶

`addressFromPublicKey`¶

Derive a Dilithia address from a public key.

TypeScriptPythonRustGoJavaC#

addressFromPublicKey(publicKeyHex: string): Promise<string>

def address_from_public_key(self, public_key_hex: str) -> str

fn address_from_public_key(&self, public_key_hex: &str) -> Result<String, String>

func (a *CryptoAdapter) AddressFromPublicKey(ctx context.Context, publicKeyHex string) (string, error)

String addressFromPublicKey(String publicKeyHex) throws CryptoException

string AddressFromPublicKey(string publicKeyHex)

Parameter	Type	Description
`publicKeyHex`	`string`	Hex-encoded ML-DSA-65 public key

Returns: The derived Dilithia address string.

`addressFromPkChecksummed`¶

Derive a checksummed Dilithia address from a public key.

TypeScriptPythonRustGoJavaC#

addressFromPkChecksummed(publicKeyHex: string): Promise<string>

def address_from_pk_checksummed(self, public_key_hex: str) -> str

fn address_from_pk_checksummed(&self, public_key_hex: &str) -> Result<String, String>

func (a *CryptoAdapter) AddressFromPKChecksummed(ctx context.Context, publicKeyHex string) (string, error)

String addressFromPkChecksummed(String publicKeyHex) throws CryptoException

string AddressFromPkChecksummed(string publicKeyHex)

Parameter	Type	Description
`publicKeyHex`	`string`	Hex-encoded ML-DSA-65 public key

Returns: Checksummed Dilithia address.

`addressWithChecksum`¶

Add a checksum to a raw (un-checksummed) Dilithia address.

TypeScriptPythonRustGoJavaC#

addressWithChecksum(rawAddr: string): Promise<string>

def address_with_checksum(self, raw_addr: str) -> str

fn address_with_checksum(&self, raw_addr: &str) -> Result<String, String>

func (a *CryptoAdapter) AddressWithChecksum(ctx context.Context, rawAddr string) (string, error)

String addressWithChecksum(String rawAddr) throws CryptoException

string AddressWithChecksum(string rawAddr)

Parameter	Type	Description
`rawAddr`	`string`	Raw Dilithia address

Returns: Address with an embedded checksum.

`validateAddress`¶

Validate a Dilithia address (including checksum verification).

TypeScriptPythonRustGoJavaC#

validateAddress(addr: string): Promise<string>

def validate_address(self, addr: str) -> str

fn validate_address(&self, addr: &str) -> Result<String, String>

func (a *CryptoAdapter) ValidateAddress(ctx context.Context, addr string) (string, error)

String validateAddress(String addr) throws CryptoException

string ValidateAddress(string addr)

Parameter	Type	Description
`addr`	`string`	Address to validate

Returns: The normalized address on success. Throws/returns error if invalid.

Signing Operations¶

`signMessage`¶

Sign a message using an ML-DSA-65 secret key.

TypeScriptPythonRustGoJavaC#

signMessage(secretKeyHex: string, message: string): Promise<DilithiaSignature>

def sign_message(self, secret_key_hex: str, message: str) -> DilithiaSignature

fn sign_message(&self, secret_key_hex: &str, message: &str) -> Result<DilithiaSignature, String>

func (a *CryptoAdapter) SignMessage(ctx context.Context, secretKeyHex, message string) (Signature, error)

DilithiaSignature signMessage(String secretKeyHex, String message) throws CryptoException

DilithiaSignature SignMessage(string secretKeyHex, string message)

Parameter	Type	Description
`secretKeyHex`	`string`	Hex-encoded ML-DSA-65 secret key
`message`	`string`	The message to sign

Returns: A DilithiaSignature containing the algorithm identifier ("mldsa65") and the hex-encoded signature.

`verifyMessage`¶

Verify a signature against a public key and message.

TypeScriptPythonRustGoJavaC#

verifyMessage(publicKeyHex: string, message: string, signatureHex: string): Promise<boolean>

def verify_message(self, public_key_hex: str, message: str, signature_hex: str) -> bool

fn verify_message(&self, public_key_hex: &str, message: &str, signature_hex: &str) -> Result<bool, String>

func (a *CryptoAdapter) VerifyMessage(ctx context.Context, publicKeyHex, message, signatureHex string) (bool, error)

boolean verifyMessage(String publicKeyHex, String message, String signatureHex) throws CryptoException

bool VerifyMessage(string publicKeyHex, string message, string signatureHex)

Parameter	Type	Description
`publicKeyHex`	`string`	Hex-encoded ML-DSA-65 public key
`message`	`string`	The original message
`signatureHex`	`string`	Hex-encoded signature to verify

Returns: true if the signature is valid, false otherwise.

Validation Operations¶

`validatePublicKey`¶

Validate that a hex string represents a well-formed ML-DSA-65 public key.

TypeScriptPythonRustGoJavaC#

validatePublicKey(publicKeyHex: string): Promise<void>

def validate_public_key(self, public_key_hex: str) -> None

fn validate_public_key(&self, public_key_hex: &str) -> Result<(), String>

func (a *CryptoAdapter) ValidatePublicKey(ctx context.Context, publicKeyHex string) error

void validatePublicKey(String publicKeyHex) throws CryptoException

void ValidatePublicKey(string publicKeyHex)

Parameter	Type	Description
`publicKeyHex`	`string`	Hex-encoded public key to check

Returns: Nothing on success. Throws/returns error if invalid.

`validateSecretKey`¶

Validate that a hex string represents a well-formed ML-DSA-65 secret key.

TypeScriptPythonRustGoJavaC#

validateSecretKey(secretKeyHex: string): Promise<void>

def validate_secret_key(self, secret_key_hex: str) -> None

fn validate_secret_key(&self, secret_key_hex: &str) -> Result<(), String>

func (a *CryptoAdapter) ValidateSecretKey(ctx context.Context, secretKeyHex string) error

void validateSecretKey(String secretKeyHex) throws CryptoException

void ValidateSecretKey(string secretKeyHex)

Parameter	Type	Description
`secretKeyHex`	`string`	Hex-encoded secret key to check

Returns: Nothing on success. Throws/returns error if invalid.

`validateSignature`¶

Validate that a hex string represents a well-formed ML-DSA-65 signature (structural check only -- does not verify against a message).

TypeScriptPythonRustGoJavaC#

validateSignature(signatureHex: string): Promise<void>

def validate_signature(self, signature_hex: str) -> None

fn validate_signature(&self, signature_hex: &str) -> Result<(), String>

func (a *CryptoAdapter) ValidateSignature(ctx context.Context, signatureHex string) error

void validateSignature(String signatureHex) throws CryptoException

void ValidateSignature(string signatureHex)

Parameter	Type	Description
`signatureHex`	`string`	Hex-encoded signature to validate

Returns: Nothing on success. Throws/returns error if structurally invalid.

Key Generation¶

`keygen`¶

Generate a new random ML-DSA-65 keypair using a secure random source.

TypeScriptPythonRustGoJavaC#

keygen(): Promise<DilithiaKeypair>

def keygen(self) -> DilithiaKeypair

fn keygen(&self) -> Result<DilithiaKeypair, String>

func (a *CryptoAdapter) Keygen(ctx context.Context) (Keypair, error)

DilithiaKeypair keygen() throws CryptoException

DilithiaKeypair Keygen()

Returns: A DilithiaKeypair containing the secret key, public key, and derived address.

`keygenFromSeed`¶

Generate a deterministic ML-DSA-65 keypair from a 32-byte seed.

TypeScriptPythonRustGoJavaC#

keygenFromSeed(seedHex: string): Promise<DilithiaKeypair>

def keygen_from_seed(self, seed_hex: str) -> DilithiaKeypair

fn keygen_from_seed(&self, seed_hex: &str) -> Result<DilithiaKeypair, String>

func (a *CryptoAdapter) KeygenFromSeed(ctx context.Context, seedHex string) (Keypair, error)

DilithiaKeypair keygenFromSeed(String seedHex) throws CryptoException

DilithiaKeypair KeygenFromSeed(string seedHex)

Parameter	Type	Description
`seedHex`	`string`	Hex-encoded 32-byte seed

Returns: A deterministic DilithiaKeypair. The same seed always produces the same keypair.

Warning

The seed must be exactly 32 bytes (64 hex characters). Using a shorter or longer value will produce an error.

Hash Operations¶

`hashHex`¶

Hash hex-encoded data using the currently configured hash algorithm.

TypeScriptPythonRustGoJavaC#

hashHex(dataHex: string): Promise<string>

def hash_hex(self, data_hex: str) -> str

fn hash_hex(&self, data_hex: &str) -> Result<String, String>

func (a *CryptoAdapter) HashHex(ctx context.Context, dataHex string) (string, error)

String hashHex(String dataHex) throws CryptoException

string HashHex(string dataHex)

Parameter	Type	Description
`dataHex`	`string`	Hex-encoded data to hash

Returns: Hex-encoded hash digest.

`setHashAlg`¶

Set the hash algorithm used by hashHex and related operations.

TypeScriptPythonRustGoJavaC#

setHashAlg(alg: string): Promise<void>

def set_hash_alg(self, alg: str) -> None

fn set_hash_alg(&self, alg: &str) -> Result<(), String>

func (a *CryptoAdapter) SetHashAlg(ctx context.Context, alg string) error

void setHashAlg(String alg) throws CryptoException

void SetHashAlg(string alg)

Parameter	Type	Description
`alg`	`string`	One of: `"sha3_512"`, `"blake2b512"`, `"blake3_256"`

Returns: Nothing on success. Throws/returns error for unknown algorithms.

`currentHashAlg`¶

Return the name of the currently active hash algorithm.

TypeScriptPythonRustGoJavaC#

currentHashAlg(): Promise<string>

def current_hash_alg(self) -> str

fn current_hash_alg(&self) -> String

func (a *CryptoAdapter) CurrentHashAlg(ctx context.Context) (string, error)

String currentHashAlg()

string CurrentHashAlg()

Returns: The active algorithm name (e.g. "sha3_512").

`hashLenHex`¶

Return the output length (in hex characters) of the current hash algorithm.

TypeScriptPythonRustGoJavaC#

hashLenHex(): Promise<number>

def hash_len_hex(self) -> int

fn hash_len_hex(&self) -> usize

func (a *CryptoAdapter) HashLenHex(ctx context.Context) (int, error)

int hashLenHex()

int HashLenHex()

Returns: The number of hex characters in a hash digest for the current algorithm.

`constantTimeEq`¶

Compare two hex-encoded byte strings in constant time, preventing timing side-channel attacks.

TypeScriptPythonRustGoJavaC#

constantTimeEq(aHex: string, bHex: string): Promise<boolean>

def constant_time_eq(self, a_hex: str, b_hex: str) -> bool

fn constant_time_eq(&self, a_hex: &str, b_hex: &str) -> Result<bool, String>

func (a *CryptoAdapter) ConstantTimeEq(ctx context.Context, aHex, bHex string) (bool, error)

boolean constantTimeEq(String aHex, String bHex) throws CryptoException

bool ConstantTimeEq(string aHex, string bHex)

Parameter	Type	Description
`aHex`	`string`	First hex-encoded value
`bHex`	`string`	Second hex-encoded value

Returns: true if the decoded byte sequences are equal, false otherwise. The comparison runs in constant time regardless of where the values differ.

Tip

Always use constantTimeEq when comparing secrets, signatures, or hashes to avoid leaking information through timing.

Crypto Adapter API Reference¶

Mnemonic Operations¶

generateMnemonic¶

validateMnemonic¶

seedFromMnemonic¶

Wallet Operations¶

recoverHdWallet¶

recoverHdWalletAccount¶

createHdWalletFileFromMnemonic¶

createHdWalletAccountFromMnemonic¶

recoverWalletFile¶

HD Wallet Derivation¶

deriveChildSeed¶

Address Operations¶

addressFromPublicKey¶

addressFromPkChecksummed¶

addressWithChecksum¶

validateAddress¶

Signing Operations¶

signMessage¶

verifyMessage¶

Validation Operations¶

validatePublicKey¶

validateSecretKey¶

validateSignature¶

Key Generation¶

keygen¶

keygenFromSeed¶

Hash Operations¶

hashHex¶

setHashAlg¶

currentHashAlg¶

hashLenHex¶

constantTimeEq¶

`generateMnemonic`¶

`validateMnemonic`¶

`seedFromMnemonic`¶

`recoverHdWallet`¶

`recoverHdWalletAccount`¶

`createHdWalletFileFromMnemonic`¶

`createHdWalletAccountFromMnemonic`¶

`recoverWalletFile`¶

`deriveChildSeed`¶

`addressFromPublicKey`¶

`addressFromPkChecksummed`¶

`addressWithChecksum`¶

`validateAddress`¶

`signMessage`¶

`verifyMessage`¶

`validatePublicKey`¶

`validateSecretKey`¶

`validateSignature`¶

`keygen`¶

`keygenFromSeed`¶

`hashHex`¶

`setHashAlg`¶

`currentHashAlg`¶

`hashLenHex`¶

`constantTimeEq`¶