Merge pull request #24 from MinaProtocol/dkijania/quality-improvements

Author: dkijania

.github/workflows/integration.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   integration:
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 20
 
     services:
       mina:
@@ -24,6 +24,7 @@ jobs:
         ports:
           - 8080:8080
           - 8181:8181
+          - 8282:8282
           - 3085:3085
 
     steps:
@@ -49,10 +50,32 @@ jobs:
       - name: Acquire test accounts
         id: accounts
         run: |
-          SENDER=$(curl -s http://127.0.0.1:8181/acquire-account?unlockAccount=true)
-          RECEIVER=$(curl -s http://127.0.0.1:8181/acquire-account)
-          SENDER_PK=$(echo "$SENDER" | python -c "import sys,json; print(json.load(sys.stdin)['pk'])")
-          RECEIVER_PK=$(echo "$RECEIVER" | python -c "import sys,json; print(json.load(sys.stdin)['pk'])")
+          # Helper: retry curl until we get a valid account with 'pk' field
+          acquire_account() {
+            local url="$1"
+            local label="$2"
+            for i in $(seq 1 60); do
+              RESP=$(curl -s "$url" 2>&1 || echo "")
+              if [ -n "$RESP" ]; then
+                PK=$(echo "$RESP" | python -c "import sys,json; d=json.load(sys.stdin); print(d.get('pk',''))" 2>/dev/null)
+                if [ -n "$PK" ]; then
+                  echo "$PK"
+                  return 0
+                fi
+              fi
+              echo "Attempt $i/60: $label not ready yet (response: $RESP)" >&2
+              sleep 5
+            done
+            echo "Failed to acquire $label after 60 attempts" >&2
+            return 1
+          }
+
+          # Debug: check which ports are responding
+          echo "Checking port 8181..." && curl -sf http://127.0.0.1:8181/ 2>&1 | head -1 || echo "8181 not responding"
+          echo "Checking port 8282..." && curl -sf http://127.0.0.1:8282/ 2>&1 | head -1 || echo "8282 not responding"
+
+          SENDER_PK=$(acquire_account "http://127.0.0.1:8181/acquire-account?unlockAccount=true" "sender")
+          RECEIVER_PK=$(acquire_account "http://127.0.0.1:8181/acquire-account" "receiver")
           echo "sender_pk=$SENDER_PK" >> "$GITHUB_OUTPUT"
           echo "receiver_pk=$RECEIVER_PK" >> "$GITHUB_OUTPUT"
           echo "Sender: $SENDER_PK"

CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- `DaemonConnectionError` exception (replaces shadowed `ConnectionError`)
+- `Currency.__rmul__` for `3 * Currency(10)` support
+- Export all public types from `mina_sdk`: `AccountBalance`, `AccountData`,
+  `BlockInfo`, `DaemonStatus`, `PeerInfo`, `SendPaymentResult`,
+  `SendDelegationResult`, `GraphQLError`, `DaemonConnectionError`,
+  `CurrencyUnderflow`
+- Input validation for `MinaDaemonClient` configuration parameters
+- Docstrings on all public classes, methods, and dataclass fields
+- 11 new unit tests (49 total)
+
+### Fixed
+- HTTP status code now checked before parsing JSON response body
+- JSON decode errors are caught and wrapped as `DaemonConnectionError`
+- Negative `Currency` values are rejected with `ValueError`
+
+### Changed
+- `Currency.__mul__` only accepts `int` scalars (was also accepting `Currency`,
+  which produced nonsensical nanomina-squared units)
+- `ConnectionError` is now an alias for `DaemonConnectionError` (backwards compatible)
+
+## [0.1.0] - 2025-11-20
+
+### Added
+- Initial release
+- `MinaDaemonClient` with GraphQL queries and mutations
+- `Currency` type with nanomina-precision arithmetic
+- Typed response dataclasses
+- Automatic retry with configurable backoff
+- Context manager support
+- Unit tests with HTTP mocking
+- Integration tests against live daemon
+- CI workflows: lint, test, release, integration, schema drift
+- PyPI publishing via trusted publishers

README.md

@@ -4,10 +4,10 @@ Python SDK for interacting with [Mina Protocol](https://minaprotocol.com) nodes.
 
 ## Features
 
-- **Daemon GraphQL client** — query node status, accounts, blocks; send payments and delegations
+- **Daemon GraphQL client** -- query node status, accounts, blocks; send payments and delegations
 - Typed response objects with `Currency` arithmetic
 - Automatic retry with configurable backoff
-- Context manager support
+- Context manager support for clean resource management
 
 ## Installation
 
@@ -49,34 +49,34 @@ with MinaDaemonClient() as client:
 ```python
 client = MinaDaemonClient(
     graphql_uri="http://127.0.0.1:3085/graphql",  # default
-    retries=3,        # retry failed requests
-    retry_delay=5.0,  # seconds between retries
-    timeout=30.0,     # HTTP timeout in seconds
+    retries=3,        # retry failed requests (must be >= 1)
+    retry_delay=5.0,  # seconds between retries (must be >= 0)
+    timeout=30.0,     # HTTP timeout in seconds (must be > 0)
 )
 ```
 
 ## API Reference
 
 ### Queries
 
-| Method | Description |
-|--------|-------------|
-| `get_sync_status()` | Node sync status (SYNCED, BOOTSTRAP, etc.) |
-| `get_daemon_status()` | Comprehensive daemon status |
-| `get_network_id()` | Network identifier |
-| `get_account(public_key)` | Account balance, nonce, delegate |
-| `get_best_chain(max_length)` | Recent blocks from best chain |
-| `get_peers()` | Connected peers |
-| `get_pooled_user_commands(public_key)` | Pending transactions |
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get_sync_status()` | `str` | Node sync status (SYNCED, BOOTSTRAP, etc.) |
+| `get_daemon_status()` | `DaemonStatus` | Comprehensive daemon status |
+| `get_network_id()` | `str` | Network identifier |
+| `get_account(public_key)` | `AccountData` | Account balance, nonce, delegate |
+| `get_best_chain(max_length)` | `list[BlockInfo]` | Recent blocks from best chain |
+| `get_peers()` | `list[PeerInfo]` | Connected peers |
+| `get_pooled_user_commands(public_key)` | `list[dict]` | Pending transactions |
 
 ### Mutations
 
-| Method | Description |
-|--------|-------------|
-| `send_payment(sender, receiver, amount, fee)` | Send a payment |
-| `send_delegation(sender, delegate_to, fee)` | Delegate stake |
-| `set_snark_worker(public_key)` | Set/unset SNARK worker |
-| `set_snark_work_fee(fee)` | Set SNARK work fee |
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `send_payment(sender, receiver, amount, fee)` | `SendPaymentResult` | Send a payment |
+| `send_delegation(sender, delegate_to, fee)` | `SendDelegationResult` | Delegate stake |
+| `set_snark_worker(public_key)` | `str \| None` | Set/unset SNARK worker |
+| `set_snark_work_fee(fee)` | `str` | Set SNARK work fee |
 
 ### Currency
 
@@ -90,6 +90,51 @@ c = Currency.from_nanomina(1_000_000_000)  # 1 MINA
 print(a + b)        # 11.500000000
 print(a.nanomina)   # 10000000000
 print(a > b)        # True
+print(3 * b)        # 4.500000000
+```
+
+### Error Handling
+
+```python
+from mina_sdk import MinaDaemonClient, GraphQLError, DaemonConnectionError, CurrencyUnderflow
+
+with MinaDaemonClient(retries=3, retry_delay=2.0) as client:
+    try:
+        account = client.get_account("B62q...")
+    except ValueError as e:
+        # Account not found on ledger
+        print(f"Account does not exist: {e}")
+    except GraphQLError as e:
+        # Daemon returned a GraphQL-level error
+        print(f"GraphQL error: {e}")
+        print(f"Raw errors: {e.errors}")
+    except DaemonConnectionError as e:
+        # All retry attempts exhausted
+        print(f"Cannot reach daemon after retries: {e}")
+
+# Currency underflow
+from mina_sdk import Currency, CurrencyUnderflow
+
+try:
+    result = Currency(1) - Currency(2)
+except CurrencyUnderflow:
+    print("Subtraction would result in negative balance")
+```
+
+### Data Types
+
+All response types are importable from the top-level package:
+
+```python
+from mina_sdk import (
+    AccountBalance,    # total, liquid, locked balances
+    AccountData,       # public_key, nonce, balance, delegate, token_id
+    BlockInfo,         # state_hash, height, slots, creator, tx count
+    DaemonStatus,      # sync_status, chain height, peers, uptime
+    PeerInfo,          # peer_id, host, port
+    SendPaymentResult,     # id, hash, nonce
+    SendDelegationResult,  # id, hash, nonce
+)
 ```
 
 ## Development
@@ -102,6 +147,34 @@ pip install -e ".[dev]"
 pytest
 ```
 
+### Running integration tests
+
+Integration tests require a running Mina daemon:
+
+```bash
+MINA_GRAPHQL_URI=http://127.0.0.1:3085/graphql \
+MINA_TEST_SENDER_KEY=B62q... \
+MINA_TEST_RECEIVER_KEY=B62q... \
+pytest tests/test_integration.py -v
+```
+
+## Troubleshooting
+
+**Connection refused / DaemonConnectionError**
+
+The daemon is not running or not reachable at the configured URI. Check:
+- Is the daemon running? (`mina client status`)
+- Is the GraphQL port open? (default: 3085)
+- Is `--insecure-rest-server` set if connecting from a different host?
+
+**GraphQLError: field not found**
+
+The SDK's queries may be out of sync with the daemon's GraphQL schema. This can happen after a daemon upgrade. Check the [schema drift CI](https://github.com/MinaProtocol/mina-sdk-python/actions/workflows/schema-drift.yml) for compatibility status.
+
+**Account not found**
+
+`get_account()` raises `ValueError` when the account doesn't exist on the ledger. This is normal for new accounts that haven't received any transactions yet.
+
 ## License
 
 Apache License 2.0

examples/basic_usage.py

@@ -1,9 +1,15 @@
 """Basic usage of the Mina Python SDK."""
 
-from mina_sdk import MinaDaemonClient, Currency
+from mina_sdk import (
+    Currency,
+    DaemonConnectionError,
+    GraphQLError,
+    MinaDaemonClient,
+)
 
 
 def main():
+    """Demonstrate core SDK features against a local daemon."""
     # Connect to a local Mina daemon (default: http://127.0.0.1:3085/graphql)
     with MinaDaemonClient() as client:
         # Check sync status
@@ -19,41 +25,52 @@ def main():
         network_id = client.get_network_id()
         print(f"Network: {network_id}")
 
-        # Query an account
-        account = client.get_account("B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtS5vH1tH...")
-        print(f"Balance: {account.balance.total} MINA")
-        print(f"Nonce: {account.nonce}")
+        # Query an account (replace with a real public key)
+        try:
+            account = client.get_account("B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtS5vH1tH...")
+            print(f"Balance: {account.balance.total} MINA")
+            print(f"Nonce: {account.nonce}")
+        except ValueError as e:
+            print(f"Account not found: {e}")
 
         # Get recent blocks
         blocks = client.get_best_chain(max_length=5)
         for block in blocks:
-            print(f"Block {block.height}: {block.state_hash[:20]}... "
-                  f"({block.command_transaction_count} txns)")
+            print(
+                f"Block {block.height}: {block.state_hash[:20]}... "
+                f"({block.command_transaction_count} txns)"
+            )
 
         # Send a payment (requires sender account unlocked on node)
-        result = client.send_payment(
-            sender="B62qsender...",
-            receiver="B62qreceiver...",
-            amount=Currency("1.5"),   # 1.5 MINA
-            fee=Currency("0.01"),     # 0.01 MINA fee
-            memo="hello from SDK",
-        )
-        print(f"Payment sent! Hash: {result.hash}, Nonce: {result.nonce}")
+        try:
+            result = client.send_payment(
+                sender="B62qsender...",
+                receiver="B62qreceiver...",
+                amount=Currency("1.5"),  # 1.5 MINA
+                fee=Currency("0.01"),  # 0.01 MINA fee
+                memo="hello from SDK",
+            )
+            print(f"Payment sent! Hash: {result.hash}, Nonce: {result.nonce}")
+        except GraphQLError as e:
+            print(f"Payment failed: {e}")
 
 
 def connect_to_remote_node():
-    """Connect to a remote daemon."""
-    client = MinaDaemonClient(
-        graphql_uri="http://my-mina-node:3085/graphql",
-        retries=5,
-        retry_delay=10.0,
-        timeout=60.0,
-    )
+    """Connect to a remote daemon with custom retry settings."""
     try:
-        status = client.get_sync_status()
-        print(f"Remote node status: {status}")
-    finally:
-        client.close()
+        client = MinaDaemonClient(
+            graphql_uri="http://my-mina-node:3085/graphql",
+            retries=5,
+            retry_delay=10.0,
+            timeout=60.0,
+        )
+        try:
+            status = client.get_sync_status()
+            print(f"Remote node status: {status}")
+        finally:
+            client.close()
+    except DaemonConnectionError as e:
+        print(f"Could not reach remote node: {e}")
 
 
 if __name__ == "__main__":