Metadata-Version: 2.4
Name: neo-n3-wallet
Version: 0.1.0
Summary: Neo N3 Python Wallet Library with BIP-39 mnemonic support, HD wallet derivation, and complete key management
Author: Neo N3 Python Community
License: MIT
Project-URL: Homepage, https://github.com/neo-project/neo-n3-python-wallet
Project-URL: Documentation, https://github.com/neo-project/neo-n3-python-wallet#readme
Project-URL: Repository, https://github.com/neo-project/neo-n3-python-wallet
Project-URL: Issues, https://github.com/neo-project/neo-n3-python-wallet/issues
Keywords: neo,neo3,blockchain,wallet,bip39,bip32,bip44,cryptocurrency,mnemonic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: mnemonic>=0.20
Requires-Dist: ecdsa>=0.18.0
Requires-Dist: base58>=2.1.1
Requires-Dist: pycryptodome>=3.19.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.0.285; extra == "dev"

# 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

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

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

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

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

---

## Running Tests

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