autonomi-client 0.3.0

Autonomi client API

Autonomi Python Bindings

The Autonomi client library provides Python bindings for easy integration with Python applications.

Installation

We recommend using uv for Python environment management:

uv venv
uv pip install autonomi-client

Quick Start

from autonomi_client import Client, Wallet, PaymentOption

# Initialize wallet with private key
wallet = Wallet("your_private_key_here")
print(f"Wallet address: {wallet.address()}")
print(f"Balance: {wallet.balance()}")

# Connect to network
client = Client.connect(["/ip4/127.0.0.1/tcp/12000"])

# Create payment option
payment = PaymentOption.wallet(wallet)

# Upload data
data = b"Hello, Safe Network!"
addr = client.data_put_public(data, payment)
print(f"Data uploaded to: {addr}")

# Download data
retrieved = client.data_get_public(addr)
print(f"Retrieved: {retrieved.decode()}")

API Reference

Client

The main interface to interact with the Autonomi network.

Connection Methods

• connect(peers: List[str]) -> Client
  • Connect to network nodes
  • peers: List of multiaddresses for initial network nodes

Data Operations

• data_put_public(data: bytes, payment: PaymentOption) -> str

  • Upload public data to the network
  • Returns address where data is stored

• data_get_public(addr: str) -> bytes

  • Download public data from the network
  • addr: Address returned from data_put_public

• data_put(data: bytes, payment: PaymentOption) -> DataMapChunk

  • Store private (encrypted) data
  • Returns access information for later retrieval

• data_get(access: DataMapChunk) -> bytes

  • Retrieve private data
  • access: DataMapChunk from previous data_put

Pointer Operations

• pointer_get(address: str) -> Pointer

  • Retrieve pointer from network
  • address: Hex-encoded pointer address

• pointer_put(pointer: Pointer, wallet: Wallet)

  • Store pointer on network
  • Requires payment via wallet

• pointer_cost(key: VaultSecretKey) -> str

  • Calculate pointer storage cost
  • Returns cost in atto tokens

Vault Operations

• vault_cost(key: VaultSecretKey) -> str

  • Calculate vault storage cost

• write_bytes_to_vault(data: bytes, payment: PaymentOption, key: VaultSecretKey, content_type: int) -> str

  • Write data to vault
  • Returns vault address

• fetch_and_decrypt_vault(key: VaultSecretKey) -> Tuple[bytes, int]

  • Retrieve vault data
  • Returns (data, content_type)

• get_user_data_from_vault(key: VaultSecretKey) -> UserData

  • Get user data from vault

• put_user_data_to_vault(key: VaultSecretKey, payment: PaymentOption, user_data: UserData) -> str

  • Store user data in vault
  • Returns vault address

Wallet

Ethereum wallet management for payments.

• new(private_key: str) -> Wallet

  • Create wallet from private key
  • private_key: 64-char hex string without '0x' prefix

• address() -> str

  • Get wallet's Ethereum address

• balance() -> str

  • Get wallet's token balance

• balance_of_gas() -> str

  • Get wallet's gas balance

PaymentOption

Configure payment methods.

• wallet(wallet: Wallet) -> PaymentOption
  • Create payment option from wallet

Pointer

Handle network pointers for referencing data.

• new(target: str) -> Pointer

  • Create new pointer
  • target: Hex-encoded target address

• address() -> str

  • Get pointer's network address

• target() -> str

  • Get pointer's target address

VaultSecretKey

Manage vault access keys.

• new() -> VaultSecretKey

  • Generate new key

• from_hex(hex: str) -> VaultSecretKey

  • Create from hex string

• to_hex() -> str

  • Convert to hex string

UserData

Manage user data in vaults.

• new() -> UserData

  • Create new user data

• add_file_archive(archive: str) -> Optional[str]

  • Add file archive
  • Returns archive ID if successful

• add_private_file_archive(archive: str) -> Optional[str]

  • Add private archive
  • Returns archive ID if successful

• file_archives() -> List[Tuple[str, str]]

  • List archives as (id, address) pairs

• private_file_archives() -> List[Tuple[str, str]]

  • List private archives as (id, address) pairs

DataMapChunk

Handle private data storage references.

• from_hex(hex: str) -> DataMapChunk

  • Create from hex string

• to_hex() -> str

  • Convert to hex string

• address() -> str

  • Get short reference address

Utility Functions

• encrypt(data: bytes) -> Tuple[bytes, List[bytes]]
  • Self-encrypt data
  • Returns (data_map, chunks)

Examples

See the examples/ directory for complete examples:

• autonomi_example.py: Basic data operations
• autonomi_pointers.py: Working with pointers
• autonomi_vault.py: Vault operations
• autonomi_private_data.py: Private data handling
• autonomi_data_registers.py: Using data registers
• autonomi_private_encryption.py: Data encryption
• autonomi_advanced.py: Advanced usage scenarios

Best Practices

1. Always handle wallet private keys securely
2. Check operation costs before executing
3. Use appropriate error handling
4. Monitor wallet balance for payments
5. Use appropriate content types for vault storage
6. Consider using pointers for updatable references
7. Properly manage and backup vault keys

For more examples and detailed usage, see the examples in the repository.