neo-n3-wallet 0.1.0

Neo N3 Python Wallet Library with BIP-39 mnemonic support, HD wallet derivation, and complete key management

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

Feature	Details
BIP-39 Mnemonics	12 / 15 / 18 / 21 / 24 words, 8 languages
HD Derivation	BIP-32 over secp256r1 (NIST P-256), BIP-44 path m/44'/888'/0'/0/0
NEP-2 Encryption	scrypt + AES-256-ECB passphrase-protected private keys
NEP-6 Wallets	Save / load standard Neo wallet JSON files
WIF	Wallet Import Format encode / decode
Signing	secp256r1 sign & verify

---

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

MIT