Update docs
- update readme
- add contributing strategy
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..f87c715
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,87 @@
+# Contributing to Apache ResilientDB Python SDK
+
+We love your input! We want to make contributing to Apache ResilientDB Python SDK as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+## Development Process
+
+We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code follows the project's coding standards.
+6. Issue that pull request!
+
+## Development Setup
+
+1. Clone your fork:
+ ```bash
+ git clone https://github.com/YOUR_USERNAME/incubator-resilientdb-python-sdk.git
+ cd incubator-resilientdb-python-sdk
+ ```
+
+2. Set up development environment:
+ ```bash
+ sh INSTALL.sh
+ python3.10 -m venv venv
+ source venv/bin/activate
+ pip install -r requirements.txt
+ ```
+
+3. Create a branch:
+ ```bash
+ git checkout -b your-feature-name
+ ```
+
+## Coding Standards
+
+- Follow PEP 8 style guide for Python code
+- Use type hints for function parameters and return values
+- Write docstrings for all public methods and classes
+- Keep functions focused and concise
+- Add comments for complex logic
+- Include unit tests for new functionality
+
+## Pull Request Process
+
+1. Update the README.md with details of changes to the interface, if applicable.
+2. Update the documentation with details of any new functionality.
+3. The PR will be merged once you have the sign-off of at least one maintainer.
+
+
+## Issue Reporting Guidelines
+
+
+### Bug Reports
+
+When filing an issue, make sure to answer these questions:
+
+1. What version of Python are you using?
+2. What operating system are you using?
+3. What did you do?
+4. What did you expect to see?
+5. What did you see instead?
+
+### Feature Requests
+
+We welcome feature requests! When submitting a feature request, please:
+
+1. Explain the problem you're trying to solve
+2. Describe the solution you'd like to see
+3. Provide context about alternative solutions you've considered
+
+## Community
+
+- Subscribe to our [mailing lists](https://lists.apache.org/list.html?dev@resilientdb.apache.org)
+- Join our discussions on [GitHub Issues](https://github.com/apache/incubator-resilientdb-python-sdk/issues)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License, Version 2.0.
\ No newline at end of file
diff --git a/README.md b/README.md
index d4fe107..fa5ba5f 100644
--- a/README.md
+++ b/README.md
@@ -1,52 +1,214 @@
-# ResilientDB SDK
+# Apache ResilientDB Python SDK (Incubating)
-## Check Python is up-to-date (3.9+)
-`$ python3 --version`
+<div align="center">
-If your Python version number is too low you may encounter type hinting issues when attempting to run the code. You can use a Python virtual environment, as shown below.
+[](LICENSE)
+[](https://github.com/apache/incubator-resilientdb-python-sdk)
+[](./docs)
+[](./CONTRIBUTING.md)
+[]()
-## First-time set up
+High-performance blockchain database SDK for Python applications
-`$ sh INSTALL.sh`
+[Quick Start](#quick-start) •
+[Documentation](#documentation) •
+[Examples](#examples) •
+[Contributing](#contributing) •
+[Support](#support)
-`$ python3.10 -m venv venv`
+</div>
-`$ source venv/bin/activate`
+> [!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.
-`$ pip install -r requirements.txt`
+## 🚀 Quick Start
-The correct Python configuration is needed for transaction validation.
+### Installation
-## Running KV service
+```bash
+# Clone the repository
+git clone https://github.com/apache/incubator-resilientdb-python-sdk.git
+cd incubator-resilientdb-python-sdk
-If your virtual environment is not already active:
+# Set up the environment
+sh INSTALL.sh
+python3.10 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
-`$ source venv/bin/activate`
+### Basic Usage
-Run the script to start 4 local nodes
+```python
+from resdb_driver import Resdb
+from resdb_driver.crypto import generate_keypair
+from typing import Dict, Any
-`$ sh service/tools/start_kv_service_sdk.sh`
+# Initialize the client
+db = Resdb('http://127.0.0.1:18000')
-## Running Crow service (HTTP endpoints)
+# Generate keypairs for the example
+alice, bob = generate_keypair(), generate_keypair()
-`$ bazel build service/http_server/crow_service_main`
+# Create a digital asset
+asset = {
+ "data": {
+ "token_for": "example",
+ "description": "Example token",
+ },
+}
-`$ bazel-bin/service/http_server/crow_service_main service/tools/config/interface/client.config service/http_server/server_config.config`
+# 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,
+)
-For a list of endpoints visit [here](./service/http_server/README.md)
+# Sign the transaction
+fulfilled_tx = db.transactions.fulfill(
+ prepared_tx,
+ private_keys=alice.private_key
+)
-## Testing
-
-`$ bazel-bin/service/kv_service/kv_service_tools service/tools/config/interface/service.config set test 1234`
-
-## Running the driver
-
-Examples of using the driver can be seen in [test_driver](/test_driver.py)
-
-Replace the db_root_url with the address of the ResilientDB HTTP endpoints e.g. `127.0.0.1:18000`
+# Send the transaction
+tx_id_str = db.transactions.send_commit(fulfilled_tx)
-## TODO
-- Setting up linting (using [black](https://github.com/psf/black)) through github hooks
-- convert the sdk into a package (for pip install)
-- Potentially have a docker setup which fetched the Resdb image and runs it locally
+# 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
+
+```bash
+source venv/bin/activate
+sh service/tools/start_kv_service_sdk.sh
+```
+
+### 2. Start the HTTP Service
+
+```bash
+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
+
+- [Complete API Reference](./docs/api_reference.md)
+- [HTTP Endpoints Guide](./service/http_server/README.md)
+- [Contributing Guidelines](./CONTRIBUTING.md)
+- [Example Use Cases](./test_driver_2.py)
+
+## 🏗️ 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
+
+1. **Connection Refused**
+ ```
+ Solution: Ensure the HTTP service is running on port 18000
+ ```
+
+2. **Python Version Mismatch**
+ ```
+ Solution: Use Python 3.9 or higher, preferably in a virtual environment
+ ```
+
+3. **Bazel Build Failures**
+ ```
+ Solution: Check Bazel version and ensure all dependencies are installed
+ ```
+
+## 🤝 Contributing
+
+We welcome contributions! See our [Contributing Guidelines](./CONTRIBUTING.md) for:
+- How to submit patches
+- Development workflow
+- Coding standards
+
+## 📄 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## 💬 Support
+
+- [GitHub Issues](https://github.com/apache/incubator-resilientdb-python-sdk/issues)
+- [Mailing Lists](https://lists.apache.org/list.html?dev@resilientdb.apache.org)
+
+## 🗺️ Roadmap
+
+### Current Goals
+- [ ] Setting up linting (using [black](https://github.com/psf/black))
+- [ ] Convert to pip-installable package
+- [ ] Docker setup for local ResilientDB
+
+### Connection Improvements
+- [ ] WebSocket support for real-time updates
+- [ ] Connection pooling optimization
+- [ ] Automatic node health checking
+- [ ] Custom retry strategies
+- [ ] Connection encryption options
+- [ ] Bulk operations support
+- [ ] Load balancing strategies
+- [ ] Metrics and monitoring
+
+### API Enhancements
+- [ ] Add async/await support using aiohttp
+- [ ] Complete implementation of async/sync transaction modes
+- [ ] Add batch transaction support
+- [ ] Implement streaming responses for large datasets
+- [ ] Add support for complex query operations
+- [ ] Implement automatic request compression
+- [ ] Improve transaction ID handling
+- [ ] Add retry mechanisms for failed transactions
\ No newline at end of file
