calimero-client-py-bindings 0.1.4

Python client library for Calimero Network - a comprehensive blockchain API client

Calimero Python Client Bindings

This directory contains the Python bindings for the Calimero Rust client, providing a complete Python interface to all Calimero client functionality.

🚀 Features

• Complete API Coverage: All 39 methods from the Rust client are available
• Professional Implementation: Clean, documented, and maintainable code
• Full Workflow Support: From application installation to alias management
• Enterprise Features: Permissions, proposals, governance, and synchronization
• Comprehensive Testing: Integration tests with real Merobox nodes

📦 Installation

Prerequisites

• Python 3.8+
• Rust toolchain
• Docker (for Merobox testing)

Building from Source

1. Clone the repository:

   git clone <repository-url>
   cd core/crates/client
   

2. Build the Python wheel:

   # Set compatibility for Python 3.13+
   export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1

   # Build the wheel
maturin build --features python

3. Install the wheel:

   </code></pre>
   </li>
   </ol>
   <p>pip install target/wheels/calimero_client_py_bindings-*.whl</p>
   <pre><code>
   ## 🔧 Usage
   
   ### Basic Usage
   
   ```python
   from calimero_client_py_bindings import create_connection, create_client
   
   # Create a connection to a Calimero node
   connection = create_connection("http://localhost:2528", "my-node")
   
   # Create a client from the connection
       client = create_client(connection)
       
   # Use the client methods
   apps = client.list_applications()
   print(f"Installed applications: {apps}")
   

   Available Methods

   The Python client provides access to all methods from the Rust client. Here's the complete API reference:

   Connection & Client Creation (2)

   • create_connection(api_url, node_name=None) - Create a connection to a Calimero node
   • create_client(connection) - Create a client from a connection

   Application Management (5)

   • install_application(url, hash=None, metadata=None) - Install applications from URLs
   • install_dev_application(path, metadata=None) - Install development applications from local paths
   • uninstall_application(app_id) - Remove installed applications
   • list_applications() - List all installed applications
   • get_application(app_id) - Get information about specific applications

   Blob Management (3)

   • list_blobs() - List all blobs
   • get_blob_info(blob_id) - Get information about specific blobs
   • delete_blob(blob_id) - Delete blobs

   Context Management (8)

   • create_context(app_id, protocol, params=None) - Create new contexts
   • delete_context(context_id) - Delete contexts
   • get_context(context_id) - Get context information
   • list_contexts() - List all contexts
   • get_context_storage(context_id) - Get context storage information
   • get_context_identities(context_id) - Get context member identities
   • get_context_client_keys(context_id) - Get context client keys
   • sync_context(context_id) - Synchronize context state

   Context Collaboration (2)

   • invite_to_context(context_id, inviter_id, invitee_id) - Invite nodes to contexts
   • join_context(context_id, invitee_id, invitation_payload) - Join contexts using invitation payload

   Identity & Networking (2)

   • generate_context_identity() - Generate new context identities
   • get_peers_count() - Get connected peers count

   Function Execution (1)

   • execute_function(context_id, method, args, executor_public_key) - Execute functions via JSON-RPC

   Permissions & Governance (6)

   • grant_permissions(context_id, granter_id, grantee_id, capability) - Grant capabilities to users
   • revoke_permissions(context_id, revoker_id, revokee_id, capability) - Revoke capabilities from users
   • update_context_application(context_id, app_id, executor_public_key) - Update context application
   • get_proposal(context_id, proposal_id) - Get proposal information
   • get_proposal_approvers(context_id, proposal_id) - Get proposal approvers
   • list_proposals(context_id, args=None) - List proposals in a context

   Synchronization (2)

   • sync_context(context_id) - Sync individual context
   • sync_all_contexts() - Sync all contexts

   Alias Management (16)

   • create_context_alias(alias, context_id) - Create context aliases
   • create_context_identity_alias(context_id, alias, public_key) - Create context identity aliases
   • create_application_alias(alias, app_id) - Create application aliases
   • create_alias_generic(alias, value, scope=None) - Create generic aliases
   • delete_context_alias(alias) - Delete context aliases
   • delete_context_identity_alias(alias, context_id) - Delete context identity aliases
   • delete_application_alias(alias) - Delete application aliases
   • list_context_aliases() - List context aliases
   • list_context_identity_aliases(context_id) - List context identity aliases
   • list_application_aliases() - List application aliases
   • lookup_context_alias(alias) - Lookup context alias values
   • lookup_context_identity_alias(alias, context_id) - Lookup context identity alias values
   • lookup_application_alias(alias) - Lookup application alias values
   • resolve_context_alias(alias) - Resolve context aliases
   • resolve_context_identity_alias(alias, context_id) - Resolve context identity aliases
   • resolve_application_alias(alias) - Resolve application aliases

   Connection Methods (2)

   • get(path) - Make a GET request to a specific path
   • detect_auth_mode() - Check if authentication is required

   Client Properties (1)

   • get_api_url() - Get the API URL of the client

   Total: 48 methods (including the 2 creation functions)

   🧪 Testing

   Prerequisites for Testing

   1. Install Merobox:

      pip install merobox
      

   2. Install PyYAML (for workflow tests):

      pip install pyyaml
      

   3. Install Pytest (for pytest tests):

      pip install pytest
      

   Running Tests

   Quick Verification

   Test that the bindings are working correctly:

   python run_tests.py --mode quick
   

   Standalone Integration Test

   Run the comprehensive integration test with Merobox cluster management:

   python run_tests.py --mode standalone
   

   Pytest Tests

   Run pytest-based tests with fixtures:

   python run_tests.py --mode pytest
   

   All Tests

   Run all tests in sequence:

   python run_tests.py --mode all
   

   Test Modes

   1. Merobox Cluster Management

   Uses Merobox's cluster() context manager for automatic node management:

   from merobox.testing import cluster
   
   with cluster(count=2, prefix="test", image="ghcr.io/calimero-network/merod:edge") as env:
       nodes = env["nodes"]
       endpoints = env["endpoints"]
       # Your test code here
       # Nodes are automatically cleaned up on exit
   

   2. Merobox Workflow Setup

   Uses Merobox's workflow() context manager for complex test scenarios:

   from merobox.testing import workflow
   
   with workflow("workflow.yml", prefix="test") as env:
       workflow_result = env["workflow_result"]
       nodes = env["nodes"]
       endpoints = env["endpoints"]
       # Your test code here
       # Workflow environment is automatically cleaned up on exit
   

   3. Pytest Fixtures

   Use the provided pytest fixtures for integration testing:

   # conftest.py provides these fixtures:
   # - merobox_cluster: 2-node cluster for testing
   # - merobox_workflow: workflow-based testing
   # - test_environment: test environment with cluster access
   
   def test_something(test_environment):
       endpoints = test_environment["endpoints"]
       nodes = test_environment["nodes"]
       # Your test code here
   

   Test Coverage

   The integration tests cover:

   1. Basic Connectivity: Connection and client creation
   2. Application Workflow: Installation, listing, and management
   3. Context Workflow: Creation, management, and collaboration
   4. Identity Management: Generation and invitation workflows
   5. Function Execution: Cross-node function calls
   6. Additional Methods: Peers, blobs, and synchronization
   7. Alias Methods: Complete alias lifecycle management

   🏗️ Architecture

   Binding Structure

   • PyConnectionInfo: Python wrapper for connection information
   • PyClient: Python wrapper for the Calimero client
   • PyJwtToken: Python wrapper for JWT tokens
   • PyClientError: Python wrapper for client errors
   • PyAuthMode: Python wrapper for authentication modes

   Error Handling

   All methods return PyResult<PyObject> and properly handle:

   • Network errors
   • Authentication errors
   • Storage errors
   • Internal errors
   • Invalid input parameters

   Method Signatures & Parameters

   Core Types

   • Application IDs: String identifiers that must be valid ApplicationId format
   • Context IDs: String identifiers that must be valid ContextId format
   • Public Keys: String identifiers that must be valid PublicKey format
   • Blob IDs: String identifiers that must be valid BlobId format
   • Hash: String identifiers that must be valid Hash format

   Parameter Formats

   • Initialization Parameters: None or JSON string for context creation
   • Permissions: JSON string array of [public_key, capability] pairs
   • Function Arguments: JSON string for function execution
   • Metadata: Optional bytes for application installation

   Return Values

   All methods return Python objects that can be:

   • Dictionaries (for structured responses)
   • Lists (for collections)
   • Strings (for simple values)
   • Numbers (for counts and IDs)
   • None (for void operations)

   Error Response Format

   try:
       result = client.some_method()
   except Exception as e:
       # e will contain the error details
       print(f"Error: {e}")
   

   Complete Parameter Reference

   Quick Reference Table

   Method Category	Method Count	Key Parameters
   Connection	2	api_url, node_name
   Applications	5	app_id, url, path, hash, metadata
   Blobs	3	blob_id
   Contexts	8	context_id, protocol, params
   Collaboration	2	inviter_id, invitee_id, invitation_payload
   Identity	2	None
   Functions	1	method, args, executor_public_key
   Permissions	6	granter_id, grantee_id, revoker_id, capability
   Sync	2	context_id
   Aliases	16	alias, context_id, public_key, scope

   Connection & Client Creation

   • create_connection(api_url, node_name=None)

     • api_url (str, required): Full URL to the Calimero node (e.g., "http://localhost:2528")
     • node_name (str, optional): Node identifier for authentication. Use None for local testing

   • create_client(connection)

     • connection (PyConnectionInfo, required): Connection object from create_connection

   Application Management

   • install_application(url, hash=None, metadata=None)

     • url (str, required): URL to the WASM application file
     • hash (str, optional): Hex string of the expected file hash (32 bytes)
     • metadata (bytes, optional): Application metadata bytes

   • install_dev_application(path, metadata=None)

     • path (str, required): Local filesystem path to the WASM application file
     • metadata (bytes, optional): Application metadata bytes

   • uninstall_application(app_id)

     • app_id (str, required): Application ID to remove

   • list_applications()

     • No parameters

   • get_application(app_id)

     • app_id (str, required): Application ID to retrieve

   Blob Management

   • list_blobs()

     • No parameters

   • get_blob_info(blob_id)

     • blob_id (str, required): Blob ID to retrieve information for

   • delete_blob(blob_id)

     • blob_id (str, required): Blob ID to delete

   Context Management

   • create_context(app_id, protocol, params=None)

     • app_id (str, required): Application ID to create context for
     • protocol (str, required): Protocol name (e.g., "ethereum", "near", "stellar", "icp")
     • params (str, optional): JSON string of initialization parameters, or None

   • delete_context(context_id)

     • context_id (str, required): Context ID to delete

   • get_context(context_id)

     • context_id (str, required): Context ID to retrieve

   • list_contexts()

     • No parameters

   • get_context_storage(context_id)

     • context_id (str, required): Context ID to get storage info for

   • get_context_identities(context_id)

     • context_id (str, required): Context ID to get identities for

   • get_context_client_keys(context_id)

     • context_id (str, required): Context ID to get client keys for

   • sync_context(context_id)

     • context_id (str, required): Context ID to synchronize

   Context Collaboration

   • invite_to_context(context_id, inviter_id, invitee_id)

     • context_id (str, required): Context ID to invite to
     • inviter_id (str, required): Public key of the inviter
     • invitee_id (str, required): Public key of the invitee

   • join_context(context_id, invitee_id, invitation_payload)

     • context_id (str, required): Context ID to join
     • invitee_id (str, required): Public key of the joining node
     • invitation_payload (str, required): Base58-encoded invitation payload containing protocol, network, and contract details

     Note: The invitation payload contains all necessary information (protocol, network, contract_id) and should be used as-is from the invitation response.

   Identity & Networking

   • generate_context_identity()

     • No parameters

   • get_peers_count()

     • No parameters

   Function Execution

   • execute_function(context_id, method, args, executor_public_key)
     • context_id (str, required): Context ID to execute function in
     • method (str, required): Function name to call
     • args (str, required): JSON string of function arguments
     • executor_public_key (str, required): Public key of the executing node

   Permissions & Governance

   • grant_permissions(context_id, granter_id, grantee_id, capability)

     • context_id (str, required): Context ID to grant permissions in
     • granter_id (str, required): Public key of the user granting the permission
     • grantee_id (str, required): Public key of the user receiving the permission
     • capability (str, required): JSON string representation of the capability to grant

   • revoke_permissions(context_id, revoker_id, revokee_id, capability)

     • context_id (str, required): Context ID to revoke permissions in
     • revoker_id (str, required): Public key of the user revoking the permission
     • revokee_id (str, required): Public key of the user losing the permission
     • capability (str, required): JSON string representation of the capability to revoke

   • update_context_application(context_id, app_id, executor_public_key)

     • context_id (str, required): Context ID to update
     • app_id (str, required): New application ID
     • executor_public_key (str, required): Public key of the executing node

   • get_proposal(context_id, proposal_id)

     • context_id (str, required): Context ID containing the proposal
     • proposal_id (str, required): Hash of the proposal to retrieve

   • get_proposal_approvers(context_id, proposal_id)

     • context_id (str, required): Context ID containing the proposal
     • proposal_id (str, required): Hash of the proposal to get approvers for

   • list_proposals(context_id, args=None)

     • context_id (str, required): Context ID to list proposals for
     • args (str, optional): JSON string of additional arguments for filtering proposals

   Synchronization

   • sync_context(context_id)

     • context_id (str, required): Context ID to synchronize

   • sync_all_contexts()

     • No parameters

   Alias Management

   • create_context_alias(alias, context_id)

     • alias (str, required): Alias name to create
     • context_id (str, required): Context ID to alias

   • create_context_identity_alias(context_id, alias, public_key)

     • context_id (str, required): Context ID for the identity alias
     • alias (str, required): Alias name to create
     • public_key (str, required): Public key to alias

   • create_application_alias(alias, app_id)

     • alias (str, required): Alias name to create
     • app_id (str, required): Application ID to alias

   • create_alias_generic(alias, value, scope=None)

     • alias (str, required): Alias name to create
     • value (str, required): Value to alias (parsed as ContextId by default)
     • scope (str, optional): Scope for the alias (currently unused in implementation)

   • delete_context_alias(alias)

     • alias (str, required): Alias name to delete

   • delete_context_identity_alias(alias, context_id)

     • alias (str, required): Alias name to delete
     • context_id (str, required): Context ID for the identity alias

   • delete_application_alias(alias)

     • alias (str, required): Alias name to delete

   • list_context_aliases()

     • No parameters

   • list_context_identity_aliases(context_id)

     • context_id (str, required): Context ID to list identity aliases for

   • list_application_aliases()

     • No parameters

   • lookup_context_alias(alias)

     • alias (str, required): Alias name to lookup

   • lookup_context_identity_alias(alias, context_id)

     • alias (str, required): Alias name to lookup
     • context_id (str, required): Context ID for the identity alias

   • lookup_application_alias(alias)

     • alias (str, required): Alias name to lookup

   • resolve_context_alias(alias)

     • alias (str, required): Alias name to resolve

   • resolve_context_identity_alias(alias, context_id)

     • alias (str, required): Alias name to resolve
     • context_id (str, required): Context ID for the identity alias

   • resolve_application_alias(alias)

     • alias (str, required): Alias name to resolve

   Connection Methods

   • get(path)

     • path (str, required): API path to make GET request to

   • detect_auth_mode()

     • No parameters

   Client Properties

   • get_api_url()
     • No parameters

   Parameter Validation & Formats

   ID Format Requirements

   • Application IDs: Must be valid base58-encoded strings (e.g., "37H2H5sXEquiq6WypfnKcrwCmM5WgfPW6WaZKXoVnVVT")
   • Context IDs: Must be valid base58-encoded strings
   • Public Keys: Must be valid base58-encoded strings (e.g., "4MFSzKrtmu19fXjXie8H2wFE8BSUfvHCkfrXtzcT5AEt")
   • Blob IDs: Must be valid base58-encoded strings
   • Hash: Must be valid hex strings (32 bytes)

   JSON Parameter Examples

   # Context initialization parameters
   init_params = json.dumps({"name": "my-context", "version": "1.0"})
   
   # Function execution arguments
   function_args = json.dumps({"key": "hello", "value": "world"})
   
   # Permissions (array of [public_key, capability] pairs)
   permissions = json.dumps([
       ["4MFSzKrtmu19fXjXie8H2wFE8BSUfvHCkfrXtzcT5AEt", "read"],
       ["8ftA1B4ojHXdzHVH3yrq6JLvAdxPbrrANEwYEGFGgP4b", "write"]
   ])
   

   Optional Parameters

   • params=None: Use for context creation without initialization
   • hash=None: Skip hash verification for application installation
   • metadata=None: Skip metadata for application installation
   • node_name=None: Skip authentication for local testing

   Parameter Type Conversion

   The bindings automatically handle:

   • String to ID type conversion (with validation)
   • JSON string parsing for complex parameters
   • Base58 encoding/decoding for IDs
   • Hex encoding/decoding for hashes

   Async Support

   The bindings properly handle async Rust operations using:

   • tokio::runtime::Runtime for async execution
   • Python::with_gil() for Python GIL management
   • Proper error propagation from Rust to Python

   🔍 Troubleshooting

   Common Issues

   1. Import Errors: Ensure the wheel is properly installed
   2. Version Compatibility: Use PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 for Python 3.13+
   3. Merobox Not Found: Install with pip install merobox
   4. Docker Issues: Ensure Docker is running for Merobox tests

   Context Creation Issues

   Problem: create_context() may return a 500 Internal Server Error even with valid parameters.

   Symptoms:

   • Server returns 500 error for all context creation attempts
   • Different protocol names and initialization parameters don't help
   • Application installation and listing work correctly

   Possible Causes:

   • Server-side issue with the context creation endpoint
   • Protocol name validation on the server
   • Initialization parameter format requirements
   • Server configuration or deployment issues

   Workarounds:

   1. Use params=None: Pass None instead of initialization parameters
   2. Try Different Protocols: Test with "kv-store", "kvstore", "test", or "default"
   3. Check Server Logs: Look for server-side error details
   4. Verify Application: Ensure the application is properly installed and accessible
   5. Skip Context Tests: Continue with other functionality while investigating the server issue

   Note: This appears to be a server-side issue, not a client binding problem. The Python bindings are correctly implemented and working.

   API Design Issues

   Problem: The join_context method requires protocol, network, and contract_id parameters that should come from the invitation payload.

   Current Implementation:

   # Current (problematic) signature
   client.join_context(context_id, invitee_id, protocol, network, contract_id)
   

   What It Should Be:

   # Better design - just pass the invitation payload
   client.join_context(context_id, invitee_id, invitation_payload)
   

   Why This Is Wrong:

   • The joiner shouldn't need to know protocol/network/contract details
   • These values are already encoded in the invitation payload
   • It creates unnecessary complexity and potential for errors
   • The invitation payload contains all the necessary information

   Workaround: For now, extract the protocol, network, and contract_id from the invitation response when inviting someone, then pass them to join_context. This is not ideal but works with the current implementation.

   Debug Mode

   Enable verbose output:

   python run_tests.py --verbose
   

   Manual Testing

   Test individual components:

   # Test imports
   from calimero_client_py_bindings import create_connection, create_client
   
   # Test connection
   conn = create_connection("http://localhost:9999", "test")
   print(f"Connection: {conn.api_url}")
   
   # Test client
   client = create_client(conn)
   print(f"Client methods: {[m for m in dir(client) if not m.startswith('_')]}")
   

   📚 Examples

   Complete Workflow Example

   from calimero_client_py_bindings import create_connection, create_client
   import json
   
   # Setup - Note: node_name=None for local testing (no authentication)
   connection = create_connection("http://localhost:2528", None)
   client = create_client(connection)
   
   # Install application
   app_response = client.install_application(
       "https://example.com/app.wasm"
   )
   app_id = app_response['data']['applicationId']  # Note: 'applicationId' not 'application_id'
   
   # Create context - Note: params=None for no initialization parameters
   context_response = client.create_context(
       app_id, 
       "ethereum",  # Use actual protocol name like "ethereum", "near", "stellar"
       None  # No initialization parameters
   )
   context_id = context_response['data']['context_id']
   
   # Example: Invite another node to the context
   invitation_response = client.invite_to_context(
       context_id,
       "inviter-public-key",  # Your public key
       "invitee-public-key"   # Their public key
   )
   invitation_payload = invitation_response['data']['invitation_payload']
   
   # Example: Join context using invitation payload
   join_response = client.join_context(
       context_id,
       "invitee-public-key",  # Your public key
       invitation_payload      # The invitation payload from the invite
   )
   
   # Execute function
   result = client.execute_function(
       context_id,
       "set",
       json.dumps({"key": "hello", "value": "world"}),
       "executor-public-key"  # Must be a valid public key
   )
   
   print(f"Function result: {result}")
   

   Important Usage Notes

   1. Authentication: For local testing, pass node_name=None to avoid authentication prompts
   2. Initialization Parameters: The create_context method accepts params=None for no initialization
   3. Response Format: Check the actual response structure - fields may use camelCase (e.g., applicationId)
   4. Public Keys: Identity-related methods expect valid public key strings
   5. JSON Parameters: Methods like grant_permissions expect JSON strings, not Python objects

   🤝 Contributing

   1. Fork the repository
   2. Create a feature branch
   3. Make your changes
   4. Add tests for new functionality
   5. Ensure all tests pass
   6. Submit a pull request

   📄 License

   This project is licensed under the same terms as the main Calimero project.

   🆘 Support

   For issues and questions:

   1. Check the troubleshooting section
   2. Review the test examples
   3. Open an issue on GitHub
   4. Check the Calimero documentation

   ---

   🎉 Congratulations! You now have access to the complete Calimero Python client API with comprehensive testing infrastructure.