antd-py -- Python SDK for Autonomi

Python SDK for the antd daemon. Provides synchronous and asynchronous clients with both REST and gRPC transports.

Installation

# REST transport (recommended)
pip install antd[rest]

# gRPC transport
pip install antd[grpc]

# Both transports
pip install antd[all]

# From source (development)
pip install -e ".[all]"

Compatibility

This package talks to a running antd daemon; it does not join the network itself. Python 3.10+. Tested against antd 0.12.x; health() fields such as version/evm_network need antd 0.4.0 or newer, and the pointer methods need antd 0.16.0 or later, the first release with pointers. For a daemon-less client see the ant-sdk package (import ant_ffi). Not related to the Ant Design UI library.

Quick Start

from antd import AntdClient

client = AntdClient()  # REST transport, localhost:8082

# Health check
status = client.health()
print(f"{status.network} -- healthy: {status.ok}")

# Store and retrieve data
result = client.data_put_public(b"Hello, Autonomi!")
print(f"Address: {result.address}, chunks: {result.chunks_stored}")

data = client.data_get_public(result.address)
print(data.decode())  # "Hello, Autonomi!"

Transports

from antd import AntdClient, AsyncAntdClient

# REST (default)
client = AntdClient(transport="rest", base_url="http://localhost:8082", timeout=30)

# gRPC (wallet operations and payment_mode are available via REST only)
client = AntdClient(transport="grpc", target="localhost:50051")

# Async REST
aclient = AsyncAntdClient(transport="rest")
status = await aclient.health()
await aclient.close()

The gRPC stubs in src/antd/_proto/ are generated from antd/proto and committed. After changing the protos, regenerate them and commit the result (CI fails when they drift):

pip install grpcio-tools==1.80.0   # the version the script pins
python scripts/generate_proto.py

API Reference

Factory Functions

Client Methods

Health

Data

Chunks

Files

Manifests

A manifest (ADR-0006) describes a set of files as one .ant file, or as an ant://manifest/ link when it is small enough. Each entry has an optional path and size, and either an embedded DataMap (a private file: the manifest is its key) or a public DataMap address. The daemon builds and decodes manifests through ant-core, so the SDK never handles the format. Every method is on all four clients (sync and async, REST and gRPC) with the same signatures, types and errors, and needs antd 0.16.0 or later, the first release with manifests. See examples/10_manifests.py.

Nothing is uploaded or paid for. Building and decoding only read the network: on build the default embedding policy resolves shrunk DataMaps, and on decode resolve=True fetches each entry's DataMap (never its content). A call can therefore time out, and retrying it is safe. Upload the files first (data_put_public, file_put, ...) and pass their addresses or DataMaps.

The .ant bytes are always raw bytes in this API: REST carries them as base64 and gRPC as bytes, and the clients convert. Sizes are Python ints, and an unset size or exact_size is None, never 0 (0 is an empty file). Over gRPC the manifest calls use a second channel to the same target, with its message limits raised to 256 MiB each way (a manifest can be 64 MiB); every other call keeps gRPC's defaults.

Each ManifestEntryInput takes an optional sha256 (the plaintext's SHA-256, hex), recorded in the manifest, and each ManifestEntryInfo reports it; requires antd 0.17.0 or later. The client sends it as given (unset or "" is omitted) and the daemon validates it, so a malformed one raises BadRequestError.

An invalid entry, such as a bad path (../x) or malformed hex, raises BadRequestError (HTTP 400 / gRPC INVALID_ARGUMENT) with the daemon's message, which names entries[i]. One the client refuses before sending (both or neither of data_map/address, a bad size, empty decode input) is the same error with status_code 400 and the daemon's wording, such as 2 invalid entries: entries[0]: give data_map or address, not both; entries[2]: needs a data_map or an address, so one except covers both.

from antd import AntdClient, ManifestEntryInput

client = AntdClient()
a = client.data_put_public(b"note one").address   # pays
b = client.data_put_public(b"note two").address   # pays

built = client.build_manifest(                    # free
    [
        ManifestEntryInput(address=a, path="notes/one.txt"),
        ManifestEntryInput(address=b, path="notes/two.txt"),
    ],
    name="example",
)
print(built.link)

decoded = client.decode_manifest_link(built.link, resolve=True)   # free
for e in decoded.entries:
    print(e.effective_name, e.kind, e.exact_size)

Run the example with ANTD_BASE_URL=http://localhost:8082 python examples/10_manifests.py; it needs a wallet, and pays for its two uploads only.

External Signer

Two-phase upload — daemon prepares the payment intent, caller signs + submits the payForQuotes tx, daemon finalizes once the chain confirms. See examples/07_external_signer.py + docs/external-signer-flow.md. A finalize that stores only some chunks raises PartialUploadError — see Partial uploads for how to finish the upload without paying twice.

Pointers

A pointer is a small, owner-signed, mutable reference. Its address is derived from the owner's key and never changes; what it points at (a chunk, such as a public data or file address, or another pointer) can be changed by the owner. The daemon holds the owner keys, loaded at startup with antd --pointer-keys <file-or-dir> (files in the format ant pointer keygen writes), so every write names the pointer by its address (owner), never by a key. Every method is on all four clients (sync and async, REST and gRPC) with the same signatures, types and errors. See examples/09_pointers.py.

Every write pays, and the SDK never retries one. A create, update or transfer costs about the price of one chunk, and every attempt pays again, so do not retry pointer_create, pointer_update, pointer_transfer or pointer_finalize automatically. The one exception is a pointer_finalize that raises CloseGroupShortfallError with retryable=True: the daemon kept the paid state, and repeating the call with the same upload_id stores it against the same payment (bound that loop). Reads are free to retry; a read during an update or churn can raise CloseGroupShortfallError.

Counters are Python ints. The daemon sends them as decimal strings because a final state (a transfer or freeze) sits at POINTER_FINAL_COUNTER (2^64−1); a counter that is not a decimal u64 raises InternalError instead of reading as 0. Addresses are 64 hex characters; the daemon accepts a 0x prefix on input but always returns bare lowercase hex, so normalise before comparing.

from antd import AntdClient, PointerFinalityStatus

client = AntdClient()
owner = client.pointer_keys()[0]

v1 = client.data_put_public(b"version 1").address
v2 = client.data_put_public(b"version 2").address

client.pointer_create(owner, v1)          # pays once
client.pointer_update(owner, v2)          # pays once; counter 1
assert client.pointer_resolve(owner).target == v2

f = client.pointer_finality(owner)
print(f.status is PointerFinalityStatus.OPEN, f.counter)

Models

All models are frozen dataclasses (immutable).

sha256 on DataPutResult, DataPutPublicResult, FilePutResult, FilePutPublicResult and FinalizeUploadResult: the plaintext's SHA-256 (hex); requires antd 0.17.0 or later, none on older daemons (None).

Enums: PointerKind (CHUNK, POINTER), PointerOp (CREATE, UPDATE, TRANSFER), PointerFinalityStatus (above). Unset values read as None on both transports (REST sends null, gRPC an empty string or absent message).

Error Handling

All errors inherit from AntdError:

from antd import AntdClient, AntdError, NotFoundError, PaymentError

client = AntdClient()

try:
    data = client.data_get_public("nonexistent_address")
except NotFoundError:
    print("Data not found on the network")
except PaymentError:
    print("Insufficient funds")
except AntdError as e:
    print(f"Error ({e.status_code}): {e}")

The four pointer-era codes share their status with older errors, so the SDK reads the REST body's code, and over gRPC the x-antd-error-code trailing metadata, which it trusts only when it agrees with the status code (a FAILED_PRECONDITION without the tag is still a PaymentError). The daemon tags these on any call, so a chunk or data store whose close group fell short raises CloseGroupShortfallError too; daemons before the pointer API sent that as a 500 (InternalError).

Partial uploads

finalize_upload / finalize_merkle_upload can fail after the wallet has paid: some chunks store, others miss quorum after the daemon's own retries. That surfaces as PartialUploadError (a NetworkError subclass, so existing except NetworkError / except AntdError blocks still catch it). The on-chain payment persists and the stored chunks stay on the network. retryable and retention_known say how to finish (retryable implies retention_known):

• retryable — the daemon kept the paid attempt (payment proofs + unstored chunks) under the same upload_id. Call the same finalize method again with the same arguments (the same upload_id and payment artefacts) to store the remainder against the same payment: no re-prepare, no second signature, no double payment. Bound the loop — a persistent failure raises again on every call, so cap the attempts and treat a chunks_failed that stops shrinking as stuck. The retained attempt expires with the daemon's pending-upload TTL (one hour). Sent by antd ≥ 0.14.0.
• retention_known and not retryable — the daemon confirmed it kept nothing (e.g. a merkle finalize whose signer deliberately left some sub-batches unpaid). Re-prepare the same content: already-stored chunks are skipped, so the retry pays only for the remainder.
• not retention_known — retention is unknown. The daemon may still hold the paid attempt: it records the resume handle before it returns the error. Stop automatic recovery, keep the upload_id and the original payment artefacts (tx_hashes / winner_pool_hash), and reconcile before re-preparing or paying again. Never pay again on this signal alone. Daemons older than 0.14.0 never send retryable, so their REST partial uploads read as unknown.

Over gRPC a partial upload used to raise ForkError; it now raises PartialUploadError. The daemon sends ABORTED only for PARTIAL_UPLOAD, so code that caught ForkError around a finalize should catch PartialUploadError.

Over REST the counts and flags come from the structured error body. Over gRPC a partial upload is an ABORTED status whose message starts with the daemon's fixed Partial upload: prefix, and the counts and flags are parsed from that message. An ABORTED that does not start with the prefix (including one that only embeds it, e.g. upstream error: Partial upload: ...) is not a partial upload and raises ForkError as before. Full contract: docs/external-signer-flow.md §6.

Malformed input is read conservatively and never escapes as a raw ValueError / TypeError / OverflowError:

• REST. Each count must be a JSON integer from 0 to 2^64−1. A quoted number ("1"), bool, float (including Infinity), array, object, negative or larger value reads as 0. retryable is True only for the JSON literal true; "true", 1 and everything else read as False. retention_known is True only when retryable is a JSON bool (true or false); absent, null or any other type reads as unknown. Only a string code of exactly "PARTIAL_UPLOAD" selects PartialUploadError. A body that is not a JSON object, or has any other code, keeps the plain 502 → NetworkError mapping, as does a body Python cannot decode at all. A non-string error makes the raw response body the message.
• gRPC. The message reads Partial upload: S/T chunks stored, F failed after retries: <reason> (<hint>). retention_known is True only when the message starts with that counts pattern, all three counts fit in a u64, and it ends with one of the daemon's two hints. A (paid attempt retained...) hint sets retryable. A (stored chunks persist; re-prepare the same content...) hint means the daemon confirmed nothing was retained; daemons older than 0.14.0 write only this one. A pattern miss or an out-of-range count reads the counts as 0 with both flags False. Readable counts with a missing, truncated or unrecognised hint keep the counts, but both flags stay False: retention is unknown, not "nothing retained".

import time
from antd import PartialUploadError

def finalize_with_retry(client, upload_id, tx_hashes, max_attempts=5):
    last_failed = None
    for attempt in range(1, max_attempts + 1):
        try:
            return client.finalize_upload(upload_id, tx_hashes)  # every chunk stored
        except PartialUploadError as e:
            if not e.retryable:
                # retention_known: the daemon kept nothing, so re-prepare.
                # Otherwise retention is unknown: stop, keep upload_id and
                # tx_hashes, and reconcile. Never pay again on this alone.
                raise
            stuck = last_failed is not None and e.chunks_failed >= last_failed
            if attempt == max_attempts or stuck:
                raise  # paid attempt still retained under upload_id: retry the same finalize later
            last_failed = e.chunks_failed
            time.sleep(2 * attempt)

Examples

Run examples from the examples/ directory:

# Requires antd daemon running on local testnet
python examples/01_connect.py      # Health check
python examples/02_data.py         # Store/retrieve data
python examples/03_chunks.py       # Raw chunks
python examples/04_files.py        # File upload/download
python examples/06_private_data.py # Private data with data maps
python examples/07_external_signer.py # External-signer file + chunk upload
python examples/08_grpc.py          # gRPC transport (requires antd[grpc])
ANTD_POINTER_OWNER=<address> python examples/09_pointers.py  # Create, update, resolve a pointer (pays)

The pointer example needs a daemon started with --pointer-keys and a wallet; ANTD_POINTER_OWNER is one of its pointer_keys(). Set ANTD_BASE_URL to reach a daemon that is not on http://localhost:8082.

Or use the dev CLI:

ant dev example data
ant dev example all