# Scallop Crypto Keys

> Sui keypair management - generate, import, and sign with Ed25519 keys. Use when user says "keypair", "private key", "public key", "generate key", "sign transaction", "wallet address", "bech32", "suiprivkey", "Ed25519", or asks about creating wallets, managing keys, deriving addresses, or signing on Sui blockchain.

- Skill: `scallop-io/scallop-crypto-keys` (Agent Skill)
- Install (CLI): `npx skillmds@latest add scallop-io/scallop-crypto-keys`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scallop-io/scallop-crypto-keys/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: scallop-io (https://skillmd.com/u/scallop-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/scallop-io/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

```python
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...`):

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

### From Hex

```python
# 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)

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

### From Raw Bytes

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

## Properties

```python
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

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

### Sign Transaction

```python
# 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

```python
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

```python
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

```python
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

```python
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

```python
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](../../references/sui-basics.md) - Sui blockchain fundamentals
- [Client Setup](../scallop-client-setup/SKILL.md) - SDK initialization