Metadata-Version: 2.4
Name: accumulate-sdk-opendlt
Version: 2.0.0
Summary: Accumulate Python SDK (V2/V3 unified) with DevNet-first flows
Author-email: OpenDLT <dev@opendlt.dev>
License: MIT License
        
        Copyright (c) 2024 Accumulate Foundation
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/opendlt/accumulate-python-sdk
Project-URL: Documentation, https://github.com/opendlt/accumulate-python-sdk#readme
Project-URL: Issues, https://github.com/opendlt/accumulate-python-sdk/issues
Keywords: blockchain,accumulate,jsonrpc,client,devnet,crypto
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32
Requires-Dist: cryptography>=42
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.8; python_version < "3.11"
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: ecdsa>=0.18.0
Requires-Dist: websockets>=11.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pdoc; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: genbadge[coverage]; extra == "dev"
Requires-Dist: psutil; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: websockets>=11.0.0; extra == "dev"
Requires-Dist: ecdsa>=0.18.0; extra == "dev"
Requires-Dist: coincurve>=21.0.0; extra == "dev"
Provides-Extra: secp256k1
Requires-Dist: ecdsa>=0.18.0; extra == "secp256k1"
Requires-Dist: coincurve>=21.0.0; extra == "secp256k1"
Dynamic: license-file

# OpenDLT Accumulate Python SDK

[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Production-ready Python SDK for the Accumulate blockchain protocol. Supports all signature types, V2/V3 API endpoints, and provides a high-level signing API with automatic version tracking.

## Features

- **Multi-Signature Support**: Ed25519, RCD1, BTC, ETH, RSA-SHA256, ECDSA-SHA256
- **Smart Signing**: Automatic signer version tracking with `SmartSigner`
- **Complete Protocol**: All 33 transaction types and account operations
- **Cross-Platform**: Pure Python implementation
- **Network Ready**: Mainnet, Testnet (Kermit), and local DevNet support

## Installation

```bash
pip install accumulate-client
```

Or install from source:

```bash
git clone https://github.com/opendlt/accumulate-python.git
cd accumulate-python/unified
pip install -e ".[dev]"
```

## Quick Start

```python
from accumulate_client import AccumulateClient
from accumulate_client.crypto.ed25519 import Ed25519KeyPair
from accumulate_client.signing.smart_signer import SmartSigner

# Connect to Kermit testnet
client = AccumulateClient("https://kermit.accumulatenetwork.io/v3")

# Generate key pair and derive lite account URLs
kp = Ed25519KeyPair.generate()
lid = kp.lite_identity_url()
lta = kp.lite_token_account_url()

print(f"Lite Identity: {lid}")
print(f"Lite Token Account: {lta}")

# Query account
account = client.query(lta)
print(f"Account: {account}")
```

## Smart Signing API

The `SmartSigner` class handles version tracking automatically:

```python
from accumulate_client import AccumulateClient
from accumulate_client.crypto.ed25519 import Ed25519KeyPair
from accumulate_client.signing.smart_signer import SmartSigner
from accumulate_client.convenience import TxBody

# Connect to testnet
client = AccumulateClient("https://kermit.accumulatenetwork.io/v3")
kp = Ed25519KeyPair.generate()
lid = kp.lite_identity_url()
lta = kp.lite_token_account_url()

# Create SmartSigner - automatically queries and tracks signer version
signer = SmartSigner(
    client=client,
    keypair=kp,
    signer_url=lid,
)

# Sign, submit, and wait for delivery in one call
result = signer.sign_submit_and_wait(
    principal=lta,
    body=TxBody.send_tokens_single(
        to_url="acc://recipient.acme/tokens",
        amount="100000000",  # 1 ACME
    ),
    memo="Payment",
)

if result.success:
    print(f"Transaction delivered: {result.txid}")
```

## Supported Signature Types

| Type | Key Pair Class | Use Case |
|------|---------------|----------|
| Ed25519 | `Ed25519KeyPair` | Default, recommended |
| RCD1 | `RCD1KeyPair` | Factom compatibility |
| BTC | `Secp256k1KeyPair` | Bitcoin ecosystem |
| ETH | `Secp256k1KeyPair` | Ethereum ecosystem |
| RSA-SHA256 | `RsaKeyPair` | Enterprise/legacy systems |
| ECDSA-SHA256 | `EcdsaKeyPair` | P-256 curve operations |

## Transaction Builders

Build transactions using the `TxBody` class:

```python
from accumulate_client.convenience import TxBody

# Send tokens
TxBody.send_tokens_single(to_url="acc://...", amount="100000000")

# Add credits
TxBody.add_credits(recipient="acc://...", amount=1000000, oracle=oracle_price)

# Create ADI
TxBody.create_identity(url="acc://my-adi.acme", key_book_url="acc://my-adi.acme/book", public_key_hash=key_hash)

# Create token account
TxBody.create_token_account(url="acc://my-adi.acme/tokens", token_url="acc://ACME")

# Create custom token
TxBody.create_token(url="acc://my-adi.acme/mytoken", symbol="MTK", precision=8)

# Write data
TxBody.write_data(entries_hex=[data_hex])
```

## Network Endpoints

```python
from accumulate_client import AccumulateClient

# Public networks
mainnet = AccumulateClient("https://mainnet.accumulatenetwork.io/v3")
testnet = AccumulateClient("https://kermit.accumulatenetwork.io/v3")

# Local development
devnet = AccumulateClient("http://localhost:26660/v3")
```

## Examples

See [`examples/`](examples/) for complete working examples:

| Example | Description |
|---------|-------------|
| `example01_lite_identities.py` | Lite identity and token account operations |
| `example02_accumulate_identities.py` | ADI creation |
| `example03_adi_token_accounts.py` | ADI token account management |
| `example04_data_accounts.py` | Data account operations |
| `example05_send_acme_adi_to_adi.py` | ADI-to-ADI transfers |
| `example06_custom_tokens.py` | Custom token creation |
| `example09_key_management.py` | Key page and key book management |
| `example12_quickstart_demo.py` | Complete zero-to-hero workflow |

Run any example:
```bash
python examples/example01_lite_identities.py
```

## Project Structure

```
src/accumulate_client/
├── api_client.py      # V2/V3 API client
├── convenience.py     # TxBody builders and helpers
├── crypto/            # Key pair implementations
├── signing/           # SmartSigner, signature management
├── signers/           # Signature type classes
├── tx/                # Transaction builders
├── types.py           # Protocol types (103 types)
├── enums.py           # Protocol enums (14 enums)
└── runtime/           # URL handling, codecs, validation
examples/
├── example01_*.py     # V3 API examples with SmartSigner
└── ...                # 12 complete workflow examples
tests/
├── unit/              # Unit tests
├── integration/       # Network integration tests
└── conformance/       # Cross-implementation compatibility
```

## Development

### Running Tests
```bash
pytest tests/                    # All tests
pytest tests/unit/               # Unit tests only
pytest tests/integration/        # Integration tests (requires network)
```

### Code Quality
```bash
ruff check src/
mypy src/
ruff format src/
```

### Self-Check
```bash
python scripts/selfcheck.py
```

Expected output:
```
Status: PASS
Checks: 11/11 passed (100.0%)
Enums=14, Types=103, Signatures=16, Transactions=33, API methods=35
```

## Error Handling

```python
from accumulate_client.api_client import (
    AccumulateAPIError,
    AccumulateNetworkError,
    AccumulateValidationError,
)

try:
    result = client.submit(envelope)
except AccumulateValidationError as e:
    print(f"Validation error: {e}")
except AccumulateNetworkError as e:
    print(f"Network error: {e}")
except AccumulateAPIError as e:
    print(f"API error: {e.code} - {e}")
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [Accumulate Protocol](https://accumulatenetwork.io/)
- [API Documentation](https://docs.accumulatenetwork.io/)
- [Kermit Testnet Explorer](https://kermit.explorer.accumulatenetwork.io/)
