EncryptionNonce

12-byte AES-GCM encryption nonce

12-byte AES-GCM encryption nonce used for calldata encryption.

Overview

EncryptionNonce is a fixed-size byte type representing a 12-byte nonce for AES-GCM encryption. It's used in Seismic transactions to ensure each encryption operation is unique.

Definition

class EncryptionNonce(HexBytes):
    """12-byte AES-GCM encryption nonce."""
    _size = 12

Inheritance

• Inherits from HexBytes (from the hexbytes package)

• HexBytes itself inherits from Python's bytes type

• Fully compatible with any API expecting bytes

Construction

EncryptionNonce can be constructed from:

• Hex strings (with or without "0x" prefix)

• Raw bytes objects

• Integer values (converted to 12-byte big-endian)

Parameters

Parameter	Type	Required	Description
val	bytes | str | int	Yes	The value to convert to a 12-byte nonce

Raises

• ValueError - If the resulting length is not exactly 12 bytes

Examples

From Hex String

from seismic_web3 import EncryptionNonce

# With 0x prefix
nonce = EncryptionNonce("0x123456789012345678901234")

# Without prefix
nonce = EncryptionNonce("123456789012345678901234")

From Raw Bytes

import os
from seismic_web3 import EncryptionNonce

# Generate random 12 bytes
nonce = EncryptionNonce(os.urandom(12))

From Integer

from seismic_web3 import EncryptionNonce

# Convert integer to 12-byte big-endian
nonce = EncryptionNonce(12345)  # 0x000000000000000000003039

Use in Security Parameters

from seismic_web3 import SeismicSecurityParams, EncryptionNonce
import os

# Explicitly provide nonce (usually auto-generated)
nonce = EncryptionNonce(os.urandom(12))
security_params = SeismicSecurityParams(
    encryption_nonce=nonce,
    blocks_window=100,
)

Length Validation

from seismic_web3 import EncryptionNonce

# This will raise ValueError
try:
    invalid = EncryptionNonce("0x1234")  # Too short (2 bytes)
except ValueError as e:
    print(e)  # "EncryptionNonce: expected 12 bytes, got 2"

try:
    invalid = EncryptionNonce(os.urandom(16))  # Too long (16 bytes)
except ValueError as e:
    print(e)  # "EncryptionNonce: expected 12 bytes, got 16"

Methods

to_0x_hex()

Returns the hex string representation with "0x" prefix.

nonce = EncryptionNonce(os.urandom(12))
hex_str = nonce.to_0x_hex()  # "0xabcd...ef"

Properties

• Immutable - Cannot be modified after construction

• Hashable - Can be used as dictionary keys or in sets

• 12 bytes - Always exactly 12 bytes

• Compatible with bytes - Passes isinstance(x, bytes) checks

AES-GCM Nonce Requirements

The 12-byte length is optimal for AES-GCM:

• Must be unique for each encryption with the same key

• 12 bytes is the recommended nonce size for AES-GCM (NIST SP 800-38D)

• Never reuse a nonce with the same key (breaks security)

Automatic Generation

In most cases, you don't need to create nonces manually:

# SDK auto-generates random nonce
result = await contract.write.transfer(recipient, amount)

Only provide explicit nonces when:

• Testing with specific values

• Implementing custom encryption flows

• Debugging transaction construction

Notes

• Used in SeismicElements for encryption_nonce

• Auto-generated by the SDK if not specified in SeismicSecurityParams

• Must be cryptographically random for production use

• Reusing nonces with the same key compromises encryption security

See Also

• Bytes32 - General 32-byte type

• SeismicElements - Uses EncryptionNonce

• SeismicSecurityParams - Optional nonce override

• aes_gcm_encrypt - AES-GCM encryption with nonce

• aes_gcm_decrypt - AES-GCM decryption with nonce