commit	493ebc0a963512317e70d873f47551ede7b966c2	[log] [tgz]
author	Arindaam Roy <alpharoy14@gmail.com>	Tue May 20 22:02:04 2025 -0400
committer	GitHub <noreply@github.com>	Tue May 20 22:02:04 2025 -0400
tree	b3dabd991b0de6813ee237a3762473ad3cde194d
parent	ac21909914d06c1f1eedf573df7c43c31de66d10 [diff]

tree: b3dabd991b0de6813ee237a3762473ad3cde194d

README.md

Apache ResilientDB Python SDK (Incubating)

High-performance blockchain database SDK for Python applications

Quick Start • Documentation • Examples • Contributing • Support

[!NOTE]
Apache ResilientDB is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects.

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/apache/incubator-resilientdb-python-sdk.git
cd incubator-resilientdb-python-sdk

# Set up the environment
sh INSTALL.sh
python3.10 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Basic Usage

from resdb_driver import Resdb
from resdb_driver.crypto import generate_keypair
from typing import Dict, Any

# Initialize the client
db = Resdb('http://127.0.0.1:18000')

# Generate keypairs for the example
alice, bob = generate_keypair(), generate_keypair()

# Create a digital asset
asset = {
    "data": {
        "token_for": "example",
        "description": "Example token",
    },
}

# Prepare transaction
prepared_tx = db.transactions.prepare(
    operation='CREATE',
    signers=alice.public_key,
    recipients=[([bob.public_key], 10)],  # Transfer 10 tokens to Bob
    asset=asset,
)

# Sign the transaction
fulfilled_tx = db.transactions.fulfill(
    prepared_tx, 
    private_keys=alice.private_key
)

# Send the transaction
tx_id_str = db.transactions.send_commit(fulfilled_tx)


# Retrieve the transaction
result = db.transactions.retrieve(fulfilled_tx["id"])
print(f"Retrieved transaction: {result}")

🌟 Features

Transaction Management
- Create and send transactions with digital signatures
- Retrieve and query transaction details
- Asset-based transaction querying
Block Operations
- Retrieve blocks by transaction
- Query block ranges
- Real-time block updates
Asset & Metadata Management
- Asset search and retrieval
- Metadata management
- Output tracking
DB Connection
- Automatic failover
- Round-robin load balancing
- Connection pooling
- Exponential backoff

📋 Requirements

Python 3.9 or higher
Bazel build system
Debian based linux distros e.g. Ubuntu
Virtual environment (recommended)

🔧 Setup & Configuration

1. Start the Key-Value Service

source venv/bin/activate
sh service/tools/start_kv_service_sdk.sh

2. Start the HTTP Service

bazel build service/http_server/crow_service_main
bazel-bin/service/http_server/crow_service_main \\
    service/tools/config/interface/client.config \\
    service/http_server/server_config.config

📚 Documentation

🏗️ Project Structure

resilientdb-python-sdk/
├── docs/               # Documentation and guides
├── resdb_driver/      # Core SDK implementation
├── service/           # Service implementations
│   ├── http_server/   # HTTP API service (Crow)
│   └── kv_service/    # Key-Value service
└── test/              # Test suite

🧪 Testing

TODO: add tests

🔍 Troubleshooting

Common Issues

Connection Refused

Solution: Ensure the HTTP service is running on port 18000

Python Version Mismatch

Solution: Use Python 3.9 or higher, preferably in a virtual environment

Bazel Build Failures

Solution: Check Bazel version and ensure all dependencies are installed

🤝 Contributing

We welcome contributions! See our Contributing Guidelines for:

How to submit patches
Development workflow
Coding standards

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.