decdn 0.1.0__tar.gz

decdn-0.1.0/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

decdn-0.1.0/LICENSE-MIT

@@ -0,0 +1,19 @@
+Copyright 2026 deCDN Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

decdn-0.1.0/PKG-INFO

@@ -0,0 +1,349 @@
+Metadata-Version: 2.4
+Name: decdn
+Version: 0.1.0
+Summary: Python client for deCDN over a decdn gateway: verified fetches, bundles, loopback capabilities and namespace pointers.
+Keywords: decdn,cdn,blake3,content-addressed,gateway
+License-Expression: MIT OR Apache-2.0
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx>=0.28
+Requires-Dist: blake3>=1.0
+Requires-Dist: coincurve>=20
+Requires-Dist: pycryptodome>=3.20
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/decdn/sdk-python
+Project-URL: Repository, https://github.com/decdn/sdk-python
+Project-URL: Issues, https://github.com/decdn/sdk-python/issues
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable-file MD033 MD041 -->
+<p align="center">
+  <a href="https://decdn.org">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/decdn/decdn/main/.github/assets/wordmark-dark.svg">
+      <img alt="deCDN" src="https://raw.githubusercontent.com/decdn/decdn/main/.github/assets/wordmark-light.svg" width="150">
+    </picture>
+  </a>
+</p>
+
+<h1 align="center">decdn</h1>
+
+<h3 align="center">Python client for deCDN: verified fetches, bundles, loopback capabilities and namespace pointers.</h3>
+
+<p align="center">
+  <a href="https://github.com/decdn/sdk-python/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/decdn/sdk-python/ci.yml?branch=main&label=CI&logo=github" alt="CI"></a>
+  <a href="https://github.com/decdn/sdk-python/actions/workflows/codeql.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/decdn/sdk-python/codeql.yml?branch=main&label=CodeQL&logo=github" alt="CodeQL"></a>
+  <a href="https://pypi.org/project/decdn/"><img src="https://img.shields.io/pypi/v/decdn?logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://pypi.org/project/decdn/"><img src="https://img.shields.io/pypi/pyversions/decdn?logo=python&logoColor=white" alt="Python versions"></a>
+  <a href="#compatibility"><img src="https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdecdn%2Fsdk-python%2Fmain%2Fpyproject.toml&query=%24.tool.decdn.gateway-floor&label=decdn%20gateway&prefix=%E2%89%A5%20v" alt="decdn gateway floor"></a>
+  <a href="#license"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue" alt="License: MIT OR Apache-2.0"></a>
+  <a href="https://www.conventionalcommits.org"><img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow" alt="Conventional Commits"></a>
+  <a href="https://discord.gg/vVbNswKVGX"><img src="https://img.shields.io/badge/chat-Discord-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+</p>
+
+<h3 align="center">
+  <a href="https://decdn.org">Website</a> ·
+  <a href="https://docs.decdn.org">Docs</a> ·
+  <a href="https://github.com/decdn/decdn/blob/main/adr/appendix-gateway.md">Gateway spec</a> ·
+  <a href="https://github.com/decdn/decdn">deCDN</a> ·
+  <a href="https://discord.gg/vVbNswKVGX">Discord</a>
+</h3>
+
+Python client for [deCDN](https://github.com/decdn/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](#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 `int`s.
+
+## Contents
+
+- [Install](#install)
+- [Gateways](#gateways)
+- [Compatibility](#compatibility)
+- [Public gateway](#public-gateway)
+- [Loopback gateway](#loopback-gateway)
+- [Verification](#verification)
+- [Errors](#errors)
+- [Namespace pointers](#namespace-pointers)
+- [API at a glance](#api-at-a-glance)
+- [Development](#development)
+- [License](#license)
+
+## Install
+
+```sh
+pip install decdn
+# or
+uv add decdn
+```
+
+## Gateways
+
+The client talks to one of two kinds of gateway:
+
+| Gateway                                                  | Where it runs                          | Who pays                                          |
+| -------------------------------------------------------- | -------------------------------------- | ------------------------------------------------- |
+| Public (`decdn gateway --public-url https://decdn.link`) | Anywhere with network access           | The operator's pool, within a daily allowance     |
+| Loopback (`decdn gateway`, `http://127.0.0.1:8484`)      | The same machine, with the gateway token | The capability registered for the requesting host |
+
+The gateway's HTTP contract is
+[appendix-gateway](https://github.com/decdn/decdn/blob/main/adr/appendix-gateway.md);
+bundles and their manifests are
+[appendix-bundles](https://github.com/decdn/decdn/blob/main/adr/appendix-bundles.md).
+
+## Compatibility
+
+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](https://github.com/decdn/decdn/blob/main/adr/appendix-gateway.md#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](CONTRIBUTING.md#the-contract-suite-fake-and-real-gateway)).
+  It is empty until that release exists: the released-gateway run starts with
+  the first decdn release that ships the Python harness.
+
+## Public gateway
+
+```python
+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.
+
+## Loopback gateway
+
+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:
+
+```python
+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`).
+
+## Verification
+
+`get` takes `verify="auto" | True | False` (default `"auto"`, or the client's
+own default from its constructor). `response.verified` says what happened:
+
+| Request                     | `verified` | How                                                                                                                |
+| --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
+| A blob by hash              | `True`     | The whole body hashes to the URI's hash.                                                                           |
+| A bundle entry              | `True`     | The client reads the bundle manifest (cached per client, itself verified) and the body hashes to the entry's hash. |
+| A page or stylesheet entry  | `True`     | A site rewrites HTML and CSS as it serves them, so the client fetches these by their entry hash instead.           |
+| A `range` of a bundle entry | `"skipped"` | A window does not hash to anything. A blob has no declared size, so a range on one is refused with `CONFIG`.       |
+| A bundle's index or listing | `"skipped"` | The gateway renders it.                                                                                            |
+| Any, with `verify=False`    | `False`    | Nothing is hashed and no manifest is read.                                                                         |
+
+`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.
+
+## Errors
+
+Every failure is a `DecdnError` with a stable `code`:
+
+| Code                    | When                                                                                                |
+| ----------------------- | --------------------------------------------------------------------------------------------------- |
+| `PAYMENT_REQUIRED`      | 402: the allowance is spent, the entry does not fit what is left, or no capability covers the host  |
+| `POOL_UNFUNDED`         | 503: the gateway's pool cannot pay                                                                  |
+| `NOT_FOUND`             | 404                                                                                                 |
+| `RANGE_NOT_SATISFIABLE` | 416: the range starts past the end; `size` holds the entry's size                                   |
+| `UNAUTHORIZED`          | 401: the loopback token is missing or wrong                                                         |
+| `FORBIDDEN`             | 403                                                                                                 |
+| `BAD_URI`               | A `decdn:` URI that does not parse, or 400                                                          |
+| `RATE_LIMITED`          | 429                                                                                                 |
+| `UPSTREAM`              | 502: the gateway's pull failed upstream                                                             |
+| `PAYLOAD_TOO_LARGE`     | 413                                                                                                 |
+| `CONFLICT`              | 409: a pointer `seq` that is not newer, or a capability already registered                          |
+| `UNPROCESSABLE`         | 422                                                                                                 |
+| `HASH_MISMATCH`         | The bytes do not hash to the hash that names them                                                   |
+| `TRUNCATED`             | The body is shorter or longer than declared, or the stream failed                                   |
+| `MALFORMED_MANIFEST`    | A bundle manifest that does not parse                                                               |
+| `BAD_CAPABILITY`        | A `dcap1:` token that does not decode                                                               |
+| `NETWORK`               | The gateway could not be reached                                                                    |
+| `CONFIG`                | The client is not set up for the call, or the call cannot be honoured as asked                      |
+| `HTTP`                  | A status the gateway contract does not name                                                         |
+
+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.
+
+## Namespace pointers
+
+On a public gateway, the owner of a namespace on the `PublisherRegistry`
+points it at a bundle, and `https://<ns>.<host>/` serves that bundle:
+
+```python
+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:
+
+```python
+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.
+
+## API at a glance
+
+| Export                                                                                  | What it does                                                                                                                                                                  |
+| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Client(gateway_url, ...)`, `AsyncClient(gateway_url, ...)`                             | A client on a public or loopback gateway (`token`, `host`, `pointer`, `transport`, `verify`, `manifest_cache_size`, `timeout`); a context manager                              |
+| `client.get(uri, range=, verify=, retry=)`                                              | Fetches a blob, a bundle, a bundle entry or a range as a `Response` / `AsyncResponse` (`verified`, `iter_bytes`, `read`, `text`, `json`)                                      |
+| `client.head(uri)`                                                                      | The size, hash and content type of what a URI names, without its bytes                                                                                                        |
+| `client.resolve(uri)`                                                                   | A URI's kind, hash, bare and site URLs, and its manifest entry (reads the manifest for a bundle or entry)                                                                     |
+| `client.manifest(hash_or_uri)`                                                          | A bundle's verified manifest, cached per client                                                                                                                               |
+| `client.site_url(uri)`, `client.namespace_url(ns)`                                      | The site URL of a bundle or entry; the URL a namespace's pointer serves at (`https://<ns>.<host>/`). Neither makes a request                                                  |
+| `client.loopback.delegate()`                                                            | Mints a delegate key on a loopback gateway, held for 15 minutes unless a capability claims it                                                                                 |
+| `client.loopback.register_capability(capability=, scope=)`, `.capabilities()`           | Registers a `dcap1:` capability for a scope (`example.com`, `*.example.com` or `*`); lists the capabilities the gateway holds (needs the token)                               |
+| `client.pointer.set(namespace=, root=, seq=, signer=)`                                  | Signs and publishes a namespace pointer on a public gateway                                                                                                                   |
+| `pointer_typed_data`, `pointer_signing_hash`, `sign_pointer`, `recover_pointer_signer`  | The pointer's EIP-712 typed data and signing hash, its signature, and the signer a signature recovers to                                                                      |
+| `parse_uri`, `format_uri`                                                               | Parse and canonically format a `decdn:` URI, following the Rust client's grammar exactly (`BAD_URI` on anything it refuses)                                                   |
+| `hash_to_base32`, `base32_to_hash`                                                      | A hash to and from its site label                                                                                                                                             |
+| `blake3_hex`, `create_blake3`                                                           | BLAKE3, one-shot and incremental                                                                                                                                              |
+| `parse_manifest`, `parse_capability`                                                    | Decodes a v1 bundle manifest, checking its hash when given one; decodes a `dcap1:` token without checking its signature                                                       |
+| `DecdnError`                                                                            | Every failure, with a stable `code` ([Errors](#errors))                                                                                                                       |
+| `read_loopback_token`, `default_data_dir`                                               | From `decdn.local`: the loopback gateway's token and data dir (`~/.decdn/gateway`)                                                                                            |
+
+Namespaces, sequence numbers, caps and expiries are `int`.
+
+## Development
+
+```sh
+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`](https://github.com/decdn/decdn/blob/main/crates/e2e/src/sdk_contract.rs)),
+so the two cannot drift apart. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Releases are cut from signed `v*` tags ([RELEASING.md](RELEASING.md)); the
+keys that sign them are in [`KEYS`](KEYS) (`gpg --import KEYS`, then
+`git verify-tag vX.Y.Z`).
+
+## License
+
+Dual-licensed under either [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE),
+at your option.