Scallop Crypto Keys

Cryptographic Keys

Generate, import, and manage Ed25519 keypairs for Sui transactions.

Overview

The SDK provides SuiKeypair for Ed25519 key management. It handles key generation, multiple import formats, address derivation, and transaction signing.

Generate a New Keypair

from sui_scallop_sdk import SuiKeypair

keypair = SuiKeypair.generate()

print(f"Address: {keypair.address}")
print(f"Public Key (base64): {keypair.public_key_base64}")
print(f"Private Key (hex): {keypair.private_key.hex()}")

Import Existing Keys

From Bech32 (Sui Wallet Format)

The standard format exported by Sui wallets (suiprivkey1...):

keypair = SuiKeypair.from_bech32("suiprivkey1qp...")
print(f"Address: {keypair.address}")

From Hex

# With or without 0x prefix
keypair = SuiKeypair.from_hex("0x1a2b3c4d...")
keypair = SuiKeypair.from_hex("1a2b3c4d...")

From Base64

Supports multiple lengths:

• 32 bytes: raw private key
• 33 bytes: scheme flag (0x00) + private key
• 64 bytes: full keypair (private + public)

keypair = SuiKeypair.from_base64("Gis7ChsKBwQ...")

From Raw Bytes

private_key_bytes = bytes.fromhex("1a2b3c4d" * 8)  # 32 bytes
keypair = SuiKeypair(private_key_bytes)

Properties

keypair.private_key       # bytes: 32-byte raw private key
keypair.public_key        # bytes: 32-byte Ed25519 public key
keypair.public_key_base64 # str: base64-encoded with 0x00 scheme prefix
keypair.address           # str: Sui address (0x-prefixed, derived from public key)

Signing

Sign Raw Message

message = b"Hello, Sui!"
signature = keypair.sign(message)  # 64-byte Ed25519 signature

Sign Transaction

# tx_bytes from ScallopTxBlock.build_bcs_transaction()
signature = keypair.sign_transaction(tx_bytes)
# Returns base64 string: scheme (1 byte) + signature (64 bytes) + public key (32 bytes)

The sign_transaction method automatically:

1. Prepends the Sui intent message ([0, 0, 0] + tx_bytes)
2. Hashes with Blake2b-256
3. Signs with Ed25519
4. Encodes as base64 with scheme flag

Address Derivation

from sui_scallop_sdk.crypto import derive_address_from_public_key, SIGNATURE_SCHEME_ED25519

# Derive address from a raw public key
address = derive_address_from_public_key(
    public_key=public_key_bytes,   # 32 bytes
    scheme=SIGNATURE_SCHEME_ED25519,  # 0x00 (default)
)
print(f"Address: {address}")

Algorithm: Blake2b-256(scheme_flag || public_key_bytes) → hex with 0x prefix.

Signature Schemes

from sui_scallop_sdk.crypto import (
    SIGNATURE_SCHEME_ED25519,    # 0x00 - Default, used by SuiKeypair
    SIGNATURE_SCHEME_SECP256K1,  # 0x01
    SIGNATURE_SCHEME_SECP256R1,  # 0x02
)

The SDK only implements Ed25519 signing. The scheme constants are provided for address derivation compatibility.

Using with ScallopClient

from sui_scallop_sdk import ScallopClient, SuiKeypair

# Option 1: Pass key at construction
client = ScallopClient(
    secret_key="suiprivkey1...",
    network="mainnet",
)

# Option 2: Set keypair after construction
client = ScallopClient(network="mainnet")
keypair = SuiKeypair.generate()
client.set_keypair(keypair)

# Option 3: Set on builder
builder = client.create_builder()
builder.set_keypair(keypair)

Complete Example: Create Wallet and Fund

from sui_scallop_sdk import SuiKeypair, ScallopClient

# Generate new wallet
keypair = SuiKeypair.generate()
print(f"New wallet address: {keypair.address}")
print(f"Private key (save securely!): suiprivkey format")

# Use with Scallop
client = ScallopClient(network="mainnet")
client.set_keypair(keypair)

# Check balance
query = client.create_query()
balance = query.get_balance(keypair.address)
print(f"SUI Balance: {balance / 1e9:.4f}")

Security Notes

• Never hardcode private keys in source code
• Use environment variables or secure key management
• The generate() method uses os.urandom() for cryptographic randomness
• Private keys are 32 bytes — store them securely

import os

# Good: from environment
keypair = SuiKeypair.from_bech32(os.environ["SUI_PRIVATE_KEY"])

# Good: from file
with open("~/.sui/key.bech32") as f:
    keypair = SuiKeypair.from_bech32(f.read().strip())

References

• Sui Basics - Sui blockchain fundamentals
• Client Setup - SDK initialization