Metadata-Version: 2.4
Name: moneta-testnet-sdk
Version: 0.13.2a16.dev20260907
Summary: Moneta Public Testnet Alpha Python SDK and MWS-1 wallet helpers
Author: Moneta contributors
License-Expression: MIT
Project-URL: Homepage, https://moneta-public-testnet.ajsingh1943.chatgpt.site
Project-URL: Documentation, https://moneta-public-testnet.ajsingh1943.chatgpt.site/#protocol
Project-URL: Issues, https://discord.gg/bRKzxcxstr
Keywords: moneta,blockchain,wallet,testnet,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx[socks]<1,>=0.27
Requires-Dist: python-socks[asyncio]<3,>=2.7
Requires-Dist: argon2-cffi<26,>=25.1
Requires-Dist: cryptography<51,>=47
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.15; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/official-moneta-logo.png" alt="Official Moneta logo" width="320" />
</p>

<h1 align="center">Moneta Developer SDK</h1>
<p align="center"><strong>Build wallets, explorers, services and integrations on Moneta Public Testnet Alpha.</strong></p>

<p align="center">
  <a href="https://github.com/tussi-dev/moneta-sdk/releases"><img src="https://img.shields.io/github/v/release/tussi-dev/moneta-sdk?include_prereleases&style=flat-square&label=release" alt="release" /></a>
  <a href="https://github.com/tussi-dev/moneta-sdk/actions"><img src="https://img.shields.io/github/actions/workflow/status/tussi-dev/moneta-sdk/ci.yml?branch=main&style=flat-square&label=CI" alt="CI" /></a>
  <img src="https://img.shields.io/badge/Python-3.11%2B-5b8cff?style=flat-square" alt="Python 3.11+" />
  <img src="https://img.shields.io/badge/wallet%20standard-MWS--1-7c6cff?style=flat-square" alt="MWS-1" />
  <img src="https://img.shields.io/badge/signatures-ML--DSA--65-7c6cff?style=flat-square" alt="ML-DSA-65" />
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-58d68d?style=flat-square" alt="MIT license" /></a>
</p>

<p align="center">
  <strong><a href="https://github.com/tussi-dev/moneta-sdk/releases">Releases</a></strong> ·
  <a href="NODE_API.md">Node API</a> ·
  <a href="MWS-1.md">MWS-1</a> ·
  <a href="https://github.com/tussi-dev/moneta-network">Network</a> ·
  <a href="https://github.com/tussi-dev/moneta-wallet">Wallet</a>
</p>

## One SDK, protocol-first

This repository is intentionally separate from the consumer Wallet. It exists for people building **compatible software**, not for ordinary users who just want to hold or send tMON.

| Module | Purpose |
|---|---|
| `MonetaClient` | Persistent typed sync client with retries and strict chain/genesis pinning |
| `AsyncMonetaClient` | Asyncio client for concurrent services, bots and indexers |
| Discovery | Rank healthy exact-identity nodes by chainwork and measured latency |
| MWS-1 helpers | Generate/restore deterministic 24-word wallets |
| ML-DSA signing | Build and sign Moneta transactions locally |
| Address helpers | Derive and validate `mnpq1…` addresses |
| SDK Explorer | JavaScript desktop GUI for inspecting nodes, testing APIs and copying examples |
| Protocol docs | Byte-precise wallet recovery and Node API references |

## Install

From a checked-out repository:

```bash
python -m pip install .
```

Or install the wheel attached to a matching GitHub prerelease when available.

Read-only API operations do not require private signing material. MWS-1 signing uses the portable `cryptography` ML-DSA-65 interface with an OpenSSL compatibility path retained for supported environments.

## 30-second example

```python
from moneta_sdk import MonetaClient, closest_node

node = closest_node()
with MonetaClient(node.url) as client:
    status = client.status()
    print(status["network"], status["height"])
```

Expected network identity:

```text
moneta-public-testnet-alpha-1
```

## Wallet interoperability

MWS-1 defines the recovery boundary between implementations.

```mermaid
flowchart LR
    W[24 words] --> S[MWS-1 seed derivation]
    S --> K[ML-DSA-65 key]
    K --> A[mnpq1 address]
    A --> T[Signed Moneta transaction]
    T --> N[Moneta node]
```

A compatible implementation must reproduce the published MWS-1 test vectors exactly. Do not substitute random library key generation and then assume recovery will interoperate.

See [`MWS-1.md`](MWS-1.md) before implementing wallet recovery in another language.

## Node API

The SDK targets the Moneta Node API rather than a privileged hosted backend.

Typical operations include:

```text
GET  /status
GET  /address/{address}
GET  /tx/{txid}
GET  /economy
GET  /chain
GET  /mempool
POST /tx
POST /block
POST /chain/import
```

The alpha.8 client also exposes `iter_chain()`, `observer()`,
`network_registry()`, `mining_template()`, `submit_block()` and
`import_chain()`. Async equivalents are available on `AsyncMonetaClient`.

## Node discovery

```python
from moneta_sdk import closest_node

peer = closest_node()
print(peer.url, peer.chainwork, peer.latency_ms)
```

Discovery starts from the official GitHub registry, merges permissionless hints
from reachable full nodes, rejects public endpoints that do not use clean HTTPS
and public DNS, then pins chain ID, genesis and client version. Higher-work
candidates rank ahead of merely faster stale nodes. Discovery hints are never
consensus authority.

See [`NODE_API.md`](NODE_API.md) for the API contract and validation expectations.

## SDK Explorer

The release includes a separate JavaScript desktop Explorer for node/API work
on Windows, Linux x64/ARM64 and macOS Intel/Apple Silicon. The SDK itself stays
a clean Python library and does not import Electron.

Download `MonetaSDKExplorer` for your platform from Releases. The legacy Tk
developer console remains available from source for compatibility. Neither
developer tool is bundled into the consumer Wallet release.

## Design principles

- **No server-side wallet custody.** Signing helpers work locally.
- **No app lock-in.** Recovery compatibility is defined by MWS-1, not one GUI.
- **Strict network identity.** Clients reject a node on the wrong Moneta chain ID.
- **Deterministic transaction format.** Transaction bytes/fields are consensus data, not UI conventions.
- **Test vectors first.** Independent implementations should be test-vector compatible before mainnet consideration.

## Engineering differentiators

- Sync and asyncio clients expose the same node concepts and use persistent
  HTTP sessions, bounded responses and typed failure categories.
- Chain ID and genesis are pinned together; discovery ranks only validated
  candidates and puts cumulative work ahead of latency.
- Paginated chain iteration, observer/economy state, mining templates, block
  submission and survivor-chain import are first-class APIs rather than raw
  URL examples.
- MWS-1 recovery, ML-DSA-65 identity derivation and transaction signing ship in
  the same typed package as the node client, with no server-side custody.
- Wheels and source distributions carry a `py.typed` marker for downstream
  type checkers and are tested on Windows, macOS and Linux.

These are SDK completeness improvements, not a claim that async clients,
typed exceptions or deterministic wallets are new ideas in the wider ecosystem.

## Network identity

```text
Chain ID     moneta-public-testnet-alpha-1
Genesis hash 0634b3e931f65ea29a842ac899b51be253e08537842a497d7c8ccd7909e5acca
Node source  official registry + peer registries (automatic)
```

## Repository layout

```text
moneta_sdk/        Python SDK
moneta_core/       protocol/crypto primitives needed by SDK
MWS-1.md           recovery standard
NODE_API.md        node API contract
developer_console.py
examples/          integration examples, when present
tests/             interoperability and API tests
```

## Moneta repositories

| Repository | Purpose |
|---|---|
| [moneta-wallet](https://github.com/tussi-dev/moneta-wallet) | End-user self-custodial wallet |
| [moneta-miner](https://github.com/tussi-dev/moneta-miner) | Consumer CPU/GPU miner |
| [moneta-network](https://github.com/tussi-dev/moneta-network) | Full node, pool and bridge infrastructure |
| **moneta-sdk** | Developer API, signing and interoperability tools |

## Public-testnet warning

The SDK targets **experimental public-testnet software**. APIs and consensus-adjacent interfaces may still change before any mainnet specification freeze.

MIT licensed. See [`LICENSE`](LICENSE).
