decdn

Python client for deCDN, for Python 3.11+. It speaks HTTP to a decdn gateway, which pays for every pull and verifies it, and it hashes the bytes again with BLAKE3 wherever it holds a whole blob named by its hash. No iroh, no wallet library. Client is synchronous and AsyncClient is its asyncio twin; both take the same arguments and return the same shapes.

• Verified streaming. A blob, or a whole bundle entry, is hashed with BLAKE3 as it streams; a body that does not hash to its name raises HASH_MISMATCH instead of ending cleanly. Ranges and rendered pages are "skipped" (Verification).
• Bundles. Entries are checked against the bundle manifest, which is itself verified and cached per client.
• Byte ranges of sized entries, for large files such as model weights. A window does not hash to anything, so its verified is "skipped".
• Loopback gateways. Mint delegate keys and register capabilities on a local decdn gateway.
• Namespace pointers. Point a PublisherRegistry namespace at a bundle on a public gateway, signing EIP-712 typed data with a private key or an eth-account-style sign_typed_data signer.
• Small and typed. Fully annotated (py.typed); namespaces, seq, caps and expiries are exact ints.

• Install
• Gateways
• Compatibility
• Public gateway
• Loopback gateway
• Verification
• Errors
• Namespace pointers
• API at a glance
• Development
• License

pip install decdn
# or
uv add decdn

The client talks to one of two kinds of gateway:

The gateway's HTTP contract is appendix-gateway; bundles and their manifests are appendix-bundles.

Python 3.11 or later. Python 3.14 is not yet supported: coincurve ships no 3.14 wheels; the matrix grows when it does.

Two floors in pyproject.toml ([tool.decdn]) say which decdn gateway releases the SDK works against:

• gateway-floor (0.3.0) is the oldest gateway whose HTTP contract the SDK supports, checked at release. It is the release that carries cross-origin reads, which a public gateway needs; any loopback gateway works.
• harness-floor is the first decdn release whose e2e harness runs this SDK's contract suite (CONTRIBUTING.md). It is empty until that release exists: the released-gateway run starts with the first decdn release that ships the Python harness.

from decdn import AsyncClient, ByteRange, Client

with Client("https://decdn.link") as client:
    # A blob, streamed and hashed as it arrives.
    blob = client.get("decdn:<64 hex>")
    blob.verified  # True
    data = blob.read()  # raises HASH_MISMATCH on bad bytes

    # One file of a bundle, checked against the bundle's manifest.
    page = client.get("decdn:<manifest hash>/docs/index.html")
    text = page.text()

    # A window of a sized entry: 206, not verifiable.
    part = client.get("decdn:<manifest hash>/model.bin", range=ByteRange(offset=0, length=1 << 20))
    part.content_range  # ContentRange(offset=0, length=1048576, size=...)

# The same calls, awaited.
async with AsyncClient("https://decdn.link") as client:
    blob = await client.get("decdn:<64 hex>")
    data = await blob.read()

    # Or stream it: the mismatch raises at the end of the iteration.
    streamed = await client.get("decdn:<64 hex>")
    async for chunk in streamed.iter_bytes():
        ...

ByteRange takes an offset and, optionally, a length. A response is a context manager too; leaving the block closes the connection if the body was not read.

A loopback gateway pays with a capability a pool owner issued to one of its delegate keys. Mint the delegate, have the owner assign it, and register it for the host your requests name:

from decdn import AsyncClient, Client
from decdn.local import read_loopback_token

with Client(
    "http://127.0.0.1:8484",
    token=read_loopback_token(),  # ~/.decdn/gateway/token
    host="example.com",  # sent as x-decdn-host
) as client:
    delegate = client.loopback.delegate()
    # The pool owner: decdn pool assign --pool <id> --signer <delegate.address> ...
    client.loopback.register_capability(capability="dcap1:...", scope="example.com")
    r = client.get("decdn:<64 hex>")

async with AsyncClient("http://127.0.0.1:8484", token=read_loopback_token(), host="example.com") as client:
    delegate = await client.loopback.delegate()
    await client.loopback.register_capability(capability="dcap1:...", scope="example.com")
    r = await client.get("decdn:<64 hex>")

client.loopback.capabilities() lists what the gateway holds. Without a covering capability a request fails with PAYMENT_REQUIRED. A dcap1: token decodes offline with parse_capability.

The SDK does not start the gateway. Run it yourself (decdn gateway, or the decdn/decdn Docker image). A localhost, 127.0.0.1 or ::1 URL opens a loopback client; a public gateway you run locally needs another host name, such as decdn.localhost. read_loopback_token(data_dir=None) reads the token from the gateway's data dir (default_data_dir(), ~/.decdn/gateway).

get takes verify="auto" | True | False (default "auto", or the client's own default from its constructor). response.verified says what happened:

verify=True refuses a request that cannot be verified with CONFIG.

A verified body is hashed as it streams, and a body is consumed once: by read() (also text() and json()) or by iter_bytes(), not both. A mismatch raises HASH_MISMATCH (or TRUNCATED when the gateway cuts the stream) from read(), or from the iteration at its end, and the same error again on every later call. Chunks read before the end are not yet verified; act on them only once the iteration finishes. Ranges are never verified.

Every failure is a DecdnError with a stable code:

The error carries the details its failure has, and None for the rest: status, body, retry_after_secs and fallback_uri (402 and 503), size (416) and seq (409). The cause, when there is one, is the chained exception.

fallback_uri is the canonical decdn: URI: fetch it with a paying client of your own (decdn get <uri>), or wait retry_after_secs. The SDK retries nothing on its own; get(uri, retry=True) waits out one Retry-After and tries once more, and retry=30.0 does so only when the wait is at most 30 seconds.

On a public gateway, the owner of a namespace on the PublisherRegistry points it at a bundle, and https://<ns>.<host>/ serves that bundle:

from decdn import AsyncClient, Client, PointerDomain

domain = PointerDomain(chain_id=421614, publisher_registry="0x...")

with Client("https://decdn.link", pointer=domain) as client:
    result = client.pointer.set(
        namespace=42,
        root="decdn:<manifest hash>/",
        signer="0x...",  # a raw secp256k1 key: hex or 32 bytes
    )
    result.url  # https://42.decdn.link/

async with AsyncClient("https://decdn.link", pointer=domain) as client:
    result = await client.pointer.set(namespace=42, root="decdn:<manifest hash>/", signer="0x...")

A wallet signs instead: any object with sign_typed_data(typed_data) -> str is a TypedDataSigner. For an eth-account LocalAccount, whose sign_typed_data returns a SignedMessage, a three-line adapter does it:

class AccountSigner:
    def __init__(self, account):
        self.account = account

    def sign_typed_data(self, typed_data):
        return "0x" + self.account.sign_typed_data(full_message=typed_data).signature.hex()

then signer=AccountSigner(account).

The pointer is EIP-712 typed data (pointer_typed_data gives it to a wallet), seq defaults to the current Unix second, and the gateway takes only a seq above the last one it holds from the same signer. The chain id and registry are the deployment the gateway verifies against.

Namespaces, sequence numbers, caps and expiries are int.

uv sync --frozen
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest        # unit tests and the contract suite against the fake gateway
uv build             # dist/: sdist and wheel

tests/fake_gateway.py reproduces the gateway's HTTP contract. The contract suite in tests/contract runs against it by default, and against a real gateway in decdn's CI (sdk_contract.rs), so the two cannot drift apart. See CONTRIBUTING.md.

Releases are cut from signed v* tags (RELEASING.md); the keys that sign them are in KEYS (gpg --import KEYS, then git verify-tag vX.Y.Z).

Dual-licensed under either MIT or Apache-2.0, at your option.