crypto

Module for cryptographic operations.

This module provides functions for generating mnemonics, deriving key pairs, signing data, and generating random bytes.

Examples:

// Generate a new mnemonic and derive a key pair
val words = crypto.createMnemonic();
val kp = words.toKeyPair();

// Sign a cell
val signature = crypto.sign(kp.privateKey, myCell);

// Generate random bytes
val randomBytes = crypto.getSecureRandomBytes(32);

Definitions

crypto

struct crypto

KeyPair

struct KeyPair {
    privateKey: int
    publicKey: int
}

Represents an Ed25519 key pair.

The privateKey is a 256-bit seed used to derive the full signing key. The publicKey is the corresponding 256-bit Ed25519 public key.

Both fields are plain int for compatibility with TVM builtins like isSignatureValid.

Mnemonic

type Mnemonic = array<string>

crypto.createMnemonic

fun crypto.createMnemonic(): Mnemonic

Generates a new random BIP39-compatible mnemonic phrase.

Returns an array of 24 English words that can be used to derive a key pair via Mnemonic.toKeyPair.

Example:

val words = crypto.createMnemonic();
// words is an array of 24 strings

Mnemonic.toKeyPair

fun Mnemonic.toKeyPair(self): KeyPair

Derives an Ed25519 KeyPair from a mnemonic phrase.

self must be a Mnemonic (array<string>) of 24 valid BIP39 words, for example as returned by crypto.createMnemonic.

Example:

val words = crypto.createMnemonic();
val kp = words.toKeyPair();
// kp.privateKey — 32-byte seed
// kp.publicKey  — 32-byte public key

crypto.sign

fun crypto.sign(privateKey: int, data: cell): slice

Signs a cell by hashing it and then signing the hash.

This is a convenience wrapper around crypto.rawSign that first computes the cell hash and then signs it with the given private key. Returns a 512-bit (64-byte) Ed25519 signature as a slice.

Example:

val kp = words.toKeyPair();
val signature = crypto.sign(kp.privateKey, myCell);

crypto.rawSign

fun crypto.rawSign(privateKey: int, data: int): slice

Signs a raw 256-bit hash with the given private key using Ed25519.

Returns a 512-bit (64-byte) Ed25519 signature as a slice. The privateKey must be a 32-byte seed as int

Example:

val kp = words.toKeyPair();
val hash = myCell.hash();
val signature = crypto.rawSign(kp.privateKey, hash);

crypto.getSecureRandomBytes

fun crypto.getSecureRandomBytes(bytesNum: uint16): slice

Generates cryptographically secure random bytes.

Returns a slice containing bytesNum random bytes.

Current accepted range is 1..127. 0 and values >= 128 fail.

Example:

val randomBytes = crypto.getSecureRandomBytes(32);

crypto.getFastRandomBytes

fun crypto.getFastRandomBytes(bytesNum: uint16, seed: int? = null): slice

Generates fast (non-cryptographic) deterministic random bytes using a seed.

If seed is not provided, the current blockchain.now() value is used at the moment of the call. The maximum bytesNum is 127; values >= 128 will throw an error

Same seed always produces the same output, which is useful for reproducible tests.

Practical determinism note:

• Passing an explicit seed gives fully time-independent reproducibility.
• Omitting seed makes the result deterministic only for a fixed blockchain time. In tests, testing.setNow(...) can be used to freeze that time.
• If the blockchain time changes between calls, the output changes too.

Example:

val bytes = crypto.getFastRandomBytes(16, 42);

Example with fixed emulation time:

testing.setNow(1700004321);
val a = crypto.getFastRandomBytes(16);
val b = crypto.getFastRandomBytes(16);
// `a == b` because both calls used the same `blockchain.now()`

crypto.generateKeyPair

fun crypto.generateKeyPair(): KeyPair

Generates a random Ed25519 KeyPair without creating a mnemonic.

Much faster than crypto.createMnemonic + Mnemonic.toKeyPair because it skips BIP39 word generation. Use this when you don't need the mnemonic itself.

Example:

val kp = crypto.generateKeyPair();

crypto.seedToKeyPair

fun crypto.seedToKeyPair(seed: uint256): KeyPair

Derives an Ed25519 KeyPair from a 256-bit seed. The seed is used as the Ed25519 private key seed; the corresponding public key is computed deterministically. The same seed always yields the same key pair.

Example:

val kp = crypto.seedToKeyPair(mySeed);