# Dragonchain Python SDK

A self-contained Python SDK for interacting with Dragonchain (Prime) nodes.

## Installation

```bash
pip install prime-sdk-python
```

Or, from a local checkout:

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

Requires Python 3.9+.

## Usage

```python
from prime_sdk import DragonchainSDK, TransactionCreateRequest

# Initialize the SDK
client = DragonchainSDK(
    "your-public-id",
    "your-auth-key-id",
    "your-auth-key",
    "https://your-dragonchain-endpoint.com",
)

# Check system health (raises DragonchainAPIError if unhealthy)
client.system.health()

# Get system status
status = client.system.status()
print(f"Chain ID: {status.id}, Level: {status.level}")

# Create a transaction
resp = client.transaction.create(
    TransactionCreateRequest(
        txn_type="my-transaction-type",
        payload='{"message": "Hello Dragonchain"}',
        tag="example-tag",
    )
)
print(f"Created transaction: {resp.transaction_id}")
```

## Transaction Modes

`create` and `create_bulk` return **immediately** with the assigned transaction
ID(s). They do **not** wait for block inclusion. Blocks are assembled
asynchronously on a ~5-second cycle.

### Fire and Forget

Most use cases only need the transaction ID. No polling required.

```python
resp = client.transaction.create(
    TransactionCreateRequest(
        txn_type="my-transaction-type",
        payload='{"message": "Hello Dragonchain"}',
    )
)
print("Transaction ID:", resp.transaction_id)
# Done — no need to wait for a block.
```

### Wait for Block

If you need the block ID (e.g. for interchain verification or Daria), poll
`get` until `header.block_id` is populated.

```python
import time

resp = client.transaction.create(
    TransactionCreateRequest(
        txn_type="my-transaction-type",
        payload='{"message": "Hello Dragonchain"}',
    )
)

while True:
    txn = client.transaction.get(resp.transaction_id)
    if txn.header.block_id:
        print("Block ID:", txn.header.block_id)
        break
    time.sleep(2)
```

## Loading credentials from a file

The SDK can read chain credentials from a YAML file:

```yaml
default: my-public-id
chains:
  - name: my-chain
    publicId: my-public-id
    authKeyId: my-auth-key-id
    authKey: my-auth-key
    endpoint: https://chains.dragonchain.com
```

```python
from prime_sdk import DragonchainSDK
from prime_sdk.credentials import load_config

cfg = load_config("~/.dragonchain/credentials.yaml")
chain = cfg.get_default_chain()

client = DragonchainSDK(
    chain.public_id, chain.auth_key_id, chain.auth_key, chain.endpoint
)
```

## Available Endpoints

### System
- `system.health()` — Check system health
- `system.status()` — Get system status

### Transaction
- `transaction.create(req)` — Create a new transaction
- `transaction.create_bulk(req)` — Create multiple transactions
- `transaction.get(transaction_id)` — Get transaction by ID
- `transaction.list()` — List all transactions

### Transaction Type
- `transaction_type.create(req)` — Create a new transaction type
- `transaction_type.get(txn_type)` — Get transaction type by name
- `transaction_type.list()` — List all transaction types
- `transaction_type.delete(txn_type)` — Delete a transaction type

### Smart Contract
- `contract.create(req)` — Create a new smart contract
- `contract.get(contract_id)` — Get smart contract by ID
- `contract.list()` — List all smart contracts
- `contract.update(contract_id, req)` — Update a smart contract
- `contract.upload(contract_id, filepath)` — Upload smart contract code
- `contract.delete(contract_id)` — Delete a smart contract

### Block
- `block.get(block_id)` — Get block by ID

## Authentication

The SDK uses HMAC-SHA256 authentication. You need to provide:
- `public_id` — Your Dragonchain public ID
- `auth_key_id` — Your authentication key ID
- `auth_key` — Your authentication key
- `base_url` — The base URL of your Dragonchain node (e.g. "https://chains.dragonchain.com")

## Error handling

Any non-2xx response raises `prime_sdk.DragonchainAPIError`, which exposes
`.status_code` and `.body`:

```python
from prime_sdk import DragonchainAPIError

try:
    client.transaction.get("nonexistent-id")
except DragonchainAPIError as e:
    print(e.status_code, e.body)
```

## License

Apache-2.0