Python SDK¶

The ACDC Python SDK (acdc-py) provides a Pythonic interface for interacting with the Alpha and Delta chains.

:::info Coming Soon The Python SDK is currently in development. This page documents the planned API.

For now, you can interact with ACDC using: - Direct JSON-RPC calls via requests or httpx - The TypeScript SDK via Node.js - The Rust SDK for performance-critical applications :::

Planned Installation¶

pip install acdc-py

Requirements (planned): - Python 3.10+ - asyncio support

Planned Quick Start¶

from acdc import AcdcClient

# Connect to Delta mainnet
client = AcdcClient(chain="delta", network="mainnet")

# Get balance
balance = await client.get_balance("dx1abc123...")
print(f"Balance: {balance.formatted} ACDC")

Planned API¶

Client Setup¶

from acdc import AcdcClient

# Basic setup
client = AcdcClient(
    chain="delta",
    network="mainnet"
)

# With options
client = AcdcClient(
    chain="delta",
    network="mainnet",
    rpc_url="https://custom-rpc.example.com",
    api_key="your-api-key",
    timeout=30
)

# From environment
client = AcdcClient.from_env()

Wallet Management¶

from acdc import Wallet

# Generate new wallet
wallet = Wallet.create()
print(f"Address: {wallet.address}")
print(f"Mnemonic: {wallet.mnemonic}")

# From mnemonic
wallet = Wallet.from_mnemonic("abandon abandon abandon ...")

# From private key
wallet = Wallet.from_private_key("0x...")

# Connect to client
connected = wallet.connect(client)

Querying Data¶

# Get balance
balance = await client.get_balance("dx1abc...")
print(f"Balance: {balance.formatted} ACDC")
print(f"Raw: {balance.raw} wei")

# Get block
block = await client.get_block("latest")
print(f"Block {block.number}: {block.hash}")

# Get transaction
tx = await client.get_transaction("0xtxhash...")
print(f"From: {tx.from_address}")
print(f"To: {tx.to_address}")
print(f"Value: {tx.value_formatted} ACDC")

Sending Transactions¶

from acdc import parse_units

# Simple transfer
tx = await connected.send_transaction(
    to="dx1recipient...",
    value=parse_units("1.0", 18)
)

# Wait for confirmation
receipt = await tx.wait()
print(f"Confirmed in block {receipt.block_number}")

# With options
tx = await connected.send_transaction(
    to="dx1recipient...",
    value=parse_units("1.0", 18),
    gas_limit=21000,
    gas_price=parse_units("10", 9)
)

Contract Interaction¶

from acdc import Contract

# ERC20 ABI (simplified)
erc20_abi = [
    "function balanceOf(address) view returns (uint256)",
    "function transfer(address, uint256) returns (bool)"
]

# Read-only contract
token = Contract("dx1token...", erc20_abi, client)
balance = await token.balance_of("dx1holder...")
print(f"Token balance: {balance}")

# Writable contract
token = Contract("dx1token...", erc20_abi, connected)
tx = await token.transfer("dx1recipient...", parse_units("100", 18))
await tx.wait()

Subscriptions¶

# Subscribe to new blocks
async for block in client.subscribe_blocks():
    print(f"New block: {block.number}")

# Subscribe to address activity
async for event in client.subscribe_address("dx1abc..."):
    print(f"Activity: {event.tx_hash}")

Using JSON-RPC Directly¶

While waiting for the Python SDK, you can use direct JSON-RPC calls:

import httpx
import asyncio

async def get_balance(address: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://delta-rpc.ac-dc.network",
            json={
                "jsonrpc": "2.0",
                "id": 1,
                "method": "account_getBalance",
                "params": [address, "latest"]
            }
        )
        return response.json()

async def main():
    result = await get_balance("dx1abc123...")
    balance = result["result"]["balance"]
    # Convert from wei to ACDC (18 decimals)
    acdc_balance = int(balance) / 10**18
    print(f"Balance: {acdc_balance} ACDC")

asyncio.run(main())

Helper Functions¶

def parse_units(value: str, decimals: int = 18) -> int:
    """Convert human-readable value to base units."""
    parts = value.split(".")
    if len(parts) == 1:
        return int(parts[0]) * (10 ** decimals)
    integer = parts[0]
    fraction = parts[1][:decimals].ljust(decimals, "0")
    return int(integer + fraction)

def format_units(value: int, decimals: int = 18) -> str:
    """Convert base units to human-readable value."""
    s = str(value).zfill(decimals + 1)
    return f"{s[:-decimals]}.{s[-decimals:]}".rstrip("0").rstrip(".")

# Usage
wei = parse_units("1.5", 18)  # 1500000000000000000
acdc = format_units(wei, 18)  # "1.5"

WebSocket Subscriptions¶

import asyncio
import websockets
import json

async def subscribe_blocks():
    uri = "wss://delta-ws.ac-dc.network"
    async with websockets.connect(uri) as ws:
        # Subscribe to new blocks
        await ws.send(json.dumps({
            "jsonrpc": "2.0",
            "id": 1,
            "method": "subscribe",
            "params": ["newBlocks"]
        }))

        # Receive subscription confirmation
        response = await ws.recv()
        print(f"Subscribed: {response}")

        # Listen for events
        async for message in ws:
            data = json.loads(message)
            if "params" in data:
                block = data["params"]["result"]
                print(f"New block: {block['number']}")

asyncio.run(subscribe_blocks())

Contributing¶

Interested in helping build the Python SDK? Check out the repository:

Key areas needing contribution: - Core client implementation - Wallet and signing - Contract interaction - WebSocket subscriptions - Type hints and documentation