pysui-crypto

A Python extension providing zkLogin and SEAL threshold encryption support for Sui, extending the pysui SDK.

The library is backed by a Rust crate compiled via PyO3 and maturin, exposing a native Python extension module.

Requirements

• Python 3.10 or later
• pysui — integrated in the upcoming pysui 1.1.0 release (date TBD)

Installation

From PyPI (sdist)

Only a source distribution is published to PyPI. Installing it requires a Rust toolchain and maturin:

pip install maturin
pip install pysui-crypto

Pre-built wheels

Platform wheels for Linux (x86_64, aarch64), Windows (x64), and macOS (x86_64, aarch64) are attached to each GitHub release as zip archives. Download the archive for your platform and install the wheel directly:

pip install pysui_crypto-<version>-<platform>.whl

Build from source

maturin is required to compile the Rust extension:

pip install maturin
maturin develop          # installs into the active virtual environment

To produce a wheel:

maturin build --release --out dist

zkLogin Support

Functions for constructing and submitting zkLogin authenticated transactions on Sui.

generate_ephemeral_keypair(as_secp256r1)

Generate an Ed25519 (default) or secp256r1 ephemeral key pair for nonce construction. Returns {"public_key": bytes, "private_key": bytes}.

extract_jwt_claims(jwt)

Parse a zkLogin JWT and enforce Sui size constraints. Returns (iss, sub, aud, nonce).

compute_nonce(epk_bytes, max_epoch, randomness)

Compute the Poseidon-hashed nonce to embed in the OAuth authorization request.

compute_address_seed(key_claim_name, key_claim_value, audience, user_salt)

Compute the 32-byte BN254/Poseidon address seed from JWT claims and a user salt.

compute_zklogin_address(iss, address_seed, legacy)

Derive the final Blake2b256 Sui address from the issuer string and address seed.

build_zklogin_signature(proof_json, ephemeral_sig, address_seed, max_epoch)

Assemble and BCS-serialize a ZkLoginAuthenticator; returns standard base64 ready for the Sui RPC.

SEAL Support

Functions for SEAL threshold encryption. SEAL requires access to one or more running SEAL key servers; this library provides the client-side cryptographic primitives only.

DemType

Enum of supported data-encapsulation mechanisms: AesGcm256, Hmac256Ctr, Plain.

EncryptedObject

Parse and inspect a SEAL encrypted object (parse(data) / to_bytes()). Exposes version, package_id, id, threshold, services, dem_type.

seal_encrypt(package_id, id, key_servers, public_keys, threshold, data, dem_type, aad)

Threshold-encrypt plaintext using IBE. Returns (ciphertext, dem_key) where dem_key is non-None only for Plain mode.

seal_decrypt(encrypted_object, user_secret_keys, public_keys)

Decrypt a SEAL ciphertext using user secret keys collected from key servers.

generate_session_keypair()

Generate an Ed25519 session key pair for SEAL key server authentication. Returns {"public_key": bytes, "private_key": bytes}.

generate_elgamal_keypair()

Generate an ElGamal key pair for SEAL key server encryption. Returns {"public_key": bytes, "private_key": bytes}.

elgamal_decrypt(sk, encryption)

Decrypt an ElGamal ciphertext using a private key.

verify_user_secret_key(usk, full_id, public_key)

Verify a user secret key returned by a key server; raises ValueError on failure.

seal_signed_message(package_id, session_vk, creation_time, ttl_min)

Construct the key server request message for signing; returns hex-encoded bytes.

License

Apache-2.0