kaspanet · smartgoo · May 2, 2026 · Apr 29, 2026 · Apr 30, 2026 · May 1, 2026
diff --git a/README.md b/README.md
@@ -16,8 +16,9 @@ A native extension module, `kaspa`, is built from these bindings using [PyO3](ht
 
 This SDK provides features in two primary categories:
 
-- RPC Client - Connect to Kaspa nodes & PNN, perform calls, subscriptions, etc.
-- Wallet Management - Wallet related functionality (key management, derivation, addresses, transactions, etc.).
+- RPC Client — RPC API for the Kaspa node using WebSockets.
+- Wallet SDK — Bindings for wallet-related primitives such as key management, derivation, and transactions.
+- Managed Wallet — a fully managed interface for the Rusty Kaspa Wallet API bundled into one Python class.
 
 This package strives to mirror the [Kaspa WASM32 SDK](https://kaspa.aspectron.org/docs/) from a feature and API perspective, while respecting Python conventions.
 

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -20,6 +20,7 @@
 - Wallet-specific exception classes populated into the `kaspa.exceptions` submodule, covering the rusty-kaspa wallet error variants (e.g. `WalletInsufficientFundsError`, `WalletAccountNotFoundError`, `WalletNotSyncedError`, etc.).
 - Examples under `examples/wallet/` demonstrating wallet usage
 - Pytest options `--network-id` and `--rpc-url` for targeting integration tests at a specific network / node.
+- TypedDicts for `RpcClient` subscription event payloads — `BlockAddedEvent`, `VirtualChainChangedEvent`, `FinalityConflictEvent`, `FinalityConflictResolvedEvent`, `UtxosChangedEvent`, `SinkBlueScoreChangedEvent`, `VirtualDaaScoreChangedEvent`, `PruningPointUtxoSetOverrideEvent`, `NewBlockTemplateEvent`, `ConnectEvent`, `DisconnectEvent` — and their notification body TypedDicts (`RpcBlockAddedNotification`, etc.) for typing event-listener callbacks.
 
 ### Changed
 - `py_error_map!` macro extended to register wallet exception variants into the `kaspa.exceptions` submodule.
@@ -28,6 +29,7 @@
 - `pyproject.toml`: set `python-source = "python"` and moved the package stub tree under `python/kaspa/` (`kaspa.pyi` → `python/kaspa/__init__.pyi`).
 - `Hash` accepts `str` in addition to `Hash` instances wherever it is used as an argument, and gained `to_hex()` and `__repr__` methods.
 - Added `Balance` `__repr__` method.
+- Documentation site reorganization
 
 ### Fixed
 - `AccountDescriptor.__repr__` now correctly renders optional fields.

diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,40 @@
+# Examples
+
+Runnable examples live in the SDK repository, not in these docs. Each
+script is self-contained and demonstrates one feature end-to-end.
+
+[Browse examples on GitHub →](https://github.com/kaspanet/kaspa-python-sdk/tree/main/examples)
+
+## What's there
+
+- **[`rpc/`](https://github.com/kaspanet/kaspa-python-sdk/tree/main/examples/rpc)**
+  — connecting via the resolver, calling RPC methods, subscribing to
+  notifications.
+- **[`wallet/`](https://github.com/kaspanet/kaspa-python-sdk/tree/main/examples/wallet)**
+  — managed `Wallet` lifecycle: creating, opening, accounts, sending,
+  export/import.
+- **[`transactions/`](https://github.com/kaspanet/kaspa-python-sdk/tree/main/examples/transactions)**
+  — building transactions with the `Generator`, `UtxoContext`,
+  multisig, and KRC-20 deploys.
+- **[`derivation.py`](https://github.com/kaspanet/kaspa-python-sdk/blob/main/examples/derivation.py)**
+  — BIP-32 / BIP-44 key derivation.
+- **[`mnemonic.py`](https://github.com/kaspanet/kaspa-python-sdk/blob/main/examples/mnemonic.py)**
+  — generating and restoring mnemonics.
+- **[`message_signing.py`](https://github.com/kaspanet/kaspa-python-sdk/blob/main/examples/message_signing.py)**
+  — signing and verifying messages with a private key.
+- **[`addresses.py`](https://github.com/kaspanet/kaspa-python-sdk/blob/main/examples/addresses.py)**
+  — encoding, parsing, and validating Kaspa addresses.
+
+## Running them
+
+Clone the repo, install the SDK, and run any script directly:
+
+```bash
+git clone https://github.com/kaspanet/kaspa-python-sdk
+cd kaspa-python-sdk
+pip install kaspa
+python examples/rpc/all_calls.py
+```
+
+See [Installation](getting-started/installation.md) for build-from-source
+instructions.
diff --git a/docs/getting-started/examples.md b/docs/getting-started/examples.md
diff --git a/docs/getting-started/security.md b/docs/getting-started/security.md
@@ -0,0 +1,68 @@
+# Security
+
+The SDK gives you direct access to mnemonics, seeds, private keys, and wallet
+files. Anyone who obtains them can spend your funds. Treat them with care.
+
+## What counts as secret material
+
+| Type | Compromise consequence |
+| --- | --- |
+| **Mnemonic phrase** / **BIP-39 seed** | Full recovery of every wallet derived from it |
+| **Extended private key (XPrv)** | Full control of every account derived under it |
+| **Private key** | Full control of every UTXO that pays its address |
+| **Wallet secret** (password) | Decrypts the on-disk wallet file |
+| **Wallet file** (`.kaspa/`) | Encrypted, but only as strong as the password |
+
+## Why Python makes this hard
+
+Python wasn't designed for handling secrets. Be aware of:
+
+- **No secure memory.** `str` and `bytes` are immutable — you can't reliably
+  zero them after use. Copies linger in interpreter caches, tracebacks, and the
+  garbage collector until reclaimed.
+- **Leaks via `repr` and logging.** Frameworks happily dump local variables in
+  exception traces, debuggers, and structured logs. A `PrivateKey` in scope
+  during an unhandled exception can land in your error tracker.
+- **Process introspection.** Other code in the same interpreter (debuggers,
+  profilers, third-party libraries, malicious dependencies) can read your
+  memory. Supply-chain risk is real — audit what you `pip install`.
+- **Shell history and env dumps.** Secrets passed as CLI args show up in
+  `ps`/`history`; secrets in `os.environ` show up in crash reports and
+  subprocess inheritance.
+
+## Handling secrets in Python
+
+- **Source secrets at runtime, never from source code.** Use environment
+  variables loaded from a `.env` file (with `python-dotenv`), an OS keyring
+  (`keyring`), a cloud secret manager (AWS Secrets Manager, GCP Secret
+  Manager, HashiCorp Vault), or `getpass.getpass()` for interactive prompts.
+- **Keep secrets in narrow scope.** Load, use, drop the reference. Don't
+  attach them to long-lived objects, module globals, or class attributes.
+- **Strip `print()` and disable verbose logging in production.** Filter
+  sensitive fields out of structured logs before they reach disk or a SaaS
+  collector.
+- **Isolate signing.** For high-value keys, sign in a separate process,
+  container, or hardware device — not the same Python process that handles
+  network I/O.
+- **Pin and audit dependencies.** Use a lockfile, review transitive deps, and
+  prefer `pip install --require-hashes` for production installs.
+
+## Operational rules
+
+1. **Never commit secrets to git.** Add wallet storage paths and any
+   `*.json`, `seed.txt`, `mnemonic.txt` artefacts to `.gitignore` *before*
+   generating real keys.
+2. **Never paste a real mnemonic into source code, an issue, a chat message,
+   an LLM prompt, or a screenshot.**
+3. **Don't reuse mainnet keys for testing.** Use a fresh testnet mnemonic.
+4. **Use a wallet passphrase ("25th word") for high-value wallets.**
+5. **Store backups offline** — paper, hardware-encrypted USB, hardware
+   wallet. Not iCloud Notes.
+6. **Generate keys on a machine you trust** — not a shared CI runner.
+
+## In these docs
+
+Code samples pass literal hex strings and short passwords inline for
+readability. **That is not how to handle real secrets.** Replace inline
+strings with values sourced from a secret manager, environment variable,
+hardware wallet, or interactive prompt.