Metadata-Version: 2.4
Name: mst-sdk-python
Version: 1.0.0
Summary: A modular and lightweight Python SDK for interacting with MST-compatible blockchain networks.
Author-email: Mst Blockchain <tech@mstblockchain.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Masterstroke-technosoft/mst-sdk-python
Project-URL: Issues, https://github.com/Masterstroke-technosoft/mst-sdk-python/issues
Keywords: blockchain,sdk,web3
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: web3>=6.15.0
Requires-Dist: eth-account>=0.11.0
Dynamic: license-file

# MST Blockchain SDK (Python)

A modular and lightweight blockchain development kit for interacting with any MST-compatible network. This is a Python port of the [MST Blockchain SDK](https://github.com/Masterstroke-technosoft/basic-bc-sdk) (JS), built on `web3.py` and `eth-account`, providing the same easy-to-use abstractions for providers, signers, and contract interactions.

## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
  - [1. Initialize the Client](#1-initialize-the-client)
  - [2. Generate a Random Wallet](#2-generate-a-random-wallet)
  - [3. Check Account Balance (via Provider)](#3-check-account-balance-via-provider)
  - [4. Estimate Gas & Send Transactions](#4-estimate-gas--send-transactions)
  - [5. Deploy Contract & Get Address](#5-deploy-contract--get-address)
- [Networks](#networks)
- [Core Modules](#core-modules)
  - [1. Client](#1-client)
  - [2. Provider](#2-provider-read-only)
  - [3. Signer](#3-signer-identity--writing)
  - [4. Errors](#4-errors)
- [Testing](#testing)
- [License](#license)

## Features

- **Client Orchestration**: Universal entry point for all SDK features.
- **Provider Management**: Simple JSON-RPC provider (via `web3.py`) for fetching block data and account state.
- **Secure Signing**: Integrated `Signer` using `eth-account` for secure transaction signing and address management.
- **Balances**: Built-in utilities for checking native token balances.
- **Network Selection**: Pick `"mainnet"` or `"testnet"` and the SDK resolves the correct RPC endpoint for you — no config files or env vars needed.

## Installation

```bash
pip install -r requirements.txt
```

For local development (so the `blockchain_sdk` package resolves from `src/`), install it in editable mode:

```bash
pip install -e .
```

*(Recommended: do this inside a virtual environment — `python -m venv .venv` then activate it — before installing.)*

There is no `.env` file or environment configuration to set up. The network is selected by name at runtime, and the private key is passed directly wherever you construct a `Client` — both are plain user input, not config.

## Quick Start

### 1. Initialize the Client

```python
from blockchain_sdk import Client

private_key = "0x..."

client = Client("testnet", private_key)   # or "mainnet"
```

### 2. Generate a Random Wallet

```python
# Creates a new client with a fresh random private key
client = Client.create_random("testnet")
print(f"Generated Address: {client.signer.address}")
print(f"Private Key: {client.signer.get_private_key()}")
```

### 3. Check Account Balance (via Provider)

```python
address = "0x..."
# Access balance through the provider
balance = client.provider.get_balance(address)
print(f"Address Balance: {balance} wei")
```

### 4. Estimate Gas & Send Transactions

```python
to_address = "0x..."
amount = "1000000000000000000"  # 1 TOKEN

# 1. Estimate gas first
gas_limit = client.signer.estimate_gas("sendNative", [to_address, amount])
print(f"Estimated Gas: {gas_limit}")

# 2. Send the transaction
tx_hash = client.signer.send_native(to_address, amount)
print(f"Transaction Hash: {tx_hash}")
```

### 5. Deploy Contract & Get Address

```python
abi = [...]
bytecode = "0x..."
args = ["InitialValue"]

# 1. Start deployment
tx_hash = client.signer.deploy(abi, bytecode, args)
print(f"Deployment Hash: {tx_hash}")

# 2. Wait for it to be mined
receipt = client.provider.wait_for_transaction(tx_hash)

# 3. Get the new contract address
print(f"Contract Deployed at: {receipt.contractAddress}")
```

## Networks

`Client` resolves its RPC endpoint from a network name (defined in `blockchain_sdk.utils.constants.NETWORKS`):

| Network   | RPC URL |
|-----------|---------|
| `testnet` (default) | `https://testnetrpc.mstblockchain.com` |
| `mainnet` | `https://mariorpc.mstblockchain.com/` |

```python
from blockchain_sdk import Client

testnet_client = Client("testnet", private_key)
mainnet_client = Client("mainnet", private_key)
```

Passing an unrecognized network name raises a `ValueError`.

## Core Modules

### 1. `Client`
The root container and main entry point.
- `Client(network="testnet", private_key=None)`: Resolves the RPC URL for `network` and constructs the `Provider`/`Signer`.
- `Client.create_random(network="testnet")`: Returns a new `Client` instance with a random signer.
- `provider`: Instance of `Provider`.
- `signer`: Instance of `Signer` (if `private_key` provided).

### 2. `Provider` (Read-only)
Accessed via `client.provider`.
- `get_block_number()`: Returns the latest block.
- `get_balance(address)`: Fetches raw balance.
- `get_transaction_receipt(tx_hash)`: Fetches the receipt of a mined txn.
- `wait_for_transaction(tx_hash)`: Waits for a txn to be mined.
- `estimate_gas(transaction)`: Estimates gas for a raw transaction object.

### 3. `Signer` (Identity & Writing)
Accessed via `client.signer`.
- `Signer.create_random(provider)`: Generates a new random `Signer` attached to a provider.
- `get_private_key()`: Returns the private key of the current wallet.
- `estimate_gas(method, args)`: Estimates gas for Signer methods (`sendNative`, `sendToken`, `deploy`).
- `send_transaction(tx)`: Signs and broadcasts any transaction.
- `send_native(to, amount)`: Shortcut for sending native tokens.
- `send_token(token_address, to, amount)`: Sends ERC20 tokens.
- `deploy(abi, bytecode, args=None)`: Deploys smart contracts.
- `get_address()`: Returns the signer's public address.

### 4. `Errors`
Custom error classes for better debugging (`blockchain_sdk.Errors`).
- `ProviderError`: Network or RPC issues.
- `TransactionError`: Validation or on-chain submission failures.
- `WalletError`: Private key or signer initialization issues.

## Testing

Run the test suite to ensure everything is configured correctly:

```bash
pytest
```

## License

MIT
