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.rawSignSlice

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

Signs the data bytes of a slice with the given private key using Ed25519.

Unlike crypto.rawSign (which signs a fixed 32-byte hash, matching the on-chain isSignatureValid / CHKSIGNU check), this signs the raw bytes of data itself — the counterpart of isSliceSignatureValid / CHKSIGNS. The semantics mirror CHKSIGNS exactly: only the slice's own data bits are signed (references are ignored, just as the verifier ignores them), and the bit length must be a multiple of 8.

Returns a 512-bit (64-byte) Ed25519 signature as a slice.

Example:

val kp = crypto.generateKeyPair();
val message = beginCell().storeUint(0xdeadbeef, 32).toSlice();
val signature = crypto.rawSignSlice(kp.privateKey, message);
// isSliceSignatureValid(message, signature, kp.publicKey) == true

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): slice

Generates fast (non-cryptographic) random bytes from the current VM random state.

Each call consumes from the VM's random number generator (via random.uint256), so successive calls return different bytes. The maximum bytesNum is 127; values >= 128 will throw an error.

Reproducibility: The output is deterministic for a fixed VM random seed. In tests, call testing.setRandomSeed (or random.setSeed) with an explicit seed before calling this function to make the result reproducible.

Example:

val bytes = crypto.getFastRandomBytes(16);

Example with a fixed random seed:

testing.setRandomSeed(42);
val a = crypto.getFastRandomBytes(16);
testing.setRandomSeed(42);
val b = crypto.getFastRandomBytes(16);
// `a == b` because both calls started from the same VM random seed

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);