neo-n3-wallet

The Python wallet library for Neo N3 — with BIP-39 mnemonic support, HD key derivation, and full key management. Filling the gap that Rust and neon-js filled for other languages.

Aligned with Neo-CLI v3.10.0's expanded BIP-39 support (12 and 24-word phrases).

pip install neo-n3-wallet

Features

What's New in v0.1.2 — NEP-6 Compliance Fix

Full NEP-6 spec compliance after COZ team review:

• NFC password normalization — passphrase is Unicode NFC-normalized before any scrypt/encrypt/decrypt operation per NEP-2 spec
• Variable scrypt params — wallet JSON n/r/p values are now read and applied instead of ignored
• lock, contract, extra fields — Account now stores and round-trips all NEP-6 fields including contract.script (base64), contract.parameters, contract.deployed, and extra
• Single default account — setting one account as default now clears all others; enforced on load too
• Thread safety — threading.RLock() added to all wallet operations
• wallet.save() password fix — tracks current password so save() always uses the right one after a password change
• Duplicate prevention — derive_accounts() and load() deduplicate by address

Quick Start

from neo_n3_wallet import Wallet, MnemonicManager, Account, KeyPair

# --- Create a brand-new HD wallet (24-word mnemonic) ---
wallet = Wallet.create(word_count=24)
print(wallet.mnemonic)   # 24 BIP-39 words

# Derive the first account (m/44'/888'/0'/0/0)
account = wallet.derive_account(index=0)
print(account.address)   # NXxx...  Neo N3 address

# Derive 5 accounts at once
accounts = wallet.derive_accounts(count=5)

# Save as NEP-6 JSON (accounts are encrypted with the passphrase)
wallet.save("my_wallet.json", passphrase="s3cur3!")

# --- Restore a wallet from an existing mnemonic ---
wallet2 = Wallet.from_mnemonic(
    "abandon abandon abandon ... art",
    passphrase=""          # optional BIP-39 passphrase
)

# --- Load a NEP-6 file ---
loaded = Wallet.load("my_wallet.json", passphrase="s3cur3!")
print(loaded.accounts[0].address)

Mnemonic Management

from neo_n3_wallet import MnemonicManager

m = MnemonicManager()                # default: English
phrase = m.generate(24)              # 24-word mnemonic
assert m.validate(phrase)            # True

seed = m.to_seed(phrase)             # 64-byte BIP-39 seed
entropy = m.to_entropy(phrase)       # recover original entropy
restored = m.from_entropy(entropy)   # back to phrase

# Other languages
m_jp = MnemonicManager("japanese")
phrase_jp = m_jp.generate(12)

Key Pair & Accounts

from neo_n3_wallet import KeyPair, Account

# Random key pair
kp = KeyPair.generate()
print(kp.address)          # Neo N3 address
print(kp.public_key_hex)   # 33-byte compressed public key
print(kp.to_wif())         # WIF-encoded private key

# From WIF
kp2 = KeyPair.from_wif("KwdMAjGmer...")

# Sign & verify
sig = kp.sign(b"my message")
assert kp.verify(b"my message", sig)

# Account with NEP-2 encryption
acct = Account.from_private_key(bytes.fromhex("..."))
nep2 = acct.encrypt("my-passphrase")   # encrypt in-place
acct.lock()                             # wipe key from memory
acct.unlock("my-passphrase")           # restore it

HD Derivation Paths

Neo N3 uses SLIP-0044 coin type 888 and secp256r1:

m / 44' / 888' / account' / change / index

Wallet.derivation_path(account=0, change=0, index=0)
# → "m/44'/888'/0'/0/0"

Running Tests

python -m pytest tests/ -v --no-cov   # fast
python -m pytest tests/ -v            # with coverage

Project Layout

neo_n3_wallet/
├── __init__.py      public API
├── wallet.py        Wallet (HD + NEP-6)
├── account.py       Account (NEP-2 lock/unlock)
├── key_pair.py      KeyPair (sign / verify)
├── mnemonic.py      BIP-39 MnemonicManager
├── hd.py            BIP-32 derivation (secp256r1)
├── nep2.py          NEP-2 encrypt / decrypt
├── wif.py           WIF encode / decode
├── address.py       Neo N3 address utilities
├── crypto.py        secp256r1 primitives
├── constants.py     Neo N3 constants
└── exceptions.py    Custom exceptions

License

Apache 2.0