lineage-sdk 1.0.0__tar.gz

lineage_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lineage 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.

lineage_sdk-1.0.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include requirements.txt
+include requirements-test.txt
+include lineage/py.typed
+
+recursive-include lineage *.py
+recursive-include lineage/utils *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod]
+recursive-exclude tests * 

lineage_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: lineage-sdk
+Version: 1.0.0
+Summary: Python SDK for interacting with the Lineage blockchain
+Author-email: Lineage Foundation <info@lineage.foundation>
+License: MIT License
+        
+        Copyright (c) 2026 Lineage 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/lineage-foundation/sdk-python
+Project-URL: Documentation, https://github.com/lineage-foundation/sdk-python/tree/main/docs
+Project-URL: Bug Tracker, https://github.com/lineage-foundation/sdk-python/issues
+Keywords: blockchain,lineage,cryptocurrency
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.1
+Requires-Dist: pynacl>=1.4.0
+Requires-Dist: mnemonic>=0.20
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: base58>=2.1.1
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: bip32utils>=0.3.0
+Dynamic: license-file
+
+# Lineage Python SDK
+
+Python SDK for interacting with the Lineage blockchain. This SDK provides a simple interface for wallet operations and blockchain queries.
+
+## Installation
+
+```bash
+pip install lineage-sdk
+```
+
+The distribution is published as `lineage-sdk`; the import name is `lineage`:
+
+```python
+import lineage
+```
+
+## Quick Start
+
+### Basic Blockchain Queries
+
+```python
+from lineage.blockchain import BlockchainClient
+
+# Initialize blockchain client. api_key is optional and, when set, is sent
+# as the x-api-key header on every request.
+client = BlockchainClient(
+    storage_host='https://storage.aiblock.dev',
+    mempool_host='https://mempool.aiblock.dev',
+    api_key='your-api-key'
+)
+
+# Query blockchain
+latest_block = client.get_latest_block()
+if latest_block.is_ok:
+    print(f"Latest block: {latest_block.get_ok()['content']['block_num']}")
+
+# Get specific block by number
+block = client.get_block_by_num(1)
+if block.is_ok:
+    print(f"Block 1: {block.get_ok()['content']}")
+
+# Get blockchain entry by hash
+entry = client.get_blockchain_entry('some_hash')
+
+# Get transaction by hash
+transaction = client.get_transaction_by_hash('tx_hash')
+
+# Get multiple transactions
+transactions = client.fetch_transactions(['hash1', 'hash2'])
+
+# Get supply information (requires mempool host) - returns {total, issued}
+total_supply = client.get_total_supply()
+issued_supply = client.get_issued_supply()
+```
+
+### Wallet Operations
+
+```python
+from lineage.wallet import Wallet
+
+# Create wallet
+wallet = Wallet()
+
+# Generate seed phrase
+seed_phrase = wallet.generate_seed_phrase()
+print(f"Seed phrase: {seed_phrase}")
+
+# Initialize wallet from seed. apiKey is optional and, when set, is sent
+# as the x-api-key header on every mempool request.
+config = {
+    'passphrase': 'your-secure-passphrase',
+    'mempoolHost': 'https://mempool.aiblock.dev',
+    'storageHost': 'https://storage.aiblock.dev',
+    'valenceHost': 'https://valence.aiblock.dev',
+    'apiKey': 'your-api-key'
+}
+
+result = wallet.from_seed(seed_phrase, config)
+if result.is_ok:
+    print(f"Wallet address: {wallet.get_address()}")
+else:
+    print(result.error, result.error_message)
+
+# Check balance - fetch_balance returns {balance: {address: {...}}}
+balance_result = wallet.fetch_balance([wallet.current_keypair.address])
+if balance_result.is_ok:
+    print(balance_result.get_ok())
+
+# Create an item asset via POST /v1/items. On success this returns
+# {asset, to_address, tx_hash}.
+item_result = wallet.create_item_asset(
+    secret_key=wallet.current_keypair.secret_key,
+    public_key=wallet.current_keypair.public_key,
+    amount=1
+)
+if item_result.is_ok:
+    print(item_result.get_ok())
+
+# Send a payment. This builds and signs a real UTXO transaction client-side
+# (the same construction as sdk-js) and submits it via POST /v1/transactions.
+# On success this returns {transaction_hash, payment_address, asset, used_addresses}.
+payment_result = wallet.create_transactions(
+    destination_address='recipient-address',
+    amount=100
+)
+if payment_result.is_ok:
+    print(payment_result.get_ok())
+```
+
+## Features
+
+### Blockchain Client
+- **get_latest_block()** - Get the latest block information
+- **get_block_by_num(block_num)** - Get a specific block by number
+- **get_blockchain_entry(hash)** - Get blockchain entry by hash
+- **get_transaction_by_hash(tx_hash)** - Get transaction details
+- **fetch_transactions(tx_hashes)** - Get multiple transactions
+- **get_total_supply()** - Get total token supply
+- **get_issued_supply()** - Get issued token supply
+
+### Wallet Operations
+- Generate and manage seed phrases
+- Create and manage keypairs
+- Construct and submit real, client-signed transactions (payments)
+- Create item assets
+- Check balances
+- Two-way payment protocol support (via the separate valence service)
+
+All of the above talk to the `/v1` REST API on the mempool/storage hosts.
+Reads and writes go through `lineage/blockchain.py`'s shared transport,
+which maps `application/problem+json` error bodies onto the SDK's
+`IResult` error types. The 2-way payment flow (`make_2way_payment`,
+`fetch_pending_2way_payments`, `accept_2way_payment`, `reject_2way_payment`)
+is unrelated to `/v1` - it talks to the valence node directly and its
+wire format hasn't changed.
+
+`create_transactions` now does real work: it fetches the current balance
+for the spending addresses, selects UTXOs, builds and signs a
+`CreateTransaction` the same way sdk-js does, and submits it to
+`POST /v1/transactions`. Previously this only produced a signed payload
+without ever confirming it reached the network - callers who relied on
+the old behaviour should check `payment_result.get_ok()['transaction_hash']`
+to confirm the payment was actually accepted.
+
+## Configuration
+
+The SDK uses environment variables for configuration. Create a `.env` file:
+
+```bash
+LINEAGE_PASSPHRASE="your-secure-passphrase"
+LINEAGE_STORAGE_HOST="https://storage.aiblock.dev"
+LINEAGE_MEMPOOL_HOST="https://mempool.aiblock.dev"
+LINEAGE_VALENCE_HOST="https://valence.aiblock.dev"
+
+# Optional - sent as the x-api-key header on every /v1 request
+LINEAGE_API_KEY="your-api-key"
+```
+
+## Error Handling
+
+All methods return `IResult` objects with proper error handling:
+
+```python
+result = client.get_latest_block()
+if result.is_ok:
+    data = result.get_ok()
+    print(f"Success: {data}")
+else:
+    print(result.error, result.error_message)
+```
+
+## Development
+
+1. Clone the repository
+2. Install uv (https://docs.astral.sh/uv/)
+3. Run tests: `uv pip install -q pytest requests-mock && uv run pytest -q`
+
+The suite is offline by default; tests marked `integration` talk to a live network and are excluded from the default run.
+
+## Documentation
+
+- [API Reference](docs/api-reference.md) - Complete API documentation
+- [Examples](docs/examples.md) - Usage examples and patterns
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
+
+## Links
+
+- [Lineage Foundation](https://lineage.foundation)
+- [Other SDKs](https://github.com/lineage-foundation) – sdk-python, sdk-php, sdk-js, sdk-laravel
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT – see [LICENSE](LICENSE).

lineage_sdk-1.0.0/README.md

@@ -0,0 +1,197 @@
+# Lineage Python SDK
+
+Python SDK for interacting with the Lineage blockchain. This SDK provides a simple interface for wallet operations and blockchain queries.
+
+## Installation
+
+```bash
+pip install lineage-sdk
+```
+
+The distribution is published as `lineage-sdk`; the import name is `lineage`:
+
+```python
+import lineage
+```
+
+## Quick Start
+
+### Basic Blockchain Queries
+
+```python
+from lineage.blockchain import BlockchainClient
+
+# Initialize blockchain client. api_key is optional and, when set, is sent
+# as the x-api-key header on every request.
+client = BlockchainClient(
+    storage_host='https://storage.aiblock.dev',
+    mempool_host='https://mempool.aiblock.dev',
+    api_key='your-api-key'
+)
+
+# Query blockchain
+latest_block = client.get_latest_block()
+if latest_block.is_ok:
+    print(f"Latest block: {latest_block.get_ok()['content']['block_num']}")
+
+# Get specific block by number
+block = client.get_block_by_num(1)
+if block.is_ok:
+    print(f"Block 1: {block.get_ok()['content']}")
+
+# Get blockchain entry by hash
+entry = client.get_blockchain_entry('some_hash')
+
+# Get transaction by hash
+transaction = client.get_transaction_by_hash('tx_hash')
+
+# Get multiple transactions
+transactions = client.fetch_transactions(['hash1', 'hash2'])
+
+# Get supply information (requires mempool host) - returns {total, issued}
+total_supply = client.get_total_supply()
+issued_supply = client.get_issued_supply()
+```
+
+### Wallet Operations
+
+```python
+from lineage.wallet import Wallet
+
+# Create wallet
+wallet = Wallet()
+
+# Generate seed phrase
+seed_phrase = wallet.generate_seed_phrase()
+print(f"Seed phrase: {seed_phrase}")
+
+# Initialize wallet from seed. apiKey is optional and, when set, is sent
+# as the x-api-key header on every mempool request.
+config = {
+    'passphrase': 'your-secure-passphrase',
+    'mempoolHost': 'https://mempool.aiblock.dev',
+    'storageHost': 'https://storage.aiblock.dev',
+    'valenceHost': 'https://valence.aiblock.dev',
+    'apiKey': 'your-api-key'
+}
+
+result = wallet.from_seed(seed_phrase, config)
+if result.is_ok:
+    print(f"Wallet address: {wallet.get_address()}")
+else:
+    print(result.error, result.error_message)
+
+# Check balance - fetch_balance returns {balance: {address: {...}}}
+balance_result = wallet.fetch_balance([wallet.current_keypair.address])
+if balance_result.is_ok:
+    print(balance_result.get_ok())
+
+# Create an item asset via POST /v1/items. On success this returns
+# {asset, to_address, tx_hash}.
+item_result = wallet.create_item_asset(
+    secret_key=wallet.current_keypair.secret_key,
+    public_key=wallet.current_keypair.public_key,
+    amount=1
+)
+if item_result.is_ok:
+    print(item_result.get_ok())
+
+# Send a payment. This builds and signs a real UTXO transaction client-side
+# (the same construction as sdk-js) and submits it via POST /v1/transactions.
+# On success this returns {transaction_hash, payment_address, asset, used_addresses}.
+payment_result = wallet.create_transactions(
+    destination_address='recipient-address',
+    amount=100
+)
+if payment_result.is_ok:
+    print(payment_result.get_ok())
+```
+
+## Features
+
+### Blockchain Client
+- **get_latest_block()** - Get the latest block information
+- **get_block_by_num(block_num)** - Get a specific block by number
+- **get_blockchain_entry(hash)** - Get blockchain entry by hash
+- **get_transaction_by_hash(tx_hash)** - Get transaction details
+- **fetch_transactions(tx_hashes)** - Get multiple transactions
+- **get_total_supply()** - Get total token supply
+- **get_issued_supply()** - Get issued token supply
+
+### Wallet Operations
+- Generate and manage seed phrases
+- Create and manage keypairs
+- Construct and submit real, client-signed transactions (payments)
+- Create item assets
+- Check balances
+- Two-way payment protocol support (via the separate valence service)
+
+All of the above talk to the `/v1` REST API on the mempool/storage hosts.
+Reads and writes go through `lineage/blockchain.py`'s shared transport,
+which maps `application/problem+json` error bodies onto the SDK's
+`IResult` error types. The 2-way payment flow (`make_2way_payment`,
+`fetch_pending_2way_payments`, `accept_2way_payment`, `reject_2way_payment`)
+is unrelated to `/v1` - it talks to the valence node directly and its
+wire format hasn't changed.
+
+`create_transactions` now does real work: it fetches the current balance
+for the spending addresses, selects UTXOs, builds and signs a
+`CreateTransaction` the same way sdk-js does, and submits it to
+`POST /v1/transactions`. Previously this only produced a signed payload
+without ever confirming it reached the network - callers who relied on
+the old behaviour should check `payment_result.get_ok()['transaction_hash']`
+to confirm the payment was actually accepted.
+
+## Configuration
+
+The SDK uses environment variables for configuration. Create a `.env` file:
+
+```bash
+LINEAGE_PASSPHRASE="your-secure-passphrase"
+LINEAGE_STORAGE_HOST="https://storage.aiblock.dev"
+LINEAGE_MEMPOOL_HOST="https://mempool.aiblock.dev"
+LINEAGE_VALENCE_HOST="https://valence.aiblock.dev"
+
+# Optional - sent as the x-api-key header on every /v1 request
+LINEAGE_API_KEY="your-api-key"
+```
+
+## Error Handling
+
+All methods return `IResult` objects with proper error handling:
+
+```python
+result = client.get_latest_block()
+if result.is_ok:
+    data = result.get_ok()
+    print(f"Success: {data}")
+else:
+    print(result.error, result.error_message)
+```
+
+## Development
+
+1. Clone the repository
+2. Install uv (https://docs.astral.sh/uv/)
+3. Run tests: `uv pip install -q pytest requests-mock && uv run pytest -q`
+
+The suite is offline by default; tests marked `integration` talk to a live network and are excluded from the default run.
+
+## Documentation
+
+- [API Reference](docs/api-reference.md) - Complete API documentation
+- [Examples](docs/examples.md) - Usage examples and patterns
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
+
+## Links
+
+- [Lineage Foundation](https://lineage.foundation)
+- [Other SDKs](https://github.com/lineage-foundation) – sdk-python, sdk-php, sdk-js, sdk-laravel
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT – see [LICENSE](LICENSE).

lineage_sdk-1.0.0/lineage/__init__.py

@@ -0,0 +1,54 @@
+"""
+Lineage Python SDK
+
+A Python SDK for interacting with the Lineage blockchain.
+"""
+
+from lineage.blockchain import BlockchainClient
+from lineage.wallet import Wallet
+from lineage.config import get_config, validate_config, get_default_config
+from lineage import utils
+
+# Import key functions from key_handler
+from lineage.key_handler import (
+    generate_seed_phrase,
+    validate_seed_phrase,
+    generate_master_key,
+    generate_keypair,
+    encrypt_master_key,
+    decrypt_master_key,
+    encrypt_keypair,
+    decrypt_keypair,
+    validate_address,
+    construct_address
+)
+
+try:
+    from importlib.metadata import version as _pkg_version, PackageNotFoundError as _PkgNotFound
+    try:
+        __version__ = _pkg_version("lineage-sdk")
+    except _PkgNotFound:  # running from a source tree that isn't installed
+        __version__ = "1.0.0"
+except ImportError:  # pragma: no cover - importlib.metadata is stdlib on 3.8+
+    __version__ = "1.0.0"
+
+__all__ = [
+    'BlockchainClient',
+    'Wallet', 
+    'get_config',
+    'validate_config',
+    'get_default_config',
+    'utils',
+    # Key handler functions
+    'generate_seed_phrase',
+    'validate_seed_phrase', 
+    'generate_master_key',
+    'generate_keypair',
+    'encrypt_master_key',
+    'decrypt_master_key',
+    'encrypt_keypair',
+    'decrypt_keypair',
+    'validate_address',
+    'construct_address',
+    '__version__'
+]